braidio 0.0.2__py3-none-any.whl

braidio/__init__.py

@@ -0,0 +1,242 @@
+"""braidio — weave narration with extracted media segments into productions.
+
+Braid two kinds of strand into one production: authored **narration** (TTS —
+single voice or a cycled pool) and extracted **segments** of source media (song
+clips, audiobook passages, news, SFX). The result renders to an audiovisual
+object.
+
+This is the **functional core** (pure Python over files + numbers; deps:
+``mixing``, ``elevenlabs``, and ``ffmpeg`` on PATH). An optional nw-app layer
+(graph bodies, transforms, provenance / partial re-render) will be added on top
+and imported only when ``nw`` is available — ``import braidio`` never requires
+it.
+
+Extracted from the Hamilton lyrics-podcast; see that project + issues #18/#28.
+"""
+
+from __future__ import annotations
+
+# --- composition model ---
+from braidio.script import (  # noqa: F401
+    Script,
+    Narration,
+    SegmentBeat,
+    Dialogue,
+    Beat,
+    narration_segments,
+)
+
+# --- rights profiles ---
+from braidio.rights import (  # noqa: F401
+    Profile,
+    RightsPolicy,
+    RenderPlan,
+    PlannedBeat,
+    plan_production,
+    find_verbatim_text,
+    content_violations,
+    segment_is_publishable,
+    PUBLISHABLE_CLIP_RIGHTS,
+)
+
+# --- segment sources (reference -> cuttable window) ---
+from braidio.sources import (  # noqa: F401
+    SegmentSource,
+    ResolvedSegment,
+    Segment,
+    TimedLine,
+    TimedLineSegmentSource,
+    find_segment,
+    load_timing,
+    cut_quote,
+)
+
+# --- narration synthesis ---
+from braidio.tts import (  # noqa: F401
+    narrate,
+    text_to_dialogue,
+    resolve_voice_id,
+    DEFAULT_VOICE_ID,
+    DEFAULT_MODEL_ID,
+    DEFAULT_VOICE_SETTINGS,
+    VOICE_ENV_VAR,
+)
+from braidio.conversation import (  # noqa: F401
+    ConversationCast,
+    DEFAULT_CAST,
+    render_dialogue,
+    render_turns_sequential,
+)
+from braidio.delivery import (  # noqa: F401
+    Delivery,
+    DELIVERIES,
+    BASELINE,
+    V2_TUNED,
+    V2_AGGRESSIVE,
+    V2_PRESENTER,
+    V2_NARRATOR,
+    V3_NATURAL,
+    V3_CREATIVE,
+)
+
+# --- multi-voice casting ---
+from braidio.multivoice import (  # noqa: F401
+    Voice,
+    POOL_4,
+    POOL_MANY,
+    POOLS,
+    strip_markup,
+    split_segments,
+    assign_voices,
+    group_turns,
+    render_multivoice,
+)
+
+# --- configuration ---
+from braidio.weave_config import WeaveConfig, PRESETS  # noqa: F401
+
+# --- music bed (instrumental underscore) ---
+from braidio.music import (  # noqa: F401
+    MusicBed,
+    bed_for_intensity,
+    BED_GAIN_BY_INTENSITY,
+)
+
+# --- ready-made format templates (standard-named presets) ---
+from braidio.formats import (  # noqa: F401
+    Format,
+    render_format,
+    FORMATS,
+    SOLO_EXPLAINER,
+    DEEP_DIVE,
+    INTERVIEW,
+    SONG_EXPLODER,
+    PANEL,
+    DEBATE,
+    DOCUMENTARY_VO,
+)
+
+# --- composition + weaving (audio) ---
+from braidio.compose import compose_narration  # noqa: F401
+from braidio.render import render_production  # noqa: F401
+from braidio.weave import (  # noqa: F401
+    TimelineItem,
+    extract_padded,
+    weave_timeline,
+    layout_starts,
+    duration_s,
+)
+
+# --- production kinds (pure) ---
+from braidio.kinds import WeaveKind  # noqa: F401
+
+# --- optional nw-app layer (graph bodies + provenance) --------------------
+# Registers braidio's domain/render body schemas with lacing and exposes the
+# provenance / partial-re-render helpers. Guarded: `import braidio` never needs
+# lacing/nw. `HAS_GRAPH` / `HAS_NW` report what's available.
+HAS_GRAPH = False
+HAS_NW = False
+try:  # needs lacing
+    from braidio import bodies  # noqa: F401  (registers schemas)
+    from braidio.provenance import (  # noqa: F401
+        record_render,
+        stale_after,
+        descendants_of,
+    )
+
+    HAS_GRAPH = True
+except ImportError:  # pragma: no cover - optional dep
+    pass
+try:  # needs nw
+    from braidio.project import Project  # noqa: F401
+
+    HAS_NW = True
+except ImportError:  # pragma: no cover - optional dep
+    pass
+
+__all__ = [
+    # production kinds
+    "WeaveKind",
+    "HAS_GRAPH",
+    "HAS_NW",
+    # script
+    "Script",
+    "Narration",
+    "SegmentBeat",
+    "Dialogue",
+    "Beat",
+    "narration_segments",
+    # rights
+    "Profile",
+    "RightsPolicy",
+    "RenderPlan",
+    "PlannedBeat",
+    "plan_production",
+    "find_verbatim_text",
+    "content_violations",
+    "segment_is_publishable",
+    "PUBLISHABLE_CLIP_RIGHTS",
+    # render
+    "render_production",
+    # sources
+    "SegmentSource",
+    "ResolvedSegment",
+    "Segment",
+    "TimedLine",
+    "TimedLineSegmentSource",
+    "find_segment",
+    "load_timing",
+    "cut_quote",
+    # tts
+    "narrate",
+    "resolve_voice_id",
+    "DEFAULT_VOICE_ID",
+    "DEFAULT_MODEL_ID",
+    "DEFAULT_VOICE_SETTINGS",
+    "VOICE_ENV_VAR",
+    # delivery
+    "Delivery",
+    "DELIVERIES",
+    "BASELINE",
+    "V2_TUNED",
+    "V2_AGGRESSIVE",
+    "V2_PRESENTER",
+    "V2_NARRATOR",
+    "V3_NATURAL",
+    "V3_CREATIVE",
+    # multivoice
+    "Voice",
+    "POOL_4",
+    "POOL_MANY",
+    "POOLS",
+    "strip_markup",
+    "split_segments",
+    "assign_voices",
+    "group_turns",
+    "render_multivoice",
+    # config
+    "WeaveConfig",
+    "PRESETS",
+    # music bed
+    "MusicBed",
+    "bed_for_intensity",
+    "BED_GAIN_BY_INTENSITY",
+    # formats (ready-made templates)
+    "Format",
+    "render_format",
+    "FORMATS",
+    "SOLO_EXPLAINER",
+    "DEEP_DIVE",
+    "INTERVIEW",
+    "SONG_EXPLODER",
+    "PANEL",
+    "DEBATE",
+    "DOCUMENTARY_VO",
+    # compose + weave
+    "compose_narration",
+    "TimelineItem",
+    "extract_padded",
+    "weave_timeline",
+    "layout_starts",
+    "duration_s",
+]

