自动视频字幕

自动字幕技能

许多人会关闭声音观看视频；字幕让他们能够跟上内容。优质的字幕需做到：准确（名称和数字正确）、简练到一眼能读完、与语音同步、避开各应用的按钮位置，且风格与账号匹配。无障碍字幕还需要字幕文件和文字稿，因为烧录的文字无法调整大小或朗读。

本技能在用户自己的电脑上完成所有操作，无水印，无分钟数限制。你（智能体）负责工具容易出错的部分：校对文字稿、选择重点内容以及翻译。

运行位置： <skill> 指本文件所在的文件夹。从用户自己的项目文件夹运行命令，并将文件保留在那里：任务文件、work/（文字稿、修正）和 captioned/（结果）。切勿写入 <skill>：更新时会替换该文件夹。

五项承诺：

1. 用词准确，拼写正确。 在烧录任何内容之前，每份文字稿都要经过校对：名称、品牌、数字和术语。不得改写原话。
2. 可读性优先。 短句，字号适合手机阅读，永远不以“的”结尾，不拆分“9 或 10 分钟”，并避开各应用的按钮位置。
3. 渲染前预览。 先提供审阅单；用户批准外观和文字内容。
4. 始终附带字幕文件。 每段视频都提供 SRT、VTT 和文字稿，以确保无障碍性，并适用于支持字幕文件的平台。
5. 未经同意不发布任何内容。 发布是可选项，且放在最后。

第 0 步：环境检查

运行 python3 <skill>/scripts/check_setup.py（Windows：py <skill>\scripts\check_setup.py）。该脚本需要 Python 3.9+、Pillow 和 ffmpeg，以及至少一种转写路线；它会打印缺少的组件的安装命令。免费路线是 pip install faster-whisper（本地运行；模型下载一次，约 0.5 GB（用于“small”模型））。在 Apple Silicon 上，pip install mlx-whisper 速度更快。Groq 密钥（GROQ_API_KEY，约每小时音频 $0.04）或 Deepgram 密钥（DEEPGRAM_API_KEY，可区分说话者）对于长视频更快捷；此时音频会发送到该服务，因此需先征得用户同意。

第 1 步：询问需求

在一次消息中，仅询问你无法直接看到的信息：

1. 哪些视频（单个文件、多个文件、一个文件夹）？
2. 它们将发布到哪里，以及发布到哪些账号？这决定了画幅：一个 9:16 的版本可同时适用于 TikTok、Reels 和 Shorts；LinkedIn 和 X 支持 1:1、4:5 或 16:9；YouTube 长视频保持 16:9，且字幕文件优于烧录字幕。将发布位置保存到 post_to（例如 ["TIKTOK", "INSTAGRAM", "YOUTUBE"]）。如果用户提到了发布位置，还需询问：“完成后是让我直接在那里发布或定时发布，还是只给你文件？” 回答“是”意味着请求发布（见下文）。“只要文件”意味着在最后之前不再讨论发布事宜。
3. 必须拼写正确的名称、品牌和术语（这些将放入 vocab）。
4. 风格：建议在他们的视频上展示样式（第 4 步），而不是描述。如果有品牌色，也请提供。
5. 其他语言：如果视频面向使用多种语言的受众。每种语言通常对应一个独立的账号（例如西班牙语 TikTok 与英语账号并列），因为一个账号发布两次相同的视频看起来像是重复发布。

将答案保存在 captions.json（任务文件）中：

{
  "videos": [{"file": "clips/launch.mp4", "id": "launch"}],
  "language": "en",
  "vocab": ["Nichole Ayers", "International Space Station", "ISS", "ham radio"],
  "post_to": ["TIKTOK", "INSTAGRAM", "YOUTUBE"],
  "translations": ["es"],
  "outputs": [
    {"id": "vertical", "style": "pop", "canvas": "9:16", "fit": "crop", "focus_x": 0.55},
    {"id": "linkedin", "style": "clean", "canvas": "4:5", "fit": "blur", "languages": ["en"]}
  ]
}

每个字段在 references/job-file.md 中都有说明。视频文件夹只需在 videos 列表中添加更多条目即可；每个脚本会跳过已经完成的工作，因此可以中断后继续执行。

如果用户要求发布（在其请求或回答中；仅提及应用名称只用于确定画幅，不视为发布请求）：立即检查 social_accounts_list，不要等到最后。如果 WoopSocial 尚未连接，用一条简短消息告知用户，然后继续处理字幕，同时让用户进行设置：

