[vincent65]

What

• init prints one warning line when FFmpeg or FFprobe cannot be resolved, in both the interactive and the non-interactive path. Before, it only checked when given --video.
• On macOS the FFmpeg install hint now also gives the routes that work without Homebrew: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH and .hyperframes/bin. The hint is shared, so doctor, render, snapshot, transcribe and the rest pick it up too.

FFmpeg and FFprobe not found: preview and check work, but render needs both. Install: brew install ffmpeg, or without Homebrew point HYPERFRAMES_FFMPEG_PATH and HYPERFRAMES_FFPROBE_PATH at ffmpeg and ffprobe binaries, or copy both into .hyperframes/bin

Why

Only render needs FFmpeg, so an agent could run init, go through design rounds and get approval before learning the binary was missing. On a Mac without Homebrew, the only remedy the CLI offered was brew install ffmpeg, which leads nowhere.

Related work

Refs #5232. This covers two of the three items still open in @miguel-heygen's status comment: the macOS hint and the init warning. #5237 already did the docs part.

The third item, a doctor step in the hyperframes entry skill, goes in its own PR as agreed on the issue, so the skill wording gets reviewed separately.

How

• installHint() in packages/cli/src/browser/ffmpeg.ts gets a darwin branch, next to the existing win32 one. getFFmpegInstallCommand() is unchanged, so Studio's copy button still copies only brew install ffmpeg.
• missingRenderToolsWarning() in init.ts uses the existing findFFmpeg / findFFprobe lookups. It runs after scaffolding and skills, just before the "Get started" list or the preview launch.

Test plan

• Unit tests added/updated
  • ffmpeg.test.ts: the macOS hint keeps the brew command and names both env vars and .hyperframes/bin.
  • init.test.ts: runs the real init with both overrides pointed at missing files and checks for the warning, then with both pointed at existing files and checks there is none, so the test doesn't depend on FFmpeg being installed.
  • preflight.test.ts: the darwin cannot-start hint expectation now uses the new string.
  • Mutation check: with the darwin branch disabled, the ffmpeg.test.ts case fails, and with the init warning disabled, the init.test.ts case fails.
• Manual testing performed (macOS arm64, main @ 183614b)
  • Reproduced first on unmodified main with HYPERFRAMES_FFMPEG_PATH=/nonexistent/ffmpeg HYPERFRAMES_FFPROBE_PATH=/nonexistent/ffprobe: init --non-interactive printed no warning, and doctor suggested only brew install ffmpeg.
  • After the fix, init warns in non-interactive mode and in interactive mode (run in a pty, where it shows as a clack ▲ line). With only FFprobe missing it says "FFprobe not found ... render needs it". With both present it prints nothing new. doctor shows the new hint.
• bun run lint, format:check, the CLI tsc --noEmit, check-comment-citations and comment-ratchet pass.
• CLI vitest: the touched suites pass. 15 tests in measure/media, measure/diff-offset, whisper/* and checkSweep.chromium fail on my machine on clean main as well (local whisper/FFmpeg/Chrome setup), and fileWatcher.atomic is flaky locally. None of those touch this change.
• Documentation updated: not needed, since doctor-browser.md already documents both routes (docs(cli): explain FFmpeg setup without a package manager #5237).
• Comments follow CONTRIBUTING.md "Comments"

🤖 Generated with Claude Code

[vincent65]

@miguel-heygen following your notes on #5232: this PR is items 1 and 2 only. The warning is one line, and it reads from the same lookup as the hint and doctor: findFFmpeg() / findFFprobe(), which wrap findFfBinary(name, { configuredMustExist: true }), the call getFFmpegInstallHint() already makes. So a missing or misconfigured override counts as not found in both places. No Studio or player files are touched, so there are no Before/After sections. The doctor skill step will come as its own PR. Ready for review whenever you have time.

[vincent65]

Rebased onto current main (6e8454d): no conflicts, and the touched suites, typecheck, lint, fallow and both comment checks pass again. @jrusso1020 @miguel-heygen could one of you approve the fork workflow runs so CI can run? The skill step (item 3) is now its own PR, #7208.

[vincent65]

@miguel-heygen @jrusso1020 rebased onto current main (2927fe6, v0.9.25) so it has a fresh base, no conflicts and no code changes. Typecheck, lint, format, both comment checks and the touched CLI suites (ffmpeg, preflight, init: 92 tests) pass locally. Could one of you approve the fork workflow runs and take a look when you have a moment? The doctor skill step (item 3) is in #7208. Thanks!