braidio 0.0.2__py3-none-any.whl

braidio/sources.py

@@ -0,0 +1,249 @@
+"""Segment sources: resolve a *reference* to a cuttable ``[start, end]`` window.
+
+A production weaves in extracted segments of source media. *How* a reference
+(a lyric quote, an audiobook passage, a news phrase, an SFX cue) maps to a
+concrete ``[start, end]`` span of a source asset is pluggable via the
+:class:`SegmentSource` protocol — the weave engine never needs to know it is
+lyrics.
+
+This module ships one generic implementation: :class:`TimedLineSegmentSource`,
+a token-F1 matcher over time-aligned lines (:class:`TimedLine`). It answers a
+reference by the best contiguous run of lines — handling exact, sub-line, and
+multi-line references. Consumers bind it to their own timed lines + asset (e.g.
+Hamilton binds LRCLIB line timings + owned song audio).
+
+Also provides the lower-level resolver (:func:`find_segment`, :func:`load_timing`)
+and the resolve-and-cut convenience (:func:`cut_quote`) used directly by the
+Hamilton pilot; new code should prefer the :class:`SegmentSource` protocol +
+:func:`braidio.weave.extract_padded`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+_WS_RE = re.compile(r"\s+")
+_PUNCT_RE = re.compile(r"[^\w\s]")
+
+
+def _norm(text: str) -> str:
+    return _WS_RE.sub(" ", _PUNCT_RE.sub(" ", text.lower())).strip()
+
+
+def _tokens(text: str) -> list[str]:
+    return _norm(text).split()
+
+
+@dataclass(frozen=True)
+class TimedLine:
+    """A source line with a ``[start_s, end_s)`` window (end may be None = tail)."""
+
+    index: int
+    start_s: float
+    end_s: float | None
+    text: str
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A resolved window for a reference, with the matched line span."""
+
+    start_s: float
+    end_s: float
+    score: float  # token-F1 of the matched run against the reference (0..1)
+    line_start: int
+    line_end: int
+    matched_text: str
+
+    @property
+    def duration_s(self) -> float:
+        return round(self.end_s - self.start_s, 3)
+
+
+@dataclass(frozen=True)
+class ResolvedSegment:
+    """A cuttable span of a source asset — what a :class:`SegmentSource` returns."""
+
+    asset_path: Path
+    start_s: float
+    end_s: float
+    score: float = 1.0
+    matched_text: str = ""
+
+    @property
+    def duration_s(self) -> float:
+        return round(self.end_s - self.start_s, 3)
+
+
+@runtime_checkable
+class SegmentSource(Protocol):
+    """Resolve an opaque ``reference`` to a :class:`ResolvedSegment` (or None)."""
+
+    def resolve(self, reference: str) -> ResolvedSegment | None: ...
+
+
+def load_timing(path: str | Path) -> list[TimedLine]:
+    """Load a ``{lines: [{index,start_s,end_s,text}]}`` JSON into `TimedLine`s."""
+    rec = json.loads(Path(path).read_text())
+    lines = rec["lines"] if isinstance(rec, dict) else rec
+    return [
+        TimedLine(
+            index=int(l["index"]),
+            start_s=float(l["start_s"]),
+            end_s=None if l.get("end_s") is None else float(l["end_s"]),
+            text=l["text"],
+        )
+        for l in lines
+    ]
+
+
+def _line_end(lines: list[TimedLine], i: int, *, song_end_s: float | None) -> float:
+    line = lines[i]
+    if line.end_s is not None:
+        return line.end_s
+    if i + 1 < len(lines):
+        return lines[i + 1].start_s
+    if song_end_s is not None:
+        return song_end_s
+    return line.start_s + 3.0
+
+
+def find_segment(
+    lines: list[TimedLine],
+    quote: str,
+    *,
+    max_span: int = 12,
+    min_score: float = 0.5,
+    song_end_s: float | None = None,
+) -> Segment | None:
+    """Best contiguous run of timed lines matching ``quote``, or ``None``.
+
+    Scores every run ``lines[i..j]`` (up to ``max_span`` lines) by token F1
+    against the reference's tokens and returns the highest-scoring run clearing
+    ``min_score``. Handles single-line, sub-line, and multi-line references.
+    """
+    q = set(_tokens(quote))
+    if not q or not lines:
+        return None
+
+    best: Segment | None = None
+    for i in range(len(lines)):
+        acc: list[str] = []
+        for j in range(i, min(i + max_span, len(lines))):
+            acc += _tokens(lines[j].text)
+            if not acc:
+                continue
+            aset = set(acc)
+            inter = len(q & aset)
+            if not inter:
+                continue
+            recall = inter / len(q)
+            precision = inter / len(aset)
+            f1 = 2 * precision * recall / (precision + recall)
+            if best is None or f1 > best.score:
+                best = Segment(
+                    start_s=lines[i].start_s,
+                    end_s=_line_end(lines, j, song_end_s=song_end_s),
+                    score=round(f1, 4),
+                    line_start=lines[i].index,
+                    line_end=lines[j].index,
+                    matched_text=" / ".join(lines[k].text for k in range(i, j + 1)),
+                )
+    if best is None or best.score < min_score:
+        return None
+    return best
+
+
+class TimedLineSegmentSource:
+    """A :class:`SegmentSource` over time-aligned lines + one source asset.
+
+    Binds the generic :func:`find_segment` matcher to a concrete asset so the
+    weave engine can ``resolve(reference) -> ResolvedSegment``.
+    """
+
+    def __init__(
+        self,
+        *,
+        lines: list[TimedLine],
+        asset_path: str | Path,
+        song_end_s: float | None = None,
+        min_score: float = 0.5,
+    ) -> None:
+        self._lines = lines
+        self._asset = Path(asset_path)
+        self._song_end = song_end_s
+        self._min_score = min_score
+
+    def resolve(self, reference: str) -> ResolvedSegment | None:
+        seg = find_segment(
+            self._lines, reference, min_score=self._min_score, song_end_s=self._song_end
+        )
+        if seg is None:
+            return None
+        return ResolvedSegment(
+            asset_path=self._asset,
+            start_s=seg.start_s,
+            end_s=seg.end_s,
+            score=seg.score,
+            matched_text=seg.matched_text,
+        )
+
+
+def _require_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError("ffmpeg not found on PATH (brew install ffmpeg).")
+
+
+def cut_quote(
+    audio_path: str | Path,
+    lines: list[TimedLine],
+    quote: str,
+    out_path: str | Path,
+    *,
+    pad_pre_s: float = 0.15,
+    pad_post_s: float = 0.35,
+    fade_s: float = 0.04,
+    min_score: float = 0.5,
+    song_end_s: float | None = None,
+) -> Segment:
+    """Resolve ``quote`` → segment and cut it from ``audio_path`` (pad + fades).
+
+    Convenience combining :func:`find_segment` + an ffmpeg cut. Returns the
+    resolved :class:`Segment` (raises ``LookupError`` if unmatched). New code
+    should prefer a :class:`SegmentSource` + :func:`braidio.weave.extract_padded`.
+    """
+    _require_ffmpeg()
+    seg = find_segment(lines, quote, min_score=min_score, song_end_s=song_end_s)
+    if seg is None:
+        raise LookupError(f"Could not align reference to audio: {quote[:60]!r}")
+
+    start = max(0.0, seg.start_s - pad_pre_s)
+    end = seg.end_s + pad_post_s
+    dur = end - start
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    fade_out_start = max(0.0, dur - fade_s)
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(audio_path),
+            "-t",
+            f"{dur:.3f}",
+            "-af",
+            f"afade=t=in:st=0:d={fade_s},afade=t=out:st={fade_out_start:.3f}:d={fade_s}",
+            str(out),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return seg

