Communitygithub.com

EdgeSpeak 卡拉 OK

通过一次 EdgeSpeak 转录请求,创建带单词高亮效果的卡拉 OK ASS 字幕,可选附带翻译的第二行,并烧录到本地视频中。适用于用户需要卡拉 OK 字幕、逐词高亮、ASS 文件、双语字幕、字幕样式选择或预览,以及未提供最终参考文本的硬字幕视频。

EdgeSpeak 卡拉 OK 是什么?

EdgeSpeak Karaoke 是一个专为 AI 代理设计的技能,用于从 EdgeSpeak 的一次转录请求中生成具备逐词高亮效果的卡拉 OK ASS 字幕。它支持多种样式预设(如 classic、minimal、boxed、high-contrast),并可自动根据视频内容推荐最佳样式,或通过预览让用户自主选择。该技能还能处理双语字幕场景:当转录包含翻译文本时,会生成双行字幕,并且能智能检测脚本语言(如中文、日文)并自动匹配字体,防止渲染空白方框。它提供零依赖的 Node.js 脚本用于生成 ASS 字幕、制作实时帧预览,并通过 FFmpeg 将字幕烧录到视频中。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理平台,支持 macOS Apple Silicon、Linux x86_64 和 Windows x64。其核心工作流程包括:单次 EdgeSpeak 转录(带单词级时间戳)、使用 `karaoke-ass.mjs` 生成 ASS 字幕、通过 `render-hardsub.mjs` 烧录硬字幕。它还能智能处理源视频码率,防止重编码时文件大小过度膨胀。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak/tree/HEAD/skills/edgespeak-karaoke

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 颜色、边距、输出格式和质量。

转录和对齐,仅一次

  1. 确认源文件存在,并使用 ffprobe 检查其时长、尺寸和容器格式。

  2. 调用 edgespeak_transcribe_file 一次:

    {
      "path": "/绝对路径/源媒体文件",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    仅当用户请求不同的字幕长度时才添加 min_chars / max_chars。仅当用户指定模型时才添加 model。如果位置很重要,请检查 edgespeak_list_models,并且未经同意不要选择远程模型。

  3. 在成功的单词时间戳转录后,不要调用 edgespeak_align。此请求已运行 EdgeSpeak 的内联本地强制对齐路径,并返回 segments[].words[]。

  4. 对于较长的 MCP 响应,使用 artifact_json_path。对于内联响应,将 result 对象保存为 JSON。转换器接受直接的转录 JSON 或带有 result 的包装对象。

  5. 要求每个有时间戳的片段中的单词时间戳非空。切勿发明单词时间戳或静默退回到片段时间戳。

仅当用户提供了外部最终转录文本或对 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 服务器故意从不启动自己的引擎(常驻服务器保留

…

[截断以进行翻译]

相关技能