decktalk 0.1.0__py3-none-any.whl

decktalk/__init__.py

@@ -0,0 +1,59 @@
+"""DeckTalk: narrated presentation videos, cut to the word.
+
+Public API (stable within a minor version once 1.0 is reached; before that, the file
+formats and the page contract are stable and the Python names below may still move):
+
+    Project, Section types, Settings, load_settings
+    errors: DeckTalkError, ConfigError, MissingInputError, ProviderError, ToolError
+    artifacts: Manifest, Timeline, Beats, Word, Sidecar
+    stages: narrate, resolve_beats, record, measure, check, assemble, verify, shoot,
+            soundscape, build
+
+Everything under decktalk.media, decktalk.providers and names starting with an
+underscore is internal.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .artifacts import Beats, Manifest, Sidecar, Timeline, Word
+from .config import Settings, load_settings
+from .errors import ConfigError, DeckTalkError, MissingInputError, ProviderError, ToolError
+from .project import ClipSection, PageSection, Project, Section
+from .stages import assemble, build, check, measure, narrate, record, resolve_beats, shoot, soundscape, verify
+
+try:
+    __version__ = version("decktalk")
+except PackageNotFoundError:  # running from a checkout without an install
+    __version__ = "0+unknown"
+
+__all__ = [
+    "Beats",
+    "ClipSection",
+    "ConfigError",
+    "DeckTalkError",
+    "Manifest",
+    "MissingInputError",
+    "PageSection",
+    "Project",
+    "ProviderError",
+    "Section",
+    "Settings",
+    "Sidecar",
+    "Timeline",
+    "ToolError",
+    "Word",
+    "__version__",
+    "assemble",
+    "build",
+    "check",
+    "load_settings",
+    "measure",
+    "narrate",
+    "record",
+    "resolve_beats",
+    "shoot",
+    "soundscape",
+    "verify",
+]

decktalk/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m decktalk` runs the CLI."""
+
+from .cli import main
+
+raise SystemExit(main())

decktalk/_env.py

