braidio.formats

Ready-made format templates — high-quality presets under standard names.

braidio parametrizes any commentary style (a Script of Narration / Dialogue / SegmentBeat beats, cast via ConversationCast, tuned by WeaveConfig and Delivery). This module ships the ready-made end of that: a small set of named Format presets that bundle good defaults for the recurring, industry-named ways people comment on an artifact — so render_format(DEEP_DIVE, script, …) just works, and advanced users still compose the primitives directly.

The taxonomy + recipes are in misc/docs/research/commentary-formats-and-styles.md. The organizing rule: **the talk is the spine; narration bridges and source clips are optional “illustration” layers** attached to it.

What a Format drives at render time: the dialogue cast (role→voice), the narration voice + delivery, the **clip weave/duck + loudness** (WeaveConfig), and the structural music (MusicStructure) — whether a SceneBreak beat plays a sting, and whether the bed drops out under exhibits (fade-to-spotlight). Per-clip placement renders too — set it on each SegmentBeat(placement=…); Format.clip_placement is the recommended default for the format. Music is app-supplied: a music bed renders when you pass a bed_asset to render_format() (the format’s music_bed intensity picks the gain) and scene stings play when you pass a sting_asset (without one a scene break is a beat of silence). Fields tagged (authoring) — roles, scripting — are conventions for whoever writes (or generates) the Script. Preset ids mirror the standard names so a UI can label them (“Deep Dive”, “Song Exploder-style”). The structural-music design history is braidio#25.

Functions

describe_asset_application(fmt, script, *[, ...])	Which of the supplied bed_asset / sting_asset this format will actually render, and why not otherwise (braidio#43).
render_format(fmt, script, *, source[, ...])	Render script under fmt's defaults; overrides win over them.
sting_would_play(structure, script, sting_asset)	Whether some SceneBreak in script resolves to marker "sting" under structure once sting_asset is wired in as the sting.

Classes

Format(id, name, summary[, aka, cast, ...])

A named commentary-format preset: a bundle of high-quality defaults.

class braidio.formats.Format(id, name, summary, aka=(), cast=None, narration_voice=None, narration_delivery=Delivery(name='v2-presenter', 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, supports_speed=True, note='Host/presenter commentary — lively (== v2-tuned), for the spine voice.'), weave=<factory>, structure=<factory>, roles=<factory>, clip_placement='before', music_bed='light', scripting='')

Bases: object

A named commentary-format preset: a bundle of high-quality defaults.

Rendered fields drive render_format() → braidio.render.render_production(). Authoring fields document how to write a Script for this format; clip_placement is the recommended per-beat default and music_bed the bed intensity applied when a bed_asset is supplied.

render(script, *, source, out_path=None, profile=Profile.PERSONAL, **overrides)

Render script with this format’s defaults (see render_format()).

Return type:

Path

braidio.formats.describe_asset_application(fmt, script, *, bed_asset=None, sting_asset=None)

Which of the supplied bed_asset / sting_asset this format will actually render, and why not otherwise (braidio#43).

Pure and pre-render — safe to call before paying for anything. A key stays None when its asset wasn’t supplied. bed_asset’s fate is fixed by fmt.music_bed alone: "none" never renders a bed, and render_format() refuses bed_asset there rather than spend on one that would be dropped, so bed_applied is False only via that refusal path, never in a result you got back from a successful render. sting_asset’s fate additionally depends on script: a scene break’s marker can override the format’s default, so a sting can still legitimately go unused in one script and play in another under the same format — that case is reported here, not refused.

Return type:

dict[str, bool | str | None]

braidio.formats.render_format(fmt, script, *, source, out_path=None, profile=Profile.PERSONAL, bed_asset=None, sting_asset=None, **overrides)

Render script under fmt’s defaults; overrides win over them.

Wires the format’s cast / narration_voice / narration_delivery / weave / structure into braidio.render.render_production(). Any beat may still override voice/settings per-beat (e.g. a graver book-narrator inside an otherwise lively presenter piece — pass V2_NARRATOR.voice_settings on that Narration beat).

bed_asset (a path to an app-supplied instrumental) adds a music bed at the gain implied by fmt.music_bed; pass music_bed=MusicBed(...) in overrides for full control. A format whose music_bed is "none" (e.g. SONG_EXPLODER) never renders a bed at all, so bed_asset there raises ValueError before any rendering — the caller would otherwise pay for a bed the format silently drops (braidio#43) — unless overrides itself supplies music_bed=, which always wins and makes the refusal moot. sting_asset (a path to an app-supplied short marker) is what a SceneBreak plays under the format’s structure; pass structure=MusicStructure(...) in overrides for full control. Unlike the bed, a format’s scene_marker is only the default — an individual SceneBreak.marker override can still play the sting even under a "none" default — so a sting that ends up unused is not refused, only reported (see describe_asset_application()).

Return type:

Path

braidio.formats.sting_would_play(structure, script, sting_asset)

Whether some SceneBreak in script resolves to marker "sting" under structure once sting_asset is wired in as the sting.

Takes a bare MusicStructure (not a Format) so callers with no format at all — e.g. the graph path’s _graph_structure with no format_id — can still ask against the ad hoc default structure they build in that case (braidio#53).

Return type:

bool