AudioFilters

View source
ceramic.AudioFilters (Class)

Internal manager for audio filter worklets across audio buses.

AudioFilters handles the lifecycle and processing of audio filter worklets, which are small processing units that modify audio in real-time. It manages:

  • Thread-safe registration and removal of worklets
  • Organizing worklets by audio bus
  • Synchronizing worklet changes between threads
  • Processing audio through active worklets

This class is used internally by the audio backend and should not be accessed directly. Use AudioFilter and AudioMixer for public audio filtering functionality.

Thread Safety:

  • On native platforms (sys), uses mutexes and atomic operations
  • Ensures safe access from both main thread and audio thread
  • Batches worklet changes to minimize lock contention
See: AudioFilter, AudioFilterWorklet, AudioMixer, Audio

Private Members

workletsDirty: Bool
allWorkletsLock: sys.thread.Mutex
accessBusLocks: SpinLock
lockByBus: Array<SpinLock>
pendingWorklets: Array<AudioFilterWorklet>
toRemoveWorklets: Array<AudioFilterWorklet>
syncWorklets(): Void

Synchronizes pending worklet changes with the active worklet lists.

This method processes queued additions and removals of worklets, updating the per-bus worklet arrays. Called by the audio backend before processing audio to ensure all worklet changes are applied.

Thread-safe on native platforms using mutex locks.

createWorklet(bus: Int, filterId: Int, workletClass: Class<AudioFilterWorklet>): AudioFilterWorklet

Creates a new audio filter worklet and queues it for addition.

Name Type Description
bus Int The audio bus ID where this worklet will process audio
filterId Int Unique identifier for the filter
workletClass Class<AudioFilterWorklet> The worklet class to instantiate
Returns Description
AudioFilterWorklet The created worklet instance
destroyWorklet(bus: Int, filterId: Int): Void

Destroys an audio filter worklet by queuing it for removal.

Searches for the worklet with the given filterId across all buses and pending additions, then marks it for removal during the next sync.

Name Type Description
bus Int The audio bus ID (currently unused but kept for API consistency)
filterId Int Unique identifier of the filter to destroy
beginUpdateFilterWorkletParams(bus: Int, filterId: Int): Void

Begins a parameter update operation for a filter worklet.

On native platforms, this acquires the necessary locks to ensure thread-safe parameter updates. Must be paired with endUpdateFilterWorkletParams.

Name Type Description
bus Int The audio bus ID
filterId Int Unique identifier of the filter being updated
endUpdateFilterWorkletParams(bus: Int, filterId: Int): Void

Ends a parameter update operation for a filter worklet.

Releases locks acquired by beginUpdateFilterWorkletParams.

Name Type Description
bus Int The audio bus ID
filterId Int Unique identifier of the filter being updated
processBusAudioWorklets(bus: Int, buffer: AudioFilterBuffer, samples: Int, channels: Int, sampleRate: Float, time: Float): Void

Processes audio through all active worklets on a specific bus.

Called by the audio backend during audio processing. Applies each worklet's processing in sequence to the provided audio buffer.

Name Type Description
bus Int The audio bus ID to process
buffer AudioFilterBuffer The audio buffer containing samples to process
samples Int Number of samples per channel in the buffer
channels Int Number of audio channels (1 for mono, 2 for stereo)
sampleRate Float Sample rate in Hz (e.g., 44100, 48000)
time Float Current audio time in seconds