Skip to content
Project referenceDevelopmentEngine ccf7d03f
Authored
  • 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.

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.

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.

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.

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.

Browse audio types.

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.

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.