braidio 0.0.2__py3-none-any.whl

braidio/multivoice.py

@@ -0,0 +1,244 @@
+"""Multi-voice narration: cycle a pool of voices across segments (issue #10).
+
+When one voice reads flat, variety across voices is a stronger lever than any
+single-voice setting. This renders narration by splitting it into segments
+(sentences) and assigning each a voice drawn from a pool — randomly (seeded, so
+it's reproducible) and avoiding immediate repeats so it doesn't feel like a
+rigid round-robin. Speed is jittered slightly per segment, even within one
+speaker, to break regularity.
+
+Two curated pools of **premade** ElevenLabs voices (all production quality,
+deliberately less familiar than "George", 2M/2F in :data:`POOL_4`, wider in
+:data:`POOL_MANY`). For a truly large "many people / interviews" pool, the
+shared Voice Library (thousands) can be tapped, but quality varies there, so
+those need curation — the premade pools below are the safe default.
+"""
+
+from __future__ import annotations
+
+import random
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from mixing import concatenate_audio
+
+from braidio.tts import narrate
+
+_MARKUP_RE = re.compile(r"<[^>]*>|\[[^\]]*\]")
+_SENT_SPLIT = re.compile(r"(?<=[.?!])\s+(?=[\"“']?[A-Z])")
+
+
+@dataclass(frozen=True)
+class Voice:
+    """A pooled narration voice."""
+
+    id: str
+    name: str
+    gender: str  # "M" | "F"
+    accent: str = ""
+    note: str = ""
+
+
+# 2M / 2F, mixed accents/registers, all less familiar than "George".
+POOL_4: list[Voice] = [
+    Voice("EXAVITQu4vr4xnSDxMaL", "Sarah", "F", "American", "mature, reassuring"),
+    Voice("Xb7hH8MSUJpSbSDYk0k2", "Alice", "F", "British", "clear, engaging"),
+    Voice("IKne3meq5aSn9XLyUdCD", "Charlie", "M", "Australian", "deep, energetic"),
+    Voice("cjVigY5qzO86Huf0OWal", "Eric", "M", "American", "smooth, trustworthy"),
+]
+
+# Wider pool for a "lots of different people / interviews" feel (5M / 5F).
+POOL_MANY: list[Voice] = POOL_4 + [
+    Voice("cgSgspJ2msm6clMCkdW9", "Jessica", "F", "American", "playful, bright"),
+    Voice("XrExE9yKIg1WjnnlVkGX", "Matilda", "F", "American", "professional"),
+    Voice("pFZP5JQG7iQjIQuC4Bku", "Lily", "F", "British", "velvety"),
+    Voice("N2lVS1w4EtoT3dr4eOWO", "Callum", "M", "American", "husky"),
+    Voice("bIHbv24MWmeRgasZH58o", "Will", "M", "American", "relaxed"),
+    Voice("pqHfZKP75CvOlQylNhV4", "Bill", "M", "American", "wise, mature"),
+]
+
+POOLS: dict[str, list[Voice]] = {"four": POOL_4, "many": POOL_MANY}
+
+_BASE_SETTINGS = {
+    "stability": 0.4,
+    "similarity_boost": 0.75,
+    "style": 0.3,
+    "use_speaker_boost": True,
+}
+
+
+def strip_markup(text: str) -> str:
+    return _MARKUP_RE.sub(" ", text)
+
+
+def split_segments(text: str) -> list[str]:
+    """Split narration into sentence-level segments (markup removed).
+
+    Splits on sentence-final ``.?!`` (not the ``…`` used for in-thought pacing),
+    so connected clauses stay with one speaker.
+    """
+    clean = re.sub(r"\s+", " ", strip_markup(text)).strip()
+    return [s.strip() for s in _SENT_SPLIT.split(clean) if s.strip()]
+
+
+def assign_voices(
+    n: int, pool: list[Voice], *, seed: int = 0, avoid_repeats: bool = True
+) -> list[Voice]:
+    """Assign a voice to each of ``n`` turns — random, seeded, no immediate
+    repeats (so it isn't a rigid round-robin)."""
+    rng = random.Random(seed)
+    out: list[Voice] = []
+    prev: Voice | None = None
+    for _ in range(n):
+        choices = [v for v in pool if not (avoid_repeats and v is prev)] or pool
+        v = rng.choice(choices)
+        out.append(v)
+        prev = v
+    return out
+
+
+def group_turns(
+    segments: list[str], *, min_turn: int = 1, max_turn: int = 1, seed: int = 0
+) -> list[str]:
+    """Group consecutive segments into *turns* of ``min_turn..max_turn`` segments.
+
+    A turn is what one voice speaks before the next takes over. Bigger turns =
+    each speaker talks longer (fewer switches). Each turn's segments are joined
+    into one utterance so prosody is continuous within a speaker. Turn sizes are
+    seeded-random within the range.
+    """
+    if min_turn < 1 or max_turn < min_turn:
+        raise ValueError("require 1 <= min_turn <= max_turn")
+    rng = random.Random(seed * 17 + 3)
+    turns: list[str] = []
+    i = 0
+    while i < len(segments):
+        k = rng.randint(min_turn, max_turn)
+        turns.append(" ".join(segments[i : i + k]))
+        i += k
+    return turns
+
+
+def _loudnorm(
+    src: Path, dst: Path, *, target_lufs: float = -16.0, true_peak: float = -1.5
+) -> Path:
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError("ffmpeg not found on PATH.")
+    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_multivoice(
+    segments: list[str],
+    pool: list[Voice],
+    *,
+    out_path: str | Path,
+    api_key: str | None = None,
+    work_dir: str | Path = "data/tts/multivoice",
+    seed: int = 7,
+    min_turn: int = 2,
+    max_turn: int = 4,
+    avoid_immediate_repeat: bool = True,
+    model_id: str = "eleven_multilingual_v2",
+    base_settings: dict | None = None,
+    speed_base: float = 1.0,
+    speed_jitter: float = 0.04,
+    crossfade_s: float = 0.1,
+    gap_s: float = 0.0,
+    target_lufs: float = -16.0,
+) -> list[tuple[Voice, str]]:
+    """Render ``segments`` cycling ``pool`` → ``out_path``.
+
+    Segments are first grouped into *turns* of ``min_turn..max_turn`` segments
+    (bigger = each voice talks longer). One voice per turn, no immediate repeat,
+    with a jittered speed even within a speaker. ``gap_s`` inserts silence
+    between turns (0 = none). Returns ``[(voice, turn_text), …]`` for reporting.
+
+    ``api_key`` is an optional per-request ElevenLabs key threaded to every
+    :func:`braidio.tts.narrate` call; ``None`` (default) keeps the
+    ``$ELEVENLABS_API_KEY`` fallback.
+
+    NOTE: overlapping/interrupting speakers and clip ducking are separate,
+    upcoming parameters (tracked as issues) — this renders turns sequentially.
+    """
+    settings = dict(base_settings if base_settings is not None else _BASE_SETTINGS)
+    turns = group_turns(segments, min_turn=min_turn, max_turn=max_turn, seed=seed)
+    rng = random.Random(seed * 31 + 1)
+    voices = assign_voices(
+        len(turns), pool, seed=seed, avoid_repeats=avoid_immediate_repeat
+    )
+    work = Path(work_dir)
+    work.mkdir(parents=True, exist_ok=True)
+    parts: list[Path] = []
+    for i, (turn, v) in enumerate(zip(turns, voices)):
+        speed = round(speed_base + rng.uniform(-speed_jitter, speed_jitter), 3)
+        raw = narrate(
+            turn,
+            work / f"turn{i:03d}-{v.name}.mp3",
+            api_key=api_key,
+            voice_id=v.id,
+            model_id=model_id,
+            voice_settings={**settings, "speed": speed},
+        )
+        parts.append(_loudnorm(raw, work / f"norm{i:03d}.mp3", target_lufs=target_lufs))
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if gap_s > 0:
+        _concat_with_gaps(parts, out, gap_s=gap_s)
+    else:
+        concatenate_audio(
+            *[str(p) for p in parts], output=str(out), crossfade=crossfade_s
+        )
+    return list(zip(voices, turns))
+
+
+def _concat_with_gaps(parts: list[Path], out: Path, *, gap_s: float) -> Path:
+    """Concatenate audio parts with ``gap_s`` seconds of silence between them."""
+    from mixing import Audio  # local import; audio object model
+
+    silence = None
+    pieces: list[str] = []
+    for p in parts:
+        pieces.append(str(p))
+    # Build via ffmpeg: create a silence file and interleave.
+    sil = out.parent / "_gap.mp3"
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "lavfi",
+            "-i",
+            f"anullsrc=r=44100:cl=stereo",
+            "-t",
+            f"{gap_s:.3f}",
+            str(sil),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    interleaved: list[str] = []
+    for i, p in enumerate(pieces):
+        if i:
+            interleaved.append(str(sil))
+        interleaved.append(p)
+    concatenate_audio(*interleaved, output=str(out), crossfade=0.0)
+    return out

