foley.weave.timeline#

The sound-design timeline as an editable document — hydrate, edit, caption.

The timeline is the SSOT and the reproducible seed; foley.weave.render() is a pure projection of it. This module owns the document operations, all pure and stdlib-only (no numpy, no I/O):

hydrate() — resolve each item’s symbolic anchor into a concrete Placement and fill processing/id defaults, idempotently

(hydrate ∘ hydrate == hydrate) and without clobbering a hand-set placement.
Pure edit transforms (swap_clip(), nudge(), set_gain(), toggle(), set_master()) — each returns a NEW timeline, so an edit +

re-render reproduces exactly that change (the “editable, re-renderable” DoD).
Accessibility SDH captions (to_webvtt() / to_srt()) — bracketed SFX labels ([door creak]) derived from the items, never from the narration transcript, so no speech text leaks into a shipped caption file.

Module Attributes

DISPLAY_WINDOW_S

How long a one-shot's caption stays on screen (seconds) when the item has no resolved duration of its own.

Functions

`hydrate`(timeline[, word_timeline])	Resolve every item's anchor + fill processing/id, returning a NEW timeline.
`nudge`(timeline, item_id, delta_s)	Shift an item's resolved onset by `delta_s` seconds — a NEW timeline.
`set_gain`(timeline, item_id, gain_db)	Set an item's processing gain (dB, voice-relative) — a NEW timeline.
`set_master`(timeline, master)	Set the timeline's master profile (name or `MasterProfile`) — a NEW timeline.
`swap_clip`(timeline, item_id, new_clip_ref)	Swap an item's clip (keeping its placement/processing) — a NEW timeline.
`to_srt`(timeline, *[, window_s])	Render the timeline's SFX cues as an SRT SDH caption file (report 06 / issue #8).
`to_webvtt`(timeline, *[, window_s])	Render the timeline's SFX cues as a WebVTT SDH caption file (report 06 / issue #8).
`toggle`(timeline, item_id, enabled)	Non-destructively mute/unmute an item — a NEW timeline.

foley.weave.timeline.DISPLAY_WINDOW_S: float = 2.0#: How long a one-shot’s caption stays on screen (seconds) when the item has no resolved duration of its own.

foley.weave.timeline.hydrate(timeline, word_timeline=None)[source]#

Resolve every item’s anchor + fill processing/id, returning a NEW timeline.

Idempotent: an item that already carries a Placement keeps its symbolic anchor (a hand edit is never clobbered) but is re-resolved against word_timeline so a re-recorded/re-aligned narration re-flows the SFX (report 06 §6.1). processing falls back to the sparse gain and id to a stable content hash. The resolved word_timeline is cached on the returned timeline (the reproducible seed).

Parameters:

timeline (SoundDesignTimeline) – The (sparse or partially-resolved) timeline.
word_timeline (Optional[list]) – The forced alignment; defaults to timeline.word_timeline.

Return type:

SoundDesignTimeline

Returns:

A hydrated copy with resolved placements, filled processing, stable ids.

foley.weave.timeline.nudge(timeline, item_id, delta_s)[source]#

Shift an item’s resolved onset by delta_s seconds — a NEW timeline.

Resolves the item’s anchor against the timeline’s word_timeline first, then shifts the resolved onset and pins the anchor to absolute so the manual offset survives a re-hydrate. This means nudging a still-symbolic (not-yet-hydrated) item on a timeline that carries alignment shifts from the item’s true resolved onset, not from 0. On a pre-alignment timeline with no word_timeline a word/sentence anchor is genuinely unresolvable, so there the shift is relative to 0 — hydrate/weave first for such items.