User-defined audio output interface.
The library uses this to play the sound of <video> and <audio> elements. It decodes the audio and pushes the samples to your implementation, which plays them on a device.
You can provide the library with your own AudioOutput implementation so that media audio plays through your own audio engine.
Default Implementation
A platform-specific implementation of AudioOutput is provided for you when you call App::Create(). Its source is in the SDK's platform folder if you want a starting point.
If you are using Renderer::Create() and don't provide one, media plays without sound.
Setting the Audio Output
To provide your own custom AudioOutput implementation, you should inherit from this class, handle the virtual member functions, and then pass an instance of your class to Platform::set_audio_output() before calling Renderer::Create() or App::Create(). It must stay alive until the Renderer is destroyed.
Implementing an Audio Output
Each loaded media file plays through its own stream, identified by a stream_id. A stream goes through these calls:
- CreateStream() gives you the stream's sample rate and channel count.
- PushSamples() delivers audio as it's decoded. SetVolume() and SetPaused() can come at any time.
- Flush() discards the buffered audio when the media seeks, and new samples follow.
- Stop() tells you no more samples are coming. A later Flush() can start the stream again (eg, when the media loops).
- DestroyStream() frees the stream. No more calls use its stream_id.
Samples are interleaved 32-bit floats in the range [-1.0, 1.0]. If your device wants a different sample rate or channel count, resample and downmix in your implementation.
- Warning
- The library calls these methods from several of its own threads, not only the Renderer's thread. PushSamples() can still be running when Flush() or Stop() is called for the same stream, so protect each stream's state.
- Warning
- When your buffer is full, PushSamples() should wait for room instead of dropping samples (the wait keeps decoding in step with playback). A waiting PushSamples() must return as soon as Flush() or Stop() is called for its stream, or the library can hang.
- Note
- GetPlaybackPosition() is optional. Implement it for the most accurate audio-video sync.
- Precondition
- Requires the Pro edition or higher.
- See also
- Platform::set_audio_output()
|
| virtual | ~AudioOutput () |
| virtual void | CreateStream (uint32_t stream_id, const AudioStreamFormat &format)=0 |
| | Create a new audio stream.
|
| virtual void | PushSamples (uint32_t stream_id, const float *samples, uint32_t num_frames)=0 |
| | Push decoded samples into a stream.
|
| virtual void | SetVolume (uint32_t stream_id, float volume)=0 |
| | Set the volume of a stream.
|
| virtual void | SetPaused (uint32_t stream_id, bool paused)=0 |
| | Pause or resume a stream.
|
| virtual void | Flush (uint32_t stream_id)=0 |
| | Discard a stream's buffered audio.
|
| virtual void | Stop (uint32_t stream_id)=0 |
| | Tell a stream that no more samples are coming.
|
| virtual void | DestroyStream (uint32_t stream_id)=0 |
| | Destroy a stream and free its resources.
|
| virtual uint64_t | GetPlaybackPosition (uint32_t stream_id) |
| | Get the number of frames of a stream that have been played.
|
| virtual AudioFormat | preferred_output_format () const |
| | Get the device's preferred audio format.
|