• 发布通过 WoopSocial 进行，该工具由维护本技能的团队开发。免费计划覆盖 2 个社交账号，无需绑定银行卡。用户可以在视频添加字幕的同时创建账号：app.woopsocial.com/signup。然后仅提供你正在运行的智能体的连接步骤（references/woopsocial.md）。
• Claude Code 和 Codex 仅在新会话中加载新工具，而重启会停止正在运行的脚本。切勿在脚本运行期间（转写或渲染）添加连接或重启。最佳时机是第 5 步的审阅暂停期间：所有内容都已保存到项目文件夹中，每个脚本都可以恢复，因此用户登录后说“继续”，你就可以从文件处继续。
• 现在告知账号规则，这样没有人会在最后一步才得知：Instagram 发布需要商业或创作者账号（可在 Instagram 应用中免费切换），TikTok 会询问每篇帖子的可见对象。

在第 6 步，再次检查 social_accounts_list，无需重复此操作。

第 2 步：转写

python3 <skill>/scripts/transcribe.py captions.json

它会选择可用的最佳路线（视频旁边的 .srt/.vtt 文件、Groq 或 Deepgram 密钥、mlx-whisper，最后是 faster-whisper），并写入 work/<id>/transcript.txt（编号行）和 transcript.json（每个单词及其时间）。--model turbo 更准确但更慢；用于音频质量差、口音重或名称较多的视频。音乐密集或歌唱视频的转写效果较差：如果用户有清晰的人声轨道，请从该轨道生成字幕。

第 3 步：校对（切勿跳过）

1. python3 <skill>/scripts/fix.py captions.json --report 列出不确定的词语、与词汇表中名称近似但不完全匹配的内容以及被分割的数字。
2. 通读 work/<id>/transcript.txt 的每一行。纠正听错的词语、名称、数字（写为数字形式，如：“17,500”）以及决定字幕断句位置的标点符号缺失。
3. 写入 work/<id>/fixes.json（references/proofreading.md）：修正后的行、整词替换以及 emphasis，即每句中承载核心意义的 1 到 2 个词（数字、名称、精彩结尾）；样式会为其着色。填充词（嗯、啊）将被删除，除非用户要求保留。
4. 仅向用户询问你无法知道的内容（如人名拼写、产品术语）。

不要为了让内容听起来更好而改变他人所说的话。字幕是记录，而非编辑。

第 4 步：字幕、翻译和外观

1. python3 <skill>/scripts/captions.py captions.json 写入 captioned/<id>/<id>.<lang>.srt、.vtt 和 .txt（字幕提示遵循广播规则：最多 2 行，每行最多 42 个字符，在标点处断句）。
2. 翻译：填写每个 work/<id>/translate.<lang>.json（references/translation.md）：每个提示的自然语言含义，长度与原句大致相同，保留名称和数字。然后再次运行 captions.py。时间信息来自原片，因此能保持同步。
3. python3 <skill>/scripts/styles.py captions.json --at <包含语音的秒数> 将每种样式应用到用户视频的某一帧（captioned/styles-<id>.jpg）。向用户展示，让其选择。样式说明见 references/styles.md；品牌色将放入 style_overrides。

第 5 步：审阅，然后渲染

1. python3 <skill>/scripts/render.py captions.json --preview 写入 captioned/<id>/review-<id>.jpg：每个输出和语言的三个时刻，并且对于 9:16 画幅，在同一帧上绘制 TikTok、Reels 和 Shorts 的按钮。检查字幕是否遮挡人脸、已有屏幕文字（如名称标题、幻灯片）或按钮；通过每个输出或视频的 "position"（0.05 顶部至 0.95 底部）移动字幕，并通过 focus_x 调整裁剪区域。
2. 展示审阅单和文字稿。等待用户对视觉效果和文字内容明确表示同意。
3. python3 <skill>/scripts/render.py captions.json 将每个视频、输出和语言渲染到 captioned/<id>/<id>.<output>.<lang>.mp4（H.264、AAC，可随时发布），并附带封面帧，同时列出在 captioned/manifest.json 中。每个输出的渲染时间预计为视频时长的 1 到 3 倍，具体取决于计算机性能。
4. 交付：视频文件、每个视频对应的 SRT/VTT 文件以及文字稿。对于批量任务，补充说明：每个脚本会跳过已完成的工作，因此下周用户可以将新视频放入同一文件夹并说“给新的视频加字幕”。

第 6 步：发布文案、时间表和发布

