Inno.Audio
Section titled “Inno.Audio”
- Backend-neutral playback, mixer, content-provider and device contracts.
This project defines playback, clips, mixers, content contributions and device interfaces without depending on a runtime, scene model, Editor, platform or native implementation. Use the script facade to control session audio; use the host interfaces when composing a runtime or implementing a backend.
Start with a task
Section titled “Start with a task”- Play and control audio covers preparation, completion and preload release.
- Route audio through a mixer explains buses and processor configuration.
- Provide audio from host content describes the bounded extension boundary.
Playback and device contract
Section titled “Playback and device contract”The static Audio facade resolves a host-owned IAudioService from the current strict last-in-first-out execution scope. It has no independent device or fallback service. Host composition owns the service; facade callers borrow it. Script-facing types use the InnoEngine.Audio projection. Low-level IAudioDevice, clip preparation, device completions and device limits remain host contracts.
Runtime AudioVoiceHandle values identify playback in one runtime generation. Backend clip, bus, listener and AudioDeviceVoiceHandle values belong to a device generation. These are different identities, not interchangeable native pointers. A returned runtime voice may still be preparing. Replacement invalidates handles from the old generation.
AudioClipDescriptor contains format, length, codec and load policy. Its independent IAudioClipSource supplies encoded-data access under a lease; it does not disclose an artifact path. The device owns preparation and decoding. AudioDevice exposes opaque handle encoding only through its protected backend implementation surface.
Use AudioPlayOptions.defaultValue or a validated constructor. A zero-initialized default(AudioPlayOptions) has an invalid bus. Default voice parameters have invalid zero pitch. Invalid updates return failure without changing a live voice; invalid new-play options are rejected before stealing a voice or acquiring clip work. Floating-point settings and every vector component must be finite, and enum choices must be defined. Finite zero vectors are not rejected merely for lacking unit length.
Scheduling accepts a finite, non-negative absolute dspTime. Direct device calls must also reject invalid options, invalid scheduling and non-finite bus gains. The neutral boundary does not promise that every backend implements every capability; inspect the active device’s capability snapshot.
Mixer and extension model
Section titled “Mixer and extension model”Bus, processor, parameter and codec IDs are open stable identities. The mandatory master bus anchors a validated acyclic routing graph. Standard processors include low-pass, high-pass, band-pass, notch, peaking, low/high shelf and delay. Additional processor IDs do not require editing a central enum.
Mixer extensions and features persist stable identities and neutral serialized bytes. They must not retain plugin Type objects, delegates or live extension instances in persisted configuration. Content providers submit immutable control-thread snapshots; they are not managed real-time DSP callbacks. Their complete invocation contract is in Provide audio from host content.
Device admission and completion
Section titled “Device admission and completion”AudioDeviceLimits defaults to 16,384 clips, 65,536 voices and 4,096 buses. Voice capacity includes undelivered completions, so a consumer must drain completions. These are backend resource limits, separate from the runtime’s smaller priority-based playback budget. Exhaustion returns an invalid admission handle without partially creating native resources or discarding old completions.
Runtime completion events distinguish natural end, explicit stop, stealing, decode failure and device loss. They travel through Core Events at a control-thread update point. See audio ownership and retirement before implementing a service or device.
API reference
Section titled “API reference”The reference contains selected host CLR declarations and source XML. Script projection availability is a separate contract; source presence alone does not certify a script surface.
Logical script references
Section titled “Logical script references”The compiler-selected script declarations are separate from this project’s host CLR surface. Read the script calling guide and the associated module contracts before using a projected member.
Source project facts
Section titled “Source project facts”Project: Inno.Audio
Source: src/services/audio/Inno.Audio/Inno.Audio.csproj
| Type | API | Description |
|---|---|---|
| Audio | engine | Provides script-friendly access to the audio service in the current execution context. |
| AudioBusDefinition | engine | Describes one bus and its ordered processor chain in a compiled mixer graph. |
| AudioBusHandle | engine | Identifies one backend mixer bus within a device generation. |
| AudioBusId | engine | Identifies a mixer bus without imposing a closed bus catalog. |
| AudioCapabilities | engine | Describes backend-neutral features and limits for one device generation. |
| AudioClipAsset | engine | Represents one imported audio source and its compact runtime metadata. |
| AudioClipDescriptor | engine | Describes one immutable encoded audio artifact presented to a backend device. |
| AudioClipHandle | engine | Identifies one backend clip allocation within a device generation. |
| AudioClipLoadMode | engine | Selects how encoded clip data is prepared for playback. |
| AudioClipMetadata | engine | Describes imported encoded audio independently from its runtime storage path. |
| AudioClipMetadataCodec | engine | Encodes the compact runtime header shared by audio importers and runtime asset loading. |
| AudioClipState | engine | Describes asynchronous preparation of a backend-owned clip generation. |
| AudioCodecId | engine | Identifies encoded audio data without constraining codec providers to a closed enum. |
| AudioCompletionReason | engine | Explains why a voice stopped accepting playback commands. |
| AudioContentProvider | engine | Converts arbitrary host-owned content into backend-neutral emitter and listener snapshots. |
| AudioContentProviderContext | engine | Collects one bounded, atomic provider contribution on the owning control thread. |
| AudioContentProviderExtensionAttribute | engine | Marks a reloadable provider that converts host content into immutable audio snapshots. |
| AudioDevice | engine | Provides protected opaque-handle encoding and validation helpers for audio backends. |
| AudioDevice.DeviceHandleIdentity | engine | Stores one decoded device-owned identity. |
| AudioDeviceCompletion | engine | Reports one backend-detected terminal voice transition. |
| AudioDeviceLimits | engine | Bounds device-side resource admission independently of the Runtime’s smaller gameplay voice budget. |
| AudioDeviceState | engine | Describes the availability of the active audio output generation. |
| AudioDeviceVoiceHandle | engine | Identifies a backend voice allocation, distinct from a service’s preparing playback handle. |
| AudioDistanceModel | engine | Selects the distance attenuation model for one spatial voice. |
| AudioEmitterSnapshot | engine | Describes one immutable source playback request produced by a content provider. |
| AudioExecutionContext | engine | Binds one host-owned audio service to the current asynchronous execution context. |
| AudioListenerHandle | engine | Identifies one spatial listener within a device generation. |
| AudioListenerSnapshot | engine | Describes one immutable listener candidate produced by a content provider. |
| AudioListenerState | engine | Contains one listener transform used by backend spatialization. |
| AudioMixer | engine | Contains one validated backend-neutral mixer graph. |
| AudioMixerAsset | engine | Selects a mixer extension and ordered features without defining a game-specific mixing model. |
| AudioMixerBuilder | engine | Builds and validates an open backend-neutral mixer graph. |
| AudioMixerExtension | engine | Builds a base mixer graph on the host control thread. |
| AudioMixerExtensionAttribute | engine | Marks a reloadable extension that creates the base audio mixer graph. |
| AudioMixerFeature | engine | Contributes optional buses and processors to a candidate mixer graph. |
| AudioMixerFeatureConfiguration | engine | Stores one ordered mixer feature selection using only stable data. |
| AudioMixerFeatureExtensionAttribute | engine | Marks a reloadable extension that contributes to an audio mixer graph. |
| AudioParameterId | engine | Identifies one processor parameter without imposing a processor-specific enum. |
| AudioPlayOptions | engine | Contains immutable parameters used to create one playback voice. |
| AudioPlaybackState | engine | Describes the observable lifecycle of one playback voice. |
| AudioProcessorConfiguration | engine | Describes one ordered processor instance attached to a mixer bus. |
| AudioProcessorId | engine | Identifies an audio processor implementation without imposing a closed effect catalog. |
| AudioProcessorParameter | engine | Stores one neutral numeric parameter assigned to an audio processor. |
| AudioProjectSettings | engine | Stores portable project-wide defaults for audio playback and caching. |
| AudioSpatialOptions | engine | Contains listener-relative positioning and attenuation parameters for one voice. |
| AudioStatistics | engine | Reports an immutable snapshot of runtime and backend resource usage. |
| AudioVoiceAllocator | engine | Allocates service-owned playback handles without impersonating a backend audio device. |
| AudioVoiceCompletedEvent | engine | Reports one voice terminal transition on the owning runtime’s main-thread event dispatcher. |
| AudioVoiceHandle | engine | Identifies one playback voice within a device generation. |
| AudioVoiceParameters | engine | Contains mutable voice parameters that can be changed after playback begins. |
| IAudioClipSource | engine | Supplies immutable encoded audio independently of any backend’s input layout. |
| IAudioDevice | engine | Owns one replaceable audio backend generation and all device-side audio objects. |
| IAudioService | engine | Provides backend-neutral audio playback, caching, mixer, and device-state services. |
| SerializedAudioExtensionState | engine | Stores reload-safe configuration for one mixer or feature extension generation. |
| Audio | Runtime | Provides script-friendly access to the audio service in the current execution context. |
| AudioBusDefinition | Runtime | Describes one bus and its ordered processor chain in a compiled mixer graph. |
| AudioBusHandle | Runtime | Identifies one backend mixer bus within a device generation. |
| AudioBusId | Runtime | Identifies a mixer bus without imposing a closed bus catalog. |
| AudioCapabilities | Runtime | Describes backend-neutral features and limits for one device generation. |
| AudioClipAsset | Runtime | Represents one imported audio source and its compact runtime metadata. |
| AudioClipHandle | Runtime | Identifies one backend clip allocation within a device generation. |
| AudioClipLoadMode | Runtime | Selects how encoded clip data is prepared for playback. |
| AudioClipMetadata | Runtime | Describes imported encoded audio independently from its runtime storage path. |
| AudioCodecId | Runtime | Identifies encoded audio data without constraining codec providers to a closed enum. |
| AudioCompletionReason | Runtime | Explains why a voice stopped accepting playback commands. |
| AudioContentProvider | Runtime | Converts arbitrary host-owned content into backend-neutral emitter and listener snapshots. |
| AudioContentProviderContext | Runtime | Collects one bounded, atomic provider contribution on the owning control thread. |
| AudioContentProviderExtensionAttribute | Runtime | Marks a reloadable provider that converts host content into immutable audio snapshots. |
| AudioDeviceState | Runtime | Describes the availability of the active audio output generation. |
| AudioDistanceModel | Runtime | Selects the distance attenuation model for one spatial voice. |
| AudioEmitterSnapshot | Runtime | Describes one immutable source playback request produced by a content provider. |
| AudioListenerHandle | Runtime | Identifies one spatial listener within a device generation. |
| AudioListenerSnapshot | Runtime | Describes one immutable listener candidate produced by a content provider. |
| AudioListenerState | Runtime | Contains one listener transform used by backend spatialization. |
| AudioMixer | Runtime | Contains one validated backend-neutral mixer graph. |
| AudioMixerAsset | Runtime | Selects a mixer extension and ordered features without defining a game-specific mixing model. |
| AudioMixerBuilder | Runtime | Builds and validates an open backend-neutral mixer graph. |
| AudioMixerExtension | Runtime | Builds a base mixer graph on the host control thread. |
| AudioMixerExtensionAttribute | Runtime | Marks a reloadable extension that creates the base audio mixer graph. |
| AudioMixerFeature | Runtime | Contributes optional buses and processors to a candidate mixer graph. |
| AudioMixerFeatureConfiguration | Runtime | Stores one ordered mixer feature selection using only stable data. |
| AudioMixerFeatureExtensionAttribute | Runtime | Marks a reloadable extension that contributes to an audio mixer graph. |
| AudioParameterId | Runtime | Identifies one processor parameter without imposing a processor-specific enum. |
| AudioPlayOptions | Runtime | Contains immutable parameters used to create one playback voice. |
| AudioPlaybackState | Runtime | Describes the observable lifecycle of one playback voice. |
| AudioProcessorConfiguration | Runtime | Describes one ordered processor instance attached to a mixer bus. |
| AudioProcessorId | Runtime | Identifies an audio processor implementation without imposing a closed effect catalog. |
| AudioProcessorParameter | Runtime | Stores one neutral numeric parameter assigned to an audio processor. |
| AudioProjectSettings | Runtime | Stores portable project-wide defaults for audio playback and caching. |
| AudioSpatialOptions | Runtime | Contains listener-relative positioning and attenuation parameters for one voice. |
| AudioStatistics | Runtime | Reports an immutable snapshot of runtime and backend resource usage. |
| AudioVoiceCompletedEvent | Runtime | Reports one voice terminal transition on the owning runtime’s main-thread event dispatcher. |
| AudioVoiceHandle | Runtime | Identifies one playback voice within a device generation. |
| AudioVoiceParameters | Runtime | Contains mutable voice parameters that can be changed after playback begins. |
| SerializedAudioExtensionState | Runtime | Stores reload-safe configuration for one mixer or feature extension generation. |