braidio 0.0.2__py3-none-any.whl

braidio/weave_config.py

@@ -0,0 +1,121 @@
+"""WeaveConfig — every editing choice for weaving narration + segments (#20).
+
+One frozen config object that exposes **all** the knobs (casting, turns, pacing,
+timing, clip weaving, loudness) so a composer picks combinations rather than
+inheriting one hardcoded style (the "enable all choices" mandate of #18/#28).
+
+Defaults come from ``docs/research/podcast-audio-weaving-editing.md``. This
+module is deliberately **Hamilton-agnostic** — no Genius/LRCLIB/episode imports —
+so it can move to the reusable weave package unchanged (#19). It references the
+generic voice pools/ids only.
+
+The config is designed to serialize cleanly (:meth:`WeaveConfig.to_dict`) into a
+``render-config`` provenance node (#26), so a render is reproducible from its
+recorded choices.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, replace
+from typing import Any, Mapping
+
+from braidio.multivoice import POOL_4, POOL_MANY
+from braidio.tts import DEFAULT_VOICE_ID
+
+# Research-recommended base narration settings (v2-tuned).
+_DEFAULT_VOICE_SETTINGS: dict[str, Any] = {
+    "stability": 0.35,
+    "similarity_boost": 0.75,
+    "style": 0.35,
+    "use_speaker_boost": True,
+}
+
+
+@dataclass(frozen=True)
+class WeaveConfig:
+    """All editing choices for a narration+segment weave. Frozen + serializable."""
+
+    # --- Casting ------------------------------------------------------------
+    voices: tuple[str, ...] = (DEFAULT_VOICE_ID,)  # 1 id = single; >1 = cycled pool
+    pool_label: str = "single"
+    voice_seed: int = 7
+    avoid_immediate_repeat: bool = True
+
+    # --- Delivery (TTS) -----------------------------------------------------
+    model_id: str = "eleven_multilingual_v2"
+    voice_settings: Mapping[str, Any] = field(
+        default_factory=lambda: dict(_DEFAULT_VOICE_SETTINGS)
+    )
+
+    # --- Segmentation / turns ----------------------------------------------
+    segmentation_unit: str = "sentence"  # sentence | clause | paragraph | beat
+    min_turn: int = 2  # segments a voice speaks before switching
+    max_turn: int = 4
+
+    # --- Pacing -------------------------------------------------------------
+    speed_base: float = 1.0
+    speed_jitter: float = 0.04  # ± per turn
+
+    # --- Timing between turns ----------------------------------------------
+    crossfade_s: float = 0.12
+    gap_turn_s: float = 0.0  # silence between turns (mutually exclusive w/ crossfade)
+    overlap_turn_s: float = 0.0  # speaker interruption (#22 — not yet rendered)
+
+    # --- Clip weaving (#21) -------------------------------------------------
+    clip_pre_roll_s: float = 0.4  # extend extraction before the words
+    clip_post_roll_s: float = 0.3  # …and after — capture words cleanly
+    clip_fade_in_s: float = 0.5
+    clip_fade_out_s: float = 0.8
+    clip_edge_overlap_s: float = 0.5  # tuck faded clip edges under narration
+    duck_db: float = -15.0  # duck clip under speech (speech dominant)
+
+    # --- Global mix ---------------------------------------------------------
+    target_lufs: float = -16.0
+    true_peak_dbtp: float = -1.0
+    sample_rate: int = 44100
+
+    def __post_init__(self) -> None:
+        if not self.voices:
+            raise ValueError("WeaveConfig.voices must have at least one voice id")
+        if not (1 <= self.min_turn <= self.max_turn):
+            raise ValueError("require 1 <= min_turn <= max_turn")
+
+    @property
+    def is_multivoice(self) -> bool:
+        return len(self.voices) > 1
+
+    def with_(self, **changes: Any) -> "WeaveConfig":
+        """Return a copy with fields overridden (e.g. ``cfg.with_(min_turn=1)``)."""
+        return replace(self, **changes)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Stable serialization for a ``render-config`` provenance node (#26)."""
+        d = asdict(self)
+        d["voices"] = list(self.voices)
+        d["voice_settings"] = dict(self.voice_settings)
+        return d
+
+
+# --- Presets -----------------------------------------------------------------
+
+_POOL_4_IDS = tuple(v.id for v in POOL_4)
+_POOL_MANY_IDS = tuple(v.id for v in POOL_MANY)
+
+SINGLE_NARRATOR = WeaveConfig(voices=(DEFAULT_VOICE_ID,), pool_label="single")
+
+DOCUMENTARY_LYRICS = WeaveConfig(  # the research default: one narrator, tight turns
+    voices=(DEFAULT_VOICE_ID,), pool_label="single", min_turn=1, max_turn=3
+)
+
+PANEL_4 = WeaveConfig(voices=_POOL_4_IDS, pool_label="panel-4", min_turn=2, max_turn=4)
+
+INTERVIEW_MANY = WeaveConfig(  # Hamilton's chosen default
+    voices=_POOL_MANY_IDS, pool_label="interview-many", min_turn=2, max_turn=4
+)
+
+PRESETS: dict[str, WeaveConfig] = {
+    "single_narrator": SINGLE_NARRATOR,
+    "documentary_lyrics": DOCUMENTARY_LYRICS,
+    "panel_4": PANEL_4,
+    "interview_many": INTERVIEW_MANY,
+}

