blob: 59f507b2c5e5bfb02e4a3d5164fbf809cf933c44 [file] [log] [blame]
// Copyright 2016 Google Inc. 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
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// An interface to output raw audio data.
#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/media.h"
#ifdef __cplusplus
extern "C" {
// --- 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 -------------------------------------------------------------
// Returns whether the given audio sink handle is valid.
SB_EXPORT bool SbAudioSinkIsValid(SbAudioSink audio_sink);
// Creates an audio sink for the specified |channels| and
// |sampling_frequency_hz|, acquiring all resources needed to operate it, and
// returning an opaque handle to it.
// |frame_buffers| is 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 will be the
// same as |channels|, each of the elements will be an array of
// |frames_per_channel| samples. The caller has to ensure that |frame_buffers|
// is valid until SbAudioSinkDestroy is called.
// |update_source_status_func| cannot be NULL. The audio sink will call it on
// an internal thread to query the status of the source.
// |consume_frames_func| cannot be NULL. The audio sink will call it on an
// internal thread to report consumed frames.
// |context| will be passed back into all callbacks, and is generally used to
// point at a class or struct that contains state associated with the audio
// sink.
// The audio sink will start to call |update_source_status_func| immediately
// after SbAudioSinkCreate is called, even before it returns. The caller has
// to ensure that the above callbacks returns meaningful values in this case.
// If the particular platform doesn't support the requested audio sink, the
// function returns kSbAudioSinkInvalid without calling any of the callbacks.
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. It will wait until
// all callbacks in progress is finished before returning. Upon returning of
// this function, no callbacks passed into SbAudioSinkCreate will be called
// further. This function can be called on any thread but cannot be called
// within any of the callbacks passed into SbAudioSinkCreate.
// It is not allowed to pass |audio_sink| into any other SbAudioSink function
// once SbAudioSinkDestroy has been called on it.
SB_EXPORT void SbAudioSinkDestroy(SbAudioSink audio_sink);
// Returns the maximum channel supported on the platform.
SB_EXPORT int SbAudioSinkGetMaxChannels();
// Returns the nearest supported sample rate of |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);
// Returns true if the particular SbMediaAudioSampleType is supported on this
// platform.
SB_EXPORT bool SbAudioSinkIsAudioSampleTypeSupported(
SbMediaAudioSampleType audio_sample_type);
// Returns true if the particular SbMediaAudioFrameStorageType is supported on
// this platform.
SB_EXPORT bool SbAudioSinkIsAudioFrameStorageTypeSupported(
SbMediaAudioFrameStorageType audio_frame_storage_type);
#ifdef __cplusplus
} // extern "C"