braidio/bodies/__init__.py

@@ -0,0 +1,42 @@
+"""braidio's lacing body schemas + tiers (the nw-app domain vocabulary).
+
+Importing this package **registers every schema** with lacing (side effect of
+importing the submodules). Requires ``lacing``; it is imported lazily by
+``braidio/__init__.py`` only when available, so the functional core never
+needs it.
+"""
+
+from __future__ import annotations
+
+from braidio.bodies._domain import (  # noqa: F401  (import registers)
+    COMMENTARY_V1,
+    SOURCE_V1,
+    AUDIO_CLIP_V1,
+    NARRATIVE_BEAT_V1,
+    EPISODE_V1,
+    CommentaryBodyV1,
+    SourceBodyV1,
+    AudioClipBodyV1,
+    NarrativeBeatBodyV1,
+    EpisodeBodyV1,
+    DOMAIN_SCHEMAS,
+)
+from braidio.bodies._render_nodes import (  # noqa: F401  (import registers)
+    WEAVE_CONFIG_V1,
+    SOURCE_MEDIA_V1,
+    VOICE_ASSIGNMENT_V1,
+    NARRATION_RENDER_V1,
+    SEGMENT_EXTRACTION_V1,
+    EPISODE_RENDER_V1,
+    WeaveConfigBodyV1,
+    SourceMediaBodyV1,
+    VoiceAssignmentBodyV1,
+    NarrationRenderBodyV1,
+    SegmentExtractionBodyV1,
+    EpisodeRenderBodyV1,
+    RENDER_SCHEMAS,
+)
+from braidio.bodies._tiers import TIERS, register_tiers  # noqa: F401
+
+# All schema URIs braidio registers (domain + render).
+SCHEMA_URIS: dict = {**DOMAIN_SCHEMAS, **RENDER_SCHEMAS}

