Communitygithub.com

lattifai/EdgeSpeak-Skills

通过一次EdgeSpeak转录请求,创建具有逐词高亮效果的卡拉OK ASS字幕,可选双语翻译第二行,并将其嵌入本地视频。在用户请求卡拉OK字幕、逐词高亮、ASS文件、双语/双语言字幕、字幕样式选择或预览,以及硬编码字幕视频时使用。

EdgeSpeak-Skills 是什么?

EdgeSpeak Karaoke 技能是一个强大的工具,专为需要精细控制字幕样式和生成高亮字幕(卡拉OK风格)的用户设计。它通过一次EdgeSpeak转录请求,利用内联词级强制对齐技术,直接生成包含逐词高亮动画的ASS字幕文件。该技能提供了多种预设样式(经典、简约、框式、高对比度),并通过在真实视频帧上渲染预览图让用户在最终渲染前直观选择,避免因样式错误导致昂贵的完整重渲染。对于需要双语输出的情况,它能自动处理源语言和翻译内容的布局,并智能处理字体覆盖(如CJK文字)以避免渲染乱码。支持将字幕硬编码到视频中,并智能匹配源视频码率以控制输出质量与文件大小。该技能适用于macOS Apple Silicon、Linux x86_64和Windows x64平台,依赖Node.js 18+、带libass的FFmpeg和edgespeak-cli,并通过MCP与CLI双模式提供灵活的运行方式。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/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": "/absolute/path/source-media",
      "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。对齐必须使用最终的词序列;编辑后切勿保留陈旧的时间戳。

要求

  • 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_

...(已截断以进行翻译)

相关技能