braidio.render

Render a Script into an audio file.

Walks the beats (filtered by the rights Profile): narration beats are synthesized (braidio.tts); segment beats are resolved via a SegmentSource and extracted (padded + faded); scene breaks become a sting or a pause (braidio.structure). Every spoken or clipped part is loudness-normalized, then either woven on a timeline (clips tuck under narration — braidio.weave.weave_timeline()) when a WeaveConfig enables it, or concatenated.

This is the no-graph fast path; the same core is reused by the nw-app transforms (which add provenance + partial re-render).

braidio.render.render_production(script: Script, *, source: SegmentSource, api_key: str | None = None, config: WeaveConfig | None = None, profile: Profile = Profile.PERSONAL, rights: RightsPolicy | None = None, delivery: Delivery = Delivery(name='v2-tuned', model_id='eleven_multilingual_v2', voice_settings={'stability': 0.35, 'similarity_boost': 0.75, 'style': 0.35, 'use_speaker_boost': True, 'speed': 0.98}, supports_audio_tags=False, note='★ recommended: lower stability + raised style; pairs with annotated text.'), cast: ConversationCast = ConversationCast(roles={'A': 'cgSgspJ2msm6clMCkdW9', 'B': 'iP95p4xoKVk53GoZ742B'}, model_id='eleven_v3', settings={'stability': 0.45}), out_path: str | Path | None = None, voice_id: str | None = None, crossfade_s: float = 0.12, normalize: bool = True, music_bed=None, structure=None, end_fade_s: float = 0.35, end_silence_s: float = 0.7, return_timeline: bool = False, tts_dir: str | Path = 'data/tts', clips_dir: str | Path = 'data/clips', episodes_dir: str | Path = 'data/episodes') → Path | tuple[Path, object]

Render script under profile → a single audio file. Returns the path.

With return_timeline=True returns (path, TimelineBreakdown) instead — the render records what it spent time on (per-beat kind, source interval, duration, and offset) rather than leaving it to be reconstructed afterward.

Segment beats are resolved through source (a SegmentSource). When config has clip_edge_overlap_s > 0, a clip is placement="under", or a music_bed is given, the parts are woven on a timeline; otherwise they are concatenated. rights (if given) sets which segment rights are publishable. music_bed lays an instrumental underscore under the whole production (see braidio.music.MusicBed).

structure (a braidio.structure.MusicStructure) is how the production marks its structure with music: a scene-break beat plays its sting (or a pause when there is none / the break is marked "none"), and a spotlit segment beat drops the bed out for its duration. None uses the inert defaults — no sting asset, no clip spotlit by default — so a script without scene breaks or spotlight flags renders exactly as before.

api_key is an optional per-request ElevenLabs key threaded to every synthesized beat — both narration (braidio.tts.narrate()) and dialogue (braidio.conversation.render_dialogue()). When None (default) each synthesizer falls back to $ELEVENLABS_API_KEY (unchanged behavior); an explicit key lets a caller (e.g. a per-user BYO-key request) override the environment without mutating it. Segment beats never call ElevenLabs, so the key does not touch them.