braidio/bodies/_domain.py

@@ -0,0 +1,120 @@
+"""Generic authoring body schemas for a commentary-weave production.
+
+The media-agnostic domain vocabulary: curated commentary, cited sources,
+playable media clips, narrative beats, and the episode container. Registered
+with lacing on import. (Consumer-specific schemas — e.g. Hamilton's Genius
+``song``/``lyric-line``/``referent``/``annotation`` — live in the consumer.)
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from lacing.schema import register_body_schema
+
+COMMENTARY_V1 = "annot://schema/commentary/v1"
+SOURCE_V1 = "annot://schema/source/v1"
+AUDIO_CLIP_V1 = "annot://schema/audio-clip/v1"
+NARRATIVE_BEAT_V1 = "annot://schema/narrative-beat/v1"
+EPISODE_V1 = "annot://schema/episode/v1"
+
+CommentaryFacet = Literal["historical", "musical", "biographical", "production"]
+ClipRights = Literal["copyrighted", "owned-local", "public-domain"]
+"""Rights posture of a playable segment: ``owned-local`` plays only in the
+personal cut; ``copyrighted`` never renders to audio; ``public-domain`` is safe."""
+
+
+class CommentaryBodyV1(BaseModel):
+    """A curated/generated commentary note, grounded in ``source`` nodes."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    text: str = Field(..., description="The commentary, as narrated/derived.")
+    facet: CommentaryFacet = Field(..., description="Lens: historical/musical/…")
+    source_ids: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Ids of the source/v1 nodes this draws on.",
+    )
+    generated_by: str = Field(
+        ..., description="'human:<handle>' or 'agent:<model>@<hash>'."
+    )
+
+
+class SourceBodyV1(BaseModel):
+    """A citable source node — primary material, a book, a web page."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    kind: str = Field(
+        ..., description="Open source class (e.g. 'founders-online', 'book')."
+    )
+    title: str = Field(..., description="Source title / heading.")
+    citation: str = Field(..., description="Human-readable citation string.")
+    url: str = Field("", description="Canonical URL, if any.")
+    public_domain: bool = Field(..., description="True if usable in the published cut.")
+    excerpt: Optional[str] = Field(None, description="Optional quoted excerpt.")
+
+
+class AudioClipBodyV1(BaseModel):
+    """A playable media segment. The interval is on the annotation's ``MediaRef``;
+    this body carries clip metadata and the load-bearing ``rights`` flag."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    source_node_id: str = Field(
+        ..., description="Id of the source-media/song node this clip cuts."
+    )
+    label: str = Field(..., description="Human label, e.g. 'opening 8 bars'.")
+    rights: ClipRights = Field(
+        ..., description="Rights posture (drives render profile)."
+    )
+    gain_db: Optional[float] = Field(None, description="Optional gain (dB) when mixed.")
+    fade: Optional[tuple[float, float]] = Field(
+        None,
+        description="Optional (fade_in_s, fade_out_s) applied when this clip plays.",
+    )
+
+
+class NarrativeBeatBodyV1(BaseModel):
+    """One unit of the script: spoken narration, ordered, optionally playing a clip."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    beat_id: str = Field(..., description="Zero-padded ordering key (e.g. '0007').")
+    text: str = Field(..., description="Spoken narration text.")
+    style: Optional[str] = Field(
+        None, description="Optional delivery/voice style hint."
+    )
+    draws_on: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Ids this beat is derived from (commentary / source / clip nodes).",
+    )
+    plays_clip: Optional[str] = Field(
+        None, description="Id of an audio-clip/v1 to play here."
+    )
+
+
+class EpisodeBodyV1(BaseModel):
+    """An ordered container of narrative beats (and the clips they reference)."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    title: str = Field(..., description="Episode title.")
+    ordered_member_ids: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Ids of narrative-beat nodes, in play order.",
+    )
+
+
+DOMAIN_SCHEMAS: dict[str, type[BaseModel]] = {
+    COMMENTARY_V1: CommentaryBodyV1,
+    SOURCE_V1: SourceBodyV1,
+    AUDIO_CLIP_V1: AudioClipBodyV1,
+    NARRATIVE_BEAT_V1: NarrativeBeatBodyV1,
+    EPISODE_V1: EpisodeBodyV1,
+}
+
+for _uri, _model in DOMAIN_SCHEMAS.items():
+    register_body_schema(_uri, _model)

