Requirements
| Requirement | Needed for | Notes |
|---|---|---|
| Node ≥ 18 | everything | The CLI, MCP server and library are ESM TypeScript compiled to Node. |
| FFmpeg + ffprobe | everything | brew install ffmpeg. Invoked as a separate process — never bundled or linked. Point elsewhere with the ffmpeg_path config key. |
| Chrome / Chromium | render, screenshot, capture | Auto-detected (Chrome, Chromium, Edge, Brave). Override with CLEYA_CHROME; pass flags with CLEYA_CHROME_FLAGS (for example --no-sandbox in a container). |
| FFmpeg with libfreetype | card, caption, autosub | The default Homebrew formula lacks the drawtext filter. On macOS: brew tap homebrew-ffmpeg/ffmpeg && brew install homebrew-ffmpeg/ffmpeg/ffmpeg. Cleya returns DRAWTEXT_NOT_FOUND rather than failing cryptically. |
| whisper.cpp | transcribe, autosub, clean_speech, animated_captions | Returns WHISPER_NOT_FOUND when absent. |
| macOS + Xcode CLT | contrast, align, detect_text, caption_extract, cutout, segment, bg_remove, animated_captions, image_similarity, saliency ranking | These route through the Vision framework. Native helpers compile on first use and are cached. Install with xcode-select --install. |
OPENAI_API_KEY | tts only | The only tool that touches the network. Everything else is local. |
Platform behaviour
Cleya runs on macOS, Linux and Windows. 53 of the 67 tools are platform-independent, and
that includes the entire core loop: render, draft, starters, edit, harvest, scrub,
compose, brand_check, palette, claims and diff. You can author, render, brand-check and
correct on any of the three.
Nine tools need a Mac, because they read text or shapes off a frame through the Vision framework:
contrast, align, detect_text, caption_extract, cutout, segment, bg_remove,
animated_captions and image_similarity. Five more degrade rather than fail:
review— the FFmpeg checks (black frames, frozen frames, audio dead-air) work everywhere; the OCR-based layout checks need macOS.thumbnails—rank(saliency sorting) needs macOS.reformat—crop: auto(face detection) needs macOS; every other crop mode works everywhere.smart_crop— falls back to a centre crop off macOS.
Check everything at once
cleya doctor
doctor reports FFmpeg, ffprobe, the drawtext filter, libx264, Whisper and the platform, and
exits non-zero if something required is missing.