/* Copyright (c) 2012 The Chromium Authors. All rights reserved. * Use of this source code is governed by a BSD-style license that can be * found in the LICENSE file. */ /** * This file defines the PPB_AudioConfig interface for establishing an * audio configuration resource within the browser. */ label Chrome { M14 = 1.0, M19 = 1.1 }; /** * This enumeration contains audio frame count constants. * PP_AUDIOMINSAMPLEFRAMECOUNT is the minimum possible frame * count. PP_AUDIOMAXSAMPLEFRAMECOUNT is the maximum possible * frame count. */ [unnamed] enum PP_AudioFrameSize { PP_AUDIOMINSAMPLEFRAMECOUNT = 64, PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768 }; /** * PP_AudioSampleRate is an enumeration of the different audio sampling rates. * PP_AUDIOSAMPLERATE_44100 is the sample rate used on CDs and * PP_AUDIOSAMPLERATE_48000 is the sample rate used on DVDs and * Digital Audio Tapes. */ [assert_size(4)] enum PP_AudioSampleRate { PP_AUDIOSAMPLERATE_NONE = 0, PP_AUDIOSAMPLERATE_44100 = 44100, PP_AUDIOSAMPLERATE_48000 = 48000 } ; /** * The PPB_AudioConfig interface contains pointers to several * functions for establishing your audio configuration within the browser. * This interface only supports 16-bit stereo output. * * Refer to the * Pepper * Audio API for information on using this interface. */ [macro="PPB_AUDIO_CONFIG_INTERFACE"] interface PPB_AudioConfig { /** * CreateStereo16bit() creates a 16 bit audio configuration resource. The * sample_rate should be the result of calling * RecommendSampleRate and sample_frame_count should * be the result of calling RecommendSampleFrameCount. If the * sample frame count or bit rate isn't supported, this function will fail and * return a null resource. * * A single sample frame on a stereo device means one value for the left * channel and one value for the right channel. * * Buffer layout for a stereo int16 configuration: * int16_t *buffer16; * buffer16[0] is the first left channel sample. * buffer16[1] is the first right channel sample. * buffer16[2] is the second left channel sample. * buffer16[3] is the second right channel sample. * ... * buffer16[2 * (sample_frame_count - 1)] is the last left * channel sample. * buffer16[2 * (sample_frame_count - 1) + 1] is the last * right channel sample. * Data will always be in the native endian format of the platform. * * @param[in] instance A PP_Instance identifying one instance * of a module. * @param[in] sample_rate A PP_AudioSampleRate which is either * PP_AUDIOSAMPLERATE_44100 or * PP_AUDIOSAMPLERATE_48000. * @param[in] sample_frame_count A uint32_t frame count returned * from the RecommendSampleFrameCount function. * * @return A PP_Resource containing the * PPB_Audio_Config if successful or a null resource if the * sample frame count or bit rate are not supported. */ PP_Resource CreateStereo16Bit( [in] PP_Instance instance, [in] PP_AudioSampleRate sample_rate, [in] uint32_t sample_frame_count); /** * This comment block applies to version 1.0, which is deprecated in favor of * the same function but with slightly different signature and behavior. * * RecommendSampleFrameCount() returns the supported sample frame count * closest to the requested count. The sample frame count determines the * overall latency of audio. Since one "frame" is always buffered in advance, * smaller frame counts will yield lower latency, but higher CPU utilization. * For best audio performance, use the value returned by RecommendSampleRate * as the input sample rate, then use the RecommendSampleFrameCount return * value when creating the audio configuration resource. * * Sample counts less than * PP_AUDIOMINSAMPLEFRAMECOUNT and greater than * PP_AUDIOMAXSAMPLEFRAMECOUNT are never supported on any * system, but values in between aren't necessarily glitch-free. * * @param[in] sample_rate A PP_AudioSampleRate which is either * PP_AUDIOSAMPLERATE_44100 or * PP_AUDIOSAMPLERATE_48000. * @param[in] requested_sample_frame_count A uint_32t requested * frame count. * * @return A uint32_t containing the recommended sample frame * count if successful. */ [deprecate=1.1] uint32_t RecommendSampleFrameCount( [in] PP_AudioSampleRate sample_rate, [in] uint32_t requested_sample_frame_count); /** * RecommendSampleFrameCount() returns the supported sample frame count * closest to the requested count. The sample frame count determines the * overall latency of audio. Since one "frame" is always buffered in advance, * smaller frame counts will yield lower latency, but higher CPU utilization. * * Supported sample frame counts will vary by hardware and system (consider * that the local system might be anywhere from a cell phone or a high-end * audio workstation). Sample counts less than * PP_AUDIOMINSAMPLEFRAMECOUNT and greater than * PP_AUDIOMAXSAMPLEFRAMECOUNT are never supported on any * system, but values in between aren't necessarily valid. This function * will return a supported count closest to the requested frame count. * * RecommendSampleFrameCount() result is intended for audio output devices. * * @param[in] instance * @param[in] sample_rate A PP_AudioSampleRate which is either * PP_AUDIOSAMPLERATE_44100 or * PP_AUDIOSAMPLERATE_48000. * @param[in] requested_sample_frame_count A uint_32t requested * frame count. * * @return A uint32_t containing the recommended sample frame * count if successful. */ [version=1.1] uint32_t RecommendSampleFrameCount( [in] PP_Instance instance, [in] PP_AudioSampleRate sample_rate, [in] uint32_t requested_sample_frame_count); /** * IsAudioConfig() determines if the given resource is a * PPB_Audio_Config. * * @param[in] resource A PP_Resource corresponding to an audio * config resource. * * @return A PP_Bool containing PP_TRUE if the given * resource is an AudioConfig resource, otherwise * PP_FALSE. */ PP_Bool IsAudioConfig( [in] PP_Resource resource); /** * GetSampleRate() returns the sample rate for the given * PPB_Audio_Config. * * @param[in] config A PP_Resource corresponding to a * PPB_Audio_Config. * * @return A PP_AudioSampleRate containing sample rate or * PP_AUDIOSAMPLERATE_NONE if the resource is invalid. */ PP_AudioSampleRate GetSampleRate( [in] PP_Resource config); /** * GetSampleFrameCount() returns the sample frame count for the given * PPB_Audio_Config. * * @param[in] config A PP_Resource corresponding to an audio * config resource. * * @return A uint32_t containing sample frame count or * 0 if the resource is invalid. Refer to * RecommendSampleFrameCount() for more on sample frame counts. */ uint32_t GetSampleFrameCount( [in] PP_Resource config); /** * RecommendSampleRate() returns the native sample rate that the browser * is using in the backend. Applications that use the recommended sample * rate will have potentially better latency and fidelity. The return value * is indended for audio output devices. If the output sample rate cannot be * determined, this function can return PP_AUDIOSAMPLERATE_NONE. * * @param[in] instance * * @return A uint32_t containing the recommended sample frame * count if successful. */ [version=1.1] PP_AudioSampleRate RecommendSampleRate( [in] PP_Instance instance); };