braidio/bodies/_render_nodes.py

@@ -0,0 +1,107 @@
+"""Render-provenance body schemas — record the render *choices* + outputs.
+
+These make a render traceable and **partially re-renderable**: each output node
+records what it was derived from (via the annotation's
+``provenance.was_derived_from``) plus a **cache key** hashing the inputs that
+actually affect the audio. Change one beat or one parameter → only its
+descendants are stale (see :mod:`braidio.provenance`). See the design in
+``misc/docs/Extraction and nw-App Design.md`` and nw's render-provenance doc.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+from lacing.schema import register_body_schema
+
+WEAVE_CONFIG_V1 = "annot://schema/weave-config/v1"
+SOURCE_MEDIA_V1 = "annot://schema/source-media/v1"
+VOICE_ASSIGNMENT_V1 = "annot://schema/voice-assignment/v1"
+NARRATION_RENDER_V1 = "annot://schema/narration-render/v1"
+SEGMENT_EXTRACTION_V1 = "annot://schema/segment-extraction/v1"
+EPISODE_RENDER_V1 = "annot://schema/episode-render/v1"
+
+
+class WeaveConfigBodyV1(BaseModel):
+    """A frozen snapshot of every render choice (``WeaveConfig.to_dict()``)."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    config: dict[str, Any] = Field(..., description="The full WeaveConfig snapshot.")
+
+
+class SourceMediaBodyV1(BaseModel):
+    """A pointer to an imported source asset (its content-addressed artifact)."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    label: str = Field(
+        ..., description="Human label for the source (e.g. a song title)."
+    )
+    asset_id: str = Field(
+        ..., description="lacing Artifact asset_id of the source media."
+    )
+    rights: str = Field("owned-local", description="Rights posture of the source.")
+
+
+class VoiceAssignmentBodyV1(BaseModel):
+    """Which voice a turn got (+ pool + seed) — a render choice."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    voice_id: str = Field(..., description="Voice id used for this turn.")
+    pool_label: str = Field("single", description="Pool the voice was drawn from.")
+    seed: int = Field(0, description="Assignment seed (for reproducibility).")
+
+
+class NarrationRenderBodyV1(BaseModel):
+    """The audio Artifact for one synthesized narration turn + its cache key."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    cache_key: str = Field(..., description="hash(text, voice, model, settings).")
+    artifact_id: Optional[str] = Field(
+        None, description="lacing Artifact asset_id (once rendered)."
+    )
+    duration_s: float = Field(0.0, description="Rendered duration, seconds.")
+
+
+class SegmentExtractionBodyV1(BaseModel):
+    """The cut+padded audio Artifact for one segment + its cache key."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    cache_key: str = Field(
+        ..., description="hash(source asset, start, end, pads, fades)."
+    )
+    start_s: float = Field(..., description="Padded extraction start (seconds).")
+    end_s: float = Field(..., description="Padded extraction end (seconds).")
+    artifact_id: Optional[str] = Field(None, description="lacing Artifact asset_id.")
+
+
+class EpisodeRenderBodyV1(BaseModel):
+    """The assembled output Artifact for an episode + its profile."""
+
+    model_config = {"frozen": True, "extra": "forbid"}
+
+    profile: str = Field(..., description="Render profile: personal | published.")
+    ordered_member_ids: tuple[str, ...] = Field(
+        default_factory=tuple, description="Ids of the member render nodes, in order."
+    )
+    artifact_id: Optional[str] = Field(None, description="lacing Artifact of the mix.")
+    duration_s: float = Field(0.0, description="Total duration, seconds.")
+
+
+RENDER_SCHEMAS: dict[str, type[BaseModel]] = {
+    WEAVE_CONFIG_V1: WeaveConfigBodyV1,
+    SOURCE_MEDIA_V1: SourceMediaBodyV1,
+    VOICE_ASSIGNMENT_V1: VoiceAssignmentBodyV1,
+    NARRATION_RENDER_V1: NarrationRenderBodyV1,
+    SEGMENT_EXTRACTION_V1: SegmentExtractionBodyV1,
+    EPISODE_RENDER_V1: EpisodeRenderBodyV1,
+}
+
+for _uri, _model in RENDER_SCHEMAS.items():
+    register_body_schema(_uri, _model)

braidio/bodies/_tiers.py

