| // Copyright 2016 The Cobalt Authors. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| // Module Overview: Starboard Audio Sink API |
| // |
| // Provides an interface to output raw audio data. |
| |
| #ifndef STARBOARD_AUDIO_SINK_H_ |
| #define STARBOARD_AUDIO_SINK_H_ |
| |
| #include "starboard/configuration.h" |
| |
| #include "starboard/export.h" |
| #include "starboard/media.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // --- Types ----------------------------------------------------------------- |
| |
| // An array of frame buffers. For interleaved audio streams, there will be |
| // only one element in the array. For planar audio streams, the number of |
| // elements in the array equal to the number of channels. |
| typedef void** SbAudioSinkFrameBuffers; |
| |
| // An opaque handle to an implementation-private structure representing an |
| // audio sink. |
| typedef struct SbAudioSinkPrivate* SbAudioSink; |
| |
| // Callback being called periodically to retrieve the status of the audio |
| // source. The first two output parameters indicating the filling level of the |
| // audio frame buffer passed to SbAudioSinkCreate as |frame_buffers|. As |
| // |frame_buffers| is a circular buffer, |offset_in_frames| can be used to |
| // calculate the number of continuous frames towards the end of the buffer. |
| // The audio sink can play the frames only when |is_playing| is true. It should |
| // pause the playback when |is_playing| is false. |
| // The audio sink may cache certain amount of audio frames before start |
| // playback. It will start playback immediately when |is_eos_reached| is true |
| // even if the amount of cached audio frames are not enough as no more frames |
| // will be appended into the buffer when |is_eos_reached| is true. |
| // It is possible for a host to set |is_eos_reached| to false after setting it |
| // to true, usually this is caused by a seek. |
| // All parameters except |context| cannot be NULL. |
| // Note that this function only reports the status of the source, it doesn't |
| // remove audio data from the source frame buffer. |
| typedef void (*SbAudioSinkUpdateSourceStatusFunc)(int* frames_in_buffer, |
| int* offset_in_frames, |
| bool* is_playing, |
| bool* is_eos_reached, |
| void* context); |
| |
| // Callback used to report frames consumed. The consumed frames will be |
| // removed from the source frame buffer to free space for new audio frames. |
| typedef void (*SbAudioSinkConsumeFramesFunc)(int frames_consumed, |
| void* context); |
| |
| // Well-defined value for an invalid audio sink. |
| #define kSbAudioSinkInvalid ((SbAudioSink)NULL) |
| |
| // --- Functions ------------------------------------------------------------- |
| |
| // Indicates whether the given audio sink handle is valid. |
| // |
| // |audio_sink|: The audio sink handle to check. |
| SB_EXPORT bool SbAudioSinkIsValid(SbAudioSink audio_sink); |
| |
| // Creates an audio sink for the specified |channels| and |
| // |sampling_frequency_hz|, acquires all resources needed to operate the |
| // audio sink, and returns an opaque handle to the audio sink. |
| // |
| // If the particular platform doesn't support the requested audio sink, the |
| // function returns |kSbAudioSinkInvalid| without calling any of the callbacks. |
| // If there is a platform limitation on how many audio sinks can coexist |
| // simultaneously, then calls made to this function that attempt to exceed |
| // that limit must return |kSbAudioSinkInvalid|. Multiple calls to |
| // SbAudioSinkCreate must not cause a crash. |
| // |
| // |channels|: The number of audio channels, such as left and right channels |
| // in stereo audio. |
| // |sampling_frequency_hz|: The sample frequency of the audio data being |
| // streamed. For example, 22,000 Hz means 22,000 sample elements represents |
| // one second of audio data. |
| // |audio_sample_type|: The type of each sample of the audio data -- |
| // |int16|, |float32|, etc. |
| // |audio_frame_storage_type|: Indicates whether frames are interleaved or |
| // planar. |
| // |frame_buffers|: An array of pointers to sample data. |
| // - If the sink is operating in interleaved mode, the array contains only |
| // one element, which is an array containing (|frames_per_channel| * |
| // |channels|) samples. |
| // - If the sink is operating in planar mode, the number of elements in the |
| // array is the same as |channels|, and each element is an array of |
| // |frames_per_channel| samples. The caller has to ensure that |
| // |frame_buffers| is valid until SbAudioSinkDestroy is called. |
| // |frames_per_channel|: The size of the frame buffers, in units of the |
| // number of samples per channel. The frame, in this case, represents a |
| // group of samples at the same media time, one for each channel. |
| // |update_source_status_func|: The audio sink calls this function on an |
| // internal thread to query the status of the source. It is called |
| // immediately after SbAudioSinkCreate is called, even before it returns. |
| // The caller has to ensure that the callback functions above return |
| // meaningful values in this case. The value cannot be NULL. |
| // |consume_frames_func|: The audio sink calls this function on an internal |
| // thread to report consumed frames. The value cannot be NULL. |
| // |context|: A value that is passed back to all callbacks and is generally |
| // used to point at a class or struct that contains state associated with the |
| // audio sink. |
| |
| SB_EXPORT SbAudioSink |
| SbAudioSinkCreate(int channels, |
| int sampling_frequency_hz, |
| SbMediaAudioSampleType audio_sample_type, |
| SbMediaAudioFrameStorageType audio_frame_storage_type, |
| SbAudioSinkFrameBuffers frame_buffers, |
| int frames_per_channel, |
| SbAudioSinkUpdateSourceStatusFunc update_source_status_func, |
| SbAudioSinkConsumeFramesFunc consume_frames_func, |
| void* context); |
| |
| // Destroys |audio_sink|, freeing all associated resources. Before |
| // returning, the function waits until all callbacks that are in progress |
| // have finished. After the function returns, no further calls are made |
| // callbacks passed into SbAudioSinkCreate. In addition, you can not pass |
| // |audio_sink| to any other SbAudioSink functions after SbAudioSinkDestroy |
| // has been called on it. |
| // |
| // This function can be called on any thread. However, it cannot be called |
| // within any of the callbacks passed into SbAudioSinkCreate. |
| // |
| // |audio_sink|: The audio sink to destroy. |
| SB_EXPORT void SbAudioSinkDestroy(SbAudioSink audio_sink); |
| |
| // Returns the maximum number of channels supported on the platform. For |
| // example, the number would be |2| if the platform only supports stereo. |
| SB_EXPORT int SbAudioSinkGetMaxChannels(); |
| |
| // Returns the supported sample rate closest to |sampling_frequency_hz|. |
| // On platforms that don't support all sample rates, it is the caller's |
| // responsibility to resample the audio frames into the supported sample rate |
| // returned by this function. |
| SB_EXPORT int SbAudioSinkGetNearestSupportedSampleFrequency( |
| int sampling_frequency_hz); |
| |
| // Indicates whether |audio_sample_type| is supported on this platform. |
| SB_EXPORT bool SbAudioSinkIsAudioSampleTypeSupported( |
| SbMediaAudioSampleType audio_sample_type); |
| |
| // Indicates whether |audio_frame_storage_type| is supported on this |
| // platform. |
| SB_EXPORT bool SbAudioSinkIsAudioFrameStorageTypeSupported( |
| SbMediaAudioFrameStorageType audio_frame_storage_type); |
| |
| // Returns the minimum frames required by audio sink to play without underflows. |
| // Returns -1, if |channels|, |sample_type| or |sampling_frequency_hz| is not |
| // supported. It's user's responsibility to ensure that there're enough |
| // frames written into audio sink during playing, or it may have underflows. |
| // |
| // |channels|: The number of audio channels, such as left and right channels |
| // in stereo audio. |
| // |audio_sample_type|: The type of each sample of the audio data -- |
| // |int16|, |float32|, etc. |
| // |sampling_frequency_hz|: The sample frequency of the audio data being |
| // streamed. For example, 22,000 Hz means 22,000 sample elements represents |
| // one second of audio data. |
| SB_EXPORT int SbAudioSinkGetMinBufferSizeInFrames( |
| int channels, |
| SbMediaAudioSampleType sample_type, |
| int sampling_frequency_hz); |
| |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // STARBOARD_AUDIO_SINK_H_ |