pub type AudioQueueProcessingTapCallback = Option<unsafe extern "C-unwind" fn(NonNull<c_void>, AudioQueueProcessingTapRef, u32, NonNull<AudioTimeStamp>, NonNull<AudioQueueProcessingTapFlags>, NonNull<u32>, NonNull<AudioBufferList>)>;AudioQueue and objc2-core-audio-types only.Expand description
A function called when an audio queue has data to be processed by its tap
A processing callback is invoked when the audio queue has data that can be processed by a given tap.
The audio queue will call the processing callback when it has sufficient data to provide for processing.
In the case of a siphoning tap, the callback function can inspect the audio data in ioData, but should not otherwise modify it. The callback should not call AudioQueueProcessingTapGetSourceAudio.
A non-siphoning callback should call AudioQueueProcessingTapGetSourceAudio to request from the queue as much source data as it needs in order to produce the requested number of output samples. When the callback requests source data it may receive less data than it requests.
In the case of a tap on an audio output queue, the tap must emit the exact number of sample frames that the queue requests. In normal circumstances, the tap’s requests for source data will be satisfied (as the client running the audio queue is also providing the queue with the audio source material). If there is insufficient source data available (this is indicated by the outNumberFrames from the GetSource call), then the processing tap should deal as best as it can; it can either return less data than was requested or insert silence, noise, etc. itself. If it returns less data than requested, the hosting audio queue will fill in the remainder with silence.
In the case of a tap on an audio input queue, the tap may provide back less audio data than is being requested. Typically this will occur because the tap will ask for source data that is not available at this time (the audio input hasn’t arrived yet), so the tap should cache the source data that it needs and return as many processed samples as it can. If the processing tap falls behind and is not providing data quickly enough silence will be generated in the data provided to the client (and there is no signal about this either).
A processing tap executes in a semi-real-time context, so the general limitations for real-time processing apply. Avoid using API’s which may block. In particular, it is not safe to call the audio queue on which the tap was installed, with the exceptions of AudioQueueProcessingTapGetSourceAudio and AudioQueueProcessingTapGetQueueTime.
In normal operation the source data will be continuous from the last time the callback was called and the processed samples should be continuous from the previous samples returned. If there is any discontinuity between the last samples provided for processing the audio queue will set the bit for kAudioQueueProcessing_StartOfStream in the inFlags. After a discontinuity the first sample that the processing tap outputs should correspond to the first sample that was provided in the source samples (so a reset and then consequent process serves to re-anchor a relationship between the processing tap’s source and processed samples). In this case the processing tap will typically discard any previous state (for instance, if a processing tap was adding a reverb to a signal, then the discontinuity flag would act the same as AudioUnitReset; any previous source information in the processing tap should be discarded).
The caller is responsible for absorbing any processing delays. For example, if the processing is to be done by an audio unit that reports a processing latency, then the caller should remove those latency samples from the audio unit’s rendering and not return them to the audio queue.
The processing tap is able to operate on the provided source data in place (that is, it can do “in place processing”) and return pointers to that buffer rather than its own. This works in a similar way as AudioUnit render operations.
When an output audio queue is being stopped asynchronously, the processing tap will see the kAudioQueueProcessingTap_EndOfStream bit set on return from GetSourceAudio, and is responsible for propagating this bit from the callback when its processing has reached this point.
A processing tap will NEVER see the same source data again, so, it should keep its own copy if it needs to keep it for further reference past the duration of this call. It also cannot assume that the pointers to the source data that it retrieves will remain valid AFTER the processing tap has executed.
The processing tap should ensure that the data pointers it provides in outProcessedData remain valid until the tap is executed again.
A processing tap is destroyed implicitly when its audio queue is disposed. It may also be removed explicitly, via AudioQueueProcessingTapDispose.
Parameter inClientData: the client data pointer passed to AudioQueueProcessingTapNew
Parameter inAQTap: The tap for this callback.
Parameter inNumberFrames: The requested number of sample frames to be rendered.
Parameter ioFlags: On entry, the flags passed at construction time are provided. On exit,
the start/end of stream flags should be set when appropriate.
Parameter ioTimeStamp: On an input audio queue, the timestamp must be returned from this function.
On an output audio queue, the callback is provided a continuous timestamp.
Parameter outNumberFrames: The number of frames of audio data provided in the processed data. Can be 0.
Parameter ioData: For non-siphoning taps, on entry, the buffer pointers are null and the lengths
are zero. On exit, they should contain the tap’s output.
Siphoning taps receive valid buffers which they must not alter.
See also Apple’s documentation
Aliased Type§
pub enum AudioQueueProcessingTapCallback {
None,
Some(unsafe extern "C-unwind" fn(NonNull<c_void>, *mut OpaqueAudioQueueProcessingTap, u32, NonNull<AudioTimeStamp>, NonNull<AudioQueueProcessingTapFlags>, NonNull<u32>, NonNull<AudioBufferList>)),
}Variants§
None
No value.
Some(unsafe extern "C-unwind" fn(NonNull<c_void>, *mut OpaqueAudioQueueProcessingTap, u32, NonNull<AudioTimeStamp>, NonNull<AudioQueueProcessingTapFlags>, NonNull<u32>, NonNull<AudioBufferList>))
Some value of type T.