卡拉OK字幕 是做什么的?
流程:视频 → 16 kHz音频 → DashScope ASR带单词时间戳 → LLM选择术语并编写中文注释 → ASS卡拉OK字幕 → ffmpeg和libass烧录。
所有工作通过一个非交互式CLI scripts/pipeline.py 完成。此文件中的路径相对于技能目录。从任意目录运行命令,前面加上技能路径,例如 python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor。
首次运行前
- 运行
python3 scripts/pipeline.py doctor。退出码0表示就绪。当密钥已设置时,会发起一次免费请求检查DASHSCOPE_BASE是否与密钥所在区域匹配。不会上传或计费。添加--offline可跳过该请求。 - 如果退出码为3,运行
bash scripts/install.sh并修复它打印的每个FAIL行。如果脚本提示sudo需要密码,或API密钥缺失,请停止并询问用户。切勿要求用户将密钥粘贴到聊天中;请让他们将密钥放入.env文件(参见.env.example)。 - 设置详情和配置项:
references/prerequisites.md。
与用户确认
- 视频:本地文件或URL。用户必须拥有处理该视频的权限。
- 注释:开启(默认)或关闭(
--no-annotate)。 - 结果输出位置:默认返回输出文件路径。
除非用户要求更改,否则保持视觉风格不变。样式值:references/ass-style.md。
运行
一条命令执行所有步骤并在中断后恢复:
python3 scripts/pipeline.py all "<url-or-file>" --work ./job [--no-annotate]
或者逐步运行各个步骤。每个步骤在作业目录中写入固定文件名,并跳过已存在输出的工作。添加 --force 可重做某一步骤。每个子命令都有 --help。
| 步骤 | 写入文件 | 付费API |
|---|---|---|
fetch <url-or-file> | src.mp4 | 否 |
transcribe [--audio-url URL] | audio.mp3, asr_task.json, transcription.json | 是 |
annotate | annotations.json | 是 |
ass [--no-pop] [--no-annotate] | subs.ass | 否 |
render [--segment 1200] [--out FILE] | karaoke.mp4 | 否 |
ASR API从URL读取音频。默认情况下,transcribe 将 job/audio.mp3 上传到DashScope的免费临时存储。该存储保留文件48小时,仅此账户的ASR模型可读取。无需存储桶或额外设置。如果用户希望使用自己的存储,可以在 .env 中设置 AUDIO_URL_CMD 来上传文件并打印URL,或者传递 --audio-url URL。
进度输出到stderr。每个步骤在stdout上打印其输出路径。
退出码
| 退出码 | 含义 | 处理方式 |
|---|---|---|
| 0 | 完成 | 继续。 |
| 2 | 用法错误 | 阅读子命令的 --help。 |
| 3 | 环境未就绪 | 按照 next: 行操作,或运行 doctor。请用户提供密钥或sudo,或修正区域设置。 |
| 4 | 远程服务失败 | 按照 next: 行操作。重新运行相同命令会保留已完成的工作。 |
| 5 | 上一步骤的输入缺失 | 运行 next: 行中指定的步骤。 |
| 1 | 意外失败 | 阅读错误信息上方的工具输出。 |
长时间作业
转写和渲染可能耗时超过shell工具允许的范围。将命令放入后台并记录日志,例如 nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &,然后读取日志直至结束。如果进程终止,重新运行相同命令。转写会恢复已保存的ASR任务,避免重复付费;渲染会重用已完成的片段。
交付前检查
从输出视频的中间提取一帧(ffmpeg -ss <seconds> -i job/karaoke.mp4 -frames:v 1 check.jpg),如果您能查看图片则检查该帧。如果源视频已包含烧录的硬字幕,请告知用户并提供两个选项:用模糊带覆盖它们,或将新字幕移至顶部。
规则
- 切勿打印、记录或提交
DASHSCOPE_API_KEY。doctor仅报告它是否已设置。 transcribe和annotate会消耗用户账户的费用。除非用户同意,否则不要对它们使用--force。- 注释仅限简体中文。对于不懂中文的观众,请使用
--no-annotate。 - ASR可能听错名称和术语,且可能返回小写文本。请告知用户在分享视频前审阅字幕。