decktalk 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decktalk
-Version: 0.2.0
+Version: 0.3.0
 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
+1:1.1bowl            1.25     1.25    0.93    0.00    +30ms   +31ms  changed
+3:3.4name           84.72   123.32    2.76    0.00     +0ms    -4ms  changed
+8:7.1checked        10.03   238.31    0.83    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.3.0}/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
+1:1.1bowl            1.25     1.25    0.93    0.00    +30ms   +31ms  changed
+3:3.4name           84.72   123.32    2.76    0.00     +0ms    -4ms  changed
+8:7.1checked        10.03   238.31    0.83    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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.0"
+version = "0.3.0"
 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.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.0"
+version = "0.3.0"
 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.3.0}/src/decktalk/__init__.py

@@ -8,10 +8,10 @@ still move, and a rename is a breaking change once the project leaves the 0.x se
     project tables: Voice, Mix, Soundscape, Transition
     errors: DeckTalkError, ConfigError, MissingInputError, ProviderError, ToolError
     artifacts: Manifest, Timeline, Beats, Word, Sidecar
-    stages: narrate, resolve_beats, record, measure, check, assemble, verify, shoot,
-            soundscape, build, status
-    results: NarrateResult, BeatsResult, Recording, LeadMeasurement, RecordingCheck,
-             AssembleResult, VerifyResult, SoundscapeItem, BuildResult, StatusReport
+    stages: narrate, resolve_beats, preflight, record, measure, check, assemble, verify, shoot,
+            soundscape, build, status, cut_clip, spoken_words
+    results: NarrateResult, BeatsResult, PreflightResult, Recording, LeadMeasurement, RecordingCheck,
+             AssembleResult, VerifyResult, SoundscapeItem, BuildResult, StatusReport, ClipResult, SectionWords
     speech: SpeechProvider, SpeechRequest, register
 
 Everything under decktalk.media, everything under decktalk.providers other than the
@@ -31,21 +31,27 @@ from .stages import (
     AssembleResult,
     BeatsResult,
     BuildResult,
+    ClipResult,
     LeadMeasurement,
     NarrateResult,
+    PreflightResult,
     Recording,
     RecordingCheck,
+    SectionWords,
     SoundscapeItem,
     VerifyResult,
     assemble,
     build,
     check,
+    cut_clip,
     measure,
     narrate,
+    preflight,
     record,
     resolve_beats,
     shoot,
     soundscape,
+    spoken_words,
     verify,
 )
 from .status import StatusReport, status
