Repository navigation
macOS support: nobody has ever run Clips Studio on a Mac #62
Description
Clips Studio is Windows-only today. Nothing about the design requires that, but nobody has done the work, and the maintainer does not own a Mac and cannot test one. So this needs somebody who has one.
Apple Silicon is a genuinely good fit for a local-first AI app. Unified memory means a 12B model runs comfortably on a machine with no discrete GPU, which is precisely the situation Clips Studio is built for.
What already works
core/binaries.py resolves binaries with os.name == "nt" checks, so it already looks for ffmpeg rather than ffmpeg.exe off Windows. The Python engine is ordinary cross-platform code. Ollama runs natively on macOS and uses Metal.
What needs doing
Packaging
ui/electron-builder.ymlhas nomac:target. Needs one, probablydmgpluszip.scripts/build_installer.pyassumesapi.exe, filters artifacts on.exe/.7z, and drives NSIS. Needs a macOS path.scripts/fetch_ollama.pyhardcodesollama-windows-amd64.zip. macOS needs the darwin build.scripts/fetch_ffmpeg.pypulls a Windows build from gyan.dev. macOS needs a different source, and the licence note in that script has to stay accurate for whichever build is used.
GPU and encoding
requirements.txtinstalls CUDA PyTorch. Apple Silicon wants the MPS build instead.video/tracker.pyandvideo/asd.pychecktorch.cuda.is_available()and otherwise fall back to CPU. On a Mac they will silently run on CPU when MPS is available and much faster. Worth handling, though CPU fallback means it still works.transcription/transcriber.pypickscudaorcpu. faster-whisper via CTranslate2 has no MPS backend, so CPU is expected here, and Apple Silicon CPU is decent at it.video/encoding.pyknowsnvenc,amfandqsv. macOS wantsh264_videotoolbox, which is the single highest-value item on this list: software encoding is what made rendering slow and memory-hungry in testing.
Distribution
- Unsigned Mac apps are blocked by Gatekeeper more firmly than Windows SmartScreen warns. Notarization needs a paid Apple Developer account, so an unsigned first build will need
xattr -dr com.apple.quarantineinstructions, which is ugly but honest. - The payload is ~6 GB and lives on Hugging Face rather than GitHub Releases, because a release asset caps at 2 GiB. A Mac build would use the same arrangement. See
docs/RELEASING.md.
Ways to help, smallest first
You do not need to do all of this. Any of these is genuinely useful:
- Run the engine from source on a Mac and report what breaks.
pip install -r requirements.txt, thenpython main.py serve. This alone would tell us a lot and needs no packaging work. - Run the UI too:
cd ui && npm install && npm run dev. - Add
h264_videotoolboxtovideo/encoding.py. Small, self-contained, big payoff. - Make MPS work for tracking, so Apple Silicon is not stuck on CPU.
- Add the
mac:target and produce a DMG. - Full port, including notarization.
Please say in a comment which part you are taking, so two people do not do the same one.
What to report
Mac model and chip:
macOS version:
RAM:
What you tried:
What worked:
What broke (with the error):
Even "the engine starts but ffmpeg is not found" is a useful data point. Nobody has ever run this on a Mac, so there is no baseline at all.
Related
docs/DOCKER.mdshows the engine already runs outside Windows in a Linux container, so the Python side is not deeply Windows-bound.- Bundled yt-dlp goes stale between releases, so a site change breaks every install #39, on yt-dlp going stale, touches the same packaging scripts.
Activity
ColinGPT9 commentedon Aug 11, 2026
Thank you for your help, I couldn't get it a clips to render in a sandbox environment today because I ran out of ram can psutil be an issue on Windows machines installing it for the first time? I got it to analyze 40 clips then it failed with 0 being made.
ColinGPT9 commentedon Aug 11, 2026
Thank you so much for your help. I gave the app to some people I know that makes videos of youtubers hoping they test it but I am unsure if a full run went through yet because my sandbox crash.
ColinGPT9 commentedon Aug 12, 2026
When I was making it it didn't work correctly for gaming because I couldn't get the tracker to work on split screen. I tested it on Marvel Rivals and it was confusing people in games for people the webcam. I used it for just chatting and IRL focus because that is what is more popular now and those are the creators that offered me money to post clips of them in the past. I figured I would add the fix later as a separate pipeline if people wanted it. Gaming and Reaction videos gave me issues with the tracker so I put it off not to delay the alpha release.
ColinGPT9 commentedon Aug 12, 2026
I had a big problem with face tracking on who was talking when I used OpenCV and YoloV8 it was selecting the bigger person if their was multiple people in the same frame and I needed to transition the tracking to TalkNet to measure lip movement to select the right speaker. TalkNet ended up fixing it but made the whole pipeline run longer and when I tried split screen reaction videos it would select where their is more activity. I tried a video of a reaction and they were looking at a twitter post then the tracker focused on the wrong section of screen and not the image the streamer was reacting too. This was before I added TalkNet for the tracking. When I tried Marvel RIvals their was images on the side of the screen for other character and it focused on the images instead of the actual gameplay. I figured it was a future problem because their was so many variables with different types of games. If i made it work with Marvel Rivals I might have an issue with a different game and now I am also thinking I want to add sports highlights to the app eventually because a lot of people post NBA highlights to social media. I am trying to grow it across all different types of media and make the app a platform people can add different AI models or make it work for new types of videos in a separate pipeline. I had a separate toggle for gaming or reaction content to force split screen I reverted changes after not being able to make it work. it's in the commit history somewhere.
Write down the memory requirement that everyone keeps discovering
ColinGPT9 commentedon Aug 12, 2026
Went through the report properly. Three things: the memory finding turned out to be the important one, the psutil one is real, and I don't think the encoder one holds up.
The 12 GB was the most useful thing in here
That is now written down, because it was not written down anywhere useful before. The Requirements list in the README named no RAM figure at all — 16 GB was sitting in a hardware table halfway down the page that nobody reads before installing. It says it up front now, along with the part that actually confuses people: at 8 GB the job analyses the whole video and then renders nothing, which reads as a crash rather than a limit. I hit exactly that in a sandbox this week, so you and I found the same wall from different directions.
docs/DOCKER.mdnow says to give the VM 12 GB, and repeats your point about an hour of source being roughly the ceiling there.psutil: real, and there is a shortcut in the meantime
Confirmed.
psutil-5.9.8publishes Linux wheels for x86_64 and i686 only, no aarch64 file in the release at all. Your Mac buildslinux/arm64, pip finds no wheel, falls back to the sdist, andpython:3.11-slimhas no compiler.requirements.txtpinspsutil>=5.9.8,<6and the aarch64 wheels only start at 7.x, so the resolver cannot climb out of it either.To answer the question I asked earlier in this thread, for anyone reading later: this cannot affect a Windows install. The installer ships a PyInstaller build with psutil already frozen in and never runs pip.
gcc+python3-devis the right fix and a PR is welcome from anyone who can test it on a Mac. I would rather merge it having seen it work than guess at it from Windows.There is a route that works today, and I had documented it badly:
The published image is amd64 only, so
pullgives you a prebuilt image that runs under emulation and compiles nothing. What sent you into the compiler wasdocs/DOCKER.mdclaiming a local build "works everywhere" — true on x86_64, false on yours. Fixed.The encoder one I don't think is right, and I want to show why rather than just decline
Two things, both checkable in the source.
Those messages are not the encoder.
_probe()runs FFmpeg withcapture_output=True, so everything the encoder probe prints is swallowed and never reaches a terminal:https://github.com/ColinGPT9/clips-studio/blob/main/video/encoding.py#L37-L52
The
AVHWDeviceContextlines come from-hwaccel auto, which is a decode flag out ofhwaccel_input_args(), and it reaches the console becausesampled_frames()opens FFmpeg withPopen(cmd, stdout=subprocess.PIPE)and leaves stderr attached.video.encoderdoes not touch that path, soencoder: cpuwould not have silenced them.And with no GPU,
autoalready iscpu. All three candidates fail their probe when there is no device,_select()falls through toCPU_ARGS, and the FFmpeg command is byte-identical to the oneencoder: cpuproduces. The two settings you compared were running the same command.Which points back at memory. You raised the limit to 12 GB and you changed the encoder, and I think the first one is what moved your render success. That would also explain why it was 1-in-3 rather than 0-in-3: three clips render at once, so under a cap the first through the door survives and the others do not.
One thing that would settle it: when a render failed, did you get a truncated file or no file at all? Those are different bugs and I would like to know which before touching anything. If it turns out to be truncation, that is on me — there is a spot where a short decode is currently accepted without complaint.
I am not going to default to CPU encoding, because it would cost every NVENC user hardware encoding to fix something it does not actually fix. Not a dismissal of the report, just of that one line.
Still the valuable part
Leaving this open.
h264_videotoolboxand themac:target are untouched and worth more than either of the above. The videotoolbox one is small and self-contained, and you are currently the only person who can test it.ColinGPT9 commentedon Aug 12, 2026
Was claude that wrote that didn't know it would reply it's my first time building a project on github
Write down the memory requirement that everyone keeps discovering
dillonstreator commentedon Oct 21, 2026
Repo map follows the encoder lines; README stays as it was
Encoding: Apple VideoToolbox as a hardware encoder candidate (#172)