JimLiu/baocut / skills/baocut/built-in-skills/subtitle-workflow
subtitle-workflow
Verified用户给了视频链接或本机音视频,要转录、加字幕、做译文字幕或双语字幕时用:建可编辑视频并导入,转写、润色、给说话人实名,需要时翻译,把字幕层放到画面上,再按需导出字幕文件或成片。有媒体时「转录」「加字幕」「翻译成某种语言」都按这个流程。不用于与视频无关的文字翻译。
转录与字幕
用户丢来一个链接或一个文件,说「加个字幕」。他要的成品是一个可编辑视频:素材在时间线上,转写润色过,需要时有译文,字幕层放在画面上;之后他能在编辑器里改一个字、挪一条字幕、换一种语言,要文件时再从视频导出。不要只交一个下载下来再改过的字幕文件:那样他改不了,也放不回视频上。
最容易做坏的样子:步骤顺序乱了,或者漏了一步。先翻译再润色,译文全过期;要双语时先建了原文字幕层再润色,原文层按润色前的标点切条,和译文层对不上;长转写只润色几处就往下走,说话人还是「Speaker 1」,标题和简介里明明写着是谁;跨回合接着做时从头来一遍,用户等了两次。所以全程按这个顺序:确认 → 建视频并导入 → 转写 → 润色 → 说话人实名 → 章节(旁路) → 翻译 → 建字幕层 → 导出 → 交付说明。只要原文字幕时,转写时建好的字幕层留着用:润色写回时它的文字跟着改(第 3 步)。每一步等工具的回执或任务完成再走下一步;跨回合接着做时,先 videos_inspect 看已经做到哪一步,从那里接着做,不重复已完成的步骤。
1. 先确认
动手前把这几件事弄清楚,弄不清的问一次,不要边做边猜:
- 交付物:原文字幕、译文字幕还是双语字幕;要不要文件(字幕文件、带字幕的成片)。用户说「翻译成某种语言」是要译文字幕,说「双语」是双语字幕;只说转录、加字幕时是原文字幕。
- 目标语言:用 BCP 47 标签(如
zh-Hans、en、ja、es)。要翻译、用户又没说译成什么时问一次。 - 原文语言、人名与术语:用户说了就记下。语言给转写;人名与术语在转写模型收识别提示时给转写当 hint(见第 3 步),不收时只在润色时用。没说语言的让转写自动识别。
- 来源元数据:从链接导入的素材,videos_inspect 的
assets[].source有标题、发布者、简介(description,最多 1200 字符)与作者的章节(chapters);转写或下载完成时pipeline.summary.description与pipeline.summary.sourceChapters也给出简介和作者章节的条数。润色、说话人实名、章节都用它。 - 在哪个视频上做:编辑器里打开的或用户点名的视频就在它上面做;videos_inspect 看已有的素材、转写、译文与字幕层,已有的接着用。
- 用户明确只要一个字幕文件、不要视频或项目时,不走这个流程,按
translate-subtitles的文件一节做(只转录不翻译时就交下载目录里的文稿)。
2. 建视频并导入
- 链接:transcribe 给
url(可给 language、hint、name、noCaptions),它新建视频、下载导入、放上时间线、转写并建字幕层;用户说了原文语言时带上 language,给了人名术语、而转写模型收提示时带上 hint(见第 3 步)。download 给newVideo: true与transcribe: true也新建视频并转写,但只用默认设置、不建字幕层。jobs_inspect 等到 completed:pipeline.summary.videoId是新视频,pipeline.summary.assetId是素材。新建的视频在之后的步骤失败时保留,不要再建一次。 - 本机文件:transcribe 给
file(可给 language、hint、name),它新建视频、导入、放上时间线并转写;第 3 步的转写就在这一步里。只要建视频不要转写时,videos_create 新建视频(名字取文件名;竖屏素材给竖屏的宽高),用 assets_import 导入并放上时间线(给 place)。 - 链接下载失败时照 error.details.remedy 告诉用户怎么补救,不要用别的方式下载。
3. 转写
- 第 2 步用 transcribe 或带了
transcribe: true的 download 时已经在转;已有视频要转写、或要带 language、hint 时用 transcribe 给 video(可给 asset;先 models_capabilities 看有没有可用的转写服务)。 - 字幕层建不建:只要原文字幕时不加 noCaptions,转完字幕就在画面上;第 4 步润色写回时 Runtime 在同一笔里把这层的文字跟着改,时间与切条不动,不用删掉重建。要译文或双语字幕时加
noCaptions: true,原文层等润色、翻译之后由第 8 步建:切条按润色后的标点,才和译文层对得上。 - hint 看模型:带 hint 之前先在 models_capabilities 里看要用的转写模型(不给 model 时是默认的那只)的
acceptsHint。默认的 MOSS 不收提示:带了也照常转写,但提示被忽略,转写任务带hint-ignored提醒。这时不带 hint,人名与术语留到第 4 步润色,也不为了用上 hint 换到收提示的模型。 - 转一次就用它:不因为自己觉得识别得不够好就换模型或重转(transcribe 的
target: replace)。少量错字、人名与术语听错是正常的,第 4 步润色会改。只有用户要求换模型或重转,或者结果不能用(空的、语言认错、大段乱码)时,才重转。结果不能用时不用先问,直接重转一次,语言认错就带上正确的 language(不带时自动识别多半再认错);然后告诉用户第一次的结果哪里不能用、重转改了什么、重转后的结果怎样,仍不能用时停下来问用户。重转一次是几分钟,用户在等。 - jobs_inspect 等到 completed:
pipeline.summary.documentId是新转写(transcribe 给 url 或 download 带transcribe: true时同样在pipeline.summary.documentId)。 - 返回 CAPABILITY_NOT_CONFIGURED 时照它的 next 告诉用户要启用哪项服务,停在这里。
4. 润色
按 polish-transcript 的做法润色转写,写回同一份转写。默认只改错字、术语与标点,一词对一词,词的时间不动;用户说不要润色时跳过。润色必须在翻译之前:它会改分句。
按它的做法,来源元数据当背景参考用(人名、术语的准确写法只在说话人明显在说它时才照改,不往文稿里加东西)。
画面上已有这份转写的原文字幕层时,写回的回执里 syncedCaptions 是跟着改了字的字幕文档数;keptCaptionCues 列出文字被手改过、没跟着改的句子,交付时告诉用户这几句要自己看。转写回来几乎没有句末标点(一长段用逗号连到底)、润色补了很多句末标点时,那层字幕条仍是按宽度和停顿切的:写回后先问用户,确认后删掉那层,按第 8 步重建。
5. 说话人实名
转写的 speakers[] 里还有占位名(「说话人 1」「Speaker 1」「SPEAKER_00」这类)时,润色之后、翻译与建字幕层之前给他们换上真名,按 polish-transcript 第 7 节的做法。这一步不挂在润色上:用户说不要润色、只改了几处、长转写只润色了一部分,都照样做;它只要证据所在的几段,不用读完全文。转写或下载完成的 next 会说分出了几位说话人。
- 证据:素材的
assets[].source(标题、发布者、简介);转写开头一段;每位说话人第一次开口前后的几句(自我介绍、被介绍、被点名、点名后紧接着的回答)。简介列了几位嘉宾时,还要在文稿里把名字对到声音上,不按顺序填。 - 一位说话人:标题或简介写明是谁在讲(演讲、讲座、单人节目),或说话人自我介绍了,也给这一位实名;说不清是谁就留着。
- 写回:有证据的名字用 edits_apply 的
renameSpeakers一笔写回,不先问用户(能撤销);拿不准的留着占位名。只改名字,译文不用重译。
6. 章节(旁路)
每次转写默认给视频分章,除非用户说不要,或 videos_inspect 看到视频已经有章节(不覆盖;用户要重分时按 video-chapters 先问清替换还是调整)。章节是旁路:不阻塞翻译、字幕层和导出;失败不致命,最多重试一次,仍不行就在交付说明里如实写原因,接着做后面的步骤。
- 有作者章节(
assets[].source.chapters不为空,或pipeline.summary.sourceChapters大于 0,或简介里有0:00 开场这类时间戳大纲):用 chapters_adopt 给 video,把作者的章节吸到文稿的段落或句子起点上并写进视频,不用自己分;chapters是空的、简介里却看得到时间戳大纲时,把那段大纲给outline。读回执的sourceChapters:matched、ambiguous、unanchored 各几条,交付时说明。带untitled的章节只有分界、标题是占位名(Untitled Chapter N),按转写起标题后用outline再调用,不写占位名。 - 没有作者章节(chapters_adopt 返回
NO_SOURCE_CHAPTERS也是这种情况,不算失败):按video-chapters的做法自己分。 - 用户要你自己写的章节,或要和作者大纲不同的粗细时,也按
video-chapters自己分,作者大纲当参考。 - 返回
ASSET_NOT_PLACED时素材还不在时间线上:先放上时间线再做。
7. 翻译
需要译文或双语时,按 translate-subtitles 的做法翻译。润色写回之后重新 documents_read 读转写(view 给 sentences,有 nextCursor 时读完所有页),用那时的 translationBasis 翻译;已有同一语言的译文时在它上面更新,不新建第二份。
8. 建字幕层
用 captions_create 把字幕放到画面上,BaoCut 按句对齐时间、按宽度切成字幕条:
- 原文字幕:documentId 给转写文档。
- 译文字幕:documentId 给译文文档。
- 双语字幕:给译文文档并带
bilingual: true。
用户要改位置、字色或念到的词的效果(不高亮、换色、KTV 扫色)时,建层时带 style,建好的用 edits_apply 的 setCaptionStyle 改,键见 BaoCut 的字幕页。
同一份文档每调用一次就多建一层,不覆盖。调用前先 videos_inspect 看这份文档是不是已经有字幕层:有了就不重复建(转写时建的原文层已经跟着润色改了字,照用;双语时 captions_create 也沿用它,不再建原文层);用户要重做时先说明会多出一层,问清是否删掉旧的。回执给出 transactionId 和字幕条数,说给用户。
9. 导出
用户要文件时用 export,等 jobs_inspect 到 completed,把 outputs 里的 path 告诉用户:
- 双语字幕文件:kind
subtitles,bilingual: true(主文档是转写,副文档是译文,每句一条)。 - 只要译文的字幕文件:kind
subtitles,给 language;要求画面上已有这种语言的字幕层(第 8 步)。 - 原文字幕文件:kind
subtitles,主文档是转写。 - 带字幕的成片:导出 mp4 或 webm,画面上的字幕层会画进去。
10. 要避免的
- 不要只交一个字幕文件,除非用户明确只要文件。
- 不要在润色前翻译;要译文或双语时,不要在润色前建原文字幕层。
- 润色写回后不要为了改字删掉字幕层重建:文字已经跟着改了。
- 不要因为自己觉得识别得不够好就重转;不要为了用上 hint 换模型。
- 不要在同一份文档上重复建字幕层;不要重建已经新建过的视频。
- 跨回合时不要从头来:先 videos_inspect 看做到哪了。
- 不要因为跳过或只做了一部分润色,就带着能认出的占位名交付。
- 章节失败不要反复重试,也不要让它卡住后面的步骤。
- 用户要的翻译或字幕层还没做时不要结束回合;结果读得不全(分页、被截断)就接着读,不是停下的理由。
11. 交付说明
写给用户看的,说清他拿到了什么、哪里要他自己看一眼:
- 视频在哪:名字与所在位置;是新建的还是用户原来的。
- 字幕层:建了哪几层(原文、译文、双语),各多少条;润色时没跟着改字的句子(
keptCaptionCues)。 - 文件:导出的路径。
- 润色改了什么、统一了哪些术语;译文的目标语言与句数。
- 说话人:给谁实名了、凭的什么证据(一句话);哪些没有证据、仍是占位名。
- 章节:几章;用的是作者的章节还是自己分的;作者章节里没对上的条目(ambiguous、unanchored);没做或失败时说明原因。
- 哪里拿不准:没改成的转写错误、不确定的译法、识别质量差的段落。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |