video-chapters

# 分章节 章节是话题标题加一句话摘要，帮观众在视频里跳着看。分在自然的话题转换处，每章从一段话的开头开始。 ## 1. 取材料 1. 用 videos_inspect 看视频：时长、已有的章节（chapters）、文档。没有转写（kind 为 speech 的文档）时先转写，告诉用户转写在进行。从链接导入的素材另有 `assets[].source`：`chapters` 是作者的章节（平台给的结构化章节，或从简介里的时间戳大纲解析出来的），没有时是 `[]`；`description` 是截断的简介。 2. 带时间码的文稿：export（kind `transcript`、format `md`、timestamps `true`；有几份文稿时按它列出的候选用 documentId 指定），jobs_inspect 等到 completed，读 outputs 里的文件。它按段落给出剪辑后时间线上的时间，章节的时间就取段落开头的这个时间码，不要自己估算。 3. 视频已经有章节时，先问用户是要替换、调整还是保留；用户只说「加章节」而已有的章节是新的，不要覆盖。 ## 2. 有作者章节或用户给了大纲时 来源素材自带章节（`assets[].source.chapters` 不为空），或用户贴来一份带时间的大纲（`0:00 开场`、`1:02:03 问答` 这类）时，用 chapters_adopt 照它来，不自己分，也不手工对时间： - 作者章节：给 `video`（素材不止一个时给 `asset`，有几份转写时给 `document`）。用户贴的大纲：给 `outline`，可以是 `[{ at, title }]`，也可以是贴来的原文。不确定时先带 `dryRun` 看回执，再正式写。 - 它把每一条吸到文稿里最近的段落或句子起点（段落优先，其次句子、字幕条、词），清洗标题后整份写进视频的章节（替换已有的；已有章节要先按第 1 步问过用户）。 - 读回执的 `sourceChapters`：`entries` 共几条；`matched` 吸到了起点；`ambiguous` 附近有几个起点、取了离作者时间最近的那个（同样近取靠后的）；`snapped` 时间挪动过；`unanchored` 对不上、保留了原来的时间。`rows` 逐条给标题、写入的时间 `at`、原来的时间 `sourceAt` 与状态；带 `offTimeline` 的条目对应的地方不在时间线上（比如剪掉了）。交付时说清对上几条，把 ambiguous、unanchored、offTimeline 的条目逐条列给用户。 - 返回 `NO_SOURCE_CHAPTERS`：素材没有作者章节，按下面的做法自己分。返回 `ASSET_NOT_PLACED`：素材不在时间线上，先放上去。 - 用户要你自己写的章节，或想要和作者大纲不同的粗细时，才走下面的做法自己分，作者的大纲当参考：转写和它吻合的地方沿用它的分界和标题（保留作者用的语言与措辞），只在转写明显不同的地方增、并、删章；大纲的时间只是大致的，章节的起点仍取文稿里段落的时间码。 ## 3. 分几章 按粗细定一个大致的目标章数，不硬凑： | 粗细 | 大约多长一章 | | --- | --- | | 粗 | 约 10 分钟 | | 适中（默认） | 约 5 分钟 | | 细 | 约 2.5 分钟 | 目标章数 = 时长 ÷ 每章时长，取整；至少 2 章，最多 20 章，超过一小时的录音上限按每小时 20 章放大。有作者大纲当参考、用户又没指定粗细时，目标章数取大纲的条数。话题真正的转换比这个少时，少分几章没关系。 ## 4. 怎么分 - 每章从一段话的开头开始；时间取文稿里那一段的时间码。不编造时间，不把章节放在一句话的中间。 - 第一章通常从 0 秒开始。 - 每章一个标题和一句话的摘要（不超过约 20 个词，说清这一章讨论什么）。 - 标题和摘要不能为空，彼此不同，风格一致；用转写的语言写，用户要别的语言时才换。 - 录音很长时分几部分读：每部分先列出话题单元（各自的起点段落、标题和摘要），再把它们合成最终的章节。单元比目标章数多时，把属于同一个更大话题的相邻单元合成一章，起点取合并后第一个单元的起点，标题和摘要覆盖合并后的整段；分部分的接缝处尤其要合并，那里一个话题常被人为切开。不是第一部分时，开头可能接着上一部分的话题，不必在这一部分的第一段强加一章。 ## 5. 写进视频 用 edits_apply 的 setChapters 一次写入整份章节列表（at 是上面取到的秒数，按时间严格递增；title、summary 照写）。只改一两章时用 upsertChapter 或 removeChapter。章节固定在时间线的时刻上，之后再剪辑不会跟着移动：剪辑改了时长时提醒用户章节可能要重新对一遍。 ## 6. 交付 - 列出写进去的章节：时间（时:分:秒，不到一小时写分:秒）、标题、摘要。 - 说明用的是作者的大纲还是自己分的，粗细与章数。用了作者大纲时报吸附统计：共几条、对上几条；ambiguous、unanchored、offTimeline 的条目逐条列出。 - 分章失败不影响转写和其他结果：如实说明原因，最多重试一次，不反复重试。