narration

Narration-driven finished video

In a narration-driven finished video, everything is decided bythe script and the voice: the length of the script sets the length of the finished video, and the consistency of the voice determines whether the audience believes it is one person speaking. Order:

First measure the speaking rate, then calculate the character count, then write the script (Section 1).
Write the script one sentence per line; write how it is said separately from what is said (Section 2).
Choose a voice whose timbre can be locked, synthesize once with one set of instructions, and record the seed (Section 3).
Measure, check the seams, and re-record only the sentences that fail; do not stretch duration with speed changes (Section 4).
Cut the visuals to the narration (Section 5).
Acceptance check (Section 6).

Section 3 "Record it yourself" is inspired by an editing tip shared by "大师的AI小灶" (@dashiAIxz): when a synthesized voice differs greatly from the person's own intonation and emotion, switch to the person's own recording.

1. First measure the speaking rate, then calculate the character count

When there is no sample audio for the current configuration and a draft is needed first, use skills_read to read baocut-catalog-voice-language-rates: estimate the first-draft budget from the target language's Unit and Rate, then revise it with the measurements below. The table includes full language data, calibration conditions, and fallbacks for unlisted languages; there is no need to synthesize audio first just to consult the table.
The character count is not a guess:first have the model and voice you will use read a short, representative passage, with the same set of tone instructions, and use the resulting duration to calculate units/second. If sample audio with the same configuration, same language, and a similar style already exists, reuse it and do not regenerate.
The counting method follows the target language: count characters for scripts such as Chinese that are suited to character counting, and count words for languages with established word segmentation; for other languages or mixed-language text, use a consistent, reproducible character or segmentation method, apply the same method to both the sample audio and the full script, and do not fall back to English speaking rates. Count numbers and abbreviations as they are actually read, and do not count stage directions or punctuation.
When calculating the average speaking rate from the total duration of the sample audio,unit budget = seconds available for narration × measured units/second, pauses are already included and must not be deducted again. If the vocal speaking rate is measured separately from alignment timings, then unit budget = (available seconds − estimated pause seconds) × vocal units/second; you cannot simply subtract seconds from the character count. External language rate tables can only serve as a drafting reference; recalibrate after changing the model, language, or performance.
If the script runs long, compress it within the scope where rewriting is allowed; do not rely on speeding up. When the user requires verbatim reading, keep the original script, explain its conflict with the duration budget, and do not delete sentences on your own.
Duration is a target, not a quota: if the script reads in 55 seconds, deliver 55 seconds; do not pad, loop, or change speed to stretch it to 60.

2. How to write the script