braidio/music.py

@@ -0,0 +1,111 @@
+"""Music bed — an instrumental underscore laid under the whole production, ducked.
+
+The bed is the spanning generalization of a per-clip ``under`` placement: instead
+of one clip beneath one talk beat, an app-supplied **instrumental** asset runs
+beneath the entire timeline at reduced gain, entering after speech onset and
+fading at the ends (the conventions from
+``docs/research/commentary-formats-and-styles.md``: bed 10–15 dB under voice,
+~1.5s fade-in, *posted* after the start; beds must be instrumental).
+
+braidio ships **no music** — the caller supplies the asset (a licensed/owned
+instrumental). A :class:`~braidio.formats.Format`'s ``music_bed`` *intensity*
+(continuous / light / sparse / none) picks a sensible gain via
+:data:`BED_GAIN_BY_INTENSITY`; :func:`render_format` builds the bed for you when
+given a ``bed_asset``.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+# Bed gain (dB under the mixed voice) by a Format's music_bed intensity.
+# None means "no bed" for that intensity.
+BED_GAIN_BY_INTENSITY: dict[str, float | None] = {
+    "continuous": -20.0,
+    "light": -24.0,
+    "sparse": -28.0,
+    "none": None,
+}
+
+
+@dataclass(frozen=True)
+class MusicBed:
+    """An instrumental underscore spanning the production, mixed under the talk.
+
+    ``asset_path`` is an app-supplied instrumental. ``gain_db`` sets how far under
+    the voice it sits; ``lead_in_s`` posts the bed *after* speech onset so its
+    entrance feels motivated; ``start_s`` is the in-point into the asset;
+    ``loop`` repeats the asset to cover a timeline longer than it.
+    """
+
+    asset_path: str
+    gain_db: float = -22.0
+    fade_in_s: float = 1.5
+    fade_out_s: float = 2.0
+    lead_in_s: float = 2.0
+    start_s: float = 0.0
+    loop: bool = True
+
+
+def bed_for_intensity(asset_path: str, intensity: str, **overrides) -> MusicBed | None:
+    """Build a :class:`MusicBed` at the gain for a Format ``music_bed`` intensity.
+
+    Returns ``None`` for ``"none"`` (or an unknown intensity), so callers can do
+    ``bed = bed_for_intensity(asset, fmt.music_bed)`` and skip when falsy.
+    """
+    gain = BED_GAIN_BY_INTENSITY.get(intensity)
+    if gain is None:
+        return None
+    return MusicBed(asset_path=asset_path, gain_db=gain, **overrides)
+
+
+def _require_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError("ffmpeg not found on PATH (brew install ffmpeg).")
+
+
+def prepare_bed(
+    bed: MusicBed, target_s: float, out_path: str | Path, *, sample_rate: int = 44100
+) -> Path:
+    """Render ``bed`` to a ready-to-mix underscore of length ``target_s - lead_in_s``.
+
+    Seeks to ``bed.start_s`` (looping if needed), trims to the covered length, and
+    bakes in fades + ``gain_db`` + stereo. The caller mixes the result delayed by
+    ``bed.lead_in_s``. Returns ``out_path``.
+    """
+    _require_ffmpeg()
+    length = max(0.05, target_s - bed.lead_in_s)
+    fo_start = max(0.0, length - bed.fade_out_s)
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    pre_input: list[str] = []
+    if bed.loop:
+        pre_input += ["-stream_loop", "-1"]
+    if bed.start_s > 0:
+        pre_input += ["-ss", f"{bed.start_s:.3f}"]
+    af = (
+        f"afade=t=in:st=0:d={bed.fade_in_s},"
+        f"afade=t=out:st={fo_start:.3f}:d={bed.fade_out_s},"
+        f"volume={bed.gain_db}dB,"
+        f"aformat=sample_rates={sample_rate}:channel_layouts=stereo"
+    )
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            *pre_input,
+            "-i",
+            str(bed.asset_path),
+            "-t",
+            f"{length:.3f}",
+            "-af",
+            af,
+            str(out),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return out

braidio/project.py

@@ -0,0 +1,26 @@
+"""braidio as an nw app: a :class:`nw.Project` for commentary-weave productions.
+
+Subclassing ``nw.Project`` inherits the whole folder facade + lacing graph +
+freshness (``stale_after``) machinery; braidio adds its production kind and its
+domain/render body-schema vocabulary (registered on import of
+:mod:`braidio.bodies`). This module requires ``nw``; it is imported lazily by
+``braidio/__init__`` only when ``nw`` is available.
+
+The costed ``plan``/``execute`` Transform pipeline (each transform delegating to
+braidio's functional core for the actual audio, and recording provenance via
+:mod:`braidio.provenance`) is the next increment — see the design doc and
+nw#9 (generalizing nw's shot/mp4 render seam).
+"""
+
+from __future__ import annotations
+
+import nw
+
+from braidio import bodies as _bodies  # noqa: F401  (import registers schemas)
+from braidio.kinds import WeaveKind
+
+
+class Project(nw.Project):
+    """An nw project for a braidio commentary-weave production."""
+
+    KIND: WeaveKind = WeaveKind.COMMENTARY_WEAVE

braidio/provenance.py

@@ -0,0 +1,152 @@
+"""Record render choices as linked artifacts → trace + partial re-render.
+
+A render is a *projection* of the graph, so the render **choices** belong in the
+graph too. :func:`record_render` writes the render-provenance nodes
+(weave-config, voice-assignment, narration-render, segment-extraction,
+episode-render) with ``was_derived_from`` edges to their inputs.
+:func:`stale_after` then returns exactly the nodes downstream of a change — the
+partial-re-render frontier (a memoized build DAG for audio; mirrors nw's
+``stale_after``). See the design doc + nw's render-provenance rationale.
+
+Requires ``lacing``; imported lazily by ``braidio/__init__`` only when present.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID, uuid4
+
+from lacing import Annotation, NodeRef, Provenance, RationalTime, TimeInterval
+
+from braidio.bodies import register_tiers
+from braidio.bodies._render_nodes import (
+    EPISODE_RENDER_V1,
+    NARRATION_RENDER_V1,
+    SEGMENT_EXTRACTION_V1,
+    VOICE_ASSIGNMENT_V1,
+    WEAVE_CONFIG_V1,
+)
+
+_RATE = 1000
+
+
+def _node(store, tier: str, uri: str, body: dict, *, derived_from=()) -> UUID:
+    """Add a render node to ``store`` with provenance; return its id."""
+    aid = uuid4()
+    store.add(
+        Annotation(
+            id=aid,
+            tier=tier,
+            reference=NodeRef(
+                scene_path=f"{tier}/{aid}",
+                interval=TimeInterval.from_seconds(0.0, 1.0, rate=_RATE),
+            ),
+            body=body,
+            body_schema_uri=uri,
+            provenance=Provenance(
+                was_generated_by="braidio:render",
+                was_attributed_to="braidio",
+                was_derived_from=list(derived_from),
+                generated_at_time=RationalTime.now(rate=_RATE),
+                activity="derive",
+            ),
+        )
+    )
+    return aid
+
+
+def record_render(
+    store, *, weave_config: dict, beats: list[dict], profile: str = "personal"
+) -> dict:
+    """Write the provenance graph for one render into ``store``.
+
+    ``beats`` is an ordered list of dicts, each either::
+
+        {"kind": "narration", "source_id": <UUID of the beat/commentary node>,
+         "cache_key": str, "voice_id": str, "pool_label": str, "seed": int,
+         "duration_s": float, "artifact_id": str | None}
+        {"kind": "segment", "source_id": <UUID of the source-media/clip node>,
+         "cache_key": str, "start_s": float, "end_s": float, "artifact_id": str | None}
+
+    Returns ``{"config": UUID, "members": [UUID,…], "episode": UUID}``.
+    """
+    register_tiers(store)  # idempotent
+    cfg = _node(store, "weave-configs", WEAVE_CONFIG_V1, {"config": weave_config})
+    members: list[UUID] = []
+    for b in beats:
+        src = b["source_id"]
+        if b["kind"] == "narration":
+            va = _node(
+                store,
+                "voice-assignments",
+                VOICE_ASSIGNMENT_V1,
+                {
+                    "voice_id": b.get("voice_id", ""),
+                    "pool_label": b.get("pool_label", "single"),
+                    "seed": int(b.get("seed", 0)),
+                },
+                derived_from=[
+                    src,
+                    cfg,
+                ],  # depends on the beat AND the config (pool/seed)
+            )
+            nid = _node(
+                store,
+                "narration-renders",
+                NARRATION_RENDER_V1,
+                {
+                    "cache_key": b["cache_key"],
+                    "artifact_id": b.get("artifact_id"),
+                    "duration_s": float(b.get("duration_s", 0.0)),
+                },
+                derived_from=[src, va, cfg],
+            )
+            members.append(nid)
+        else:  # segment
+            sid = _node(
+                store,
+                "segment-extractions",
+                SEGMENT_EXTRACTION_V1,
+                {
+                    "cache_key": b["cache_key"],
+                    "start_s": float(b.get("start_s", 0.0)),
+                    "end_s": float(b.get("end_s", 1.0)),
+                    "artifact_id": b.get("artifact_id"),
+                },
+                derived_from=[src, cfg],
+            )
+            members.append(sid)
+    episode = _node(
+        store,
+        "episode-renders",
+        EPISODE_RENDER_V1,
+        {
+            "profile": profile,
+            "ordered_member_ids": tuple(str(m) for m in members),
+            "artifact_id": None,
+            "duration_s": 0.0,
+        },
+        derived_from=[*members, cfg],
+    )
+    return {"config": cfg, "members": members, "episode": episode}
+
+
+def descendants_of(store, changed_id: UUID) -> set[UUID]:
+    """Every annotation transitively derived from ``changed_id`` (via
+    ``provenance.was_derived_from``). Excludes ``changed_id`` itself."""
+    children: dict[UUID, list[UUID]] = {}
+    for a in store.all():
+        for parent in a.provenance.was_derived_from:
+            children.setdefault(parent, []).append(a.id)
+    out: set[UUID] = set()
+    stack = [changed_id]
+    while stack:
+        cur = stack.pop()
+        for child in children.get(cur, []):
+            if child not in out:
+                out.add(child)
+                stack.append(child)
+    return out
+
+
+# The partial-re-render frontier of a change (mirrors nw.stale_after semantics).
+stale_after = descendants_of