braidio 0.0.2__tar.gz

braidio-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

braidio-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@v0.1.81`).
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`) because `inherit` does
+    # not reliably propagate caller-repo secrets to a reusable workflow owned
+    # by a different account (verified empirically: personal-account caller +
+    # i2mint-org workflow → `${{ secrets.PYPI_PASSWORD }}` resolved to empty).
+    #
+    # This list is the per-repo *transport*: it should contain PYPI_PASSWORD
+    # (for publishing) plus every secret your tests/CI need. It is generated
+    # from [tool.wads.ci.env] in pyproject.toml. To add one, run
+    #   wads-secrets add VAR_NAME            # updates pyproject + this block
+    # or just append a line below. *Which* of these become job env vars (and
+    # which are required) is controlled by [tool.wads.ci.env] — passing a
+    # secret here does not by itself put it in the environment.
+    #
+    # A secret name must also be declared in the reusable workflow's superset
+    # (wads/ci_secrets.py). `wads-secrets add` warns if it is not.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

braidio-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

braidio-0.0.2/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.

braidio-0.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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