One sentence per line, one idea per sentence, ending each sentence with a period, question mark, or exclamation mark: the synthesis engine splits sentences and inserts pauses at these punctuation marks, and subtitles also break lines at these points. Do not use semicolons to join two sentences into one.
Write numbers, years, and abbreviations as they are read ("two thousand twenty-six, October first", "thirty frames per second"); for polyphonic characters and proper nouns, first check the speech model you will use in models_capabilities for its readings(local models are under local.readings ; online models do not have this field, so treat it as unsupported）：annotated pronunciation annotations (<银行|yin2 hang2>, written in the speak text);unsupported ones (the local qwen3-tts is one) have no pronunciation channel, and annotations will be read out as their surface text, so in that case switch to the phonetic spelling (substitute homophones, split into words that read correctly) and do not write annotations.
Place memes and quips after the factual sentences as separate sentences; achieve rhythm through sentence length and editing cuts, not by making the voice read faster.
Separate how to say it from what to say: the style note should state only tone, scene, and character ("young news anchor, bright and natural, with a hint of a smile when quipping"), and no dialogue; do not put parenthetical notes or stage directions inside the dialogue. When the model responds to them, you may request performance pacing such as "slow and soothing" or "rushed and excited", but you cannot use it to promise exact seconds or to rescue an overlong script; settle the performance first, then measure the budget as in Section 1. "Fast editing rhythm" does not automatically mean "the voice reads fast".

3. Choose a voice, synthesize in one pass

For multi-sentence narration, prefer timbres anchored to a reference recording: cloned timbres already authorized in the user's library (library:<id>), or built-in timbres in models_capabilities whose voices[].source is builtin . Each of their chunks is generated against the same reference recording, so the timbre stays stable.
source Preset speakers whose model (the kind of local model that accepts style notes) are sampled independently per chunk, and pitch drifts 3–5 semitones between chunks, sounding like a different person: use them only for short narration under 60 characters, or when the user specifically asks for them—in that case, state this risk in the report. Online models follow their own documentation.
One character in the whole piece gets one timbre and one set of style notes; when a model does not accept style notes, rely on timbre selection alone.
Submit the whole passage at once(or by paragraph, a few hundred characters per submission), not sentence by sentence: the engine splits into chunks by sentence itself and unifies pauses and loudness between chunks; submitting sentence by sentence does not make the timbre more consistent, and instead stretches the total duration and slows each character. Use sentence-by-sentence only to re-dub a particular sentence (Section 4).
When the model accepts a seed (acceptsSeed), give it a fixed seed and record it; when re-dubbing a sentence, change only that sentence's seed and leave the rest untouched. Models that do not take a seed (most online ones) have no such option; for re-dubbing, redo the whole passage as in Section 4.
A result that includes video is candidate material and is not yet on the timeline; after synthesis, measure it first (Section 4), then place it.
User records themselves: when the user cares whether the narration sounds like themselves (intonation, emotion), or already has a recording, use the recording instead of synthesis: a synthesized timbre's delivery is often far from the person, and a cloned timbre only locks in the timbre. Write the script as in Sections 1 and 2, but change the speech rate to the user's own measured rate (ask the user to read a short passage first to measure it), and give it to the user line by line to read; once recorded, import it with assets_import, and the recording's duration is authoritative; do the alignment and seam checks of Section 4 as usual, trim silence from overly long pauses, and ask the user to re-record any sentence that was misread or has the wrong tone—do not splice in synthesized sentences; Section 5 applies as usual.

4. Measure, check seams, re-dub

Measure: The duration of the result is taken from the media facts in the result, checked against the budget. If it is over, determine per Section 1 whether compression is allowed, then re-dub that segment without changing the timeline speed; if it is short, deliver it as is.
Align: transcribe the narration asset to obtain the time of each character (pass the narration asset to transcribe, with the language asserted as the language of the script); use this timing for both subtitles and shot cuts, do not estimate by feel. To choose a model with word timings of native : first check the transcription model's wordTimestampsin models_capabilities; when the default model is none(e.g. MOSS), explicitly pass model(on this machine e.g. qwen3-asr), otherwise you cannot get character timings; only models withacceptsHint set to true accept proper nouns in the prompt. When not waiting for the result (after jobs_wait), the transcription document's id is in the job result's pipeline.summary.documentId; read it with documents_read. Before building subtitles, use edits_apply's updateWords to correct misrecognized characters (homophones, proper nouns) back to the script's spelling, without moving the word timings (for the method, use skills_read to read baocut-catalog-subtitles 's "polish write-back").
Check the seams(measured): using the aligned character timings and the counting method of Section 1, compute each sentence's units/second and the pauses between sentences. Sentences deviating from the median by more than 15%, and inter-sentence pauses longer than 0.8 seconds, are candidates for re-dubbing or cutting out the silence.
Re-dub one sentence: speak only that sentence (same voice, same description, different seed), and use the aligned timings to replace that sentence's range on the timeline; when the model does not accept a seed, a separately re-dubbed sentence often fails to match the original segment's tone and loudness, so if the segment is not long, re-dub the whole segment, re-align the whole segment, and rebuild the subtitles; when the new sentence is longer than the original, handle the text-versus-duration conflict per Section 1, without changing speed.
Revising the script touches only the changed segment: when a segment of the script is changed or a segment is inserted, re-dub and re-align only that segment; unchanged segments keep their original recordings and character timings, without re-dubbing or re-transcribing the whole piece.
Listen(requires a human listener): export 2–3 five-second clips from the narration (each spanning a sentence boundary) for the user to listen to, asking "does it sound like the same person" and "are the pauses natural". If you cannot listen yourself, state truthfully in the report that you "have not listened", and do not write "measured" as "listened".
On the timeline,do not add speed changes to the narration: speed changes preserve pitch but alter the ratio of speaking rate to pauses, making the original fast/slow differences more obvious; the small speed adjustments used for alignment in the translation dubbing workflow belong to that workflow, and are not used here.

5. Cut the visuals to the narration

With the narration on one track, place it and measure it first, then arrange the visuals according to the start and end of the sentences in the narration: one shot or a group of shots per sentence, with cut points falling in the pauses between sentences, not in the middle of a character.
Where the visuals come from: the user's material takes priority (for clips in the user's videos that talk about the same thing, use space_search_v2 to search by the meaning of this narration sentence,kinds passing ["speech"]; when what is wanted is the image itself (a scene, object, action),channels passing ["visual"] with an image description to search, or use videos_match_frames on the chosen source video;weak check the visuals first before using them; for material the user just provided that does not yet have a visual index, build it first following the baocut main skill); for sentences that explain concepts, metaphors, or scenes where there is no material, you may generate one still image per sentence or per group of sentences (aspect ratio per the frame, no text in the image, use the same style description for the whole piece, and include it when generating video, how to invoke with skills_read to read baocut-catalog-media 's "generate image"); for text, numbers, steps and charts use code frames (use skills_read to read motion-graphics). Static images don't move; don't linger on one too long, pair with transitions or keep the shot short; when talking about real products, people, or data, use real footage and don't pass off generated images as real.
Duck the music under the narration (setDucking, triggered by selecting the track the narration is on), place sound effects between sentences (synthesize with assets_sfx, and for how to configure use skills_read to read baocut-catalog-music 's "sound effects"). When you need music, use skills_read to read baocut-catalog-music: if the user provided music, use the user's; otherwise generate pure music locally if possible, and if the model package isn't downloaded, offer to download it as that page suggests; submit once the narration is measured and the final duration is set, and work on visuals during generation. Music for narrated videos should be sparse, dynamically steady, not compete with the voice, fade out smoothly over the last 2–3 seconds, and not cut off in the middle of the final sentence.
Break subtitles into lines according to the narration script, not according to the segmentation from the recognition result; use the character timings obtained from alignment.

6. Acceptance

The script's character count is within budget; the final duration matches the narration duration (the difference is the intro and outro).
The narration uses only one voice and one set of instructions, and the seed used is recorded in the report; when a preset speaker is chosen, the risk is stated; when the user's recording is used, that is stated.
Each sentence's characters/second and pause amount have been checked, and anomalous sentences have been handled or listed in the report.
The report has three columns: measured (duration, characters/second, pauses), viewed (cut points, subtitle positions), and to be listened to by a human (voice consistency, natural pauses, and breathing with the visuals).