braidio.music#

Music bed — an instrumental underscore laid under the whole production, ducked.

The bed is the spanning generalization of a per-clip under placement: instead of one clip beneath one talk beat, an app-supplied instrumental asset runs beneath the entire timeline at reduced gain, entering after speech onset and fading at the ends (the conventions from docs/research/commentary-formats-and-styles.md: bed 10–15 dB under voice, ~1.5s fade-in, posted after the start; beds must be instrumental).

braidio ships no music — the caller supplies the asset (a licensed/owned instrumental). A Format’s music_bed intensity (continuous / light / sparse / none) picks a sensible gain via BED_GAIN_BY_INTENSITY; render_format() builds the bed for you when given a bed_asset.

Fade-to-spotlight (braidio.structure) is expressed here as bed regions: bed_regions() cuts the bed’s span into the stretches around the spotlit windows, each with its own fades, and prepare_bed_regions() renders them so the weave mixes each in at its own start. With no spotlit window the bed is one region rendered by prepare_bed() — the unchanged single-file path.

Functions

`bed_for_intensity`(asset_path, intensity, ...)	Build a `MusicBed` at the gain for a Format `music_bed` intensity.
`bed_regions`(bed, total_s, spotlights)	Cut the bed's span `[lead_in_s, total_s]` around the `spotlights`.
`prepare_bed`(bed, target_s, out_path, *[, ...])	Render `bed` to a ready-to-mix underscore of length `target_s - lead_in_s`.
`prepare_bed_regions`(bed, regions, out_dir, ...)	Render each `BedRegion` to `out_dir/<stem>-<k>.mp3`.

Classes

`BedRegion`(start_s, end_s, fade_in_s, fade_out_s)	One stretch of the timeline the bed plays over, with its own fades.
`MusicBed`(asset_path[, gain_db, fade_in_s, ...])	An instrumental underscore spanning the production, mixed under the talk.

class braidio.music.BedRegion(start_s, end_s, fade_in_s, fade_out_s)[source]#

Bases: object

One stretch of the timeline the bed plays over, with its own fades.

start_s / end_s are timeline offsets (the bed’s own lead_in_s is already applied). The bed keeps its place in the asset across a gap: a region seeks into the asset to where the music would have been.

class braidio.music.MusicBed(asset_path, gain_db=-22.0, fade_in_s=1.5, fade_out_s=2.0, lead_in_s=2.0, start_s=0.0, loop=True, spotlight_fade_s=0.6)[source]#

Bases: object

An instrumental underscore spanning the production, mixed under the talk.

asset_path is an app-supplied instrumental. gain_db sets how far under the voice it sits; lead_in_s posts the bed after speech onset so its entrance feels motivated; start_s is the in-point into the asset; loop repeats the asset to cover a timeline longer than it. spotlight_fade_s is how fast the bed drops out before a spotlit exhibit (it resumes after the exhibit over fade_in_s).

braidio.music.bed_for_intensity(asset_path, intensity, **overrides)[source]#

Build a MusicBed at the gain for a Format music_bed intensity.

Returns None for "none" (or an unknown intensity), so callers can do bed = bed_for_intensity(asset, fmt.music_bed) and skip when falsy.

Return type:: MusicBed | None

braidio.music.bed_regions(bed, total_s, spotlights)[source]#

Cut the bed’s span [lead_in_s, total_s] around the spotlights.

Pure function. Each spotlight (start, end) (timeline seconds) opens a gap: the bed fades out over bed.spotlight_fade_s to be silent by start, and fades back in over bed.fade_in_s from end. The first region keeps the bed’s own fade-in and the last its fade-out; a region that would be empty (a spotlight at the very top, two spotlights back to back) is dropped. With no spotlights the result is the single whole-span region.

Return type:: list[BedRegion]

braidio.music.prepare_bed(bed, target_s, out_path, *, sample_rate=44100)[source]#

Render bed to a ready-to-mix underscore of length target_s - lead_in_s.

Seeks to bed.start_s (looping if needed), trims to the covered length, and bakes in fades + gain_db + stereo. The caller mixes the result delayed by bed.lead_in_s. Returns out_path.

Return type:: Path

braidio.music.prepare_bed_regions(bed, regions, out_dir, *, stem, sample_rate=44100)[source]#

Render each BedRegion to out_dir/<stem>-<k>.mp3.

Returns [(path, start_s), …] — the caller mixes each file in delayed by its start_s. A region seeks into the asset to where the bed would have been had it played through (so the music resumes in place after a spotlight), wrapping around the asset’s length when the bed loops. A non-looping bed that has already run out by a region’s start has nothing to play there: that region is dropped (seeking past the end would yield an empty file the mix can’t open).

Return type:: list[tuple[Path, float]]