decktalk 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decktalk
-Version: 0.2.1
+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
@@ -162,9 +162,9 @@ A browser does not start recording at a known time, so DeckTalk does not use a t
 <!-- 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           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
+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.1 → decktalk-0.3.0}/README.md

@@ -129,9 +129,9 @@ A browser does not start recording at a known time, so DeckTalk does not use a t
 <!-- 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           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
+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.1 → decktalk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.1"
+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"

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

@@ -1,6 +1,6 @@
 [project]
 name = "decktalk"
-version = "0.2.1"
+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"

{decktalk-0.2.1 → 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.1 → 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.1 → decktalk-0.3.0}/src/decktalk/artifacts.py

@@ -113,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:
@@ -123,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)),
         )
 
 
@@ -223,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.

{decktalk-0.2.1 → decktalk-0.3.0}/src/decktalk/cli.py

@@ -4,7 +4,9 @@
     decktalk setup                    fetch headless Chromium, ffmpeg, and KaTeX (once per machine)
     decktalk doctor                   report what is installed
     decktalk narrate [--silent]       script.md -> build/audio (ElevenLabs, word timestamps, timeline)
+    decktalk narrate --dry-run        what a voiced run would send, cache, or move (--json)
     decktalk beats                    cues.json -> build/audio/beats.json
+    decktalk preflight                takes, cues and frozen reveals before a voiced build: no credits, no recording
     decktalk soundscape               ambience, sfx, underscore (ElevenLabs)
     decktalk record                   pages -> build/rec/NN-scene.webm (Chromium)
     decktalk measure                  find narration t=0 in each recording
@@ -12,6 +14,9 @@
     decktalk assemble                 ffmpeg -> build/out/<name>.mp4
     decktalk verify [SEC:CUE ...]     section starts, cuts, and every cue landing on the final mp4
     decktalk shots                    per-step screenshots, or frames from a playing section
+    decktalk words [--json]           each spoken section's words, in seconds after the section starts
+    decktalk clip N --from S --to E --out FILE
+                                      a span of a built section and its narration -> a clip and its words file
     decktalk build [--silent]         narrate -> beats -> record -> measure -> check -> assemble -> verify
     decktalk status                   timeline and what is built
     decktalk runtime                  copy the packaged decktalk-runtime.js into the project
@@ -19,7 +24,7 @@
 Every project command takes --project/-p DIR (default: DECKTALK_PROJECT, else the current
 directory). The -v and -q flags go before or after the command name.
 Tuning flags such as --preset override decktalk.toml and DECKTALK_* env for one run.
