EdgeSpeak 卡拉 OK 是做什么的?
使用一次 EdgeSpeak 转录请求创建卡拉 OK 字幕。利用捆绑的零依赖 Node.js 脚本来实现确定性的 ASS 生成、实时帧样式预览和 FFmpeg 渲染。
让用户选择外观
收集源路径、输出位置,以及用户是否需要 ASS、硬字幕或两者都要。样式是用户能看到并可能提出异议的唯一决策,因此默认将其视为用户的选择:
- 明确指定:使用命名的预设或覆盖设置。可用的预设为
classic、minimal、boxed和high-contrast。 - 自动选择:仅在用户实际上将决定权交给您时使用——比如“你选吧”、“随便”、“尽快搞定”、“使用默认”。从下表中选择,然后继续执行,不要阻塞。
- 预览后再询问:当用户未明确说明样式偏好时,此为默认行为。在所有真实视频帧上渲染每种预设,使用运行时的图片查看功能显示 PNG,然后提出一个简洁的问题。终端可以列出路径和描述,但 ANSI 文本不是真实的视觉预览。
沉默不等于授权。从未提及样式的用户通常只是没见过选项,而非决定跳过它们。询问只会花费一次短对话;猜错则会导致整个视频重新渲染,而对于硬字幕来说,这是最耗时的路径。
对于双语输出,哪门语言放在上方是同样可见的选择——将其合并到那个单一问题中,而不是询问两次。
永远不要在渲染预览后不展示它们。 --preview-media 会在每次运行时渲染所有四种预设,因此一旦该命令完成,完整的比较结果就已存在于磁盘上。只打开一个 PNG、默默地挑选并仅报告胜出者,会隐藏用户本应看到的权衡。
对于自动模式——以及为伴随预览提供的推荐做铺垫——请检查代表性源帧并应用以下默认值:
| 素材类型 | 预设 |
|---|---|
| 常规风景或混合内容 | classic |
| 干净、大部分为深色背景 | minimal |
| 杂乱、明亮、幻灯片或屏幕录制 | boxed |
| 竖屏/移动设备或始终困难的背景 | high-contrast |
当源视频的亮度变化很大时——同一视频中既有暗场景又有亮场景——没有单个帧能确定选择。在两个对比鲜明的时间戳处渲染预览并进行比较,因为在一个亮帧上表现良好的预设可能在暗帧上变得不可见。
当前请求的指令优先。如果存在,也可选地读取 .edgespeak-skills/edgespeak-karaoke/EXTEND.md 中的偏好设置,然后是 ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md;项目偏好优先于用户偏好。有用的偏好包括预设、字体、字号、ASS 颜色、边距、输出格式和质量。
转录和对齐,仅一次
-
确认源文件存在,并使用
ffprobe检查其时长、尺寸和容器格式。 -
调用
edgespeak_transcribe_file一次:{ "path": "/绝对路径/源媒体文件", "timestamps": "word", "start_margin": 0, "end_margin": 0 }仅当用户请求不同的字幕长度时才添加
min_chars/max_chars。仅当用户指定模型时才添加model。如果位置很重要,请检查edgespeak_list_models,并且未经同意不要选择远程模型。 -
在成功的单词时间戳转录后,不要调用
edgespeak_align。此请求已运行 EdgeSpeak 的内联本地强制对齐路径,并返回segments[].words[]。 -
对于较长的 MCP 响应,使用
artifact_json_path。对于内联响应,将result对象保存为 JSON。转换器接受直接的转录 JSON 或带有result的包装对象。 -
要求每个有时间戳的片段中的单词时间戳非空。切勿发明单词时间戳或静默退回到片段时间戳。
仅当用户提供了外部最终转录文本或对 ASR 文本进行了实质性编辑时,才使用 edgespeak_align。对齐必须使用最终的单词序列;编辑后切勿保留陈旧的时间戳。
如果对齐无法放置文本,则属于错误,而非空结果:edgespeak_align 返回 isError: true,并附带 JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} 且没有单词(CLI 以非零退出,并在 stderr 中以 error: alignment_failed: 或 error: alignment_search_budget_exceeded: 开头的行中输出相同的代码和对象)。仅根据 alignment 对象做出决定:
alignment.retry_recommended: true→ 再调用一次edgespeak_align,并设置"search_effort": "extended"(CLI:--search-effort extended)。它会搜索更广的范围,运行更慢且使用更多内存;在告知用户时引用alignment.estimated_extra_bytes。- 否则,或在
alignment_search_budget_exceeded时,不要重试相同的调用。检查转录文本是否匹配此媒体,或者对齐一个更短的片段。有关代码和字段的完整列表,请参阅edgespeak-align。
永远不要从失败的对齐中构建卡拉 OK 提示:没有均匀间隔的单词,没有片段时间戳回退,也没有从编辑前的转录中沿用时间戳。
要求
- Node.js 18 或更新版本:用于捆绑的脚本。
- 使用
libass构建的 FFmpeg,以及ffprobe——一个独立的可执行文件,也必须位于 PATH 中。每个预览和每次烧录都通过ass过滤器,因此没有 libass 的 FFmpeg 会失败并显示No such filter: 'ass',无论选择哪个预设。烧录到 MP4/MOV/MKV/TS 还需要libx264;WebM 需要libvpx和libopus。Homebrew 和主流发行版软件包都包含所有这些。 - 用于转录的
edgespeak-cli(或 EdgeSpeak 应用),可在 macOS Apple Silicon、Linux x86_64 和 Windows x64 上运行。在 Windows 上,安装 EdgeSpeak 桌面应用,该应用附带 CLI。在 macOS 和 Linux 上,引导用户访问 https://edgespeak.com/docs/cli#install 下的自包含安装程序(无需桌面应用;在 Linux 上它会自动检测 NVIDIA GPU 并安装支持 CUDA 的运行时)。用户运行安装程序;您不要自己运行。前言的minCliVersion是此技能所针对的最早 CLI 版本——如果edgespeak-cli --version更旧,或者--help中缺少某个记录的标志,请运行edgespeak-cli update。
当运行因缺少依赖而失败时,报告哪个检查失败,而不是重试:
node --version # v18+
ffprobe -version # 必须与 ffmpeg 一起存在
ffmpeg -filters | grep -w ass # ASS 渲染器 (libass)
ffmpeg -encoders | grep -w libx264 # H.264 输出
生成 ASS 和预览
生成选定的预设:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /output/source.karaoke.ass \
--style classic \
--title "源标题"
为了提供选择,在每个预设上渲染实际源中的一个活跃提示。这是默认路径,不是特殊情况——并且它产生的每个 PNG 都旨在展示:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
-o /output/source.karaoke.ass \
--style classic \
--preview-media /path/to/source-video \
--preview-dir /output/source.karaoke-previews
当另一个帧更具代表性时,使用 --preview-at <秒>,并在源混合亮场景和暗场景时,使用不同的时间戳运行两次。使用 --list-styles 列出预设。使用 --font、--font-size、--margin-v、--primary、--secondary、--outline 和 --back 进行微调;ASS 颜色使用 &HAABBGGRR。该脚本保留 EdgeSpeak 片段边界,并仅将对齐的持续时间和间隙映射到 \kf / \k 标签。
单词之间的间距来自提示自身的 text,而不是每个单词一个空格。强制对齐将标点附加到其后面的单词上,因此每个 words[] 条目都是 text 的一个子字符串,并且它们的位置只会向前移动——生成器遍历 text 一次,并重用两个单词之间真正存在的任何内容。这就是保持 high-performance 连字符(对齐将其拆分为 high 和 performance,连字符不属于两者)以及保持 CJK 无空格而不是将 本地转录 渲染为 本 地 转 录 的原因。如果在 text 中找不到某个单词,生成器会回退到单个空格,而不是猜测。
双语卡拉 OK
当转录的每个片段都带有 translation 时——也就是 edgespeak-translate 所写入的内容——生成器会为每个提示发出两行,并且无需额外标志:
node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.zh.json \
-o /output/source.karaoke.ass --style boxed
两行都位于一个由 \N 分隔的 Dialogue 事件中,因此 ASS 将它们作为一个共享边距的单个块堆叠。两个单独的事件将各自锚定到该边距并重叠。
--layout translation-top(默认)将翻译放在源文本之上;source-top则翻转,供以源语言阅读的观众使用。顶行以预设大小渲染,底行以 72% 的大小渲染,因此无论哪种方式,眼睛都会落在主要语言上。--layout source-only忽略翻译并生成单语言文件。- 只有源行会扫描。单词时间戳描述的是源音频,因此翻译不会获得
\k标签——它为整个提示持有一个纯填充。将提示持续时间分配给翻译的字符将是发明的时间戳;不要添加。对于真正的目标语言单词时间戳,请使用语音合成技能(如果已安装)朗读翻译,然后对齐该音频。
字体不是可选的——在任何一行上
libass 不会像浏览器那样按字形替换字体。拉丁风格字体中的 CJK 文本会渲染为空白方框——静默地,一直贯穿到烧录。每个预设都附带一个拉丁字体,因此生成器会根据脚本选择字体,而不是继承预设的字体。这同样适用于源行,而不仅仅是翻译:中文转录如果没有 --font,则会渲染为一排方框。
- 脚本会根据行本身的文本自动检测,并通过
fc-match :lang=<标签>进行匹配,使用单个 ASCII 字体系列别名(别名列表会破坏逗号分隔的 ASS 样式行)。 --font <名称>(源)和--translation-font <名称>(翻译)会覆盖它,并且当fc-list表示该字体系列不声称支持检测到的语言时,会被拒绝。不要通过选择另一种拉丁字体来绕开错误——检查fc-list :lang=zh-cn family中覆盖该脚本的字体。- 拉丁文本保持预设字体不变;只有在预设不覆盖脚本时才会进行替换。
- 没有 fontconfig 时,自动选择会大声失败;请显式传递字体。当无法检查覆盖率时,运行会报告
source_font_verified: false/translation_font_verified: false,因此报告该说明,而不是声称字体没问题。 - 只要源不是拉丁文,运行会报告
source_font/source_script。
部分翻译的转录文本会被直接拒绝——这意味着翻译步骤提前停止,而为剩余部分发出仅源文本的提示会传递一个不完整的文件,并声称已完成。
烧录硬字幕
当源文件包含视频并且用户想要硬字幕时:
node <skill-dir>/scripts/render-hardsub.mjs \
/path/to/source-video \
/output/source.karaoke.ass
默认的 --format source 会在实际可行时保留源容器:
- MP4/M4V/MOV -> 相同的扩展名,使用 H.264/AAC。
- MKV -> MKV,使用 H.264 和复制的音频。
- WebM -> WebM,使用 VP9/Opus。
- TS/M2TS -> 相同的扩展名,使用 H.264/AAC。
- 不支持/有歧义的源扩展名 -> MKV 回退,报告为
container_fallback: true。
硬字幕始终需要视频重新编码;保留容器并不意味着复制源视频编解码器。仅当用户请求不同的交付格式时,才使用 --format mp4|mov|mkv|webm 或明确的 -o。仅在获得授权时使用 --overwrite。
匹配源比特率
以固定质量重新编码会忽略源文件的传输比特率,并且差距可能很大:将 CRF 21 烧录到精简的 1.5 Mbps AV1 文件中,会生成 4.2 Mbps 的 H.264 副本——源比特率的 2.8 倍,文件大小接近 3 倍,且没有视觉增益。因此,脚本会探测源文件,并根据其比特率推导出 -maxrate / -bufsize 上限,按输出编解码器的效率更低程度进行缩放(H.264 需要大约 AV1 的 1.6 倍比特率才能达到相当的质量)。质量仍然来自 CRF;上限只阻止其超过源比特率。
这对于 x264 目标是自动的。VP9/WebM 保持不变,因为 .webm 配置对恒定质量模式使用 -b:v 0。报告包括 source_video_bitrate、video_bitrate 和 bitrate_cap 决定——报告结果时比较前两个。
仅当用户要求特定的比特率或质量级别时才覆盖:
--crf <n>设置质量目标(越低越好,H.264 默认为 21)。--maxrate <速率>替换派生上限,例如--maxrate 4M。--maxrate none完全禁用上限并恢复为纯 CRF 行为。
比特率也是控制文件大小的杠杆。当用户对输出大小有异议时,在提出更改之前,同时引用源比特率和输出比特率,并记住平面插图或屏幕录制的素材压缩效果远好于真人动作——字幕文本本身即使在 CRF 28 下也能保持清晰,因此它从来不是限制因素。
CLI 回退
每当 MCP 无法完成工作时——包括 MCP 服务器本身已启动但其工具失败时——回退到 edgespeak-cli。最常见的情况是:桌面应用未运行,因此每个 EdgeSpeak MCP 工具都返回 runtime_error: could not reach gateway。这不是安装损坏,也不是需要重试的问题;长时间运行的 MCP 服务器故意从不启动自己的引擎(常驻服务器保留
…
[截断以进行翻译]