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.

braidio was extracted from the Hamilton lyrics-podcast (its first application) into a reusable engine. It is now live infrastructure: released on PyPI, served as a multi-tool MCP connector, and imported in production by reelee. Treat a signature change here as having downstream blast radius.

The model

A production is a Script — an ordered list of beats:

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:

from braidio import DEEP_DIVE, render_format

render_format(DEEP_DIVE, script, source=my_source, out_path="episode.mp3")

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.

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 — tracked in braidio#25.

Parametrize anything

The templates are just good defaults over the primitives — compose directly for full control:

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",
)

Cost tracking

ElevenLabs TTS is braidio's only spend (everything else is local ffmpeg). braidio.estimate_cost(script) previews a production's cost before you pay for synthesis, and real renders attribute a per-character cost onto their artifacts. Dollars are a rate estimate — set your ElevenLabs plan's rate for exact figures:

What it deliberately does not do

braidio is a thin orchestration layer. It delegates:

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

pip install braidio

ElevenLabs credentials are needed for TTS; ffmpeg must be on PATH for everything else.

License

MIT