@@ -60,6 +66,7 @@ __all__ = [
     "Beats",
     "BeatsResult",
     "BuildResult",
+    "ClipResult",
     "ClipSection",
     "ConfigError",
     "DeckTalkError",
@@ -69,11 +76,13 @@ __all__ = [
     "Mix",
     "NarrateResult",
     "PageSection",
+    "PreflightResult",
     "Project",
     "ProviderError",
     "Recording",
     "RecordingCheck",
     "Section",
+    "SectionWords",
     "Settings",
     "Sidecar",
     "Soundscape",
@@ -91,14 +100,17 @@ __all__ = [
     "assemble",
     "build",
     "check",
+    "cut_clip",
     "load_settings",
     "measure",
     "narrate",
+    "preflight",
     "record",
     "register",
     "resolve_beats",
     "shoot",
     "soundscape",
+    "spoken_words",
     "status",
     "verify",
 ]

{decktalk-0.2.0 → decktalk-0.3.0}/src/decktalk/_report.py

@@ -3,13 +3,16 @@
 from __future__ import annotations
 
 from .artifacts import Timeline
+from .config import NarrationConfig
 from .stages.beats import BeatsResult
+from .stages.clip import SectionWords
 from .stages.measure import LeadMeasurement, RecordingCheck
-from .stages.narrate import NarrateResult, Segment
+from .stages.narrate import NarrateResult, Segment, TakePlan, plan_totals
+from .stages.preflight import PreflightResult
 from .stages.soundscape import SoundscapeItem
 from .stages.verify import VerifyResult
 from .status import StatusReport, relpath
-from .verdicts import BLACK, OK, QUIET, SKIPPED, SPEECH_AT_CUT
+from .verdicts import BLACK, CHANGED, NO_CHANGE, OK, QUIET, SKIPPED, SPEECH_AT_CUT, THIN_CHANGE
 
 
 def mmss(seconds: float | None) -> str:
@@ -44,6 +47,28 @@ def segments_table(segments: list[Segment], wpm: int, result: NarrateResult | No
     return "\n".join(lines)
 
 
+def plan_table(plans: list[TakePlan], cfg: NarrationConfig, note: str | None = None) -> str:
+    """What a voiced narrate would do with each section: voice it, use its cached take, or move a take."""
+    lines = [f"{'#':>2}  {'section':<22} {'take':<10} {'sent':>6} {'spoken':>6}  reason"]
+    lines.append("-" * len(lines[0]))
+    for p in plans:
+        seg = p.segment
+        lines.append(
+            f"{seg.index:>2}  {seg.slug[:22]:<22} {p.status:<10} {len(seg.tts_text(cfg)):>6} "
+            f"{len(seg.spoken):>6}  {p.reason or '-'}"
+        )
+    t = plan_totals(plans, cfg)
+    lines.append("-" * len(lines[0]))
+    unknown = f", {t['unknown']} unknown" if t["unknown"] else ""
+    lines.append(
+        f"voice {t['synthesize']} section(s): {t['characters_sent']} characters sent, "
+        f"{t['characters_spoken']} spoken. {t['cached']} cached, {t['moved']} moved{unknown}."
+    )
+    if note:
+        lines.append(f"note: {note}")
+    return "\n".join(lines)
+
+
 def timeline_table(timeline: Timeline) -> str:
     lines = [f"{'#':>3}  {'section':<22} {'start':>7} {'end':>7} {'length':>7}"]
     for key, sec in timeline.sections.items():
@@ -72,6 +97,42 @@ def beats_table(result: BeatsResult) -> str:
     return "\n".join(lines)
 
 
+def preflight_table(result: PreflightResult) -> str:
+    """The take plan, the cues resolved on the words each section will have, and the frozen-frame estimates."""
+    root = result.root
+    voice = result.voice
+    lines = [f"voice: provider={voice['provider']} model={voice['model']}"]
+    lines.append(plan_table(result.takes, result.narration, result.note))
+    if result.placeholders:
+        lines.append(f"a voiced run refuses the unfilled placeholders {result.placeholders}")
+    lines += ["", beats_table(result.beats)]
+    if result.estimated:
+        lines.append(f"estimated words in sections {', '.join(result.estimated)}, which a voiced run will voice")
+    if result.frames is None:
+        lines += ["", "frames skipped (--no-frames)"]
+        return "\n".join(lines)
+    lines.append("")
+    lines.append(f"{'check':<18} {'step':<8} {'cue':>6} {'chg %':>7}  result")
+    for c in result.cues:
+        chg = f"{c.changed_percent:>7.2f}" if c.changed_percent is not None else f"{'-':>7}"
+        label = " ".join(part for part in (c.verdict, c.reason) if part)
+        label += f": {c.detail}" if c.detail else ""
+        label += f" ({c.note})" if c.note else ""
+        lines.append(f"{c.check:<18} {c.step or '-':<8} {c.cue_seconds:>6.2f} {chg}  {label}")
+    tally = {v: sum(c.verdict == v for c in result.cues) for v in (CHANGED, THIN_CHANGE, NO_CHANGE, SKIPPED)}
+    counts = ", ".join(f"{n} {v}" for v, n in tally.items() if n) or "none"
+    where = relpath(result.frames, root) if root is not None else result.frames
+    lines.append(f"{len(result.cues)} cue(s): {counts}. Frozen frames in {where}")
+    if result.carries:
+        lines.append("")
+        lines.append(f"{'sec':>3} {'chg %':>7}  result")
+        for k in result.carries:
+            chg = f"{k.changed_percent:>7.2f}" if k.changed_percent is not None else f"{'-':>7}"
+            label = " ".join(part for part in (k.verdict, k.reason) if part) + (f": {k.detail}" if k.detail else "")
+            lines.append(f"{k.key:>3} {chg}  {label}")
+    return "\n".join(lines)
+
+
 def leads_table(rows: list[LeadMeasurement]) -> str:
     lines = [f"{'sec':>3} {'trim':>7} {'wall':>7}  method"]
     lines += [f"{r.key:>3} {r.lead_in_seconds:>7.3f} {r.wallclock_seconds:>7.3f}  {r.method}" for r in rows]
@@ -100,6 +161,11 @@ def verify_table(result: VerifyResult) -> str:
         lines.append(f"{'sec':>3} {'cut at':>8} {'before cut':>11}  result")
         for c in result.cuts:
             lines.append(f"{c.key:>3} {c.cut_at:>8.2f} {c.rms_db:>8.1f} dB  {QUIET if c.ok else SPEECH_AT_CUT}")
+    if result.carries:
+        lines.append("")
+        lines.append(f"{'sec':>3} {'cut at':>8} {'chg %':>7}  result")
+        for k in result.carries:
+            lines.append(f"{k.key:>3} {k.cut_at:>8.2f} {k.changed_percent:>7.2f}  {k.verdict}")
     if result.cues:
         lines.append("")
         av = any(c.av_ms is not None for c in result.cues)
@@ -156,6 +222,23 @@ def status_table(report: StatusReport) -> str:
     return "\n".join(lines)
 
 
+def words_table(sections: list[SectionWords]) -> str:
+    """The text of `decktalk words`: each section's words, in seconds after the section starts."""
+    lines: list[str] = []
+    for sec in sections:
+        notes = [f"{sec.duration:.2f}s"]
+        if sec.lead_seconds:
+            notes.append(f"lead {sec.lead_seconds:g}s")
+        if sec.estimated:
+            notes.append("estimated")
+        if lines:
+            lines.append("")
+        lines.append(f"== {sec.key} {sec.title}  ({', '.join(notes)})")
+        lines.append("  start     end  word")
+        lines += [f"{w.start:7.3f} {w.end:7.3f}  {text}" for w, text in zip(sec.words, sec.texts, strict=True)]
+    return "\n".join(lines) or "no spoken sections"
+
+
 def soundscape_table(items: list[SoundscapeItem]) -> str:
     lines = []
     for it in items:

{decktalk-0.2.0 → decktalk-0.3.0}/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
@@ -112,6 +113,7 @@ class TimelineSection:
     duration: float
     speech_end: float | None
     words: list[Word] = field(default_factory=list)
+    lead_seconds: float = 0.0  # Silence joined in before the take, part of `duration`. The words already include it.
 
     @classmethod
     def from_dict(cls, d: dict[str, Any]) -> Self:
@@ -122,6 +124,7 @@ class TimelineSection:
             duration=float(d["duration"]),
             speech_end=None if d.get("speech_end") is None else float(d["speech_end"]),
             words=[Word.from_dict(w) for w in d.get("words", [])],
+            lead_seconds=float(d.get("lead_seconds", 0.0)),
         )
 
 
@@ -222,6 +225,7 @@ class Sidecar:
     lead_seconds: float  # wall-clock estimate from the recorder
     lead_in_seconds: float | None = None  # first clean frame after the magenta cover: narration t=0
     lead_method: str | None = None
+    lead_in_hash: str | None = None  # the sha256 prefix of the webm that measure read, so a stale measure shows
     warnings: list[str] = field(default_factory=list)
     page_errors: list[str] = field(default_factory=list)  # uncaught exceptions, or no runtime catalog at all
     # (seconds, ms) where the page stalled. The time is None for a gap that ended before narration t=0.
@@ -272,14 +276,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 +298,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 +405,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: