video-chapters

Divide into chapters

Chapters are for viewers to jump around: someone dragging the progress bar glances at a chapter name and knows which segment to go to; someone who has watched and wants to find a spot again relies on it too. So a chapter title must make clear what this segment covers, its start must land where the topic truly begins, and one chapter corresponds to one topic.

There are two common ways to get it wrong. One is cutting evenly by time: one chapter every five minutes, the start landing in the middle of a sentence, titles like "Part One" or "Continued Discussion"—viewers learn nothing from them. The other is titles that read too much like summaries: one long sentence per chapter, and the chapter list becomes unreadable. Chapter names are signposts, not summaries; the summary has its own one-sentence slot.

1. Gather materials

1. Use videos_inspect to look at the video: duration, existing chapters (chapters), documents. If there is no transcript (a document whose kind is speech), transcribe first and tell the user transcription is in progress. Material imported from a link may also have assets[].source：chapters are the author's chapters (structured chapters provided by the platform, or parsed from a timestamped outline in the description); when absent it is []；description is the truncated description.
2. Transcript with timecodes: export (kind transcript、format md、timestamps true; when there are several transcripts, specify by documentId from the candidates it lists), wait with jobs_inspect until completed, and read the file in outputs. It gives times on the edited timeline by paragraph; take the chapter time from this timecode at the start of the paragraph, do not estimate it yourself.
3. When the video already has chapters, first ask the user whether to replace, adjust, or keep them; if the user only says "add chapters" and the existing chapters are new, do not overwrite them.

2. When there are author chapters or the user provided an outline

Chapters the author divided themselves are usually closer to their intent than yours; follow them, do not divide yourself, and do not manually match times. When the source material comes with chapters (assets[].source.chapters is not empty), or the user pastes a timed outline (0:00 开场、1:02:03 问答 and the like), use chapters_adopt:

• Author chapters: give video(give assetwhen there is more than one piece of material, and documentwhen there are several transcripts). For an outline pasted by the user: give outline, which can be [{ at, title }], or the pasted original text. When unsure, first include dryRun to see the receipt, then write for real.
• It snaps each entry to the nearest paragraph or sentence start in the transcript (paragraph first, then sentence, caption line, word), cleans the titles, and writes the whole set into the video's chapters (replacing existing ones; if chapters already exist, ask the user first per step 1).
• Read the receipt's sourceChapters：entries for the total number of entries;matched for entries snapped to a start;ambiguous for how many starts were nearby and the one closest to the author's time was taken (ties go to the later one);snapped for times that were shifted;unanchored for entries that could not be matched and kept their original time.rows For each entry give the title, the written time at, the original time sourceAt , and the status; include offTimeline correspond to places that are not on the timeline (e.g., cut out). When delivering, say clearly how many matched; list the ambiguous, unanchored, and offTimeline entries one by one for the user: these are the places they need to check themselves.
• with untitled: true chapters (author chapters or the receipt's rows ): the platform only gave the boundaries;Untitled Chapter N is a placeholder name filled in by the download tool, not the author's title. Read the transcript between this chapter and the next to title it (in the video's language), and together with the other chapters use outline（[{ at: sourceAt, title }]) and call again. Without dryRun , using it directly returns UNTITLED_SOURCE_CHAPTERS; just add the titles per the rows in the error.
• Returns NO_SOURCE_CHAPTERS: the material has no author chapters; divide it yourself as described below. Returns ASSET_NOT_PLACED: the material is not on the timeline; put it on first.
• Only when the user wants chapters you write yourself, or wants a granularity different from the author's outline, follow the method below to divide it yourself, using the author's outline as reference: where the transcript matches it, reuse its boundaries and titles (keep the language and wording the author used); only add, merge, or delete chapters where the transcript clearly differs; the outline's times are only approximate, and chapter start points still take the timecodes of paragraphs in the manuscript.

3. How many chapters

Set a rough target chapter count based on granularity; don't force it:

Granularity	Approx. length per chapter
Coarse	About 10 minutes
Medium (default)	About 5 minutes
Fine	About 2.5 minutes

Target chapter count = duration ÷ length per chapter, rounded; at least 2 chapters, at most 20 chapters; for recordings over one hour, scale the upper limit at 20 chapters per hour. When an author's outline is available as reference and the user has not specified granularity, take the outline's entry count as the target chapter count. If there are genuinely fewer topic changes than that, fewer chapters are fine: the target chapter count is approximate, not a quota.

4. How to divide

First use speech_topic_boundaries (video; when there are several transcripts, pass documentId) to find topic transitions. It compares several preceding and following passages of speech by meaning and gives places where the topic clearly changed. By default it gives candidates for at most 24 chapters; for recordings over one hour, pass the upper limit from step 3 as maxChapters(leave room for a few more chapters than the target count, at most 200); when the user wants very short chapters, set minChapterSec smaller:

• mode is topic: chapters fall only on first(the start of the first segment) and candidates[].at , and do not start anywhere else;before / after is the original text around the transition; check against the manuscript that the topic really changes here. When there are more candidates than the target chapter count, merge according to the granularity from step 3: first merge ones where depth is clearly smaller (mostly minor episodes or examples), and merge adjacent places belonging to the same larger topic into one chapter. When candidates carry visualShift(a visual index was built for this video), and whendepth is similar and you are unsure which place to keep, keep the one where the visuals also changed (visualShift clearly larger: scene change, slide change, change of demonstration subject); it is only corroborating evidence, and do not start a new chapter based on it alone. Candidate times already fall at the start of a paragraph or sentence; use them directly.
• mode is model: no candidates (reason gives the reason: semantic model not installed, manuscript too short, or null when no clear transition was found); read the manuscript and find them yourself as described below.
• When the user wants finer granularity than the candidates provide (the candidates have far fewer chapters than the target), you may subdivide among the candidates based on the transcript, but still take the start points from the timestamps of paragraphs in the transcript, and explain at delivery which chapters you subdivided yourself.

Before starting, read through the transcript (when candidates exist, focus on the areas around the candidates) and list where topics change: the speaker switches subjects, moves from a problem to a solution, or moves from one case to the next. Chapters should fall at these points.

• Each chapter starts at the beginning of a paragraph; take the time from that paragraph's timestamp in the transcript. Do not make up times, and do not place a chapter in the middle of a sentence.
• The first chapter usually starts at 0 seconds.
• Each chapter gets a title and a one-sentence summary (no more than about 20 words, stating clearly what the chapter discusses). The title is a signpost viewers understand at a glance; use the content of that segment itself, not empty words like "Part One", "Continued", or "Other"; the summary adds a sentence on what this chapter specifically covers.
• Titles and summaries must not be empty, must differ from each other, and must be consistent in style; write them in the language of the transcript, and switch only if the user asks for another language.
• When the recording is very long, read it in several parts: for each part, first list topic units (each with its starting paragraph, title, and summary), then merge them into the final chapters. When there are more units than the target chapter count, merge adjacent units that belong to the same larger topic into one chapter, taking the start point of the first unit after merging, with the title and summary covering the whole merged span; especially merge at the seams between parts, where a topic is often artificially split. If this is not the first part, the beginning may continue the previous part's topic, so there is no need to force a chapter onto this part's first paragraph.

Compare (illustrative only):

Bad:05:00 第二部分 / 10:00 继续讨论模型 / 15:00 其他

Good:04:37 为什么蒸馏后效果掉得厉害 / 11:02 混合方案怎么配 / 16:48 上线后的三个坑

In the latter, every start point falls on the paragraph where the topic begins, and a glance at the title tells you whether to skip ahead.

5. Write into the video

Use edits_apply's setChapters to write the entire chapter list at once (at is the seconds obtained above, strictly increasing in time; write title and summary as is). To change only one or two chapters, use upsertChapter or removeChapter. Chapters are fixed to moments on the timeline: cutting speech (addCuts, accepting cut suggestions, restoring cuts) makes chapters follow the content, while other edits (moving, deleting segments, ripple delete) do not; when such edits change the duration, remind the user that chapters may need to be re-aligned.

6. What to avoid

• Do not split evenly by time, do not place start points in the middle of a sentence, and do not estimate times yourself.
• Do not write titles like "Part One", "Continued", or "Other", and do not write a whole-sentence summary as the title.
• When the material has author chapters, do not re-split them yourself; when the user already has chapters, do not overwrite them without asking.
• Do not force the target chapter count.

7. Delivery

• List the chapters written in: time (hours:minutes:seconds, or minutes:seconds if under an hour), title, summary.
• State whether the author's outline or your own split was used, along with the granularity and chapter count; when you split yourself, state whether the boundaries came from topic transition candidates (speech_topic_boundaries' mode), and point out the chapters you subdivided. When the author's outline was used, report the snapping statistics: how many entries in total, how many matched; list the ambiguous, unanchored, and offTimeline entries one by one.
• A chaptering failure does not affect the transcription or other results: explain the reason truthfully, retry at most once, and do not retry repeatedly.