@@ -0,0 +1,70 @@
+"""Build a dataclass tree from defaults, a nested mapping (parsed TOML), and environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import fields, is_dataclass
+from types import UnionType
+from typing import Any, Union, cast, get_args, get_origin, get_type_hints
+
+
+def from_env[T](
+    cls: type[T],
+    overrides: dict[str, str] | None = None,
+    prefixes: list[str] | None = None,
+    base: dict[str, Any] | None = None,
+    environ: dict[str, str] | None = None,
+) -> T:
+    """Instantiate a dataclass recursively.
+
+    Precedence, lowest to highest: the dataclass default, `base` (a nested mapping keyed
+    by field name, for example a parsed TOML file with one table per nested dataclass),
+    then the environment variable named PREFIX_FIELD (upper case, nested names joined
+    with underscores). `overrides` maps a computed env name to an alias. `environ`
+    replaces os.environ, for tests.
+    """
+    overrides = overrides or {}
+    prefixes = prefixes or []
+    base = base or {}
+    env = os.environ if environ is None else environ
+
+    def is_optional(t: Any) -> bool:
+        origin = get_origin(t)
+        args = get_args(t)
+        return origin in (Union, UnionType) and len(args) == 2 and args[1] is type(None)
+
+    hints = get_type_hints(cls)
+    args: dict[str, Any] = {}
+    for f in fields(cast(Any, cls)):
+        ftype = hints.get(f.name, f.type)
+        if is_dataclass(ftype):
+            sub = base.get(f.name)
+            args[f.name] = from_env(
+                cast(type[Any], ftype),
+                overrides,
+                [*prefixes, f.name],
+                sub if isinstance(sub, dict) else None,
+                environ,
+            )
+            continue
+        env_name = "_".join([*prefixes, f.name]).upper()
+        key = overrides.get(env_name, env_name)
+        raw: Any = env.get(key)
+        if raw is None and f.name in base:
+            raw = base[f.name]
+        if raw is None:
+            continue
+        if ftype is bool:
+            args[f.name] = raw if isinstance(raw, bool) else str(raw).lower() not in ("false", "0", "no", "")
+        elif is_optional(ftype):
+            inner = get_args(ftype)[0]
+            args[f.name] = raw if isinstance(raw, inner) else inner(raw)
+        elif get_origin(ftype) is tuple:
+            items = raw.split(",") if isinstance(raw, str) else list(raw)
+            inner = get_args(ftype)[0] if get_args(ftype) else str
+            args[f.name] = tuple(inner(x) for x in items)
+        elif isinstance(ftype, type):
+            args[f.name] = raw if isinstance(raw, ftype) else ftype(raw)
+        else:
+            args[f.name] = raw
+    return cls(**args)

decktalk/_report.py

@@ -0,0 +1,120 @@
+"""Tables the CLI prints from stage results. Internal."""
+
+from __future__ import annotations
+
+from .artifacts import Timeline
+from .stages.beats import BeatsResult
+from .stages.measure import LeadMeasurement, RecordingCheck
+from .stages.narrate import NarrateResult, Segment
+from .stages.soundscape import SoundscapeItem
+from .stages.verify import VerifyResult
+
+
+def mmss(seconds: float | None) -> str:
+    if seconds is None:
+        return "  --  "
+    return f"{int(seconds // 60)}:{int(round(seconds % 60)):02d}"
+
+
+def segments_table(segments: list[Segment], wpm: int, result: NarrateResult | None = None) -> str:
+    lines = [f"{'#':>2}  {'section':<22} {'words':>5}  {'est':>5}  {'target':>6}  {'actual':>6}  placeholders"]
+    lines.append("-" * len(lines[0]))
+    total_words = total_est = total_actual = 0.0
+    for seg in segments:
+        est = seg.word_count / wpm * 60
+        total_words += seg.word_count
+        total_est += est
+        actual = None
+        if result is not None:
+            entry = result.manifest.segments.get(seg.key)
+            if entry:
+                actual = entry.duration_seconds
+                total_actual += actual
+        ph = ",".join(seg.placeholders) if seg.placeholders else "-"
+        lines.append(
+            f"{seg.index:>2}  {seg.slug[:22]:<22} {seg.word_count:>5}  {mmss(est):>5}  "
+            f"{mmss(seg.target_seconds):>6}  {mmss(actual):>6}  {ph}"
+        )
+    lines.append("-" * len(lines[0]))
+    actual_total = mmss(total_actual) if total_actual else "  --  "
+    lines.append(f"{'':>2}  {'total':<22} {int(total_words):>5}  {mmss(total_est):>5}  {'':>6}  {actual_total:>6}")
+    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():
+        lines.append(
+            f"{int(key):>3}  {sec.title[:22]:<22} {mmss(sec.start):>7} {mmss(sec.end):>7} {sec.duration:>7.1f}"
+        )
+    est = "  (estimated: silent placeholders)" if timeline.estimated else ""
+    lines.append(f"     narration total {mmss(timeline.total_seconds)}{est}")
+    return "\n".join(lines)
+
+
+def beats_table(result: BeatsResult) -> str:
+    lines = [f"{'sec':>3}  {'speech':>6}  {'need':>5}  cues"]
+    for s in result.sections:
+        if s.skipped:
+            lines.append(f"{s.key:>3}  {'--':>6}  {s.min_seconds or '-':>5}  ({s.skipped})")
+            continue
+        cues = ",".join(f"{k}@{v}" for k, v in s.resolved.items()) or "-"
+        lines.append(f"{s.key:>3}  {s.speech_end:>6.1f}  {str(s.min_seconds or '-'):>5}  {cues}")
+        for note in s.notes:
+            lines.append(f"{'':>3}  {'':>6}  {'':>5}  ! {note}")
+    tail = f"{len(result.beats.sections)} sections with cues; {result.unresolved} unresolved"
+    if result.estimated:
+        tail += "  (estimated words: times are placeholders)"
+    lines.append(tail)
+    return "\n".join(lines)
+
+
+def leads_table(rows: list[LeadMeasurement]) -> str:
+    lines = [f"{'sec':>3} {'trim':>7} {'flash':>6} {'wall':>7}  method"]
+    lines += [
+        f"{r.key:>3} {r.lead_in_seconds:>7.3f} {r.flash_seconds:>6.3f} {r.wallclock_seconds:>7.3f}  {r.method}"
+        for r in rows
+    ]
+    return "\n".join(lines)
+
+
+def checks_table(rows: list[RecordingCheck]) -> str:
+    lines = [f"{'sec':<4} {'webm_s':<8} {'want_s':<8} {'Y10':<6} {'Y50':<6} {'Y90':<6} {'MAX50':<6}  verdict"]
+    for r in rows:
+        lines.append(
+            f"{r.key:<4} {r.duration:<8.1f} {r.wanted:<8.1f} {r.y10:<6.0f} {r.y50:<6.0f} {r.y90:<6.0f} "
+            f"{r.max50:<6.0f}  {r.verdict}"
+        )
+    return "\n".join(lines)
+
+
+def verify_table(result: VerifyResult) -> str:
+    lines = [f"{'sec':>3} {'start':>8} {'probe':>8} {'YAVG':>6} {'YMAX':>6}  result"]
+    for s in result.starts:
+        lines.append(
+            f"{s.key:>3} {s.start:>8.2f} {s.probe_at:>8.2f} {s.yavg:>6.0f} {s.ymax:>6.0f}  {'ok' if s.ok else 'BLACK'}"
+        )
+    lines.append(f"total {result.total_seconds:.2f}s; {result.black_starts} black section start(s)")
+    if result.cues:
+        lines.append("")
+        lines.append(f"{'check':<18} {'cue':>6} {'at':>8} {'chg %':>7} {'ctl %':>7}  result")
+        for c in result.cues:
+            if c.cue_seconds is None:
+                lines.append(f"{c.check:<18} {'-':>6} {'-':>8} {'-':>7} {'-':>7}  {c.note or 'MISSING'}")
+            else:
+                lines.append(
+                    f"{c.check:<18} {c.cue_seconds:>6.2f} {c.final_seconds or 0:>8.2f} {c.changed_percent or 0:>7.2f} "
+                    f"{c.control_percent or 0:>7.2f}  {'changed' if c.ok else 'NO CHANGE'}"
+                )
+    return "\n".join(lines)
+
+
+def soundscape_table(items: list[SoundscapeItem]) -> str:
+    lines = []
+    for it in items:
+        dur = f" ({it.duration_seconds}s)" if it.duration_seconds else ""
+        lines.append(f"== {it.name} -> {it.out}  [{it.status}{dur}]")
+        lines.append(f"   POST {it.endpoint}")
+        for r in it.requests:
+            lines.append(f"   {r}")
+    return "\n".join(lines) or "nothing to generate"

decktalk/artifacts.py

@@ -0,0 +1,232 @@
+"""Typed build artifacts and their JSON files under build/.
+
+These file shapes are part of the public contract: the page runtime and users' own
+scripts read them. Field names match the JSON keys.
+
+    build/audio/manifest.json     Manifest: one entry per narrated section
+    build/audio/NN-slug.words.json  list[Word]
+    build/audio/timeline.json     Timeline: absolute section and word times in narration.mp3
+    build/audio/beats.json        Beats: {"NN": "cue@seconds,..."} relative to the section start
+    build/rec/NN-scene.json       Sidecar: what the recorder did and where t=0 landed
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Self
+
+
+def _read_json(path: Path) -> Any:
+    return json.loads(path.read_text())
+
+
+def _write_json(path: Path, data: Any, indent: int = 2) -> None:
+    """Write atomically: a reader never sees a half-written file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text(json.dumps(data, indent=indent) + "\n")
+    tmp.replace(path)
+
+
+@dataclass(frozen=True)
+class Word:
+    word: str
+    start: float
+    end: float
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Self:
+        return cls(word=str(d["word"]), start=float(d["start"]), end=float(d["end"]))
+
+
+def read_words(path: Path) -> list[Word]:
+    if not path.exists():
+        return []
+    return [Word.from_dict(w) for w in _read_json(path)]
+
+
+def write_words(path: Path, words: list[Word]) -> None:
+    _write_json(path, [asdict(w) for w in words], indent=1)
+
+
+@dataclass
+class ManifestSegment:
+    index: int
+    title: str
+    file: str
+    words_file: str
+    hash: str
+    words: int
+    est_seconds: float
+    duration_seconds: float
+    target_seconds: float | None = None
+    speech_end_seconds: float | None = None
+    tail_padded_seconds: float = 0.0
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Self:
+        return cls(**{k: v for k, v in d.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class Manifest:
+    script: str
+    model: str
+    output_format: str
+    estimated: bool = False
+    estimate_basis: str = ""
+    segments: dict[str, ManifestSegment] = field(default_factory=dict)
+    total_seconds: float = 0.0
+
+    @classmethod
+    def load(cls, path: Path) -> Self | None:
+        if not path.exists():
+            return None
+        d = _read_json(path)
+        segs = {k: ManifestSegment.from_dict(v) for k, v in d.get("segments", {}).items()}
+        return cls(
+            script=str(d.get("script", "")),
+            model=str(d.get("model", "")),
+            output_format=str(d.get("output_format", "")),
+            estimated=bool(d.get("estimated", False)),
+            estimate_basis=str(d.get("estimate_basis", "")),
+            segments=dict(sorted(segs.items())),
+            total_seconds=float(d.get("total_seconds", 0.0)),
+        )
+
+    def save(self, path: Path) -> None:
+        self.segments = dict(sorted(self.segments.items()))
+        self.total_seconds = round(sum(s.duration_seconds for s in self.segments.values()), 3)
+        _write_json(path, asdict(self))
+
+
+@dataclass
+class TimelineSection:
+    title: str
+    start: float
+    end: float
+    duration: float
+    speech_end: float | None
+    words: list[Word] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Self:
+        return cls(
+            title=str(d["title"]),
+            start=float(d["start"]),
+            end=float(d["end"]),
+            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", [])],
+        )
+
+
+@dataclass
+class Timeline:
+    """Section and word times, absolute in narration.mp3."""
+
+    narration: str
+    total_seconds: float
+    sections: dict[str, TimelineSection]
+    estimated: bool = False
+
+    @classmethod
+    def load(cls, path: Path) -> Self | None:
+        if not path.exists():
+            return None
+        d = _read_json(path)
+        return cls(
+            narration=str(d.get("narration", "narration.mp3")),
+            total_seconds=float(d.get("total_seconds", 0.0)),
+            estimated=bool(d.get("estimated", False)),
+            sections={k: TimelineSection.from_dict(v) for k, v in d.get("sections", {}).items()},
+        )
+
+    def save(self, path: Path) -> None:
+        _write_json(path, asdict(self), indent=1)
+
+    def span(self, key: str) -> float | None:
+        sec = self.sections.get(key)
+        return None if sec is None else sec.end - sec.start
+
+    @property
+    def keys(self) -> list[str]:
+        return sorted(self.sections)
+
+
+@dataclass
+class Beats:
+    """Resolved cue times per section, seconds relative to the section's start."""
+
+    sections: dict[str, dict[str, float]] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: Path) -> Self:
+        if not path.exists():
+            return cls()
+        return cls({k: parse_beats_string(v) for k, v in _read_json(path).items()})
+
+    def save(self, path: Path) -> None:
+        _write_json(path, {k: self.query(k) for k in sorted(self.sections) if self.sections[k]})
+
+    def query(self, key: str) -> str | None:
+        """The ?beats= value for a section, or None when it has no resolved cues."""
+        cues = self.sections.get(key)
+        if not cues:
+            return None
+        return ",".join(f"{cue}@{t}" for cue, t in cues.items())
+
+    def get(self, key: str, cue: str) -> float | None:
+        return self.sections.get(key, {}).get(cue)
+
+
+def parse_beats_string(value: str) -> dict[str, float]:
+    """'a@1.5,b@2' -> {'a': 1.5, 'b': 2.0}; malformed items are skipped."""
+    out: dict[str, float] = {}
+    for item in value.split(","):
+        item = item.strip()
+        if not item or "@" not in item:
+            continue
+        cue, _, t = item.rpartition("@")
+        try:
+            out[cue] = float(t)
+        except ValueError:
+            continue
+    return out
+
+
+@dataclass
+class Sidecar:
+    """What the recorder did for one section, and where narration t=0 sits in the webm."""
+
+    url: str
+    requested_seconds: float
+    settle_seconds: float
+    load_seconds: float
+    lead_seconds: float  # wall-clock estimate from the recorder
+    lead_in_seconds: float | None = None  # end of the magenta marker: trim the webm here
+    marker_start_seconds: float | None = None  # start of the marker: narration t=0 in the webm
+    lead_method: str | None = None
+
+    @classmethod
+    def load(cls, path: Path) -> Self | None:
+        if not path.exists():
+            return None
+        d = _read_json(path)
+        return cls(**{k: v for k, v in d.items() if k in cls.__dataclass_fields__})
+
+    def save(self, path: Path) -> None:
+        _write_json(path, asdict(self))
+
+    @property
+    def trim_seconds(self) -> float:
+        return self.lead_in_seconds if self.lead_in_seconds is not None else self.lead_seconds
+
+    @property
+    def flash_seconds(self) -> float:
+        """How long the marker covered after t=0; the assembler holds the first clean frame this long."""
+        if self.lead_in_seconds is None or self.marker_start_seconds is None:
+            return 0.0
+        return max(0.0, round(self.lead_in_seconds - self.marker_start_seconds, 3))