ppapi/api/ppb_audio_config.idl

   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