4.0 KiB
Requirements & Caches
Credential & key priority
Run npx hyperframes auth status to see what's configured and which engines a workflow will use (see the skill's Preflight section). Keys resolve in this order — first match wins:
| Provider | Resolution order (first non-empty wins) | Local deps when used |
|---|---|---|
| HeyGen (TTS + BGM/SFX retrieval) | $HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → ~/.heygen/credentials (shared with heygen-cli; $HEYGEN_CONFIG_DIR overrides the dir; written by hyperframes auth login) |
none (REST) |
| ElevenLabs (TTS fallback) | $ELEVENLABS_API_KEY |
pip install elevenlabs |
| Lyria (BGM fallback) | $GEMINI_API_KEY → $GOOGLE_API_KEY |
pip install google-genai |
| Kokoro (TTS, no key) | always — final voice fallback | pip install kokoro-onnx soundfile |
| MusicGen (BGM, no key) | always — final music fallback | pip install transformers torch soundfile numpy |
hyperframes auth login (browser OAuth) is the recommended setup: one sign-in, every project, no per-repo .env. An OAuth login is sent as Authorization: Bearer; an API key as X-Api-Key; both are tagged with X-HeyGen-Source: cli. OAuth CLI users can consume the web-plan free allowance for HeyGen TTS (10 min/month); API keys follow the normal API billing path. With no HeyGen credential, voice/BGM run fully locally (Kokoro / MusicGen) — hyperframes auth status and hyperframes doctor both report whether those local deps are installed.
Model caches & system dependencies
Each command downloads its own model on first run and caches it under ~/.cache/hyperframes/:
- TTS (HeyGen) — no local deps; needs a HeyGen credential +
ffmpegon PATH (to transcode the mp3 response to.wav). Credential resolves like the CLI:$HEYGEN_API_KEY→$HYPERFRAMES_API_KEY→~/.heygen/credentials(shared with heygen-cli; runnpx hyperframes auth login). An OAuth login is sent asAuthorization: Bearer; an API key asX-Api-Key; both includeX-HeyGen-Source: cliso the backend can apply CLI OAuth free usage. - TTS (ElevenLabs) — same as HeyGen: API key +
ffmpeg. - TTS (Kokoro) — Kokoro-82M (~311 MB) + voices (~27 MB) in
tts/. Requires Python 3.8+ withkokoro-onnxandsoundfile(pip install kokoro-onnx soundfile). Non-English text also needsespeak-ngsystem-wide. - BGM (Lyria) — needs
$GEMINI_API_KEYor$GOOGLE_API_KEY+pip install google-genai. No local model cache. - BGM (MusicGen) —
pip install transformers torch soundfile.facebook/musicgen-small(~300 MB) cached under~/.cache/huggingface/on first run. - Transcribe — Whisper model size depending on choice (75 MB – 3.1 GB) in
whisper/. Bundleswhisper.cpp. - Remove-background —
u2net_human_seg(~168 MB ONNX) inbackground-removal/models/. Peak inference RAM ~1.5 GB.
Run npx hyperframes doctor if a command fails because of a missing dependency.