HyperFrames 音频管线凭据解析与模型缓存完全指南

导读

本指南聚焦 HyperFrames 音频引擎（TTS 配音、BGM 背景乐、转写、去背）的凭据解析优先级与本地模型缓存/系统依赖两大主题。文中依据技能文档 skills/media-use/audio/references/requirements.md 展开，并以 packages/cli/src/auth/client.ts 等源码佐证底层实现。读完你将掌握：如何用 npx hyperframes auth status 判断一次音频工作流实际会走哪个引擎、每类凭据的生效顺序、各模型首次运行时的下载体积与缓存位置，以及缺失依赖时如何用 npx hyperframes doctor 自检修复。

一、为什么需要了解凭据优先级

HyperFrames 的音频能力并非单一实现，而是按"可获得的凭据"自动降级的多层栈：

• 云端 TTS：HeyGen（主）→ ElevenLabs（备）
• 本地 TTS 兜底：Kokoro（无密钥，始终可用）
• 云端 BGM：Lyria（备）
• 本地 BGM 兜底：MusicGen（无密钥，始终可用）

同一台机器上可能同时存在多种凭据，而第一个非空（first match wins）的凭据决定实际引擎。因此，排查"为什么我的配音用的是另一个声音/为什么没走 HeyGen"这类问题时，第一件事永远是查看当前生效的凭据组合。

运行以下命令查看当前已配置的凭据以及工作流将使用的引擎（对应技能文档中的 Preflight 预检步骤）：

npx hyperframes auth status

二、凭据与密钥解析优先级（first match wins）

下表完整列出各提供方的解析顺序，第一个非空值胜出：

Provider	解析顺序（第一个非空生效）	使用时的本地依赖
HeyGen（TTS + BGM/SFX 检索）	$HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → ~/.heygen/credentials（与 heygen-cli 共享；$HEYGEN_CONFIG_DIR 覆盖目录；由 hyperframes auth login 写入）	无（REST 调用）
ElevenLabs（TTS 备用）	$ELEVENLABS_API_KEY	pip install elevenlabs
Lyria（BGM 备用）	$GEMINI_API_KEY → $GOOGLE_API_KEY	pip install google-genai
Kokoro（TTS，无需密钥）	始终可用——最终语音兜底	pip install kokoro-onnx soundfile
MusicGen（BGM，无需密钥）	始终可用——最终音乐兜底	pip install transformers torch soundfile numpy

几个值得注意的细节：

• HeyGen 的第三种来源是共享凭据文件 ~/.heygen/credentials，它由 npx hyperframes auth login 写入，并与 heygen-cli 共用，因此通过官方 CLI 登录一次即可同时供两个工具使用。
• Kokoro 与 MusicGen 永远在候补队列末端：即使完全没有云端密钥，配音与背景乐依然可以离线完成，只是质量与能力上限不同。
• 技能文档 skills/media-use/audio/references/tts.md 中给出了语音的实际选择顺序：HeyGen（Starfish 引擎，含词级时间戳）→ ElevenLabs → Kokoro 本地兜底，与上表完全对应。

推荐做法：一次 OAuth 登录，全项目生效

hyperframes auth login（浏览器 OAuth）是推荐配置：一次登录即可覆盖所有项目，无需为每个仓库维护 .env 文件。

凭据如何随请求发送（源码级验证）

在 packages/cli/src/auth/client.ts 中可以看到两个关键头常量的定义：

• HEYGEN_CLI_SOURCE_HEADER = "X-HeyGen-Source"，取值 cli
• HEYGEN_CLIENT_SOURCE_HEADER = "X-HeyGen-Client-Source"，取值 hyperframes

buildAuthHeaders()（见 packages/cli/src/auth/client.ts）展示了两种凭据的发送差异：

• OAuth 登录 → Authorization: Bearer <token>，并携带 X-HeyGen-Source: cli
• API Key → x-api-key: <key>，不携带 X-HeyGen-Source

两种请求都会携带 X-HeyGen-Client-Source: hyperframes 工具归属头，供后端在计费元数据中区分 CLI 流量。源码注释还解释了 OAuth 专属的 cli-source 头用于后端隔离 CLI 免费额度。

免费额度与计费路径

• OAuth CLI 用户可以消费 Web 套餐的 HeyGen TTS 免费额度（10 分钟/月）。
• API Key 用户走常规 API 计费路径。

这意味着：用 auth login 登录后，在免费额度内的 TTS 不产生 API 费用；而直接设置 $HEYGEN_API_KEY 则始终按 API 计费。

三、无凭据时的行为：完全本地运行

如果没有任何 HeyGen 凭据，语音与 BGM 将完全本地运行：

• 语音 → Kokoro（npx hyperframes tts 默认即本地 Kokoro）
• 背景乐 → MusicGen 或 Lyria

npx hyperframes auth status 与 npx hyperframes doctor 都会报告这些本地依赖是否已安装，方便你在预检阶段就发现环境缺口。

技能文档 skills/media-use/audio/references/bgm.md 还强调了一个重要约定："没有凭据"不等于可以静默使用本地生成。按 Preflight 流程，应运行 npx hyperframes auth status、建议用户登录，然后停下来等待用户选择（登录使用 HeyGen 音色库，或离线继续本地生成）。