@@ -0,0 +1,43 @@
+"""Generic tiers for a commentary-weave production + its render nodes.
+
+Standoff layers (no temporal nesting); a consumer adds its own structural spine
+(e.g. Hamilton's ``songs → sections → lyric-lines → words``). Add to a store
+with :func:`register_tiers`.
+"""
+
+from __future__ import annotations
+
+from lacing.tier import Tier
+
+# Authoring layers.
+_COMMENTARY = Tier("commentary")
+_SOURCES = Tier("sources")
+_AUDIO_CLIPS = Tier("audio-clips")
+_NARRATIVE_BEATS = Tier("narrative-beats")
+# Render-provenance layers.
+_WEAVE_CONFIGS = Tier("weave-configs")
+_SOURCE_MEDIA = Tier("source-media")
+_VOICE_ASSIGNMENTS = Tier("voice-assignments")
+_NARRATION_RENDERS = Tier("narration-renders")
+_SEGMENT_EXTRACTIONS = Tier("segment-extractions")
+_EPISODE_RENDERS = Tier("episode-renders")
+
+TIERS: tuple[Tier, ...] = (
+    _COMMENTARY,
+    _SOURCES,
+    _AUDIO_CLIPS,
+    _NARRATIVE_BEATS,
+    _WEAVE_CONFIGS,
+    _SOURCE_MEDIA,
+    _VOICE_ASSIGNMENTS,
+    _NARRATION_RENDERS,
+    _SEGMENT_EXTRACTIONS,
+    _EPISODE_RENDERS,
+)
+"""braidio's generic + render tiers."""
+
+
+def register_tiers(store) -> None:
+    """Add every tier in :data:`TIERS` to ``store`` (has ``add_tier``)."""
+    for tier in TIERS:
+        store.add_tier(tier)

braidio/compose.py

@@ -0,0 +1,67 @@
+"""Config-driven narration composition (#20) — the reusable entrypoint.
+
+Turn a list of narration segments + a :class:`WeaveConfig` into audio. Dispatches
+single-voice and multi-voice uniformly (single = a pool of one), reading *every*
+knob from the config. This is the seed of the reusable weave engine (#18/#19):
+it has no Hamilton-specifics — it takes plain text segments and a config.
+
+Clip weaving (padded extraction + ducking) is composed separately (#21); this
+module renders the narration track.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from braidio.multivoice import POOL_MANY, Voice, render_multivoice
+from braidio.tts import DEFAULT_VOICE_ID
+from braidio.weave_config import WeaveConfig
+
+# Registry so pooled ids render with human-readable turn labels; unknown ids
+# fall back to the id itself.
+_KNOWN_VOICES: dict[str, Voice] = {v.id: v for v in POOL_MANY}
+_KNOWN_VOICES.setdefault(
+    DEFAULT_VOICE_ID, Voice(DEFAULT_VOICE_ID, "George", "M", "British", "storyteller")
+)
+
+
+def _pool_from_config(config: WeaveConfig) -> list[Voice]:
+    return [_KNOWN_VOICES.get(vid, Voice(vid, vid[:6], "?")) for vid in config.voices]
+
+
+def compose_narration(
+    segments: list[str],
+    config: WeaveConfig,
+    *,
+    out_path: str | Path,
+    api_key: str | None = None,
+    work_dir: str | Path = "data/tts/compose",
+) -> list[tuple[Voice, str]]:
+    """Render ``segments`` under ``config`` → ``out_path``.
+
+    Single-voice and multi-voice go through the same turn-based path (a single
+    voice is just a one-voice pool). Returns the ``(voice, turn_text)``
+    assignment for reporting / provenance.
+
+    ``api_key`` is an optional per-request ElevenLabs key threaded to
+    :func:`braidio.multivoice.render_multivoice` (and thence every synthesized
+    turn); ``None`` (default) keeps the ``$ELEVENLABS_API_KEY`` fallback.
+    """
+    return render_multivoice(
+        segments,
+        _pool_from_config(config),
+        out_path=out_path,
+        api_key=api_key,
+        work_dir=work_dir,
+        seed=config.voice_seed,
+        min_turn=config.min_turn,
+        max_turn=config.max_turn,
+        avoid_immediate_repeat=config.avoid_immediate_repeat,
+        model_id=config.model_id,
+        base_settings=dict(config.voice_settings),
+        speed_base=config.speed_base,
+        speed_jitter=config.speed_jitter,
+        crossfade_s=config.crossfade_s,
+        gap_s=config.gap_turn_s,
+        target_lufs=config.target_lufs,
+    )