decktalk 0.2.0__tar.gz → 0.2.1__tar.gz

{decktalk-0.2.0 → decktalk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decktalk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Narrated presentations, cut to the word. A markdown script, an ElevenLabs voice, and HTML slides go in, and one mp4 comes out.
 Keywords: presentation,narration,elevenlabs,video,slides,text-to-speech,markdown,video-generation,explainer-video,lesson,screencast,word-timestamps,playwright,ffmpeg
 Author: Jacob Beaudin
@@ -50,7 +50,7 @@ If you change a sentence, DeckTalk voices only that section again.</p>
      1. Upload the mp4 through GitHub's editor.
      2. Put the user-attachments URL on its own line in place of the hero picture at the top.
      3. Move the caption below under that line, and uncomment it.
-     4. Under "Make your first video", change "The scaffold is a five-section lesson" to
+     4. Under "Make your first video", change "The scaffold is a lesson in nine sections, two of them optional clips" to
         "The scaffold is the project that made the demo video above".
 <p align="center">DeckTalk built this video from the project that <code>decktalk init</code> writes, in a cloned voice. Turn the sound on, and each reveal starts on its word.</p>
 -->
@@ -126,7 +126,7 @@ You need Python 3.12 or later. These steps use `uv`, a Python package manager. I
 
    This build spends ElevenLabs credits for every section. It writes the video, SRT and VTT captions, and one chapter per section. [What spends credits](https://docs.decktalk.app/requirements#what-spends-credits) lists the cost.
 
-The scaffold is a five-section lesson. The [quickstart](https://docs.decktalk.app/quickstart) shows the output of each step and [what the example video shows](https://docs.decktalk.app/quickstart#what-the-example-video-shows).
+The scaffold is a lesson in nine sections, two of them optional clips. The [quickstart](https://docs.decktalk.app/quickstart) shows the output of each step and [what the example video shows](https://docs.decktalk.app/quickstart#what-the-example-video-shows).
 
 ## What you write
 
@@ -159,12 +159,12 @@ A browser does not start recording at a known time, so DeckTalk does not use a t
 
 `decktalk verify` then measures every reveal in the finished video. This sample comes from a silent build of the scaffold.
 
-<!-- sample: decktalk verify 1:1.1bowl 3:3.4name 4:4.1words, silent build of the scaffold (cue table only) -->
+<!-- sample: decktalk verify 1:1.1bowl 3:3.4name 8:7.1checked, silent build of the scaffold (cue table only) -->
 ```text
 check                 cue       at   chg %   ctl %   offset     a/v  result
 1:1.1bowl            1.25     1.25    1.05    0.00    -10ms    -9ms  changed
-3:3.4name           71.98   110.58    2.77    0.00    +20ms   +11ms  changed
-4:4.1words          14.31   172.99    1.47    0.00    +10ms   -11ms  changed
+3:3.4name           84.72   123.32    2.74    0.00     +0ms    -4ms  changed
+8:7.1checked        10.03   238.31    6.56    0.00    +10ms    +3ms  changed
 ```
 
 The offset column is the time from the cue time to the onset of the reveal, in milliseconds. [Verify](https://docs.decktalk.app/reference/verify) defines every column and limit.

{decktalk-0.2.0 → decktalk-0.2.1}/README.md

@@ -17,7 +17,7 @@ If you change a sentence, DeckTalk voices only that section again.</p>
      1. Upload the mp4 through GitHub's editor.
      2. Put the user-attachments URL on its own line in place of the hero picture at the top.
      3. Move the caption below under that line, and uncomment it.
-     4. Under "Make your first video", change "The scaffold is a five-section lesson" to
+     4. Under "Make your first video", change "The scaffold is a lesson in nine sections, two of them optional clips" to
         "The scaffold is the project that made the demo video above".
 <p align="center">DeckTalk built this video from the project that <code>decktalk init</code> writes, in a cloned voice. Turn the sound on, and each reveal starts on its word.</p>
 -->
@@ -93,7 +93,7 @@ You need Python 3.12 or later. These steps use `uv`, a Python package manager. I
 
    This build spends ElevenLabs credits for every section. It writes the video, SRT and VTT captions, and one chapter per section. [What spends credits](https://docs.decktalk.app/requirements#what-spends-credits) lists the cost.
 
-The scaffold is a five-section lesson. The [quickstart](https://docs.decktalk.app/quickstart) shows the output of each step and [what the example video shows](https://docs.decktalk.app/quickstart#what-the-example-video-shows).
+The scaffold is a lesson in nine sections, two of them optional clips. The [quickstart](https://docs.decktalk.app/quickstart) shows the output of each step and [what the example video shows](https://docs.decktalk.app/quickstart#what-the-example-video-shows).
 
 ## What you write
 
@@ -126,12 +126,12 @@ A browser does not start recording at a known time, so DeckTalk does not use a t
 
 `decktalk verify` then measures every reveal in the finished video. This sample comes from a silent build of the scaffold.
 
-<!-- sample: decktalk verify 1:1.1bowl 3:3.4name 4:4.1words, silent build of the scaffold (cue table only) -->
+<!-- sample: decktalk verify 1:1.1bowl 3:3.4name 8:7.1checked, silent build of the scaffold (cue table only) -->
 ```text
 check                 cue       at   chg %   ctl %   offset     a/v  result
 1:1.1bowl            1.25     1.25    1.05    0.00    -10ms    -9ms  changed
-3:3.4name           71.98   110.58    2.77    0.00    +20ms   +11ms  changed
-4:4.1words          14.31   172.99    1.47    0.00    +10ms   -11ms  changed
+3:3.4name           84.72   123.32    2.74    0.00     +0ms    -4ms  changed
+8:7.1checked        10.03   238.31    6.56    0.00    +10ms    +3ms  changed
 ```
 
 The offset column is the time from the cue time to the onset of the reveal, in milliseconds. [Verify](https://docs.decktalk.app/reference/verify) defines every column and limit.

{decktalk-0.2.0 → decktalk-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Narrated presentations, cut to the word. A markdown script, an ElevenLabs voice, and HTML slides go in, and one mp4 comes out."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -60,7 +60,7 @@ Changelog = "https://github.com/jacobcbeaudin/decktalk/blob/main/CHANGELOG.md"
 decktalk = "decktalk.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.8.0,<0.12.0"]
+requires = ["uv_build>=0.8.0,<0.13.0"]
 build-backend = "uv_build"
 
 [dependency-groups]

{decktalk-0.2.0 → decktalk-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Narrated presentations, cut to the word. A markdown script, an ElevenLabs voice, and HTML slides go in, and one mp4 comes out."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -51,7 +51,7 @@ Changelog = "https://github.com/jacobcbeaudin/decktalk/blob/main/CHANGELOG.md"
 decktalk = "decktalk.cli:main"
 
 [build-system]
-requires = ["uv_build>=0.8.0,<0.12.0"]
+requires = ["uv_build>=0.8.0,<0.13.0"]
 build-backend = "uv_build"
 
 [dependency-groups]

{decktalk-0.2.0 → decktalk-0.2.1}/src/decktalk/artifacts.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 import json
 import math
+import re
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
 from typing import Any, Self
@@ -272,14 +273,15 @@ class Sidecar:
 #     build/out/<name>.vtt          the same cues as WebVTT
 #     build/out/<name>.chapters.txt an ffmetadata file with one [CHAPTER] per section
 
-CAPTION_MAX_CHARS = 42  # The longest line a cue may carry, in characters.
-CAPTION_MAX_LINES = 2
-CAPTION_MAX_GAP = 1.5  # A pause longer than this between two words ends the cue.
-CAPTION_MAX_SECONDS = 7.0  # No cue stays on screen longer than this.
+CAPTION_MAX_CHARS = 42  # The longest line a cue may carry, in characters. A cue has at most two lines.
+CAPTION_MIN_SILENCE = 1.0  # A silence at least this long between two words always ends the cue.
 CAPTION_TAIL = 0.2  # Seconds a cue lingers after its last word, unless the next cue begins first.
+CAPTION_MAX_UNITS = 8  # The most sentences one cue is ever considered to hold.
 
-_SENTENCE_END = (".", "?", "!")
-_CLAUSE_END = (",", ";", ":", "—", "-")
+# Short words a line should not end on and a split should not touch, so "billions of billions" stays whole.
+_FUNCTION_WORDS = frozenset("a an the of to in on at for and or but by with as is it its my your".split())
+_SENTENCE_END_RE = re.compile(r"[.?!][\"'”’)]*$")
+_CLAUSE_END_RE = re.compile(r"[,;:—–-]$")
 
 
 @dataclass(frozen=True)
@@ -293,42 +295,79 @@ class CaptionCue:
         return "\n".join(self.lines)
 
 
-def _chars(words: list[Word]) -> int:
-    return sum(len(w.word) for w in words) + max(len(words) - 1, 0)
+def _ends_sentence(token: str) -> bool:
+    return bool(_SENTENCE_END_RE.search(token))
 
 
-def _caption_lines(words: list[Word], max_chars: int) -> list[list[Word]]:
-    """Split one run of words into lines of at most max_chars, preferring punctuation breaks."""
-    lines: list[list[Word]] = []
-    cur: list[Word] = []
-    for w in words:
-        if cur and _chars([*cur, w]) > max_chars:
-            # Back up to the last clause break inside the line when it leaves a reasonable line behind.
-            cut = next(
-                (
-                    i + 1
-                    for i in range(len(cur) - 2, -1, -1)
-                    if cur[i].word.endswith(_CLAUSE_END) and _chars(cur[: i + 1]) >= max_chars // 2
-                ),
-                None,
-            )
-            if cut is None:
-                lines.append(cur)
-                cur = []
-            else:
-                lines.append(cur[:cut])
-                cur = cur[cut:]
-                # The carried tail plus the new word can still overflow, so flush it as its own line.
-                if _chars([*cur, w]) > max_chars:
-                    lines.append(cur)
-                    cur = []
-        cur.append(w)
-        if w.word.endswith(_SENTENCE_END) and _chars(cur) >= max_chars // 2:
-            lines.append(cur)
-            cur = []
-    if cur:
-        lines.append(cur)
-    return lines
+def _ends_clause(token: str) -> bool:
+    return bool(_CLAUSE_END_RE.search(token))
+
+
+def _is_function_word(token: str) -> bool:
+    return re.sub(r"[^\w']", "", token.lower().replace("’", "'")) in _FUNCTION_WORDS
+
+
+def _join(words: list[Word]) -> str:
+    return " ".join(w.word for w in words)
+
+
+def _wrap(words: list[Word], max_chars: int, *, several: bool = False) -> tuple[list[str], bool] | None:
+    """One line if the words fit, else the best break into two lines, or None when no break fits.
+
+    Returns the lines and whether the break falls after a sentence end. The break goes after a
+    sentence end, else after a clause mark, while the shorter line is at least a third of the
+    longer. A cue of `several` sentences takes a sentence-end break even when lopsided. Otherwise
+    the lines are balanced, and a line that ends on a function word costs the most. No line is a
+    single word unless that word is a whole sentence.
+    """
+    whole = _join(words)
+    if len(whole) <= max_chars:
+        return [whole], True
+    best: tuple[tuple[int, int], list[str], bool] | None = None
+    for i in range(1, len(words)):
+        first, second = words[:i], words[i:]
+        la, lb = len(_join(first)), len(_join(second))
+        if la > max_chars or lb > max_chars:
+            continue
+        if any(len(part) == 1 and not _ends_sentence(part[0].word) for part in (first, second)):
+            continue
+        last, nxt = first[-1].word, second[0].word
+        even = min(la, lb) >= max(la, lb) / 3
+        if _ends_sentence(last) and (even or several):
+            rank = 0
+        elif _ends_clause(last) and even:
+            rank = 1
+        else:
+            rank = 2
+        score = abs(la - lb) + 16 * _is_function_word(last) + 4 * _is_function_word(nxt)
+        if best is None or (rank, score) < best[0]:
+            best = ((rank, score), [_join(first), _join(second)], _ends_sentence(last))
+    return (best[1], best[2]) if best else None
+
+
+def _split_sentence(words: list[Word], max_chars: int) -> list[list[Word]]:
+    """Split a sentence too long for two lines into parts that each fit in two lines.
+
+    The split goes at the clause mark nearest the middle when both parts keep a third of the
+    characters, else at the word boundary nearest the middle with no function word on either
+    side. Each part keeps at least three words. A sentence with no such boundary splits at the
+    boundary nearest the middle, so no line runs past max_chars.
+    """
+    if len(words) < 2 or _wrap(words, max_chars) is not None:
+        return [words]
+    total = len(_join(words))
+    ranked: list[tuple[int, float, int]] = []
+    for i in range(3, len(words) - 2):
+        cut = len(_join(words[:i]))
+        token, nxt = words[i - 1].word, words[i].word
+        if _ends_clause(token) and min(cut, total - cut) >= total / 3:
+            ranked.append((0, abs(cut - total / 2), i))
+        elif not _ends_clause(token) and not _is_function_word(token) and not _is_function_word(nxt):
+            ranked.append((1, abs(cut - total / 2), i))
+    if not ranked:  # no boundary follows the rules, so take the middle rather than overflow a line
+        ranked = [(2, abs(len(_join(words[:i])) - total / 2), i) for i in range(1, len(words))]
+    i = min(ranked)[2]
+    return _split_sentence(words[:i], max_chars) + _split_sentence(words[i:], max_chars)
 
 
 def display_words(words: list[Word], text: str) -> list[Word]:
@@ -363,54 +402,74 @@ def caption_cues(
     words: list[Word],
     *,
     max_chars: int = CAPTION_MAX_CHARS,
-    max_lines: int = CAPTION_MAX_LINES,
-    max_gap: float = CAPTION_MAX_GAP,
-    max_seconds: float = CAPTION_MAX_SECONDS,
+    min_silence: float = CAPTION_MIN_SILENCE,
 ) -> list[CaptionCue]:
     """Cues for one section's words, so a cue never spans a section boundary.
 
-    Words are grouped into lines of at most max_chars, broken at punctuation where the line
-    would overflow, and lines are paired into cues of at most max_lines. A sentence end,
-    a pause longer than max_gap, or a cue running past max_seconds also closes the cue.
+    Every word keeps its start time. A cue ends before any silence of min_silence or more.
+    Between those breaks, whole sentences are grouped into cues at the lowest cost: each cue
+    costs 1000, a cue of several sentences whose line break cannot fall at a sentence end
+    costs 1200 more, a two-word cue 400 more, and a one-word cue 5000 more. A sentence too long
+    for two lines is split first (see `_split_sentence`), and each part is a cue of its own.
+    Each cue has one or two lines of at most max_chars (see `_wrap`).
     """
     if not words:
         return []
     runs: list[list[Word]] = [[]]
     for w in words:
-        if runs[-1] and w.start - runs[-1][-1].end > max_gap:
+        if runs[-1] and w.start - runs[-1][-1].end >= min_silence:
             runs.append([])
         runs[-1].append(w)
-    cues: list[CaptionCue] = []
-    for run in runs:
-        pending: list[list[Word]] = []
-        for line in _caption_lines(run, max_chars):
-            pending.append(line)
-            closes = (
-                len(pending) >= max_lines
-                or line[-1].word.endswith(_SENTENCE_END)
-                or line[-1].end - pending[0][0].start >= max_seconds
-            )
-            if closes:
-                cues.append(_cue(pending))
-                pending = []
-        if pending:
-            cues.append(_cue(pending))
-    # A cue lingers briefly after its last word, but never into the next cue.
-    out: list[CaptionCue] = []
-    for i, cue in enumerate(cues):
-        end = cue.end + CAPTION_TAIL
-        if i + 1 < len(cues):
-            end = min(end, cues[i + 1].start)
-        out.append(CaptionCue(cue.start, round(max(end, cue.end), 3), cue.lines))
-    return out
 
+    groups: list[list[Word]] = []
+    for run in runs:
+        sentences: list[list[Word]] = [[]]
+        for w in run:
+            sentences[-1].append(w)
+            if _ends_sentence(w.word):
+                sentences.append([])
+        units = [part for s in sentences if s for part in _split_sentence(s, max_chars)]
+        groups += _group_units(units, max_chars)
 
-def _cue(lines: list[list[Word]]) -> CaptionCue:
-    return CaptionCue(
-        start=round(lines[0][0].start, 3),
-        end=round(lines[-1][-1].end, 3),
-        lines=tuple(" ".join(w.word for w in line) for line in lines),
-    )
+    cues: list[CaptionCue] = []
+    for i, group in enumerate(groups):
+        wrapped = _wrap(group, max_chars, several=True)
+        lines = wrapped[0] if wrapped else [_join(group)]
+        end = group[-1].end + CAPTION_TAIL
+        if i + 1 < len(groups):  # a cue lingers briefly after its last word, but never into the next cue
+            end = min(end, groups[i + 1][0].start)
+        cues.append(CaptionCue(round(group[0].start, 3), round(max(end, group[-1].end), 3), tuple(lines)))
+    return cues
+
+
+def _group_units(units: list[list[Word]], max_chars: int) -> list[list[Word]]:
+    """Group consecutive units (whole sentences, or parts of a split one) into cues at the lowest cost."""
+
+    def cost(chunk: list[list[Word]]) -> int | None:
+        several = len(chunk) > 1
+        if several and not all(_ends_sentence(u[-1].word) for u in chunk):
+            return None  # only whole sentences share a cue
+        flat = [w for u in chunk for w in u]
+        wrapped = _wrap(flat, max_chars, several=several)
+        if wrapped is None:
+            return None if several else 6000  # a unit that cannot wrap still gets a cue of its own
+        c = 1000 + (1200 if several and not wrapped[1] else 0)
+        return c + (5000 if len(flat) == 1 else 400 if len(flat) == 2 else 0)
+
+    n = len(units)
+    best = [0.0] + [math.inf] * n
+    back = [0] * (n + 1)
+    for j in range(1, n + 1):
+        for i in range(max(0, j - CAPTION_MAX_UNITS), j):
+            c = cost(units[i:j])
+            if c is not None and best[i] + c < best[j]:
+                best[j], back[j] = best[i] + c, i
+    groups: list[list[Word]] = []
+    j = n
+    while j > 0:
+        groups.append([w for u in units[back[j] : j] for w in u])
+        j = back[j]
+    return groups[::-1]
 
 
 def _stamp(seconds: float, sep: str) -> str:

{decktalk-0.2.0 → decktalk-0.2.1}/src/decktalk/project.py

@@ -53,7 +53,8 @@ class ClipSection:
     """A section that is your own video clip, with its own audio.
 
     A missing clip plays a titled slate for `slate_seconds`. With `strict` that is an error,
-    unless the section is `optional`, as the scaffold's B-roll slot is.
+    unless the section is `optional`, as the scaffold's B-roll slot is. `words` names a words
+    file of the speech inside the clip, in seconds after the clip starts, which the captions add.
     """
 
     number: int
@@ -61,6 +62,7 @@ class ClipSection:
     title: str = ""
     slate_seconds: float = 5.0
     optional: bool = False
+    words: str | None = None
 
     @property
     def key(self) -> str:
@@ -241,7 +243,7 @@ class _Table:
 
 
 VOICE_KEYS = frozenset({"provider", "model", "stability", "similarity_boost", "style", "speaker_boost", "speed"})
-CLIP_KEYS = frozenset({"number", "title", "clip", "slate_seconds", "optional"})
+CLIP_KEYS = frozenset({"number", "title", "clip", "slate_seconds", "optional", "words"})
 PAGE_KEYS = frozenset({"number", "title", "page", "scene", "extra_seconds", "hold_seconds", "ambience", "params"})
 SOUND_KEYS = frozenset({"text", "out", "duration_seconds", "prompt_influence", "model_id"})
 
@@ -272,6 +274,7 @@ def _parse_section(raw: dict[str, Any], index: int) -> Section:
             title=title,
             slate_seconds=t.get_num("slate_seconds", 5.0),
             optional=t.get_bool("optional"),
+            words=t.get_str("words"),
         )
     if "page" not in raw:
         raise ConfigError(f"{where}: needs 'page' (an HTML file) or 'clip' (a video file)")

{decktalk-0.2.0 → decktalk-0.2.1}/src/decktalk/stages/assemble.py

@@ -17,8 +17,9 @@
 4. EBU R128 loudness: pass one measures integrated loudness and true peak, pass two
    applies the gain that reaches the target and a true-peak limiter at the ceiling,
    oversampled at 192 kHz. The result is measured again and reported.
-5. Captions (srt and vtt) come from the word timestamps, and chapter markers from the
-   section titles are muxed into the mp4.
+5. Captions (srt and vtt) come from the word timestamps, plus the words file of any clip
+   section that names one, and chapter markers from the section titles are muxed into the
+   mp4. Consecutive sections with the same title share one chapter.
 6. Atomic publish: work file, then one rename to build/out/<name>.mp4, plus a
    timestamped copy.
 """
@@ -688,6 +689,32 @@ def build_captions(
     return cues
 
 
+def clip_captions(project: Project, rows: list[RenderedSection]) -> list[CaptionCue]:
+    """Cues for the speech inside each clip section that names a words file.
+
+    The words count from the clip's start and carry their own punctuation. A word that starts
+    after the clip's picture ends is dropped. A slate, or a clip with no audio, gets no captions.
+    """
+    starts = section_starts(rows)
+    cues: list[CaptionCue] = []
+    for r in rows:
+        sec = r.section
+        if not isinstance(sec, ClipSection) or not sec.words or r.audio is None:
+            continue
+        path = project.path(sec.words)
+        if not path.exists():
+            log.warning("section %s: words file missing: %s; the clip plays without captions", sec.key, sec.words)
+            continue
+        shift = starts[sec.key]
+        words = [
+            Word(w.word, round(shift + w.start, 3), round(shift + min(w.end, r.duration), 3))
+            for w in read_words(path)
+            if w.start < r.duration
+        ]
+        cues += caption_cues(words)
+    return cues
+
+
 def caption_texts(project: Project, timeline: Timeline) -> dict[str, str]:
     """The spoken text per section key, which lends the captions their punctuation and case.
 
@@ -706,15 +733,17 @@ def caption_texts(project: Project, timeline: Timeline) -> dict[str, str]:
 
 
 def build_chapters(rows: list[RenderedSection]) -> list[Chapter]:
+    """One chapter per section, where consecutive sections with the same title share one chapter."""
     starts = section_starts(rows)
-    return [
-        Chapter(
-            start=starts[r.section.key],
-            end=starts[r.section.key] + r.duration,
-            title=r.section.title or f"Section {r.section.number}",
-        )
-        for r in rows
-    ]
+    chapters: list[Chapter] = []
+    for r in rows:
+        start = starts[r.section.key]
+        title = r.section.title or f"Section {r.section.number}"
+        if chapters and chapters[-1].title == title:
+            chapters[-1] = Chapter(start=chapters[-1].start, end=start + r.duration, title=title)
+        else:
+            chapters.append(Chapter(start=start, end=start + r.duration, title=title))
+    return chapters
 
 
 def mux_chapters(src: Path, chapters: Path, dst: Path) -> None:
@@ -801,14 +830,16 @@ def assemble(project: Project, *, nomix: bool = False, loudnorm: bool = True, st
 
     starts = section_starts(rows)
     cues = build_captions(timeline, narration_offsets(rows, timeline, starts), caption_texts(project, timeline))
+    cues = sorted(cues + clip_captions(project, rows), key=lambda c: c.start)
+    chapters = build_chapters(rows)
     write_srt(paths["srt"], cues)
     write_vtt(paths["vtt"], cues)
-    write_chapters(paths["chapters"], build_chapters(rows))
+    write_chapters(paths["chapters"], chapters)
     log.info("[caps] %d cue(s) -> %s, %s", len(cues), paths["srt"].name, paths["vtt"].name)
     chaptered = out_dir / f".{project.name}.chapters.mp4"
     mux_chapters(work, paths["chapters"], chaptered)
     chaptered.replace(work)
-    log.info("[chap] %d chapter(s) -> %s", len(rows), paths["chapters"].name)
+    log.info("[chap] %d chapter(s) -> %s", len(chapters), paths["chapters"].name)
 
     if not work.exists() or work.stat().st_size == 0:
         raise ToolError("render produced no output")

{decktalk-0.2.0 → decktalk-0.2.1}/src/decktalk/stages/narrate.py

@@ -9,6 +9,8 @@ project maps to a clip are skipped.
 Each section is synthesized with word timestamps, cached by a hash of model, voice,
 settings and text, padded so speech ends at least min_tail_seconds before the file
 ends, then every section is concatenated with no gaps into build/audio/narration.mp3.
+A renumbered section keeps its take: when its key misses, an entry of the previous
+manifest with the same hash lends its files, copied to the new name.
 build/audio/timeline.json records each section's absolute start and end and every
 word at absolute time; the recorder and the assembler cut the visuals to it.
 
@@ -23,7 +25,8 @@ import hashlib
 import json
 import logging
 import re
-from dataclasses import dataclass
+import shutil
+from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
@@ -251,6 +254,54 @@ def text_hash(segment: Segment, cfg: NarrationConfig, provider_key: str, setting
     return hashlib.sha256(payload.encode()).hexdigest()[:16]
 
 
+def is_cached(entry: ManifestSegment | None, seg: Segment, digest: str, audio_dir: Path) -> bool:
+    """True when the entry holds this section's take under its current file names."""
+    return (
+        entry is not None
+        and entry.hash == digest
+        and entry.file == seg.filename
+        and (audio_dir / seg.filename).exists()
+        and (audio_dir / seg.words_filename).exists()
+    )
+
+
+def reusable_entry(
+    previous: Manifest | None, seg: Segment, digest: str, audio_dir: Path
+) -> tuple[str, ManifestSegment] | None:
+    """(key, entry) of a previous take of the same text under another section number, or None.
+
+    A section that was renumbered keeps its hash, because the hash has no section number in
+    it. Only the first spoken section carries the lead-in silence, so a take never moves into
+    or out of that place.
+    """
+    if previous is None or seg.lead_break or not previous.segments:
+        return None
+    first = min(previous.segments)
+    for key, entry in previous.segments.items():
+        if (
+            key != first
+            and key != seg.key
+            and entry.hash == digest
+            and (audio_dir / entry.file).exists()
+            and (audio_dir / entry.words_file).exists()
+        ):
+            return key, entry
+    return None
+
+
+def reuse_takes(moves: list[tuple[ManifestSegment, Segment]], audio_dir: Path) -> None:
+    """Copy each take to its new file names. Every source is copied aside first, so a move never
+    overwrites a file that another move still reads."""
+    staged: list[tuple[Path, Path]] = []
+    for i, (entry, seg) in enumerate(moves):
+        for j, (src, dst) in enumerate(((entry.file, seg.filename), (entry.words_file, seg.words_filename))):
+            tmp = audio_dir / f".reuse-{i}-{j}.tmp"
+            shutil.copyfile(audio_dir / src, tmp)
+            staged.append((tmp, audio_dir / dst))
+    for tmp, dst in staged:
+        tmp.replace(dst)
+
+
 def build_timeline(project: Project, manifest: Manifest, order: list[Segment]) -> Timeline:
     cfg = project.settings.narration
     keys = [s.key for s in order if s.key in manifest.segments]
@@ -332,6 +383,26 @@ def narrate(
         if unfilled and not allow_placeholders:
             raise ConfigError(f"unfilled placeholders {unfilled} in the script; fill them or pass allow_placeholders")
         provider = get_provider(project)
+        # A renumbered section keeps its take. Its files are copied to the new names before any
+        # section is voiced, so a new take never replaces a file that a move still needs.
+        moves: list[tuple[ManifestSegment, Segment]] = []
+        for seg in targets:
+            request = SpeechRequest(
+                text=seg.tts_text(cfg), model=model, voice_settings=voice_settings, output_format=cfg.output_format
+            )
+            digest = text_hash(seg, cfg, provider.cache_key(request), voice_settings)
+            if force or is_cached(manifest.segments.get(seg.key), seg, digest, project.audio_dir):
+                continue
+            found = reusable_entry(previous, seg, digest, project.audio_dir)
+            if found is not None:
+                key, entry = found
+                moves.append((entry, seg))
+                log.info("[move] %s  from %s, the same text under section %s", seg.filename, entry.file, int(key))
+        reuse_takes(moves, project.audio_dir)
+        for entry, seg in moves:
+            manifest.segments[seg.key] = replace(
+                entry, index=seg.index, title=seg.title, file=seg.filename, words_file=seg.words_filename
+            )
 
     by_index = {s.index: s for s in all_segments}
     order = [s.index for s in all_segments]
@@ -377,14 +448,7 @@ def narrate(
         )
         digest = text_hash(seg, cfg, provider.cache_key(request), voice_settings)
         entry = manifest.segments.get(seg.key)
-        if (
-            not force
-            and entry is not None
-            and entry.hash == digest
-            and entry.file == seg.filename
-            and out_path.exists()
-            and words_path.exists()
-        ):
+        if not force and entry is not None and is_cached(entry, seg, digest, project.audio_dir):
             # min_tail_seconds is not part of the hash, so a cached take made under a shorter
             # tail is padded here. ensure_tail measures the silence first, so a take that
             # already has enough is left untouched.