braidio/tts.py

@@ -0,0 +1,163 @@
+"""ElevenLabs narration synthesis.
+
+Thin wrapper over :func:`mixing.text_to_speech` (the ElevenLabs entry point,
+with on-disk caching) applying a voice preset: the ``eleven_multilingual_v2``
+quality model and a locked voice + settings so a whole production sounds like
+one narrator.
+
+Voice defaults to "George — Warm, Captivating Storyteller"; override with the
+``BRAIDIO_TTS_VOICE`` env var (:data:`VOICE_ENV_VAR`) or the ``voice_id`` arg.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from mixing import text_to_speech
+
+# "George — Warm, Captivating Storyteller" (ElevenLabs premade voice).
+DEFAULT_VOICE_ID = "JBFqnCBsd6RMkjVDRZzb"
+DEFAULT_MODEL_ID = "eleven_multilingual_v2"
+VOICE_ENV_VAR = "BRAIDIO_TTS_VOICE"
+
+# Preset from research: neutral-expressive documentary narration.
+DEFAULT_VOICE_SETTINGS: dict[str, float | bool] = {
+    "stability": 0.5,
+    "similarity_boost": 0.75,
+    "style": 0.0,
+    "use_speaker_boost": True,
+    "speed": 0.97,
+}
+
+
+def resolve_voice_id(voice_id: str | None = None) -> str:
+    """Voice id from arg → :data:`VOICE_ENV_VAR` env → default."""
+    return voice_id or os.environ.get(VOICE_ENV_VAR) or DEFAULT_VOICE_ID
+
+
+def narrate(
+    text: str,
+    out_path: str | Path,
+    *,
+    api_key: str | None = None,
+    voice_id: str | None = None,
+    model_id: str = DEFAULT_MODEL_ID,
+    voice_settings: dict | None = None,
+    output_format: str = "mp3_44100_128",
+    refresh: bool = False,
+) -> Path:
+    """Synthesize ``text`` to ``out_path`` (mp3). Returns the path.
+
+    Caching is handled by ``mixing.text_to_speech`` (keyed on text+voice+model);
+    pass ``refresh=True`` to regenerate.
+
+    ``api_key`` is an optional per-request ElevenLabs key: when given it wins
+    over the environment; when ``None`` (default) resolution falls back to
+    ``$ELEVENLABS_API_KEY`` (unchanged behavior). This is what lets a caller
+    thread a per-user BYO key without touching the process environment.
+    """
+    audio = text_to_speech(
+        text,
+        resolve_voice_id(voice_id),
+        api_key=api_key,
+        model_id=model_id,
+        output_format=output_format,
+        voice_settings=voice_settings or DEFAULT_VOICE_SETTINGS,
+        refresh=refresh,
+    )
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(audio)
+    return out
+
+
+DIALOGUE_MODEL_ID = "eleven_v3"
+DIALOGUE_CACHE_ENV_KEY = "BRAIDIO_DIALOGUE_CACHE_DIR"
+
+
+def _dialogue_cache_dir():
+    from mixing import _cache
+
+    return _cache.default_cache_dir("braidio-dialogue", env_key=DIALOGUE_CACHE_ENV_KEY)
+
+
+def text_to_dialogue(
+    turns,
+    *,
+    model_id: str = DIALOGUE_MODEL_ID,
+    output_format: str = "mp3_44100_128",
+    settings: dict | None = None,
+    seed: int | None = None,
+    api_key: str | None = None,
+    cache=True,
+    refresh: bool = False,
+) -> bytes:
+    """Synthesize a multi-speaker exchange in ONE pass (ElevenLabs Text-to-Dialogue).
+
+    Unlike per-line :func:`narrate`, this renders the whole conversation together
+    so prosody is conditioned across turns — the key to sounding like people
+    *talking to each other* rather than alternating monologues (see braidio#1 /
+    ``docs/research/conversational-vs-narration-tts.md``). ``eleven_v3`` only.
+
+    **Cached** (like :func:`narrate`/``mixing.text_to_speech``): the result is
+    keyed on the SHA-256 of every parameter that affects the audio (turns,
+    voices, model, settings, seed, format). A cache hit returns the *same* bytes
+    instantly — no API call, deterministic master, and the basis for partial
+    re-render (change one exchange → only its key changes). ``cache=True``
+    (default) uses :data:`DIALOGUE_CACHE_ENV_KEY` / the default cache dir;
+    ``cache=False`` disables it; a path uses that dir. ``refresh=True`` forces a
+    re-render (to re-roll a v3 take). Because v3 is nondeterministic, caching a
+    seedless call freezes one random take — pass a ``seed`` for reproducibility.
+
+    Args:
+        turns: ordered ``(voice_id, text)`` pairs (or ``{"voice_id", "text"}``).
+            Keep each request under ~2000 chars total (API limit).
+        settings: optional model settings dict (e.g. ``{"stability": 0.45}``).
+
+    Returns: raw audio bytes in ``output_format``.
+    """
+    import json
+
+    from mixing import _cache
+
+    inputs = []
+    for t in turns:
+        if isinstance(t, (tuple, list)):
+            inputs.append({"voice_id": t[0], "text": t[1]})
+        else:
+            inputs.append({"voice_id": t["voice_id"], "text": t["text"]})
+
+    cache_dir = _cache.resolve_cache_dir(cache, default_factory=_dialogue_cache_dir)
+    key = None
+    if cache_dir is not None:
+        key = _cache.sha256_key(
+            "text_to_dialogue",
+            json.dumps(inputs, sort_keys=True, ensure_ascii=False),
+            model_id,
+            output_format,
+            json.dumps(settings or {}, sort_keys=True),
+            "" if seed is None else str(seed),
+        )
+        if not refresh:
+            cached = _cache.read_cache(cache_dir, key, suffix=".audio")
+            if cached is not None:
+                return cached
+
+    from elevenlabs.client import ElevenLabs
+
+    client = ElevenLabs(
+        api_key=api_key
+        or os.environ.get("ELEVENLABS_API_KEY")
+        or os.environ.get("ELEVEN_API_KEY")
+    )
+    kwargs = {"inputs": inputs, "model_id": model_id, "output_format": output_format}
+    if settings is not None:
+        kwargs["settings"] = settings
+    if seed is not None:
+        kwargs["seed"] = seed
+    audio = b"".join(client.text_to_dialogue.convert(**kwargs))
+
+    if cache_dir is not None and key is not None:
+        _cache.write_cache(cache_dir, key, audio, suffix=".audio")
+    return audio

braidio/weave.py

@@ -0,0 +1,260 @@
+"""Weave narration + audio clips on a timeline (#21) — the reusable mix engine.
+
+Two generic, Hamilton-agnostic primitives:
+
+- :func:`extract_padded` — extract ``[start, end]`` from a source asset but
+  **padded** by pre/post-roll (so the words are captured cleanly) with in/out
+  fades on the padded edges. The padded, faded edges are what we tuck under the
+  neighbouring narration.
+- :func:`weave_timeline` — place ordered narration/clip parts on a timeline
+  where each clip **overlaps its neighbours** by ``clip_edge_overlap_s`` and its
+  faded padded edges duck under the speech, so **speech stays dominant**, then
+  mix (``amix`` sum) and loudness-normalize.
+
+This is the audio counterpart of a video timeline; it consumes plain file paths
++ numbers, no Genius/lyrics knowledge (that resolution lives in
+``graph/align.py`` and the Hamilton adapters). Ducking here is achieved by
+fade-shaped overlap; a dynamic sidechain duck (``duck_db``) is a documented
+refinement (see #21 / the research).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _require_ffmpeg() -> None:
+    if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
+        raise RuntimeError("ffmpeg/ffprobe not found on PATH (brew install ffmpeg).")
+
+
+def duration_s(path: str | Path) -> float:
+    _require_ffmpeg()
+    r = subprocess.run(
+        ["ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", str(path)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return float(json.loads(r.stdout)["format"]["duration"])
+
+
+def extract_padded(
+    asset_path: str | Path,
+    start_s: float,
+    end_s: float,
+    out_path: str | Path,
+    *,
+    pre_roll_s: float = 0.4,
+    post_roll_s: float = 0.3,
+    fade_in_s: float = 0.5,
+    fade_out_s: float = 0.8,
+) -> Path:
+    """Extract ``[start_s-pre_roll, end_s+post_roll]`` with in/out fades.
+
+    The target words sit in the middle; the padded, faded head/tail are the
+    parts that overlap (tuck under) neighbouring narration in the weave.
+    """
+    _require_ffmpeg()
+    start = max(0.0, start_s - pre_roll_s)
+    end = end_s + post_roll_s
+    dur = max(0.05, end - start)
+    fo_start = max(0.0, dur - fade_out_s)
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(asset_path),
+            "-t",
+            f"{dur:.3f}",
+            "-af",
+            f"afade=t=in:st=0:d={fade_in_s},afade=t=out:st={fo_start:.3f}:d={fade_out_s}",
+            str(out),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return out
+
+
+@dataclass(frozen=True)
+class TimelineItem:
+    """One part on the weave timeline.
+
+    ``placement`` ``"sequential"`` (default — narration, and clean ``before`` /
+    ``after`` clips) lays the part in its own slot. ``"under"`` overlays the part
+    beneath the *following* sequential part (it does not consume its own slot),
+    attenuated by ``duck_db`` — a ducked underlay (a clip talked over, or later a
+    music bed).
+    """
+
+    kind: str  # "narration" | "clip"
+    path: str
+    placement: str = "sequential"  # "sequential" | "under"
+    duck_db: float = 0.0  # attenuation applied when placement == "under" (e.g. -15)
+
+
+def layout_placed(
+    kinds: list[str],
+    durs: list[float],
+    placements: list[str],
+    *,
+    clip_edge_overlap_s: float,
+    narration_crossfade_s: float,
+) -> list[float]:
+    """Start offset (s) of each part, placement-aware. Pure function.
+
+    Sequential parts advance a running cursor: a clip (or a part following a clip)
+    starts ``clip_edge_overlap_s`` before the cursor so its faded edges tuck under
+    the neighbour; narration-after-narration overlaps by ``narration_crossfade_s``.
+    An ``"under"`` part starts *at* the cursor (concurrent with the next
+    sequential part) and does **not** advance it — so it overlays what follows.
+    Clamped ≥ 0.
+    """
+    starts: list[float] = [0.0] * len(kinds)
+    cursor = 0.0
+    prev_seq_kind: str | None = None
+    for i, kind in enumerate(kinds):
+        if placements[i] == "under":
+            starts[i] = (
+                cursor  # overlay the following sequential part; cursor unchanged
+            )
+            continue
+        if prev_seq_kind is None:
+            start = 0.0
+        elif kind == "clip" or prev_seq_kind == "clip":
+            start = max(0.0, cursor - clip_edge_overlap_s)
+        else:
+            start = max(0.0, cursor - narration_crossfade_s)
+        starts[i] = start
+        cursor = start + durs[i]
+        prev_seq_kind = kind
+    return starts
+
+
+def layout_starts(
+    kinds: list[str],
+    durs: list[float],
+    *,
+    clip_edge_overlap_s: float,
+    narration_crossfade_s: float,
+) -> list[float]:
+    """Start offset (s) of each part (all sequential). Thin wrapper over
+    :func:`layout_placed` — kept for callers that don't use placement."""
+    return layout_placed(
+        kinds,
+        durs,
+        ["sequential"] * len(kinds),
+        clip_edge_overlap_s=clip_edge_overlap_s,
+        narration_crossfade_s=narration_crossfade_s,
+    )
+
+
+def weave_timeline(
+    items: list[TimelineItem],
+    out_path: str | Path,
+    *,
+    clip_edge_overlap_s: float = 0.5,
+    narration_crossfade_s: float = 0.12,
+    target_lufs: float = -16.0,
+    true_peak: float = -1.0,
+    sample_rate: int = 44100,
+    bed=None,  # optional braidio.music.MusicBed — instrumental underscore under all
+) -> Path:
+    """Place items on a timeline and mix. Clips overlap neighbours by
+    ``clip_edge_overlap_s`` (their faded edges tuck under narration); narration
+    parts butt-join with a small crossfade. Returns ``out_path``.
+
+    ``bed`` (a :class:`~braidio.music.MusicBed`) lays an instrumental underscore
+    under the whole production: it's rendered to cover the timeline, attenuated,
+    and mixed in posted by ``bed.lead_in_s``. Falls back to a plain concat feel
+    when ``clip_edge_overlap_s == 0`` and there's nothing to overlay.
+    """
+    _require_ffmpeg()
+    if not items:
+        raise ValueError("weave_timeline needs at least one item")
+
+    durs = [duration_s(it.path) for it in items]
+    starts = layout_placed(
+        [it.kind for it in items],
+        durs,
+        [it.placement for it in items],
+        clip_edge_overlap_s=clip_edge_overlap_s,
+        narration_crossfade_s=narration_crossfade_s,
+    )
+    out = Path(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    # Build one amix graph: (duck →) delay each input to its start, then sum.
+    inputs: list[str] = []
+    for it in items:
+        inputs += ["-i", it.path]
+    filters: list[str] = []
+    labels: list[str] = []
+    for i, (start, it) in enumerate(zip(starts, items)):
+        delay_ms = int(round(start * 1000))
+        lbl = f"a{i}"
+        # normalize every input to stereo @ sample_rate so amix keeps stereo
+        # (narration is mono, song clips are stereo) — else it collapses to mono.
+        chain = f"[{i}:a]aformat=sample_rates={sample_rate}:channel_layouts=stereo"
+        # ducked underlay: attenuate before delaying so it sits beneath the talk.
+        if it.placement == "under" and it.duck_db:
+            chain += f",volume={it.duck_db}dB"
+        chain += f",adelay={delay_ms}:all=1[{lbl}]"
+        filters.append(chain)
+        labels.append(f"[{lbl}]")
+
+    # Optional music bed: prepare it to cover the timeline, then mix it in posted.
+    if bed is not None:
+        from braidio.music import prepare_bed
+
+        total_s = max(s + d for s, d in zip(starts, durs))
+        bed_path = prepare_bed(
+            bed, total_s, out.parent / f"_bed_{out.stem}.mp3", sample_rate=sample_rate
+        )
+        idx = len(items)
+        inputs += ["-i", str(bed_path)]
+        lead_ms = int(round(bed.lead_in_s * 1000))
+        filters.append(
+            f"[{idx}:a]aformat=sample_rates={sample_rate}:channel_layouts=stereo,"
+            f"adelay={lead_ms}:all=1[bed]"
+        )
+        labels.append("[bed]")
+
+    n_inputs = len(labels)
+    mix = (
+        "".join(labels) + f"amix=inputs={n_inputs}:normalize=0:dropout_transition=0[m]"
+    )
+    norm = f"[m]loudnorm=I={target_lufs}:TP={true_peak}:LRA=11[out]"
+    filtergraph = ";".join(filters + [mix, norm])
+
+    subprocess.run(
+        [
+            "ffmpeg",
+            "-y",
+            *inputs,
+            "-filter_complex",
+            filtergraph,
+            "-map",
+            "[out]",
+            "-ar",
+            str(sample_rate),
+            "-ac",
+            "2",
+            "-b:a",
+            "192k",
+            str(out),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return out