Skills › HyperFrames › media-use › requirements.md

requirements.md

29 lines · skills/media-use/audio/references/requirements.md at a595755

1# Requirements & Caches

Requirements & Caches

3## Credential & key priority

5Run `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**:

7| Provider | Resolution order (first non-empty wins) | Local deps when used |

8| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |

9| **HeyGen** (TTS + BGM retrieval) | `$HEYGEN_ACCESS_TOKEN` → the `~/.hyperframes/credentials` login → `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → a saved API key (`$HYPERFRAMES_CONFIG_DIR` overrides the root; dev uses `dev/`) | none (REST) |

10| **ElevenLabs** (TTS fallback) | `$ELEVENLABS_API_KEY` | `pip install elevenlabs` |

11| **Lyria** (BGM fallback) | `$GEMINI_API_KEY` → `$GOOGLE_API_KEY` | `pip install google-genai` |

12| **Kokoro** (TTS, no key) | always — final voice fallback | `pip install kokoro-onnx soundfile` |

13| **MusicGen** (BGM, no key) | always — final music fallback | `pip install transformers torch soundfile numpy` |

15`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`; only OAuth is tagged with `X-HeyGen-Source: cli`. The server decides HyperFrames eligibility and charges; API keys use API billing. An expired or foreign OAuth session requires refresh/sign-in and never selects a saved API key. 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.

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 retrieval)	`$HEYGEN_ACCESS_TOKEN` → the `~/.hyperframes/credentials` login → `$HEYGEN_API_KEY` → `$HYPERFRAMES_API_KEY` → a saved API key (`$HYPERFRAMES_CONFIG_DIR` overrides the root; dev uses `dev/`)	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; only OAuth is tagged with X-HeyGen-Source: cli. The server decides HyperFrames eligibility and charges; API keys use API billing. An expired or foreign OAuth session requires refresh/sign-in and never selects a saved API key. 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.

Raw lines 3 to 16

17## Model caches & system dependencies

19Each command downloads its own model on first run and caches it under `~/.cache/hyperframes/`:

21- **TTS (HeyGen)** — no local deps; needs a HeyGen credential + `ffmpeg` on PATH (to transcode the mp3 response to `.wav`). Credential resolves like the CLI: the priority above; run `npx hyperframes auth login` for its isolated OAuth store. An OAuth login is sent as `Authorization: Bearer`; an API key as `X-Api-Key`; only OAuth includes `X-HeyGen-Source: cli`; the server selects billing from the verified credential.

22- **TTS (ElevenLabs)** — same as HeyGen: API key + `ffmpeg`.

23- **TTS (Kokoro)** — Kokoro-82M (~311 MB) + voices (~27 MB) in `tts/`. Requires Python 3.8+ with `kokoro-onnx` and `soundfile` (`pip install kokoro-onnx soundfile`). Non-English text also needs `espeak-ng` system-wide.

24- **BGM (Lyria)** — needs `$GEMINI_API_KEY` or `$GOOGLE_API_KEY` + `pip install google-genai`. No local model cache.

25- **BGM (MusicGen)** — `pip install transformers torch soundfile`. `facebook/musicgen-small` (~300 MB) cached under `~/.cache/huggingface/` on first run.

26- **Transcribe** — Whisper model size depending on choice (75 MB – 3.1 GB) in `whisper/`, downloaded from HuggingFace on first use. `whisper.cpp` itself is NOT bundled: the CLI resolves it from PATH, installs via Homebrew (macOS), or builds it from source with git+cmake on first use (`$HYPERFRAMES_WHISPER_PATH` overrides).

27- **Remove-background** — `u2net_human_seg` (~168 MB ONNX) in `background-removal/models/`. Peak inference RAM ~1.5 GB.

29Run `npx hyperframes doctor` if a command fails because of a missing dependency.

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 + ffmpeg on PATH (to transcode the mp3 response to .wav). Credential resolves like the CLI: the priority above; run npx hyperframes auth login for its isolated OAuth store. An OAuth login is sent as Authorization: Bearer; an API key as X-Api-Key; only OAuth includes X-HeyGen-Source: cli; the server selects billing from the verified credential.
TTS (ElevenLabs) — same as HeyGen: API key + ffmpeg.
TTS (Kokoro) — Kokoro-82M (~311 MB) + voices (~27 MB) in tts/. Requires Python 3.8+ with kokoro-onnx and soundfile (pip install kokoro-onnx soundfile). Non-English text also needs espeak-ng system-wide.
BGM (Lyria) — needs $GEMINI_API_KEY or $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/, downloaded from HuggingFace on first use. whisper.cpp itself is NOT bundled: the CLI resolves it from PATH, installs via Homebrew (macOS), or builds it from source with git+cmake on first use ($HYPERFRAMES_WHISPER_PATH overrides).
Remove-background — u2net_human_seg (~168 MB ONNX) in background-removal/models/. Peak inference RAM ~1.5 GB.

Run npx hyperframes doctor if a command fails because of a missing dependency.

Raw lines 17 to 29