-status, beats, check, verify and doctor take --json, --strict and --no-fail. They exit 1
+status, beats, preflight, check, verify and doctor take --json, --strict and --no-fail. They exit 1
 on a certain finding, and on an uncertain one (a verdict ending in ?) only with --strict.
 """
 
@@ -46,7 +51,8 @@ JSON_HELP = "Print the result as one JSON object on stdout instead of the tables
 ALLOW_UNKNOWN_HELP = "Continue when a cue id in cues.json appears nowhere in the page that plays it."
 BUILD_STRICT_HELP = (
     "fail on a missing clip or recording instead of substituting a slate "
-    "(a clip section with optional = true still plays its slate)"
+    "(a clip section with optional = true still plays its slate), "
+    "and on a recording that measure has not read since it was recorded"
 )
 
 
@@ -104,6 +110,7 @@ def _verify_findings(result: Any) -> Findings:
     verdicts: Iterable[str] = [
         *(OK if s.ok else BLACK for s in result.starts),
         *(QUIET if c.ok else SPEECH_AT_CUT for c in result.cuts),
+        *(c.verdict for c in result.carries),
         *(c.verdict for c in result.cues),
     ]
     return count(verdicts)
@@ -163,19 +170,35 @@ def cmd_runtime(args: argparse.Namespace) -> int:
 
 
 def cmd_narrate(args: argparse.Namespace) -> int:
-    from .stages.narrate import narrate, script_segments
+    from .stages.narrate import narrate, narration_plan, plan_totals, script_segments
 
+    if args.json and not args.dry_run:
+        args.parser.error("--json needs --dry-run")
     project = _project(args)
     cfg = project.settings.narration
     if args.dry_run:
         _all, spoken = script_segments(project)
         targets = [s for s in spoken if not args.only or s.index in set(args.only)]
+        model = args.model or project.voice.model or cfg.model
+        plans, note = narration_plan(project, targets, model=model, force=args.force)
+        if args.json:
+            payload = {
+                "voice": {"provider": project.voice.provider, "model": model, "settings": project.voice.api_settings()},
+                "note": note,
+                "sections": [{**p.to_dict(cfg), "text": p.segment.tts_text(cfg)} for p in plans],
+                "totals": plan_totals(plans, cfg),
+            }
+            doc = {"command": args.cmd, "version": __version__, "ok": True, "findings": Findings().to_dict()}
+            print(json.dumps({**doc, args.cmd: payload}, indent=2))
+            return 0
         for seg in targets:
             print(f"=== {seg.key} {seg.title}  -> {seg.filename}")
             print(seg.tts_text(cfg))
             print()
-        print(f"voice: model={args.model or project.voice.model or cfg.model} {project.voice.api_settings()}")
+        print(f"voice: model={model} {project.voice.api_settings()}")
         print(_report.segments_table(targets, cfg.words_per_minute))
+        print()
+        print(_report.plan_table(plans, cfg, note))
         unfilled = sorted({p for s in targets for p in s.placeholders})
         if unfilled:
             print(f"\nnote: unfilled placeholders {unfilled}; fill them before the real run.")
@@ -214,6 +237,15 @@ def cmd_beats(args: argparse.Namespace) -> int:
     return _finish(args, findings, result.to_dict(project.root), lambda: _report.beats_table(result))
 
 
+def cmd_preflight(args: argparse.Namespace) -> int:
+    from .stages.preflight import preflight
+
+    project = _project(args)
+    result = preflight(project, only=_only(args.only), frames=not args.no_frames, model=args.model)
+    findings = result.findings(allow_unknown=args.allow_unknown)
+    return _finish(args, findings, result.to_dict(project.root), lambda: _report.preflight_table(result))
+
+
 def cmd_soundscape(args: argparse.Namespace) -> int:
     from .stages.soundscape import soundscape
 
@@ -277,6 +309,46 @@ def cmd_shots(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_words(args: argparse.Namespace) -> int:
+    from .stages.clip import spoken_words
+
+    project = _project(args)
+    sections = spoken_words(project, only=_only(args.only))
+    if args.json:
+        payload = {"sections": [s.to_dict() for s in sections]}
+        doc = {"command": args.cmd, "version": __version__, "ok": True, "findings": Findings().to_dict()}
+        print(json.dumps({**doc, args.cmd: payload}, indent=2))
+        return 0
+    print(_report.words_table(sections))
+    return 0
+
+
+def cmd_clip(args: argparse.Namespace) -> int:
+    from .stages.clip import cut_clip
+    from .status import relpath
+
+    project = _project(args)
+    result = cut_clip(
+        project,
+        args.section,
+        start=args.start,
+        end=args.end,
+        out=args.out,
+        words_out=args.words,
+        gain_db=args.gain,
+        hold_seconds=args.hold,
+    )
+    video, words = (relpath(p, project.root) for p in (result.video, result.words_file))
+    source = f"{args.section:02d}-section.mp4"
+    print(
+        f"wrote {video}  ({result.duration:.2f}s: frames {result.first_frame} to {result.last_frame} of {source}, "
+        f"{result.start:.2f} to {result.end:.2f}s, hold {result.hold_seconds:g}s, gain {result.gain_db:+g} dB)"
+    )
+    print(f"wrote {words}  ({len(result.words)} words)")
+    print(f'use it in a clip section: clip = "{video}" and words = "{words}"')
+    return 0
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     from .status import status
 
@@ -372,19 +444,35 @@ def build_parser() -> argparse.ArgumentParser:
 
     s = proj(sub.add_parser("narrate", help="synthesize narration with word timestamps"))
     s.add_argument("--only", type=int, action="append", help=only_help)
-    s.add_argument("--force", action="store_true", help="ignore the text-hash cache")
+    s.add_argument(
+        "--force", action="store_true", help="ignore the text-hash cache, and let --silent replace voiced takes"
+    )
     s.add_argument(
         "--allow-placeholders", action="store_true", help="synthesize a section that still has a [CAPITAL] placeholder"
     )
-    s.add_argument("--dry-run", action="store_true", help="parse and print without any API call")
+    s.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="print each section's text and what a voiced run would voice, cache, or move, without any API call",
+    )
+    s.add_argument("--json", action="store_true", help="with --dry-run, print the plan as one JSON object on stdout")
     s.add_argument("--silent", action="store_true", help="silent placeholders, no API key")
     s.add_argument("--model", help="ElevenLabs model for this run")
-    s.set_defaults(fn=cmd_narrate)
+    s.set_defaults(fn=cmd_narrate, parser=s)
 
     s = policy(proj(sub.add_parser("beats", help="resolve cue phrases to timestamps")))
     s.add_argument("--allow-unknown", action="store_true", help=ALLOW_UNKNOWN_HELP)
     s.set_defaults(fn=cmd_beats)
 
+    s = policy(proj(sub.add_parser("preflight", help="plan the takes, resolve the cues, and estimate every reveal")))
+    s.add_argument("--only", type=int, action="append", help=only_help)
+    s.add_argument(
+        "--no-frames", action="store_true", help="skip the frozen frames, so no browser starts and nothing is written"
+    )
+    s.add_argument("--model", help="speech model to check the narration cache for")
+    s.add_argument("--allow-unknown", action="store_true", help=ALLOW_UNKNOWN_HELP)
+    s.set_defaults(fn=cmd_preflight)
+
     s = proj(sub.add_parser("soundscape", help="generate ambience, sfx and underscore"))
     s.add_argument("--only", action="append", help="one item: ambience, music, or an effect name (repeat for several)")
     s.add_argument("--force", action="store_true", help="regenerate even if the file exists")
@@ -429,11 +517,33 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--at", type=float, action="append", help="seconds after narration t=0 (with --section)")
     s.set_defaults(fn=cmd_shots, parser=s)
 
+    s = proj(sub.add_parser("words", help="each spoken section's words, in seconds after the section starts"))
+    s.add_argument("--only", type=int, action="append", help=only_help)
+    s.add_argument("--json", action="store_true", help=JSON_HELP)
+    s.set_defaults(fn=cmd_words)
+
+    s = proj(sub.add_parser("clip", help="cut a span of a built section and its narration into a clip"))
+    s.add_argument("section", type=int, help="the page section to cut from")
+    s.add_argument(
+        "--from", dest="start", type=float, required=True, metavar="SECONDS", help="start, after the section starts"
+    )
+    s.add_argument(
+        "--to", dest="end", type=float, required=True, metavar="SECONDS", help="end, after the section starts"
+    )
+    s.add_argument("--out", required=True, help="the clip file, relative to the project, such as media/open.mp4")
+    s.add_argument("--words", help="the words file (default: the clip's path with .words.json)")
+    s.add_argument("--gain", type=float, default=0.0, metavar="DB", help="gain on the clip's sound, in dB")
+    s.add_argument("--hold", type=float, default=0.0, metavar="SECONDS", help="hold the last frame this long, silent")
+    encoding(s)
+    s.set_defaults(fn=cmd_clip)
+
     policy(proj(sub.add_parser("status", help="what is built"))).set_defaults(fn=cmd_status)
 
     s = proj(sub.add_parser("build", help="run the whole pipeline"))
     s.add_argument("--silent", action="store_true", help="placeholder narration, no API key")
-    s.add_argument("--force", action="store_true", help="re-synthesize every section")
+    s.add_argument(
+        "--force", action="store_true", help="re-synthesize every section, and let --silent replace voiced takes"
+    )
     s.add_argument(
         "--only", type=int, action="append", help="re-record only these sections (repeat the flag for several)"
     )

{decktalk-0.2.1 → decktalk-0.3.0}/src/decktalk/config.py

@@ -121,6 +121,8 @@ class VerifyConfig:
     diff_level: int = 40  # Luma difference that a pixel must exceed to count as changed, for probes and control shares.
     min_changed_percent: float = 0.1  # Smallest changed share, in percent, that the reported probe needs.
     min_margin_percent: float = 0.1  # Smallest margin, in percentage points, that the reported probe needs.
+    thin_change_factor: float = 3.0  # A passing cue whose changed share or margin is below this many times its floor
+    # reads `THIN CHANGE?`, an uncertain finding. 1 turns the warning off.
     onset_percent: float = 0.01  # Rise in changed share from one frame to the next that marks the onset.
     # It is in percentage points. 0.01 is about 13 pixels.
     onset_diff_level: int = 12  # Luma difference that a pixel must exceed to count as changed, for the onset scan only.
@@ -131,6 +133,8 @@ class VerifyConfig:
     visible_ymax: float = 60  # The start check reports `BLACK` when the brightest luma of its frame is at most this.
     cut_window_seconds: float = 0.15  # Seconds of narration before each cut that the cut check measures.
     cut_max_db: float = -40.0  # Loudest RMS level of the cut window, in dBFS, that passes the cut check.
+    max_pop_percent: float = 0.1  # Largest changed share, in percent, across the cut into a section that sets
+    # `carries_previous`. A larger share reads `POP AT CUT`.
     probe_width: int = 480  # Width in pixels that frames are scaled to before a comparison.
     probe_height: int = 270  # Height in pixels that frames are scaled to before a comparison.
     block_width: int = 240  # Width in pixels of the block-averaged copy of each frame that confirms an onset.

{decktalk-0.2.1 → decktalk-0.3.0}/src/decktalk/media/ffmpeg.py

@@ -177,15 +177,28 @@ def rms_db(path: Path, start: float, seconds: float) -> float:
     return -120.0 if m[-1] == "-inf" else float(m[-1])
 
 
+SILENCE_END_TOLERANCE_SECONDS = 0.06  # A silence that ends this close to the end of the file runs to the end.
+MP3_FRAME_SAMPLES = 1152  # Samples in one MPEG-1 Layer III frame.
+
+
 def trailing_silence(path: Path, *, noise_db: int = -35, min_run: float = 0.05) -> float:
-    """Seconds of silence at the end of an audio file."""
+    """Seconds of silence at the end of an audio file.
+
+    The container length includes the encoder padding, which decodes to nothing. For an mp3 that
+    padding is up to about 50 ms, so silencedetect reports the last silence ending that far before
+    the container end. A silence that ends within one audio frame or SILENCE_END_TOLERANCE_SECONDS
+    of the end, whichever is longer, counts as running to the end.
+    """
     duration = probe_duration(path)
     err = stderr("-i", str(path), "-af", f"silencedetect=noise={noise_db}dB:d={min_run}", "-f", "null", "-")
     starts = re.findall(r"silence_start: ([0-9.]+)", err)
     ends = re.findall(r"silence_end: ([0-9.]+)", err)
     if not starts:
         return 0.0
-    if len(ends) < len(starts) or float(ends[-1]) >= duration - 0.05:
+    rate = re.search(r"Audio: [^\n]*?(\d+) Hz", err)
+    frame = MP3_FRAME_SAMPLES / int(rate.group(1)) if rate and int(rate.group(1)) > 0 else 0.0
+    tolerance = max(SILENCE_END_TOLERANCE_SECONDS, frame)
+    if len(ends) < len(starts) or float(ends[-1]) >= duration - tolerance:
         return round(duration - float(starts[-1]), 3)
     return 0.0
 
@@ -250,15 +263,20 @@ def pad_tail(path: Path, seconds: float, *, bitrate: str) -> None:
     tmp.replace(path)
 
 
-def concat_audio(files: list[Path], out: Path, *, bitrate: str, sample_rate: int) -> None:
+def concat_audio(
+    files: list[Path], out: Path, *, bitrate: str, sample_rate: int, leads: list[float] | None = None
+) -> None:
+    """Join audio files back to back. `leads` gives each file seconds of silence before it, in whole milliseconds."""
     inputs: list[str] = []
     for f in files:
         inputs += ["-i", str(f)]
-    labels = "".join(f"[{i}:a]" for i in range(len(files)))
+    delays = [int(round(x * 1000)) for x in (leads or [])] + [0] * len(files)
+    pads = "".join(f"[{i}:a]adelay=delays={delays[i]}:all=1[l{i}];" for i in range(len(files)) if delays[i] > 0)
+    labels = "".join(f"[l{i}]" if delays[i] > 0 else f"[{i}:a]" for i in range(len(files)))
     run(
         *inputs,
         "-filter_complex",
-        f"{labels}concat=n={len(files)}:v=0:a=1[a]",
+        f"{pads}{labels}concat=n={len(files)}:v=0:a=1[a]",
         "-map",
         "[a]",
         "-c:a",
@@ -386,6 +404,21 @@ def changed_pixels_percent(path: Path, t1: float, t2: float, *, level: int, widt
     return (float(m.group(1)) / 255 * 100) if m else 0.0
 
 
+def changed_images_percent(a: Path, b: Path, *, level: int, width: int, height: int) -> float:
+    """Share (0-100) of pixels whose luma differs by more than `level` between two still images.
+
+    Both images are scaled to width x height and read as luma, as the frames of changed_pixels_percent are.
+    """
+    err = stderr(
+        "-i", str(a), "-i", str(b), "-filter_complex",
+        f"[0:v]scale={width}:{height},format=gray[a];[1:v]scale={width}:{height},format=gray[b];"
+        f"[a][b]blend=all_mode=difference,{_changed_mask(level)}",
+        "-frames:v", "1", "-f", "null", "-",
+    )  # fmt: skip
+    m = re.search(r"YAVG=([0-9.]+)", err)
+    return (float(m.group(1)) / 255 * 100) if m else 0.0
+
+
 def changed_series(
     path: Path, ref_t: float, start: float, end: float, *, fps: int, level: int, width: int, height: int
 ) -> list[tuple[float, float]]: