# lsdtools.audio reference URL: https://lsd.tools/docs/sdk-lsdtools-audio Updated: 2026-10-19 SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**. Product source digest: `170db6f659e9f79609ddaaec494ffad41f1d659a96001371132843e0c17a7e27`. Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions. ```text The audio service's public contract: WAV clips a composition plays by triggers, lazily. A package authors an audio document (``lsd-audio/1``: clips with their WAV bytes, gain, loop, range and trigger -- ``start``, ``spawn:``, ``reduction:``), validates it (``validate_document``) and carries it on the ``audio`` port (``document_table``); the audio participant plays it in the editor (a device, or no device and deterministic ticks) and the compiler lowers the same document into the exported player. Resolving ``validate_document``, ``document_table`` or ``document_from_value`` imports the participant, so an entity carrying the document is a member once the participant that plays it is known. ``AudioEngine`` is the lane itself for a package that mixes on its own. Importing this facade loads no engine and no view. ``` ## `lsdtools.audio.AUDIO_PARTICIPANT` Kind: value. Source: `services/audio/src/lsd_audio/document.py:58`. ```python AUDIO_PARTICIPANT = 'audio' ``` Implementation alias: `lsd_audio.document.PARTICIPANT`. ## `lsdtools.audio.AUDIO_PORT` Kind: value. Source: `services/audio/src/lsd_audio/document.py:59`. ```python AUDIO_PORT = 'audio' ``` Implementation alias: `lsd_audio.document.AUDIO_PORT`. ## `lsdtools.audio.AudioContractError` Kind: class. Source: `services/audio/src/lsd_audio/errors.py:32`. Source docstring: ```text An audio member's table or a composition's audio settings violate the contract. ``` Implementation alias: `lsd_audio.errors.AudioContractError`. Declared bases: `ValueError`. ## `lsdtools.audio.AudioDocument` Kind: class. Source: `services/audio/src/lsd_audio/document.py:190`. Implementation alias: `lsd_audio.document.AudioDocument`. ### `lsdtools.audio.AudioDocument.clips` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:191`. ```python clips: tuple[ClipSpec, ...] ``` ### `lsdtools.audio.AudioDocument.clip` Kind: method. Source: `services/audio/src/lsd_audio/document.py:193`. ```python clip(self, name: str) -> ClipSpec ``` ```python name: str self: (unannotated) ``` ### `lsdtools.audio.AudioDocument.clip_names` Kind: method. Source: `services/audio/src/lsd_audio/document.py:200`. ```python clip_names(self) -> tuple[str, ...] ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioDocument.digest` Kind: method. Source: `services/audio/src/lsd_audio/document.py:204`. ```python digest(self) -> str ``` ```python self: (unannotated) ``` Source docstring: ```text SHA-256 over the clips' names, bytes and settings: the document's identity. ``` ### `lsdtools.audio.AudioDocument.to_dict` Kind: method. Source: `services/audio/src/lsd_audio/document.py:216`. ```python to_dict(self) -> dict[str, Any] ``` ```python self: (unannotated) ``` ## `lsdtools.audio.AudioEngine` Kind: class. Source: `services/audio/src/lsd_audio/engine.py:85`. ```python AudioEngine(self, *, backend: str='null', sample_rate: int=48000, channels: int=2, max_voices: int=64) -> None ``` Source docstring: ```text One native audio engine: ``backend`` is ``"null"`` (no device; ``tick`` renders) or ``"device"`` (the platform's default output). ``` Implementation alias: `lsd_audio.engine.AudioEngine`. ### `lsdtools.audio.AudioEngine.__init__` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:89`. ```python __init__(self, *, backend: str='null', sample_rate: int=48000, channels: int=2, max_voices: int=64) -> None ``` ```python backend: str channels: int max_voices: int sample_rate: int self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.closed` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:114`. ```python closed(self) -> bool ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.close` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:122`. ```python close(self) -> None ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.__enter__` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:127`. ```python __enter__(self) -> AudioEngine ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.__exit__` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:130`. ```python __exit__(self, *_exc: object) -> None ``` ```python _exc: object self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.reset` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:133`. ```python reset(self) -> None ``` ```python self: (unannotated) ``` Source docstring: ```text Stop every voice and zero the counters; the clips stay loaded. ``` ### `lsdtools.audio.AudioEngine.load_clip` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:139`. ```python load_clip(self, wav: bytes) -> ClipInfo ``` ```python self: (unannotated) wav: bytes ``` Source docstring: ```text Decode WAV bytes into a clip at the engine's rate and channels. ``` ### `lsdtools.audio.AudioEngine.clip_info` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:152`. ```python clip_info(self, clip: int) -> ClipInfo ``` ```python clip: int self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.clips` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:167`. ```python clips(self) -> tuple[ClipInfo, ...] ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.play` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:172`. ```python play(self, clip: int, *, gain: float=1.0, loop: bool=False, position: Any=None, range: float=0.0) -> int ``` ```python clip: int gain: float loop: bool position: Any range: float self: (unannotated) ``` Source docstring: ```text Start one voice of ``clip``; a ``position`` makes it spatial (silent at ``range`` metres from the listener). Answers the voice handle. ``` ### `lsdtools.audio.AudioEngine.stop` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:195`. ```python stop(self, voice: int) -> None ``` ```python self: (unannotated) voice: int ``` ### `lsdtools.audio.AudioEngine.move` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:198`. ```python move(self, voice: int, position: Any) -> None ``` ```python position: Any self: (unannotated) voice: int ``` ### `lsdtools.audio.AudioEngine.voice_info` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:206`. ```python voice_info(self, voice: int) -> VoiceInfo | None ``` ```python self: (unannotated) voice: int ``` Source docstring: ```text The voice as it stands, or ``None`` once it ended or was stopped. ``` ### `lsdtools.audio.AudioEngine.set_listener` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:231`. ```python set_listener(self, position: Any, forward: Any, up: Any) -> None ``` ```python forward: Any position: Any self: (unannotated) up: Any ``` ### `lsdtools.audio.AudioEngine.tick` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:242`. ```python tick(self, dt: float) -> None ``` ```python dt: float self: (unannotated) ``` Source docstring: ```text One fixed step: the null backend renders ``dt`` seconds of mix and discards it; every backend retires the voices that ended. ``` ### `lsdtools.audio.AudioEngine.counters` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:247`. ```python counters(self) -> Counters ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.state_hash` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:259`. ```python state_hash(self) -> int ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.describe` Kind: method. Source: `services/audio/src/lsd_audio/engine.py:264`. ```python describe(self) -> Any ``` ```python self: (unannotated) ``` ### `lsdtools.audio.AudioEngine.backend` Kind: attribute. Source: `services/audio/src/lsd_audio/engine.py:105`. ```python backend: str ``` ```python backend = backend ``` ### `lsdtools.audio.AudioEngine.sample_rate` Kind: attribute. Source: `services/audio/src/lsd_audio/engine.py:106`. ```python sample_rate: (unannotated) ``` ```python sample_rate = int(info.sample_rate) ``` ### `lsdtools.audio.AudioEngine.channels` Kind: attribute. Source: `services/audio/src/lsd_audio/engine.py:107`. ```python channels: (unannotated) ``` ```python channels = int(info.channels) ``` ### `lsdtools.audio.AudioEngine.max_voices` Kind: attribute. Source: `services/audio/src/lsd_audio/engine.py:108`. ```python max_voices: (unannotated) ``` ```python max_voices = int(info.max_voices) ``` ## `lsdtools.audio.ClipSpec` Kind: class. Source: `services/audio/src/lsd_audio/document.py:106`. Implementation alias: `lsd_audio.document.ClipSpec`. ### `lsdtools.audio.ClipSpec.clip` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:107`. ```python clip: str ``` ### `lsdtools.audio.ClipSpec.wav` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:108`. ```python wav: bytes ``` ### `lsdtools.audio.ClipSpec.gain` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:109`. ```python gain: float ``` ### `lsdtools.audio.ClipSpec.loop` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:110`. ```python loop: bool ``` ### `lsdtools.audio.ClipSpec.range` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:111`. ```python range: float ``` ### `lsdtools.audio.ClipSpec.trigger` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:112`. ```python trigger: Trigger ``` ### `lsdtools.audio.ClipSpec.follow` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:113`. ```python follow: bool ``` ```python follow = False ``` ### `lsdtools.audio.ClipSpec.spatial` Kind: method. Source: `services/audio/src/lsd_audio/document.py:116`. ```python spatial(self) -> bool ``` ```python self: (unannotated) ``` ### `lsdtools.audio.ClipSpec.to_dict` Kind: method. Source: `services/audio/src/lsd_audio/document.py:119`. ```python to_dict(self) -> dict[str, Any] ``` ```python self: (unannotated) ``` ## `lsdtools.audio.DOCUMENT_SCHEMA` Kind: value. Source: `services/audio/src/lsd_audio/document.py:57`. ```python DOCUMENT_SCHEMA = 'lsd-audio/1' ``` Implementation alias: `lsd_audio.document.DOCUMENT_SCHEMA`. ## `lsdtools.audio.TRIGGER_KINDS` Kind: value. Source: `services/audio/src/lsd_audio/document.py:66`. ```python TRIGGER_KINDS = ('start', 'spawn', 'reduction', 'event') ``` Implementation alias: `lsd_audio.document.TRIGGER_KINDS`. ## `lsdtools.audio.Trigger` Kind: class. Source: `services/audio/src/lsd_audio/document.py:76`. Implementation alias: `lsd_audio.document.Trigger`. ### `lsdtools.audio.Trigger.kind` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:77`. ```python kind: str ``` ### `lsdtools.audio.Trigger.name` Kind: attribute. Source: `services/audio/src/lsd_audio/document.py:78`. ```python name: str ``` ```python name = '' ``` ### `lsdtools.audio.Trigger.text` Kind: method. Source: `services/audio/src/lsd_audio/document.py:81`. ```python text(self) -> str ``` ```python self: (unannotated) ``` ### `lsdtools.audio.Trigger.parse` Kind: method. Source: `services/audio/src/lsd_audio/document.py:85`. ```python parse(cls, value: Any, what: str) -> Trigger ``` ```python cls: (unannotated) value: Any what: str ``` ## `lsdtools.audio.audio_timeline_spec` Kind: function. Source: `services/audio/src/lsd_audio/timeline.py:36`. ```python audio_timeline_spec() ``` Source docstring: ```text The declaration the games package contributes; inspecting it loads no engine. ``` Implementation alias: `lsd_audio.timeline.audio_timeline_spec`. ## `lsdtools.audio.document_from_table` Kind: function. Source: `services/audio/src/lsd_audio/document.py:269`. ```python document_from_table(table: pa.Table) -> AudioDocument ``` ```python table: pa.Table ``` Implementation alias: `lsd_audio.document.document_from_table`. ## `lsdtools.audio.document_from_value` Kind: function. Source: `services/audio/src/lsd_audio/document.py:220`. ```python document_from_value(value: Any) -> AudioDocument ``` ```python value: Any ``` Implementation alias: `lsd_audio.document.document_from_value`. ## `lsdtools.audio.document_table` Kind: function. Source: `services/audio/src/lsd_audio/document.py:253`. ```python document_table(document: AudioDocument | Mapping[str, Any]) -> pa.Table ``` ```python document: AudioDocument | Mapping[str, Any] ``` Source docstring: ```text The table an audio entity's ``audio`` port carries: one row per clip, the WAV as bytes. ``` Implementation alias: `lsd_audio.document.document_table`. ## `lsdtools.audio.engine_available` Kind: function. Source: `services/audio/src/lsd_audio/engine.py:72`. ```python engine_available() -> bool ``` Implementation alias: `lsd_audio.engine.engine_available`. ## `lsdtools.audio.validate_document` Kind: function. Source: `services/audio/src/lsd_audio/document.py:244`. ```python validate_document(value: Any) -> str | None ``` ```python value: Any ``` Source docstring: ```text The document's problem as text, or ``None`` when it validates (a step validator). ``` Implementation alias: `lsd_audio.document.validate_document`.