四、模型缓存与系统依赖清单

每个命令在首次运行时下载自身所需模型，并缓存在 ~/.cache/hyperframes/ 下。各模型的具体情况如下：

能力	模型/依赖	缓存位置	体积与说明
TTS（HeyGen）	无本地模型	—	需要 HeyGen 凭据 + PATH 上的 ffmpeg（将 mp3 响应转码为 .wav）
TTS（ElevenLabs）	无本地模型	—	与 HeyGen 相同：API Key + ffmpeg
TTS（Kokoro）	Kokoro-82M	~/.cache/hyperframes/tts/	约 311 MB 模型 + 约 27 MB 音色；需 Python 3.8+ 与 kokoro-onnx、soundfile；非英语文本还需系统级 espeak-ng
BGM（Lyria）	无本地模型缓存	—	需 $GEMINI_API_KEY 或 $GOOGLE_API_KEY + pip install google-genai
BGM（MusicGen）	facebook/musicgen-small	~/.cache/huggingface/	约 300 MB，首次运行下载；需 transformers torch soundfile
Transcribe（转写）	Whisper	~/.cache/hyperframes/whisper/	体积取决于所选模型（75 MB – 3.1 GB），首次使用时从 HuggingFace 下载
Remove-background（去背）	u2net_human_seg（ONNX）	~/.cache/hyperframes/background-removal/models/	约 168 MB；峰值推理内存约 1.5 GB

Whisper 的特殊性：whisper.cpp 未内置

转写能力的细节值得单独说明：

• Whisper 模型本身从 HuggingFace 下载（tiny 75 MB 到 large-v3 3.1 GB），缓存在 whisper/ 目录。
• whisper.cpp 二进制并不捆绑分发：CLI 先从 PATH 解析，找不到时依次尝试 Homebrew（macOS）安装，或首次使用时通过 git+cmake 从源码构建。
• 可用 $HYPERFRAMES_WHISPER_PATH 环境变量覆盖 whisper.cpp 的解析路径。

关于 Whisper 模型选型与 --language 规则，可参阅 skills/media-use/audio/references/transcribe.md：务必显式传 --model，因为 CLI 默认的 small.en 会把非英语音频静默翻译成英语，破坏原始语言。

HeyGen 凭据在模型层同样生效

TTS（HeyGen）的凭据解析与 CLI 完全一致：$HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → ~/.heygen/credentials（与 heygen-cli 共享）。若未登录，可运行 npx hyperframes auth login 补齐。

五、依赖缺失时的第一反应：npx hyperframes doctor

当某个命令因缺少依赖而失败时，统一的自检入口是：

npx hyperframes doctor

该命令会同时报告：

• 各凭据的解析结果（哪些引擎可用）；
• 本地依赖（Python 包、ffmpeg、espeak-ng、whisper.cpp）是否就绪；
• 模型缓存是否已下载。

常见修复示例：

# Kokoro / MusicGen 本地兜底
pip install kokoro-onnx soundfile
pip install transformers torch soundfile numpy

# Lyria
pip install google-genai

# 非英语 Kokoro 音素化
brew install espeak-ng        # macOS
apt-get install espeak-ng     # Debian/Ubuntu

六、从源码看凭据体系的结构

凭据体系在 CLI 包中组织为独立模块，进一步阅读可沿以下路径：

• packages/cli/src/auth/client.ts：HTTP 客户端、请求头构造、401 时的 OAuth 刷新重试逻辑；
• packages/cli/src/auth/resolver.ts（同目录）：凭据解析顺序的核心实现，对应上表"first match wins"；
• packages/cli/src/commands/auth/login.ts、packages/cli/src/commands/auth/status.ts、packages/cli/src/commands/auth/refresh.ts：auth login / status / refresh 三个命令的落地实现；
• packages/cli/src/auth/store.ts：~/.heygen/credentials 的读写与 $HEYGEN_CONFIG_DIR 覆盖逻辑。

七、速查清单

1. 先看状态：npx hyperframes auth status —— 决定本次工作流走云还是本地。
2. 推荐登录：npx hyperframes auth login（浏览器 OAuth），一次登录、全项目生效，可消费 HeyGen Web 套餐 10 分钟/月免费 TTS 额度。
3. 凭据顺序：HeyGen 为 $HEYGEN_API_KEY → $HYPERFRAMES_API_KEY → ~/.heygen/credentials；ElevenLabs 仅环境变量；Lyria 为 Gemini/Google 两个环境变量。
4. 模型首次下载：全部落在 ~/.cache/hyperframes/（MusicGen 在 ~/.cache/huggingface/），Kokoro 约 338 MB、MusicGen 约 300 MB、Whisper 75 MB – 3.1 GB、u2net 约 168 MB。
5. 缺什么装什么：Kokoro → pip install kokoro-onnx soundfile；MusicGen → pip install transformers torch soundfile numpy；Lyria → pip install google-genai；非英语语音 → 系统级 espeak-ng。
6. 失败统一入口：npx hyperframes doctor 会一次性报告凭据与本地依赖的完整状态。