/speaker-labeling

name: speaker-labeling
description: 视频里有几个人说话、要区分是谁在说或给说话人标名字时用：没区分说话人的文稿按声纹重新转录并区分，再从文稿与来源信息里找证据给每位起真名，写回转写的 speakers。只改说话人，不改正文的字。只有一个人说话、或用户只要校对错字时不用。
version: 2.0.0

说话人标注

用户要的是：文稿里每句话前面是真名，字幕上看得出谁在说，导出的文稿和配音按人分开。这件事分两步：先分清有几个声音、每句归谁（区分），再给每个声音一个真名（标注）。区分靠语音模型，标注靠证据，两步都不靠猜。

最容易做坏的样子是猜：看到简介里列了两位嘉宾，就把「说话人 1」「说话人 2」按顺序填上去。猜错的名字会出现在每一条字幕和每个导出的文件里，用户往往要看到很后面才发现，比留着「说话人 1」糟得多。

1. 先看现状

用 videos_inspect 找到这个视频的转写（kind 为 speech 的文档；有几份时按来源素材对上用户说的那段），再 documents_read 读它：

• 正文的 `speakers[]` 列出每位说话人的 id 和 name，每个词带说话人。
• **已经区分过**（有两位及以上说话人）：跳到第 3 节，只做标注。
• **没区分**（只有一位，或词上没有说话人），但用户说视频里不止一个人：做第 2 节。
• 用户只想换名字、不想重跑时，也只做第 3 节。

2. 区分：按声纹重新转录

区分要重新转录，并取代当前文稿，不另建一份。这一步会丢掉用户在文稿里手改过的字，所以先说清楚再做：

1. 先告诉用户：重新转录会取代当前文稿，之后在文稿里手改过的字会被丢掉；译文、字幕与配音会按新文稿结转。用户同意再继续。 2. 用 transcribe 给这个视频、`diarize` 为 true、`target` 为 replace；语言与提示（人名、术语）沿用这份文稿的，用户给了新的就用新的。 3. 模型不能区分时任务照常完成，结果带 `diarization-unavailable` 警告：告诉用户这个模型分不了说话人，要装「说话人区分」模型包或换能区分的模型；不要假装区分好了。 4. 文稿转录之后被用户改过时，取代会以 `TRANSCRIPT_EDITED` 拒绝：把这一点告诉用户，用户确认丢掉那些修改，才加 `acceptEdited` 重来。 5. 任务完成后重新 documents_read，看分出了几位、每位说了多少。

3. 标注：给每位起名字

动手前先把每位说话人的证据找齐，再一起定名字：

• **占位名**：转写流程自动起的「说话人 n」及它在别的界面语言里的对应（`Speaker 1`、`Sprecher 1` 这类「说话人 + 编号」）、识别服务给的编号标签（`SPEAKER_00`、`S1`、`spk-1`），以及名字为空或等于 id 的。别的名字是用户起的，不动。
• **证据从哪来**：文稿开头一段；每位说话人第一次开口前后的几句；来源素材的标题、发布者与简介（videos_inspect 的 `assets[].source`）；画面上的姓名条：用 videos_frames 取开头一两分钟和每位首次开口处的几帧看，姓名条要明确标着这一位在说话，画面上随便出现的名字不算。
• **什么算证据**：自我介绍（「我是……」「my name is …」）；对方引介（「今天请到了……」「welcome, …」）；被点名后紧接着这一位的回应；签名式的收尾；来源信息唯一地指明了其中一位。元数据里列出几位嘉宾、但分不出哪个声音是谁时，还要文稿里的证据。发言顺序、说话人编号、话题本身都不算；反过来，标题或简介点出了参与者时更要逐位找证据，把名字对到声音上。
• **名字怎么写**：材料里实际用的形式，通常是全名，没有全名时用出现的那种；保留原来的文字与拼写，不翻译、不音译；不加头衔、敬称、机构、括号、引号或说明；不超过 40 个字符。没有名字、但明确说了角色（主持人、采访者、旁白）时可以用简短的角色标签；不能只凭对话的样子编一个角色。
• **不猜**：拿不准就保留占位名。
• **一人几个 id**：区分可能把同一个人拆成几个 id，或把两个人并成一个。各自有证据时给几个 id 同一个名字，不合并 id；声音差别大、拿不准是不是同一个人时，先问用户。

对比一下（只是示意）：

不好：简介写着「嘉宾：张三、李四」，于是「说话人 1」改成张三、「说话人 2」改成李四。

好：00:12 主持人说「今天请到了张三」，紧接着「说话人 2」答「大家好」，所以「说话人 2」是张三；「说话人 1」一直在提问、没人叫过他的名字，简介也没写主持人是谁，保留占位名，或按用户的意思标成「主持人」。

4. 先确认，再写回

1. 写回之前，把方案给用户看：每位说话人起的名字、凭的证据（一句话），以及他第一次开口的时刻和那一句，方便用户在编辑器里跳过去听。 2. 用户确认或改过名字后，用 documents_put 写回同一份转写，只改 `speakers[].name`，words 与其他字段照读到的原样；几位一次写完。版本冲突说明用户刚改过：重新读，在新的正文上重做。 3. 只改名字时译文不用重译，字幕里的说话人跟着文稿变。

5. 要避免的

• 不要按简介里的名单顺序、按谁先开口来填名字。
• 不要不打招呼就重新转录；不要在模型分不了说话人时假装分好了。
• 不要给名字加头衔、机构、括号；不要翻译或音译名字。
• 不要动用户自己起的名字；不要合并 id。
• 不要改正文的字：这里只改说话人。

6. 交付

• 分出了几位说话人；如果重新转录了，说明换了哪份文稿、哪些内容被结转。
• 给谁起了名字、凭什么证据；哪些没有证据，仍是占位名。
• 区分得不对的地方（一句话里换了人、两个人被并成一个），列出时刻，请用户在编辑器的说话人设置里手动调整。