braidio 0.0.2__py3-none-any.whl

braidio/render.py

@@ -0,0 +1,228 @@
+"""Render a :class:`~braidio.script.Script` into an audio file.
+
+Walks the beats (filtered by the rights :class:`~braidio.rights.Profile`):
+narration beats are synthesized (:mod:`braidio.tts`); segment beats are resolved
+via a :class:`~braidio.sources.SegmentSource` and extracted (padded + faded).
+Every part is loudness-normalized, then either woven on a timeline (clips tuck
+under narration — :func:`braidio.weave.weave_timeline`) when a
+:class:`~braidio.weave_config.WeaveConfig` enables it, or concatenated.
+
+This is the no-graph fast path; the same core is reused by the nw-app
+transforms (which add provenance + partial re-render).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from mixing import concatenate_audio
+
+from braidio.conversation import DEFAULT_CAST, ConversationCast, render_dialogue
+from braidio.delivery import V2_TUNED, Delivery
+from braidio.rights import (
+    PUBLISHABLE_CLIP_RIGHTS,
+    Profile,
+    RightsPolicy,
+    plan_production,
+)
+from braidio.script import Script
+from braidio.sources import SegmentSource
+from braidio.tts import narrate
+from braidio.weave import TimelineItem, extract_padded, weave_timeline
+from braidio.weave_config import WeaveConfig
+
+_DEFAULT_LUFS = -16.0
+_TRUE_PEAK = -1.5
+
+
+def _require_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError("ffmpeg not found on PATH (brew install ffmpeg).")
+
+
+def _lead_gap(src: Path, dst: Path, *, gap_s: float) -> Path:
+    """Prepend ``gap_s`` seconds of silence (breathing room before a beat)."""
+    _require_ffmpeg()
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    ms = int(round(gap_s * 1000))
+    subprocess.run(
+        ["ffmpeg", "-y", "-i", str(src), "-af", f"adelay={ms}:all=1", str(dst)],
+        check=True,
+        capture_output=True,
+    )
+    return dst
+
+
+def _loudnorm(src: Path, dst: Path, *, target_lufs: float = _DEFAULT_LUFS) -> Path:
+    _require_ffmpeg()
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            "-i",
+            str(src),
+            "-af",
+            f"loudnorm=I={target_lufs}:TP={_TRUE_PEAK}:LRA=11",
+            "-ar",
+            "44100",
+            str(dst),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return dst
+
+
+def render_production(
+    script: Script,
+    *,
+    source: SegmentSource,
+    api_key: str | None = None,
+    config: WeaveConfig | None = None,
+    profile: Profile = Profile.PERSONAL,
+    rights: RightsPolicy | None = None,
+    delivery: Delivery = V2_TUNED,
+    cast: ConversationCast = DEFAULT_CAST,
+    out_path: str | Path | None = None,
+    voice_id: str | None = None,
+    crossfade_s: float = 0.12,
+    normalize: bool = True,
+    music_bed=None,  # optional braidio.music.MusicBed — instrumental underscore
+    tts_dir: str | Path = "data/tts",
+    clips_dir: str | Path = "data/clips",
+    episodes_dir: str | Path = "data/episodes",
+) -> Path:
+    """Render ``script`` under ``profile`` → a single audio file. Returns the path.
+
+    Segment beats are resolved through ``source`` (a :class:`SegmentSource`).
+    When ``config`` has ``clip_edge_overlap_s > 0``, a clip is ``placement="under"``,
+    or a ``music_bed`` is given, the parts are woven on a timeline; otherwise they
+    are concatenated. ``rights`` (if given) sets which segment rights are
+    publishable. ``music_bed`` lays an instrumental underscore under the whole
+    production (see :class:`braidio.music.MusicBed`).
+
+    ``api_key`` is an optional per-request ElevenLabs key threaded to every
+    synthesized beat — both narration (:func:`braidio.tts.narrate`) and dialogue
+    (:func:`braidio.conversation.render_dialogue`). When ``None`` (default) each
+    synthesizer falls back to ``$ELEVENLABS_API_KEY`` (unchanged behavior); an
+    explicit key lets a caller (e.g. a per-user BYO-key request) override the
+    environment without mutating it. Segment beats never call ElevenLabs, so the
+    key does not touch them.
+    """
+    publishable = rights.publishable_clip_rights if rights else PUBLISHABLE_CLIP_RIGHTS
+    plan = plan_production(script, profile, publishable_clip_rights=publishable)
+    target_lufs = config.target_lufs if config is not None else _DEFAULT_LUFS
+    duck_db = config.duck_db if config is not None else -15.0
+
+    out = (
+        Path(out_path)
+        if out_path
+        else Path(episodes_dir) / f"{script.id_slug}-{profile.value}.mp3"
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tts_dir) / f"_render_{script.id_slug}_{profile.value}"
+    work.mkdir(parents=True, exist_ok=True)
+
+    # extraction pads: from config when present, else small defaults
+    if config is not None:
+        pre, post, fi, fo = (
+            config.clip_pre_roll_s,
+            config.clip_post_roll_s,
+            config.clip_fade_in_s,
+            config.clip_fade_out_s,
+        )
+    else:
+        pre, post, fi, fo = 0.15, 0.35, 0.04, 0.04
+
+    parts: list[Path] = []
+    kinds: list[str] = []
+    placements: list[str] = []  # "sequential" | "under" (per part, for the weave)
+    for i, pb in enumerate(plan.beats):
+        if pb.kind == "narration":
+            orig = script.beats[pb.from_index]
+            beat_voice = getattr(orig, "voice", None) or voice_id  # per-beat override
+            beat_settings = (
+                getattr(orig, "voice_settings", None) or delivery.voice_settings
+            )
+            raw = narrate(
+                pb.content,
+                Path(tts_dir)
+                / f"{script.id_slug}-{profile.value}-{delivery.name}-beat{i:02d}.mp3",
+                api_key=api_key,
+                voice_id=beat_voice,
+                model_id=delivery.model_id,
+                voice_settings=beat_settings,
+            )
+            # breathing room before a register change (Narration.lead_gap_s)
+            gap = getattr(orig, "lead_gap_s", 0.0)
+            if gap and gap > 0:
+                raw = _lead_gap(
+                    raw, Path(tts_dir) / f"{script.id_slug}-lead{i:02d}.mp3", gap_s=gap
+                )
+        elif pb.kind == "dialogue":
+            raw = render_dialogue(
+                list(pb.turns),
+                cast,
+                api_key=api_key,
+                out_path=Path(tts_dir)
+                / f"{script.id_slug}-{profile.value}-dlg{i:02d}.mp3",
+            )
+        else:  # segment
+            rs = source.resolve(pb.content)
+            if rs is None:
+                raise LookupError(f"segment did not resolve: {pb.content[:50]!r}")
+            raw = Path(clips_dir) / f"{script.id_slug}-seg{i:02d}.mp3"
+            extract_padded(
+                rs.asset_path,
+                rs.start_s,
+                rs.end_s,
+                raw,
+                pre_roll_s=pre,
+                post_roll_s=post,
+                fade_in_s=fi,
+                fade_out_s=fo,
+            )
+        parts.append(
+            _loudnorm(raw, work / f"part{i:02d}.mp3", target_lufs=target_lufs)
+            if normalize
+            else raw
+        )
+        # dialogue + narration are spoken → treated as "narration" on the timeline
+        kinds.append("clip" if pb.kind == "clip" else "narration")
+        # a "under" clip becomes a ducked underlay; "before"/"after" play clean
+        seg_place = getattr(script.beats[pb.from_index], "placement", "before")
+        placements.append(
+            "under" if (pb.kind == "clip" and seg_place == "under") else "sequential"
+        )
+
+    has_under = "under" in placements
+    edge_overlap = config.clip_edge_overlap_s if config is not None else 0.0
+    crossfade = config.crossfade_s if config is not None else crossfade_s
+    # a music bed also needs the mix path (even for narration-only productions)
+    woven = music_bed is not None or (
+        "clip" in kinds and (edge_overlap > 0 or has_under)
+    )
+
+    if woven:
+        items = [
+            TimelineItem(
+                k, str(p), placement=pl, duck_db=(duck_db if pl == "under" else 0.0)
+            )
+            for k, p, pl in zip(kinds, parts, placements)
+        ]
+        weave_timeline(
+            items,
+            out,
+            clip_edge_overlap_s=edge_overlap,
+            narration_crossfade_s=crossfade,
+            target_lufs=target_lufs,
+            bed=music_bed,
+        )
+    else:
+        concatenate_audio(
+            *[str(p) for p in parts], output=str(out), crossfade=crossfade_s
+        )
+    return out

braidio/rights.py

@@ -0,0 +1,197 @@
+"""Render profiles: enforce personal-vs-published rights as data.
+
+Rights are encoded on the beats (``SegmentBeat.rights``, and — mechanically —
+the presence of forbidden verbatim text in narration) and a **render profile**
+filters the script into the beats that may actually render:
+
+- ``PERSONAL``  — include everything, including owned/copyrighted segment audio.
+- ``PUBLISHED`` — exclude any non-publishable segment audio and any beat
+  carrying forbidden verbatim text; keep original narration, publishable
+  segments, and short transformative substitutes.
+
+The rule is enforced *mechanically*: :func:`plan_production` routes beats by
+their ``rights`` flag, and :func:`find_verbatim_text` / :func:`content_violations`
+scan the resulting published beats against a **caller-supplied** set of
+forbidden texts (via :class:`RightsPolicy`) — so a leak is a test failure, not a
+judgment call. braidio owns the scanner + profile filter; the consumer injects
+*what* is forbidden (e.g. Hamilton injects the song's lyric lines).
+
+Not legal advice.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Iterable
+
+from braidio.script import Dialogue, Narration, Script, SegmentBeat
+
+# Segment ``rights`` values safe to render in the published cut.
+PUBLISHABLE_CLIP_RIGHTS: frozenset[str] = frozenset({"public-domain"})
+
+_WORD_RE = re.compile(r"\w+")
+_MARKUP_RE = re.compile(r"<[^>]*>|\[[^\]]*\]")  # SSML <break…> and v3 [audio tags]
+
+
+def _strip_markup(text: str) -> str:
+    """Drop SSML/audio-tag markup so delivery markup doesn't affect the scan."""
+    return _MARKUP_RE.sub(" ", text)
+
+
+class Profile(str, Enum):
+    """Which projection of the production we render."""
+
+    PERSONAL = "personal"
+    PUBLISHED = "published"
+
+
+@dataclass(frozen=True)
+class RightsPolicy:
+    """Injected rights configuration for the published profile.
+
+    ``forbidden_texts`` yields the strings that must not appear verbatim in
+    published narration (e.g. copyrighted lyric lines). ``publishable_clip_rights``
+    is the set of segment ``rights`` values allowed in the published cut.
+    """
+
+    forbidden_texts: Callable[[Script], Iterable[str]] = lambda _s: ()
+    publishable_clip_rights: frozenset[str] = PUBLISHABLE_CLIP_RIGHTS
+
+
+@dataclass(frozen=True)
+class PlannedBeat:
+    """A beat resolved for a profile — what the renderer actually plays.
+
+    ``kind`` is ``"narration"`` (synthesize ``content``) or ``"clip"`` (resolve
+    ``content`` as a segment reference and cut audio). ``from_index`` points at
+    the source beat; ``note`` records any substitution/drop reasoning.
+    """
+
+    kind: str  # "narration" | "clip" | "dialogue"
+    content: str  # narration/dialogue text (for scanning); clip = the reference
+    from_index: int
+    note: str = ""
+    turns: tuple | None = None  # (role, text) pairs, for dialogue beats
+
+
+@dataclass
+class RenderPlan:
+    profile: Profile
+    beats: list[PlannedBeat] = field(default_factory=list)
+    dropped: list[str] = field(default_factory=list)
+    substituted: list[str] = field(default_factory=list)
+
+
+def segment_is_publishable(
+    beat: SegmentBeat, publishable: frozenset[str] = PUBLISHABLE_CLIP_RIGHTS
+) -> bool:
+    return beat.rights in publishable
+
+
+def plan_production(
+    script: Script,
+    profile: Profile,
+    *,
+    publishable_clip_rights: frozenset[str] = PUBLISHABLE_CLIP_RIGHTS,
+) -> RenderPlan:
+    """Filter ``script`` into the beats renderable under ``profile``."""
+    plan = RenderPlan(profile=profile)
+    for i, beat in enumerate(script.beats):
+        if isinstance(beat, SegmentBeat):
+            if profile is Profile.PERSONAL or segment_is_publishable(
+                beat, publishable_clip_rights
+            ):
+                plan.beats.append(PlannedBeat("clip", beat.reference, i))
+            elif beat.published_substitute:
+                plan.beats.append(
+                    PlannedBeat(
+                        "narration", beat.published_substitute, i, "segment→substitute"
+                    )
+                )
+                plan.substituted.append(beat.label or beat.reference[:40])
+            else:
+                plan.dropped.append(beat.label or beat.reference[:40])
+        elif isinstance(beat, Narration):
+            if profile is Profile.PUBLISHED and beat.published_text is not None:
+                plan.beats.append(
+                    PlannedBeat(
+                        "narration", beat.published_text, i, "narration→published_text"
+                    )
+                )
+                plan.substituted.append(f"narration[{i}]")
+            else:
+                plan.beats.append(PlannedBeat("narration", beat.text, i))
+        elif isinstance(beat, Dialogue):
+            # our commentary → always included; content is the joined text so the
+            # published verbatim-scan can see it; turns carry the render input.
+            plan.beats.append(
+                PlannedBeat(
+                    "dialogue",
+                    " ".join(text for _role, text in beat.turns),
+                    i,
+                    turns=tuple(beat.turns),
+                )
+            )
+        else:  # pragma: no cover - exhaustive
+            raise TypeError(f"unknown beat type {type(beat).__name__}")
+    return plan
+
+
+# --- mechanical verbatim-text detection --------------------------------------
+
+
+def _word_ngrams(text: str, n: int) -> set[tuple[str, ...]]:
+    words = [w.lower() for w in _WORD_RE.findall(_strip_markup(text))]
+    return (
+        {tuple(words[i : i + n]) for i in range(len(words) - n + 1)}
+        if len(words) >= n
+        else set()
+    )
+
+
+def find_verbatim_text(
+    text: str, forbidden: Iterable[str], *, min_words: int = 5
+) -> list[str]:
+    """Forbidden lines that appear (near-)verbatim in ``text``.
+
+    A line counts as leaked if ``text`` shares a run of ``min_words`` consecutive
+    words with it (case-insensitive, word-level). Single words and short common
+    phrases don't trip it — only substantial verbatim quoting.
+    """
+    text_ngrams = _word_ngrams(text, min_words)
+    if not text_ngrams:
+        return []
+    hits: list[str] = []
+    for line in forbidden:
+        line_ngrams = _word_ngrams(line, min_words)
+        if line_ngrams and (line_ngrams & text_ngrams):
+            hits.append(line)
+    return hits
+
+
+def content_violations(
+    plan: RenderPlan, forbidden: Iterable[str], *, min_words: int = 5
+) -> list[str]:
+    """Rights violations in a *published* plan (empty list = clean).
+
+    Fails if any planned beat plays non-publishable segment audio, or any
+    narration beat contains forbidden verbatim text.
+    """
+    if plan.profile is not Profile.PUBLISHED:
+        return []
+    forbidden = list(forbidden)
+    violations: list[str] = []
+    for b in plan.beats:
+        if b.kind == "clip":
+            violations.append(
+                f"beat {b.from_index}: segment audio present in published cut"
+            )
+        elif b.kind in ("narration", "dialogue"):
+            leaks = find_verbatim_text(b.content, forbidden, min_words=min_words)
+            if leaks:
+                violations.append(
+                    f"beat {b.from_index}: verbatim forbidden text in {b.kind} → {leaks[0]!r}"
+                )
+    return violations

braidio/script.py

@@ -0,0 +1,117 @@
+"""Composition model — the ordered beats a render walks.
+
+A :class:`Script` is an ordered list of beats, each either a :class:`Narration`
+(spoken, synthesized) or a :class:`SegmentBeat` (a *reference* to a span of
+source media to resolve and weave in). This is the generic, media-agnostic
+projection a renderer consumes; how a reference maps to audio is a
+:class:`braidio.sources.SegmentSource` concern, and what the beats are backed by
+(lyrics, a graph, hand-authoring) is the consumer's concern.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Union
+
+
+@dataclass(frozen=True)
+class Narration:
+    """A spoken narration beat (authored, synthesized by TTS).
+
+    ``published_text`` is an optional rights-safe rewrite the published profile
+    uses when the default ``text`` quotes forbidden (e.g. copyrighted) content;
+    leave it ``None`` when the narration is already clean.
+
+    ``lead_gap_s`` prepends a beat of silence — breathing room before a
+    register change (e.g. a book-read entering after a conversation), so it
+    doesn't feel glued to the previous speaker.
+
+    ``voice`` and ``voice_settings`` are per-beat overrides so one timeline can
+    carry contrasting roles — e.g. a lively *presenter* and a graver *book
+    narrator* (different voice, and/or a different delivery preset's
+    ``voice_settings``). Both fall back to the render's production-level defaults
+    when ``None``.
+    """
+
+    text: str
+    style: str | None = None  # optional delivery hint (e.g. "book-passage")
+    published_text: str | None = None
+    lead_gap_s: float = 0.0
+    voice: str | None = (
+        None  # per-beat voice override (e.g. presenter vs book-narrator)
+    )
+    voice_settings: dict | None = None  # per-beat delivery override (e.g. V2_NARRATOR)
+
+
+CLIP_PLACEMENTS = ("before", "under", "after")
+
+
+@dataclass(frozen=True)
+class SegmentBeat:
+    """A span of source media to weave in, addressed by an opaque ``reference``.
+
+    The renderer resolves ``reference`` → ``[start,end)`` via a
+    :class:`~braidio.sources.SegmentSource` and cuts it. ``rights`` (e.g.
+    ``owned-local`` / ``copyrighted`` / ``public-domain``) drives the render
+    profile; ``published_substitute`` is a transformative narration the
+    published profile swaps in when the segment's audio can't be used.
+
+    ``placement`` is how the clip sits against the talk (the weaving grammar):
+    ``"before"`` (default) and ``"after"`` play the clip **clean** in its own
+    slot — the set-up→clip and clip→payoff patterns, distinguished by where you
+    order the beat relative to the talk. ``"under"`` plays the clip
+    **concurrently beneath the following talk beat**, ducked by ``duck_db`` —
+    the "host talks over the clip" technique (place the clip *immediately before*
+    the talk it should sit under).
+    """
+
+    reference: str
+    label: str = ""
+    rights: str = "owned-local"
+    published_substitute: str | None = None
+    placement: str = "before"
+
+    def __post_init__(self) -> None:
+        if self.placement not in CLIP_PLACEMENTS:
+            raise ValueError(
+                f"SegmentBeat.placement must be one of {CLIP_PLACEMENTS}, "
+                f"got {self.placement!r}"
+            )
+
+
+@dataclass(frozen=True)
+class Dialogue:
+    """A multi-speaker commentary exchange (the conversational register).
+
+    ``turns`` is an ordered tuple of ``(role, text)`` pairs (roles like
+    ``"A"``/``"B"`` map to voices via a :class:`~braidio.conversation.ConversationCast`
+    at render time). Rendered in ONE pass via Text-to-Dialogue so it sounds like
+    people talking to each other. This is our own commentary → always publishable
+    (its text is still scanned for forbidden verbatim quotes in the published cut).
+    """
+
+    turns: tuple[tuple[str, str], ...]
+    label: str = ""
+
+
+Beat = Union[Narration, SegmentBeat, Dialogue]
+
+
+@dataclass(frozen=True)
+class Script:
+    """An ordered production script."""
+
+    title: str
+    id_slug: str  # stable id for this production (e.g. "01"); no media semantics
+    beats: list[Beat] = field(default_factory=list)
+
+
+def narration_segments(script: Script) -> list[str]:
+    """All narration (default text) of a script, as sentence-level segments."""
+    from braidio.multivoice import split_segments
+
+    segs: list[str] = []
+    for beat in script.beats:
+        if isinstance(beat, Narration):
+            segs.extend(split_segments(beat.text))
+    return segs