转录与字幕

用户丢来一个链接或一个文件，说「加个字幕」。他要的成品是一个可编辑视频：素材在时间线上，转写润色过，需要时有译文，字幕层放在画面上；之后他能在编辑器里改一个字、挪一条字幕、换一种语言，要文件时再从视频导出。不要只交一个下载下来再改过的字幕文件：那样他改不了，也放不回视频上。

最容易做坏的样子：步骤顺序乱了。先翻译再润色，译文全过期；要双语时先建了原文字幕层再润色，原文层按润色前的标点切条，和译文层对不上；跨回合接着做时从头来一遍，用户等了两次。所以全程按这个顺序：确认 → 建视频并导入 → 转写 → 润色（含说话人实名） → 章节（旁路） → 翻译 → 建字幕层 → 导出 → 交付说明。只要原文字幕时，转写时建好的字幕层留着用：润色写回时它的文字跟着改（第 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，原文层等润色、翻译之后由第 7 步建：切条按润色后的标点，才和译文层对得上。
• 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 列出文字被手改过、没跟着改的句子，交付时告诉用户这几句要自己看。转写回来几乎没有句末标点（一长段用逗号连到底）、润色补了很多句末标点时，那层字幕条仍是按宽度和停顿切的：写回后先问用户，确认后删掉那层，按第 7 步重建。

5. 章节（旁路）

每次转写默认给视频分章，除非用户说不要，或 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 时素材还不在时间线上：先放上时间线再做。

6. 翻译

需要译文或双语时，按 translate-subtitles 的做法翻译。润色写回之后重新 documents_read 读转写，用那时的 translationBasis 翻译；已有同一语言的译文时在它上面更新，不新建第二份。

7. 建字幕层

用 captions_create 把字幕放到画面上，BaoCut 按句对齐时间、按宽度切成字幕条：

• 原文字幕：documentId 给转写文档。
• 译文字幕：documentId 给译文文档。
• 双语字幕：给译文文档并带 bilingual: true。

同一份文档每调用一次就多建一层，不覆盖。调用前先 videos_inspect 看这份文档是不是已经有字幕层：有了就不重复建（转写时建的原文层已经跟着润色改了字，照用；双语时 captions_create 也沿用它，不再建原文层）；用户要重做时先说明会多出一层，问清是否删掉旧的。回执给出 transactionId 和字幕条数，说给用户。

8. 导出

用户要文件时用 export，等 jobs_inspect 到 completed，把 outputs 里的 path 告诉用户：

• 双语字幕文件：kind subtitles，bilingual: true（主文档是转写，副文档是译文，每句一条）。
• 只要译文的字幕文件：kind subtitles，给 language；要求画面上已有这种语言的字幕层（第 7 步）。
• 原文字幕文件：kind subtitles，主文档是转写。
• 带字幕的成片：导出 mp4 或 webm，画面上的字幕层会画进去。

9. 要避免的

• 不要只交一个字幕文件，除非用户明确只要文件。
• 不要在润色前翻译；要译文或双语时，不要在润色前建原文字幕层。
• 润色写回后不要为了改字删掉字幕层重建：文字已经跟着改了。
• 不要因为自己觉得识别得不够好就重转；不要为了用上 hint 换模型。
• 不要在同一份文档上重复建字幕层；不要重建已经新建过的视频。
• 跨回合时不要从头来：先 videos_inspect 看做到哪了。
• 章节失败不要反复重试，也不要让它卡住后面的步骤。

10. 交付说明

写给用户看的，说清他拿到了什么、哪里要他自己看一眼：

• 视频在哪：名字与所在位置；是新建的还是用户原来的。
• 字幕层：建了哪几层（原文、译文、双语），各多少条；润色时没跟着改字的句子（keptCaptionCues）。
• 文件：导出的路径。
• 润色改了什么、统一了哪些术语；译文的目标语言与句数。
• 说话人：给谁实名了；哪些没有证据、仍是占位名。
• 章节：几章；用的是作者的章节还是自己分的；作者章节里没对上的条目（ambiguous、unanchored）；没做或失败时说明原因。
• 哪里拿不准：没改成的转写错误、不确定的译法、识别质量差的段落。