braidio-0.0.2.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: braidio
+Version: 0.0.2
+Summary: Weave narration with extracted media segments into audiovisual productions
+Project-URL: Homepage, https://github.com/thorwhalen/braidio
+Project-URL: Repository, https://github.com/thorwhalen/braidio
+Project-URL: Documentation, https://thorwhalen.github.io/braidio
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,elevenlabs,ffmpeg,narration,podcast,tts
+Requires-Python: >=3.10
+Requires-Dist: elevenlabs
+Requires-Dist: mixing
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: graph
+Requires-Dist: lacing; extra == 'graph'
+Provides-Extra: nw-app
+Requires-Dist: falaw; extra == 'nw-app'
+Requires-Dist: lacing; extra == 'nw-app'
+Requires-Dist: nw; extra == 'nw-app'
+Description-Content-Type: text/markdown
+
+# braidio
+
+**Weave *commentary* — solo, duo, panel, debate, interview, documentary — with
+source clips into a production.**
+
+`braidio` braids the strands of a piece that talks *about* something (a song, a
+book, a film, an event) into one rendered production. The **talk is the spine** —
+a single presenter, two hosts, a panel, a narrator — and **source clips and
+narration bridges are the "illustration" layers** woven onto it. Audio today,
+with visual support to follow (it braids A/V — *braid-io*, and it sounds like
+*radio*).
+
+Two things braidio gives you:
+
+1. **Ready-made format templates** under the standard, industry names people
+   already recognize — *Deep Dive*, *Song Exploder-style*, *Panel*, *Debate*,
+   *Documentary VO* — each a high-quality bundle of defaults you can render in one
+   call.
+2. **Full parametrization** underneath, so any style is expressible: a `Script`
+   of beats, cast via a `ConversationCast`, tuned by `WeaveConfig` + `Delivery`,
+   with per-beat voice/delivery overrides.
+
+> Status: early. `braidio` is extracted from the
+> [Hamilton lyrics-podcast](https://github.com/thorwhalen/Hamilton) (its first
+> application) into a reusable engine. APIs will move quickly.
+
+## The model
+
+A production is a **`Script`** — an ordered list of **beats**:
+
+| Beat | What it is |
+|---|---|
+| `Narration(text, voice?, voice_settings?, …)` | one voice reading — a narrator **or** a solo presenter. `voice` / `voice_settings` override per beat, so one timeline can carry a lively **presenter** *and* a graver **book-narrator**. |
+| `Dialogue(turns=[(role, text)])` | a multi-speaker exchange, synthesized in **one pass** (so it sounds like people *talking to each other*, not alternating monologues). A `ConversationCast` maps roles → voices. |
+| `SegmentBeat(reference)` | a span of source media to cut and weave in (resolved by a pluggable `SegmentSource` — quote → `[start, end]`). |
+
+`WeaveConfig` holds every editing knob (casting, turns, pacing, clip pre/post-roll,
+duck, crossfades, loudness). `Delivery` presets bundle the TTS model + voice
+settings (e.g. `V2_PRESENTER` lively vs `V2_NARRATOR` grave). The renderer
+loudness-normalizes every part, tucks clips under the speech (speech stays
+dominant), and masters the result.
+
+## Ready-made formats
+
+Pick a standard format and render it — the template supplies the cast, voices,
+delivery and mix defaults:
+
+```python
+from braidio import DEEP_DIVE, render_format
+
+render_format(DEEP_DIVE, script, source=my_source, out_path="episode.mp3")
+```
+
+| Preset id | Standard name | Shape |
+|---|---|---|
+| `solo_explainer` | Solo-Presenter Explainer (video/audio essay, close reading) | one presenter + exhibits |
+| `deep_dive` | Two-Host Conversation (*"Deep Dive"*, Switched on Pop, NotebookLM) | two hosts; one teaches, one probes |
+| `interview` | Interview (host + guest) | Q→A, guest is the center |
+| `interview_host_removed` | *Song Exploder*-style (host removed) | guest monologue; each claim illustrated by its isolated stem; full artifact at the tail |
+| `panel` | Panel / Roundtable (Pop Culture Happy Hour) | moderator routes distinct voices |
+| `debate` | Debate (Oxford-style) | proposition / opposition / moderator, phased |
+| `documentary_vo` | Documentary Voice-Over (*"Voice of God"*, This American Life) | narrator on top; interviews + clips + actuality beneath |
+
+**Narration bridges** and **source clips** are optional *illustration layers*
+usable with any format. The taxonomy, weaving grammar, exemplar recipes and the
+full template specs are in
+[`misc/docs/research/commentary-formats-and-styles.md`](misc/docs/research/commentary-formats-and-styles.md).
+
+*Render support note:* the cast, per-role voices, narration deliveries, loudness
+master, **per-clip placement** — `SegmentBeat(placement="before" | "under" |
+"after")`, where `under` lays the clip concurrently beneath the talk, ducked —
+and a **music bed** (`MusicBed`, an app-supplied instrumental laid under the whole
+production) are applied today. Scene stings and fade-to-spotlight (dropping the
+bed before a key exhibit) remain on the render-side roadmap (braidio#1).
+
+## Parametrize anything
+
+The templates are just good defaults over the primitives — compose directly for
+full control:
+
+```python
+from braidio import Script, Dialogue, Narration, SegmentBeat, WeaveConfig
+from braidio.conversation import ConversationCast, JESSICA, CHRIS
+from braidio import V2_NARRATOR, render_production
+
+script = Script(
+    title="…",
+    id_slug="01",
+    beats=[
+        Dialogue(
+            (("A", "First thing that gets me…"), ("B", "right — but isn't that…"))
+        ),
+        SegmentBeat("the lyric being discussed", label="hook"),
+        Narration(
+            "Here's how the book tells it —", voice_settings=V2_NARRATOR.voice_settings
+        ),  # graver, per-beat
+    ],
+)
+render_production(
+    script,
+    source=my_source,
+    cast=ConversationCast(roles={"A": JESSICA, "B": CHRIS}),
+    config=WeaveConfig(),
+    out_path="out.mp3",
+)
+```
+
+## What it deliberately does *not* do
+
+braidio is a thin orchestration layer. It **delegates**:
+
+| Concern | Owner |
+|---|---|
+| Content acquisition (Genius, audiobooks, news…) | the consuming app, via `SegmentSource` adapters |
+| Linked-artifact graph / content-addressed media | [`lacing`](https://github.com/thorwhalen/lacing) |
+| Project workflow, provenance, plan/execute, partial re-render | [`nw`](https://github.com/thorwhalen/nw) |
+| Video render + visual support | [`reelee`](https://github.com/thorwhalen/reelee) |
+| Raw audio DSP + TTS (crop, concat, duck, loudnorm, synth) | [`mixing`](https://github.com/thorwhalen/mixing) / `falaw` |
+
+braidio orchestrates these; it never reimplements the DSP or the graph.
+
+## Ecosystem
+
+`braidio` is a **production kind** on top of `nw` — a reusable definition of
+"commentary that weaves talk with extracted media" — the way a music video is
+another production kind. It sits on `lacing` (graph) + `nw` (workflow /
+provenance) + `mixing`/`falaw` (audio/TTS), and will use `reelee` for video. The
+optional nw-app layer (`braidio.HAS_GRAPH` / `HAS_NW`) records render choices as
+provenance so a change re-renders only the affected parts.
+
+## Install
+
+```bash
+pip install braidio   # (once published)
+```
+
+## License
+
+MIT

braidio-0.0.2.dist-info/RECORD

@@ -0,0 +1,25 @@
+braidio/__init__.py,sha256=KVLssvBEDrufzyNBgn36jHQsD0uOFk0uJbHUHMSD0I8,5536
+braidio/compose.py,sha256=fLzkg_CP2B5gC4-M_odBU0q6JpWzpOMXPXyII5kGD4U,2476
+braidio/conversation.py,sha256=2WI5eJ2TUdBb7YIopUWbsMUcLJwLsg9Z5G5eTtmrWIA,6251
+braidio/delivery.py,sha256=JxfEKd7mYlqG81C2c2b9-5rdUxMxU18p6TA6TgQe_fI,4083
+braidio/formats.py,sha256=dBjyTLYQs8nmLLM2lO2Xy9DQqoHoDl40nqvwamhkRXM,14263
+braidio/kinds.py,sha256=r4wNjCaKs11gHbt7_rrRV0jOXGD7n9L_aE_3UdGWf_0,333
+braidio/multivoice.py,sha256=KlBsjNP4ImtGKZCil5bzIFbdDpiZZ07kMw77sDcZ3ko,8373
+braidio/music.py,sha256=D9LeXbIf1uLKJtf1a2zOATYFSRaINvFv_KbYrnDigW0,3824
+braidio/project.py,sha256=lMk-X_RJBR5Y8Ls1G38cPtGQuFIQi5NnsiqWcUce9lU,1027
+braidio/provenance.py,sha256=rgHUApOgpluDdhqc2dvsGoobD2pxBSVM3nTIePbIZoo,5324
+braidio/render.py,sha256=HQrO-L161niOCZHSdfqDABviBNRX_RpPfM-7b0CLzWo,8499
+braidio/rights.py,sha256=Ddso4VVzrmQwQ0hnNRWD157DykRWmhzNJxJ2UT0HH8k,7338
+braidio/script.py,sha256=8v3KIjeyZuww0vkWgtGUkTz_k82r-EGOQSuNXcy-ELo,4490
+braidio/sources.py,sha256=BBwwNAvu_B5xlEpBghW4YFZ_52aK88htI-FeOfppnvc,7661
+braidio/tts.py,sha256=acFexN9_F1OMOgP8G1hnOG5Pvb2m1fTccatXqf-D81c,5749
+braidio/weave.py,sha256=2B6boSvrjmkLY-Qq51bVw5cfqGIrzzuUejgl4Ia3PjE,8851
+braidio/weave_config.py,sha256=RPOjI3OPHKK-sb_UJ4uxOJH3tS2uOb8RXBguf_De648,4755
+braidio/bodies/__init__.py,sha256=hlDEnSLs_wUOHnHO9fMkcWxwWmB5_Z6wNu2cKdQDZTo,1218
+braidio/bodies/_domain.py,sha256=lTHG7hN6yv6rXcqWXE9ZjSvc_4lBgVSl0cq640Artj8,4521
+braidio/bodies/_render_nodes.py,sha256=1gYU1m7oqJX7jjWc2CfiIbezxRwqc29WoYdjf24EkiY,4100
+braidio/bodies/_tiers.py,sha256=rklo0BG4l7hdC_Kf5cdZRhJ76bdG1V29P9HArmJdlIY,1226
+braidio-0.0.2.dist-info/METADATA,sha256=jvtEeVnplrhXdQZWpHmOJUdBty0_Kb16uwgNwVajngE,7358
+braidio-0.0.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+braidio-0.0.2.dist-info/licenses/LICENSE,sha256=ekE13yCE9fWWEJfP1NPnUJabZ_Wwrc6coKJV2ZZx27w,1068
+braidio-0.0.2.dist-info/RECORD,,

braidio-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

braidio-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.