Skip to main content
After an edit, decktalk build voices again only the sections whose text changed. Use this guide to find what an edit runs again, and to rebuild only the sections you changed.

​
Before you start

Check which kind of build the project had last, because you run the same kind again.
After a silent build, the timeline line ends in (estimated: silent placeholders). After a voiced build, it does not. If you run the other kind, read A silent build and a voiced build first.

​
Find the command for your edit

Find your edit in the first column. N is the number of the section you changed. After a silent build, add --silent to each decktalk build command. A page can show the words of the section before it, which it reads from prevwords. The scaffold’s scene 2 opens on the Open’s last frame with the Open’s count times. So after an edit to section 1, record section 2 as well.
Nine section columns cross three lanes above an assemble bar. Sections 5 and 7 are clips in every lane. In the narrate lane, section 1 reads voiced and the other page sections read cached. A plain build records every page section. With --only 1, section 1 reads recorded and the other page sections read kept. The assemble bar spans all nine sections.Nine section columns cross three lanes above an assemble bar. Sections 5 and 7 are clips in every lane. In the narrate lane, section 1 reads voiced and the other page sections read cached. A plain build records every page section. With --only 1, section 1 reads recorded and the other page sections read kept. The assemble bar spans all nine sections.

After an edit to section 1, only section 1 is voiced again, and --only 1 records only section 1.

​
What each edit runs again

The next table gives the reason for each row of the first table. A recording stays valid when a neighbor section changes length. Cue times count from the start of their own section, so a longer section 2 does not move a cue in section 3. A page that reads prevwords is the exception. It shows the words of the section before it, so record it again after that section changes.

​
The narration cache

The narration cache is build/audio/manifest.json. It holds one hash per section, made from these values:
  • the speech provider’s name and the voice id
  • the model and the output format
  • the voice settings
  • the exact text sent for the section
The narrate stage skips a section when all four of these are true:
  • The hash matches.
  • The audio file name is unchanged.
  • The mp3 exists.
  • The words file exists.
The hash leaves out the text of the neighbor sections, so an edit never voices a neighbor again. The hash also leaves out the section number. If you renumber a section and its text is unchanged, narrate copies its take from the old file names to the new ones and prints a [move] line. The first spoken section is the exception, because only its take starts with the lead-in silence. A take never moves into or out of that place. A section that is voiced again costs the characters of its whole text, not only the changed sentence. Requirements lists every command that spends credits. The record stage has no cache, so --only is the way to keep a recording.

​
Limit a build to some sections

Pass --only with a section number. Repeat the flag for more sections, because it does not take commas.
The flag limits record, measure, and check to the sections you name. The other stages still work on every section:
  • narrate voices any section whose text changed, even a section you did not name.
  • assemble cuts and joins every section, because the final mp4 needs all of them.
  • The verify stage checks every section start and every cut.
Name every section whose text or scene changed. A section you leave out keeps its old recording, even if its words moved. --only needs a page section, because a clip section has no recording.

​
Record one section again

Use these steps when a recording of section N is bad, for example after STALLED or TRUNCATED. The steps voice nothing when the text is unchanged, and they keep every other recording.
Run decktalk build --silent only if the last build was silent. In a voiced project, it stops with an error. With --force, it empties the narration cache, and the next voiced build spends credits on every section.
1

Build the section again

If the last build was voiced, run this command.
If the last build was silent, run decktalk build --silent --only N instead.
2

Measure the cues of the section

The build checks section starts, cuts, and cut continuity, but not cues. Run decktalk verify for the cues.
Every cue row of section N reads changed or skipped. The verify reference explains each result.

​
Run the stages by hand

Each stage is also a command. These are the commands that decktalk build --only 3 runs, plus a cue check.
Some edits need fewer commands.

​
Voice every section again

Use --force to ignore the narration cache. A forced run spends credits on every section.
decktalk narrate --dry-run makes no API call. It prints the text that each section would send, and a take plan that says which sections a voiced run would voice, keep cached, or move. So you can count the characters first. decktalk narrate --dry-run --json gives the same plan as JSON. decktalk preflight adds the cue check and an estimate of each reveal from frozen frames, so you can fix a small reveal before you pay for the takes.

​
A silent build and a voiced build

A silent build after a voiced build would empty the narration cache. The next voiced build would then voice every section again and spend credits on all of them. So a silent narrate or build stops when build/audio/manifest.json holds voiced takes, and it writes nothing.
The cache would be lost for three reasons:
  1. The manifest notes whether its entries came from a silent build.
  2. narrate reuses the previous manifest only when it is the same kind of build.
  3. A silent build writes a click track over the voiced mp3 of the same name, and it replaces the manifest.
In a project that has never been voiced, a silent build loses nothing. The first voiced build voices every section anyway. After a project has been voiced, rehearse with a silent build in a copy of the project. To replace the voiced takes on purpose, pass --force, as in decktalk build --silent --force. Neither kind of build replaces the final mp4 until it finishes. A timestamped copy of each finished video stays next to build/out/<name>.mp4.

​
Next