HyperFrames 音频管线凭据解析与模型缓存完全指南【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/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 的音频能力并非单一实现而是按可获得的凭据自动降级的多层栈云端 TTSHeyGen主→ ElevenLabs备本地 TTS 兜底Kokoro无密钥始终可用云端 BGMLyria备本地 BGM 兜底MusicGen无密钥始终可用同一台机器上可能同时存在多种凭据而第一个非空first match wins的凭据决定实际引擎。因此排查为什么我的配音用的是另一个声音/为什么没走 HeyGen这类问题时第一件事永远是查看当前生效的凭据组合。运行以下命令查看当前已配置的凭据以及工作流将使用的引擎对应技能文档中的Preflight预检步骤npx hyperframes auth status二、凭据与密钥解析优先级first match wins下表完整列出各提供方的解析顺序第一个非空值胜出Provider解析顺序第一个非空生效使用时的本地依赖HeyGenTTS BGM/SFX 检索$HEYGEN_API_KEY→$HYPERFRAMES_API_KEY→~/.heygen/credentials与 heygen-cli 共享$HEYGEN_CONFIG_DIR覆盖目录由hyperframes auth login写入无REST 调用ElevenLabsTTS 备用$ELEVENLABS_API_KEYpip install elevenlabsLyriaBGM 备用$GEMINI_API_KEY→$GOOGLE_API_KEYpip install google-genaiKokoroTTS无需密钥始终可用——最终语音兜底pip install kokoro-onnx soundfileMusicGenBGM无需密钥始终可用——最终音乐兜底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 中给出了语音的实际选择顺序HeyGenStarfish 引擎含词级时间戳→ ElevenLabs → Kokoro 本地兜底与上表完全对应。推荐做法一次 OAuth 登录全项目生效hyperframes auth login浏览器 OAuth是推荐配置一次登录即可覆盖所有项目无需为每个仓库维护.env文件。凭据如何随请求发送源码级验证在 packages/cli/src/auth/client.ts 中可以看到两个关键头常量的定义HEYGEN_CLI_SOURCE_HEADER X-HeyGen-Source取值cliHEYGEN_CLIENT_SOURCE_HEADER X-HeyGen-Client-Source取值hyperframesbuildAuthHeaders()见 packages/cli/src/auth/client.ts展示了两种凭据的发送差异OAuth 登录→Authorization: Bearer token并携带X-HeyGen-Source: cliAPI 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 将完全本地运行语音 → Kokoronpx hyperframes tts默认即本地 Kokoro背景乐 → MusicGen 或 Lyrianpx hyperframes auth status与npx hyperframes doctor都会报告这些本地依赖是否已安装方便你在预检阶段就发现环境缺口。技能文档 skills/media-use/audio/references/bgm.md 还强调了一个重要约定没有凭据不等于可以静默使用本地生成。按 Preflight 流程应运行npx hyperframes auth status、建议用户登录然后停下来等待用户选择登录使用 HeyGen 音色库或离线继续本地生成。四、模型缓存与系统依赖清单每个命令在首次运行时下载自身所需模型并缓存在~/.cache/hyperframes/下。各模型的具体情况如下能力模型/依赖缓存位置体积与说明TTSHeyGen无本地模型—需要 HeyGen 凭据 PATH 上的ffmpeg将 mp3 响应转码为.wavTTSElevenLabs无本地模型—与 HeyGen 相同API Key ffmpegTTSKokoroKokoro-82M~/.cache/hyperframes/tts/约 311 MB 模型 约 27 MB 音色需 Python 3.8 与kokoro-onnx、soundfile非英语文本还需系统级espeak-ngBGMLyria无本地模型缓存—需$GEMINI_API_KEY或$GOOGLE_API_KEYpip install google-genaiBGMMusicGenfacebook/musicgen-small~/.cache/huggingface/约 300 MB首次运行下载需transformers torch soundfileTranscribe转写Whisper~/.cache/hyperframes/whisper/体积取决于所选模型75 MB – 3.1 GB首次使用时从 HuggingFace 下载Remove-background去背u2net_human_segONNX~/.cache/hyperframes/background-removal/models/约 168 MB峰值推理内存约 1.5 GBWhisper 的特殊性whisper.cpp 未内置转写能力的细节值得单独说明Whisper 模型本身从 HuggingFace 下载tiny75 MB 到large-v33.1 GB缓存在whisper/目录。whisper.cpp二进制并不捆绑分发CLI 先从 PATH 解析找不到时依次尝试 HomebrewmacOS安装或首次使用时通过 gitcmake 从源码构建。可用$HYPERFRAMES_WHISPER_PATH环境变量覆盖 whisper.cpp 的解析路径。关于 Whisper 模型选型与--language规则可参阅 skills/media-use/audio/references/transcribe.md务必显式传--model因为 CLI 默认的small.en会把非英语音频静默翻译成英语破坏原始语言。HeyGen 凭据在模型层同样生效TTSHeyGen的凭据解析与 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.tsHTTP 客户端、请求头构造、401 时的 OAuth 刷新重试逻辑packages/cli/src/auth/resolver.ts同目录凭据解析顺序的核心实现对应上表first match winspackages/cli/src/commands/auth/login.ts、packages/cli/src/commands/auth/status.ts、packages/cli/src/commands/auth/refresh.tsauth login / status / refresh三个命令的落地实现packages/cli/src/auth/store.ts~/.heygen/credentials的读写与$HEYGEN_CONFIG_DIR覆盖逻辑。七、速查清单先看状态npx hyperframes auth status—— 决定本次工作流走云还是本地。推荐登录npx hyperframes auth login浏览器 OAuth一次登录、全项目生效可消费 HeyGen Web 套餐 10 分钟/月免费 TTS 额度。凭据顺序HeyGen 为$HEYGEN_API_KEY→$HYPERFRAMES_API_KEY→~/.heygen/credentialsElevenLabs 仅环境变量Lyria 为 Gemini/Google 两个环境变量。模型首次下载全部落在~/.cache/hyperframes/MusicGen 在~/.cache/huggingface/Kokoro 约 338 MB、MusicGen 约 300 MB、Whisper 75 MB – 3.1 GB、u2net 约 168 MB。缺什么装什么Kokoro →pip install kokoro-onnx soundfileMusicGen →pip install transformers torch soundfile numpyLyria →pip install google-genai非英语语音 → 系统级espeak-ng。失败统一入口npx hyperframes doctor会一次性报告凭据与本地依赖的完整状态。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HyperFrames 音频管线凭据解析与模型缓存完全指南
HyperFrames 音频管线凭据解析与模型缓存完全指南【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/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 的音频能力并非单一实现而是按可获得的凭据自动降级的多层栈云端 TTSHeyGen主→ ElevenLabs备本地 TTS 兜底Kokoro无密钥始终可用云端 BGMLyria备本地 BGM 兜底MusicGen无密钥始终可用同一台机器上可能同时存在多种凭据而第一个非空first match wins的凭据决定实际引擎。因此排查为什么我的配音用的是另一个声音/为什么没走 HeyGen这类问题时第一件事永远是查看当前生效的凭据组合。运行以下命令查看当前已配置的凭据以及工作流将使用的引擎对应技能文档中的Preflight预检步骤npx hyperframes auth status二、凭据与密钥解析优先级first match wins下表完整列出各提供方的解析顺序第一个非空值胜出Provider解析顺序第一个非空生效使用时的本地依赖HeyGenTTS BGM/SFX 检索$HEYGEN_API_KEY→$HYPERFRAMES_API_KEY→~/.heygen/credentials与 heygen-cli 共享$HEYGEN_CONFIG_DIR覆盖目录由hyperframes auth login写入无REST 调用ElevenLabsTTS 备用$ELEVENLABS_API_KEYpip install elevenlabsLyriaBGM 备用$GEMINI_API_KEY→$GOOGLE_API_KEYpip install google-genaiKokoroTTS无需密钥始终可用——最终语音兜底pip install kokoro-onnx soundfileMusicGenBGM无需密钥始终可用——最终音乐兜底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 中给出了语音的实际选择顺序HeyGenStarfish 引擎含词级时间戳→ ElevenLabs → Kokoro 本地兜底与上表完全对应。推荐做法一次 OAuth 登录全项目生效hyperframes auth login浏览器 OAuth是推荐配置一次登录即可覆盖所有项目无需为每个仓库维护.env文件。凭据如何随请求发送源码级验证在 packages/cli/src/auth/client.ts 中可以看到两个关键头常量的定义HEYGEN_CLI_SOURCE_HEADER X-HeyGen-Source取值cliHEYGEN_CLIENT_SOURCE_HEADER X-HeyGen-Client-Source取值hyperframesbuildAuthHeaders()见 packages/cli/src/auth/client.ts展示了两种凭据的发送差异OAuth 登录→Authorization: Bearer token并携带X-HeyGen-Source: cliAPI 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 将完全本地运行语音 → Kokoronpx hyperframes tts默认即本地 Kokoro背景乐 → MusicGen 或 Lyrianpx hyperframes auth status与npx hyperframes doctor都会报告这些本地依赖是否已安装方便你在预检阶段就发现环境缺口。技能文档 skills/media-use/audio/references/bgm.md 还强调了一个重要约定没有凭据不等于可以静默使用本地生成。按 Preflight 流程应运行npx hyperframes auth status、建议用户登录然后停下来等待用户选择登录使用 HeyGen 音色库或离线继续本地生成。四、模型缓存与系统依赖清单每个命令在首次运行时下载自身所需模型并缓存在~/.cache/hyperframes/下。各模型的具体情况如下能力模型/依赖缓存位置体积与说明TTSHeyGen无本地模型—需要 HeyGen 凭据 PATH 上的ffmpeg将 mp3 响应转码为.wavTTSElevenLabs无本地模型—与 HeyGen 相同API Key ffmpegTTSKokoroKokoro-82M~/.cache/hyperframes/tts/约 311 MB 模型 约 27 MB 音色需 Python 3.8 与kokoro-onnx、soundfile非英语文本还需系统级espeak-ngBGMLyria无本地模型缓存—需$GEMINI_API_KEY或$GOOGLE_API_KEYpip install google-genaiBGMMusicGenfacebook/musicgen-small~/.cache/huggingface/约 300 MB首次运行下载需transformers torch soundfileTranscribe转写Whisper~/.cache/hyperframes/whisper/体积取决于所选模型75 MB – 3.1 GB首次使用时从 HuggingFace 下载Remove-background去背u2net_human_segONNX~/.cache/hyperframes/background-removal/models/约 168 MB峰值推理内存约 1.5 GBWhisper 的特殊性whisper.cpp 未内置转写能力的细节值得单独说明Whisper 模型本身从 HuggingFace 下载tiny75 MB 到large-v33.1 GB缓存在whisper/目录。whisper.cpp二进制并不捆绑分发CLI 先从 PATH 解析找不到时依次尝试 HomebrewmacOS安装或首次使用时通过 gitcmake 从源码构建。可用$HYPERFRAMES_WHISPER_PATH环境变量覆盖 whisper.cpp 的解析路径。关于 Whisper 模型选型与--language规则可参阅 skills/media-use/audio/references/transcribe.md务必显式传--model因为 CLI 默认的small.en会把非英语音频静默翻译成英语破坏原始语言。HeyGen 凭据在模型层同样生效TTSHeyGen的凭据解析与 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.tsHTTP 客户端、请求头构造、401 时的 OAuth 刷新重试逻辑packages/cli/src/auth/resolver.ts同目录凭据解析顺序的核心实现对应上表first match winspackages/cli/src/commands/auth/login.ts、packages/cli/src/commands/auth/status.ts、packages/cli/src/commands/auth/refresh.tsauth login / status / refresh三个命令的落地实现packages/cli/src/auth/store.ts~/.heygen/credentials的读写与$HEYGEN_CONFIG_DIR覆盖逻辑。七、速查清单先看状态npx hyperframes auth status—— 决定本次工作流走云还是本地。推荐登录npx hyperframes auth login浏览器 OAuth一次登录、全项目生效可消费 HeyGen Web 套餐 10 分钟/月免费 TTS 额度。凭据顺序HeyGen 为$HEYGEN_API_KEY→$HYPERFRAMES_API_KEY→~/.heygen/credentialsElevenLabs 仅环境变量Lyria 为 Gemini/Google 两个环境变量。模型首次下载全部落在~/.cache/hyperframes/MusicGen 在~/.cache/huggingface/Kokoro 约 338 MB、MusicGen 约 300 MB、Whisper 75 MB – 3.1 GB、u2net 约 168 MB。缺什么装什么Kokoro →pip install kokoro-onnx soundfileMusicGen →pip install transformers torch soundfile numpyLyria →pip install google-genai非英语语音 → 系统级espeak-ng。失败统一入口npx hyperframes doctor会一次性报告凭据与本地依赖的完整状态。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考