1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 /** 7 * This file defines the PPB_AudioConfig interface for establishing an 8 * audio configuration resource within the browser. 9 */ 10 11 label Chrome { 12 M14 = 1.0, 13 M19 = 1.1 14 }; 15 16 /** 17 * This enumeration contains audio frame count constants. 18 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> is the minimum possible frame 19 * count. <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> is the maximum possible 20 * frame count. 21 */ 22 [unnamed] enum PP_AudioFrameSize { 23 PP_AUDIOMINSAMPLEFRAMECOUNT = 64, 24 PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768 25 }; 26 27 28 /** 29 * PP_AudioSampleRate is an enumeration of the different audio sampling rates. 30 * <code>PP_AUDIOSAMPLERATE_44100</code> is the sample rate used on CDs and 31 * <code>PP_AUDIOSAMPLERATE_48000</code> is the sample rate used on DVDs and 32 * Digital Audio Tapes. 33 */ 34 [assert_size(4)] 35 enum PP_AudioSampleRate { 36 PP_AUDIOSAMPLERATE_NONE = 0, 37 PP_AUDIOSAMPLERATE_44100 = 44100, 38 PP_AUDIOSAMPLERATE_48000 = 48000 39 } ; 40 41 42 /** 43 * The <code>PPB_AudioConfig</code> interface contains pointers to several 44 * functions for establishing your audio configuration within the browser. 45 * This interface only supports 16-bit stereo output. 46 * 47 * Refer to the 48 * <a href="/native-client/devguide/coding/audio.html">Audio 49 * </a> chapter in the Developer's Guide for information on using this 50 * interface. 51 */ 52 [macro="PPB_AUDIO_CONFIG_INTERFACE"] 53 interface PPB_AudioConfig { 54 /** 55 * CreateStereo16bit() creates a 16 bit audio configuration resource. The 56 * <code>sample_rate</code> should be the result of calling 57 * <code>RecommendSampleRate</code> and <code>sample_frame_count</code> should 58 * be the result of calling <code>RecommendSampleFrameCount</code>. If the 59 * sample frame count or bit rate isn't supported, this function will fail and 60 * return a null resource. 61 * 62 * A single sample frame on a stereo device means one value for the left 63 * channel and one value for the right channel. 64 * 65 * Buffer layout for a stereo int16 configuration: 66 * <code>int16_t *buffer16;</code> 67 * <code>buffer16[0]</code> is the first left channel sample. 68 * <code>buffer16[1]</code> is the first right channel sample. 69 * <code>buffer16[2]</code> is the second left channel sample. 70 * <code>buffer16[3]</code> is the second right channel sample. 71 * ... 72 * <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left 73 * channel sample. 74 * <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last 75 * right channel sample. 76 * Data will always be in the native endian format of the platform. 77 * 78 * @param[in] instance A <code>PP_Instance</code> identifying one instance 79 * of a module. 80 * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either 81 * <code>PP_AUDIOSAMPLERATE_44100</code> or 82 * <code>PP_AUDIOSAMPLERATE_48000</code>. 83 * @param[in] sample_frame_count A <code>uint32_t</code> frame count returned 84 * from the <code>RecommendSampleFrameCount</code> function. 85 * 86 * @return A <code>PP_Resource</code> containing the 87 * <code>PPB_Audio_Config</code> if successful or a null resource if the 88 * sample frame count or bit rate are not supported. 89 */ 90 PP_Resource CreateStereo16Bit( 91 [in] PP_Instance instance, 92 [in] PP_AudioSampleRate sample_rate, 93 [in] uint32_t sample_frame_count); 94 95 /** 96 * This comment block applies to version 1.0, which is deprecated in favor of 97 * the same function but with slightly different signature and behavior. 98 * 99 * RecommendSampleFrameCount() returns the supported sample frame count 100 * closest to the requested count. The sample frame count determines the 101 * overall latency of audio. Since one "frame" is always buffered in advance, 102 * smaller frame counts will yield lower latency, but higher CPU utilization. 103 * For best audio performance, use the value returned by RecommendSampleRate 104 * as the input sample rate, then use the RecommendSampleFrameCount return 105 * value when creating the audio configuration resource. 106 * 107 * Sample counts less than 108 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than 109 * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any 110 * system, but values in between aren't necessarily glitch-free. 111 * 112 * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either 113 * <code>PP_AUDIOSAMPLERATE_44100</code> or 114 * <code>PP_AUDIOSAMPLERATE_48000.</code> 115 * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested 116 * frame count. 117 * 118 * @return A <code>uint32_t</code> containing the recommended sample frame 119 * count if successful. 120 */ 121 [deprecate=1.1] 122 uint32_t RecommendSampleFrameCount( 123 [in] PP_AudioSampleRate sample_rate, 124 [in] uint32_t requested_sample_frame_count); 125 126 /** 127 * RecommendSampleFrameCount() returns the supported sample frame count 128 * closest to the requested count. The sample frame count determines the 129 * overall latency of audio. Since one "frame" is always buffered in advance, 130 * smaller frame counts will yield lower latency, but higher CPU utilization. 131 * 132 * Supported sample frame counts will vary by hardware and system (consider 133 * that the local system might be anywhere from a cell phone or a high-end 134 * audio workstation). Sample counts less than 135 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than 136 * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any 137 * system, but values in between aren't necessarily valid. This function 138 * will return a supported count closest to the requested frame count. 139 * 140 * RecommendSampleFrameCount() result is intended for audio output devices. 141 * 142 * @param[in] instance 143 * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either 144 * <code>PP_AUDIOSAMPLERATE_44100</code> or 145 * <code>PP_AUDIOSAMPLERATE_48000.</code> 146 * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested 147 * frame count. 148 * 149 * @return A <code>uint32_t</code> containing the recommended sample frame 150 * count if successful. 151 */ 152 [version=1.1] 153 uint32_t RecommendSampleFrameCount( 154 [in] PP_Instance instance, 155 [in] PP_AudioSampleRate sample_rate, 156 [in] uint32_t requested_sample_frame_count); 157 158 /** 159 * IsAudioConfig() determines if the given resource is a 160 * <code>PPB_Audio_Config</code>. 161 * 162 * @param[in] resource A <code>PP_Resource</code> corresponding to an audio 163 * config resource. 164 * 165 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given 166 * resource is an <code>AudioConfig</code> resource, otherwise 167 * <code>PP_FALSE</code>. 168 */ 169 PP_Bool IsAudioConfig( 170 [in] PP_Resource resource); 171 172 /** 173 * GetSampleRate() returns the sample rate for the given 174 * <code>PPB_Audio_Config</code>. 175 * 176 * @param[in] config A <code>PP_Resource</code> corresponding to a 177 * <code>PPB_Audio_Config</code>. 178 * 179 * @return A <code>PP_AudioSampleRate</code> containing sample rate or 180 * <code>PP_AUDIOSAMPLERATE_NONE</code> if the resource is invalid. 181 */ 182 PP_AudioSampleRate GetSampleRate( 183 [in] PP_Resource config); 184 185 /** 186 * GetSampleFrameCount() returns the sample frame count for the given 187 * <code>PPB_Audio_Config</code>. 188 * 189 * @param[in] config A <code>PP_Resource</code> corresponding to an audio 190 * config resource. 191 * 192 * @return A <code>uint32_t</code> containing sample frame count or 193 * 0 if the resource is invalid. Refer to 194 * RecommendSampleFrameCount() for more on sample frame counts. 195 */ 196 uint32_t GetSampleFrameCount( 197 [in] PP_Resource config); 198 199 /** 200 * RecommendSampleRate() returns the native sample rate that the browser 201 * is using in the backend. Applications that use the recommended sample 202 * rate will have potentially better latency and fidelity. The return value 203 * is intended for audio output devices. If the output sample rate cannot be 204 * determined, this function can return PP_AUDIOSAMPLERATE_NONE. 205 * 206 * @param[in] instance 207 * 208 * @return A <code>uint32_t</code> containing the recommended sample frame 209 * count if successful. 210 */ 211 [version=1.1] 212 PP_AudioSampleRate RecommendSampleRate( 213 [in] PP_Instance instance); 214 215 }; 216 217
