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": "/absolute/path/source-media", "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。对齐必须使用最终的词序列;编辑后切勿保留陈旧的时间戳。
要求
- 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上,安装包含CLI的EdgeSpeak桌面应用。在macOS和Linux上,使用curl -fsSL https://edgespeak.com/install.sh | sh(自包含,无需桌面应用;在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 "Source 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 <seconds>,并在源同时包含亮暗场景时以不同时间戳运行两次。使用 --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标签——它会在整个片段中保持纯色填充。将片段时长分布到翻译的字符上将是虚构的时间;不要添加。要获得真实的目标语言词级时间,请使用edgespeak-broadcast合成音频并对齐。
字体不是可选项——两行都是
libass 不会像浏览器那样按字形替换字体。拉丁风格字体中的CJK文本将渲染为空白方块——静默地,贯穿整个嵌入过程。每个预设都附带一种拉丁字体,因此生成器会根据文字系统选择字体,而不是继承预设的字体。这同样适用于源行,而不仅仅是翻译行:没有 --font 的中文转录文本将渲染成一排方块。
- 脚本根据行本身的文本检测,并通过
fc-match :lang=<tag>匹配,获取一个单一的ASCII系列别名(别名列表会破坏逗号分隔的ASS样式行)。 --font <name>(源行)和--translation-font <name>(翻译行)可覆盖此设置,当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 with H.264 and copied audio.
- WebM -> WebM with 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需要约1.6倍AV1的比特率才能达到可比质量)。质量仍由CRF决定;上限仅防止其超出源视频的比特率。
这对x264目标是自动的。VP9/WebM保持不变,因为 .webm 配置文件固定了 -b:v 0 以使用恒定质量模式。报告包含 source_video_bitrate、video_bitrate 和 bitrate_cap 决策——在报告结果时比较前两者。
仅在用户要求特定比特率或质量级别时覆盖:
--crf <n>设置质量目标(值越低越好,H.264默认值为21)。--maxrate <rate>替换派生的上限,例如--maxrate 4M。--maxrate none完全禁用上限,恢复纯CRF行为。
比特率也是控制文件大小的杠杆。当用户对输出大小有异议时,在提出更改前引用源比特率和输出比特率,并记住纯插图或屏幕录制画面比实景压缩效果更好——字幕文本即使在CRF 28下也很清晰,因此它从来不是限制因素。
CLI 回退
每当MCP无法完成工作时——包括当MCP服务器本身正在运行但其工具失败时——回退到 edgespeak-cli。最常见的情况是桌面应用未运行,因此每个EdgeSpeak MCP工具都返回 runtime_error: could not reach gateway。这不是安装损坏,也不是需要重试的问题;长期运行的MCP服务器有意不会启动自己的引擎(持有一个引擎的常驻服务器会与用户稍后打开的应用冲突)。CLI没有此限制——它自己启动设备上的引擎。因此,将来自任何EdgeSpeak MCP工具的 could not reach gateway 视为“现在使用CLI”,而不是需要报告的错误。
如果未找到 edgespeak-cli 命令,在Windows x64上安装EdgeSpeak桌面应用,或在macOS Apple Silicon和Linux x86_64上使用 curl -fsSL https://edgespeak.com/install.sh | sh(自包含,无需桌面应用;Linux上自动检测CUDA)。
edgespeak-cli transcribe /path/to/source-media -o /output/transcript.json \
--start-margin 0 --end-margin 0
CLI转录JSON已包含 segments[].words[]。不要对同一转录命令刚生成的文本运行 edgespeak-cli align。与捆绑脚本不同(它们在无 --overwrite 时拒绝替换现有输出),edgespeak-cli -o 会静默覆盖现有文件——如果转录路径已存在,请在覆盖前与用户确认或选择新路径。
验证与报告
- 为MCP和FFmpeg设置合理的实际时间预算;不要中断健康的静默处理过程。
- 保持
start_
...(已截断以进行翻译)