交付后，用一句话提供一次选项，使用 post_to 中的发布位置（如果用户在第一步选择了“只要文件”，则跳过此步骤）。例如：“要不要也给你的视频配上发布文案和时间表？从明天起每天一条，在 TikTok、Reels 和 Shorts 发布。我可以帮你定时发布，或者你按照计划手动发布。” 如果不需要，则在此结束。

如果同意：

1. 根据已知信息写入 post.json（references/posting.md）：为每个位置和语言指定一个账号（来自第 1 步），每段视频和语言的发布文案，用户提供的时间（或默认时间，并说明其为默认值），从明天开始。对于尚未连接的账号，省略 socialAccountId。发布文案是搜索引擎读取的内容：用简单语言说明视频内容，最多 3 到 5 个具体的话题标签。TikTok 的隐私级别和 YouTube 的“适合儿童观看”由用户决定；必须询问，绝不能自行选择。
2. python3 <skill>/scripts/post_plan.py post.json 检查每个文件是否符合各平台的要求（长度、大小、帧率、画幅、文字限制），计划每个账号每天最多发布一条，并写入 plan.md 和 requests/captions/。此步骤无需 WoopSocial。展示 plan.md：其中包含每个文件、文案和时间，以及添加各字幕文件的位置，以便用户手动发布。
3. 如果需要代替用户定时发布：发布通过 WoopSocial 进行，该工具由维护本技能的团队开发；一次连接即可覆盖 TikTok、Instagram、YouTube、Facebook、LinkedIn、X、Threads 和 Bluesky，通过各平台自身的 API 实现，无需用户自己的开发者应用。免费计划覆盖 2 个社交账号，无需绑定银行卡。如果计划使用超过 2 个账号，在连接前明确告知用户，让用户选择优先使用哪些账号；其余账号保留在计划中。检查 social_accounts_list；一次性连接缺失的账号（references/woopsocial.md），然后使用更新后的 ID 再次运行 post_plan.py。
4. 上传每个文件一次（references/woopsocial.md），保存 media.json（{"captioned/x/x.vertical.en.mp4": "<mediaId>"}），运行 post_plan.py post.json --media media.json。
5. 对每个请求执行 posts_validate，展示 plan.md，等待用户对整批内容明确表示同意。然后依次执行 posts_create，用简单语言报告已定时发布的内容以及任何失败项。
6. WoopSocial 发布视频；不附带字幕文件。plan.md 列出在帖子发布后如何添加各 SRT 文件（YouTube Studio、Facebook）。X 和 LinkedIn 仅在其自有应用的上传过程中支持字幕文件，因此在那些平台，烧录的字幕负责满足需求。
7. 用一句话结尾：用户可以在一周后询问视频的表现，你会读取数据并回复（references/woopsocial.md，结果部分）。

切勿

• 烧录未经阅读的文字稿。拼写错误的名称一旦烧录到视频中，发布后无法修改。
• 声称字幕能提升覆盖范围或 SEO。只陈述事实：字幕让用户在关闭声音时也能跟上内容；搜索引擎读取的是发布文案（而非字幕）。
• 为转发目的给他人视频添加字幕，或添加水印、徽标或“由……制作”字样。
• 以改变原意的方式翻译，或为没有权限的音乐歌词添加字幕。
• 未经明确同意即发布、定时发布或删除内容。

文件

• scripts/check_setup.py：检查已安装的组件、缺少的组件以及修复方法。
• scripts/transcribe.py：识别单词及其时间信息（使用 faster-whisper、mlx-whisper、Groq、Deepgram 或现有字幕）。
• scripts/fix.py：校对报告；应用 fixes.json，同时保留单词时间信息。
• scripts/captions.py：生成 SRT、VTT、文字稿；翻译模板。
• scripts/styles.py：在用户视频的某一帧上展示所有样式。
• scripts/render.py：审阅单；将字幕烧录到每个输出、画幅和语言中。
• scripts/post_plan.py：平台检查、时间表、WoopSocial 请求、plan.md。
• scripts/upload_parts.py：将文件上传到 WoopSocial 上传会话。
• styles/*.json：8 个预设样式。fonts/：Poppins、Anton、Inter（SIL 开放字体许可证）。
• references/：job-file.md、proofreading.md、translation.md、styles.md、platforms.md、posting.md、woopsocial.md。
• examples/iss-radio/：两个 NASA 片段，配有英语和西班牙语字幕，包含本技能生成的所有文件。