ppapi/api/ppb_audio.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 <code>PPB_Audio</code> interface, which provides
   8  * realtime stereo audio streaming capabilities.
   9  */
  10
  11 label Chrome {
  12   M14 = 1.0,
  13   M31 = 1.1
  14 };
  15
  16 /**
  17  * <code>PPB_Audio_Callback</code> defines the type of an audio callback
  18  * function used to fill the audio buffer with data. Please see the
  19  * Create() function in the <code>PPB_Audio</code> interface for
  20  * more details on this callback.
  21  *
  22  * @param[in] sample_buffer A buffer to fill with audio data.
  23  * @param[in] buffer_size_in_bytes The size of the buffer in bytes.
  24  * @param[in] latency How long before the audio data is to be presented.
  25  * @param[inout] user_data An opaque pointer that was passed into
  26  * <code>PPB_Audio.Create()</code>.
  27  */
  28 typedef void PPB_Audio_Callback([out] mem_t sample_buffer,
  29                                 [in] uint32_t buffer_size_in_bytes,
  30                                 [in, version=1.1] PP_TimeDelta latency,
  31                                 [inout] mem_t user_data);
  32
  33 /**
  34  * The <code>PPB_Audio</code> interface contains pointers to several functions
  35  * for handling audio resources. Refer to the
  36  * <a href="/native-client/devguide/coding/audio.html">Audio</a>
  37  * chapter in the Developer's Guide for information on using this interface.
  38  * Please see descriptions for each <code>PPB_Audio</code> and
  39  * <code>PPB_AudioConfig</code> function for more details. A C example using
  40  * <code>PPB_Audio</code> and <code>PPB_AudioConfig</code> follows.
  41  *
  42  * <strong>Example: </strong>
  43  *
  44  * @code
  45  * void audio_callback(void* sample_buffer,
  46  *                     uint32_t buffer_size_in_bytes,
  47  *                     void* user_data) {
  48  *   ... quickly fill in the buffer with samples and return to caller ...
  49  *  }
  50  *
  51  * ...Assume the application has cached the audio configuration interface in
  52  * audio_config_interface and the audio interface in
  53  * audio_interface...
  54  *
  55  * uint32_t count = audio_config_interface->RecommendSampleFrameCount(
  56  *     PP_AUDIOSAMPLERATE_44100, 4096);
  57  * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
  58  *     pp_instance, PP_AUDIOSAMPLERATE_44100, count);
  59  * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config,
  60  *     audio_callback, NULL);
  61  * audio_interface->StartPlayback(pp_audio);
  62  *
  63  * ...audio_callback() will now be periodically invoked on a separate thread...
  64  * @endcode
  65  */
  66 interface PPB_Audio {
  67  /**
  68   * Create() creates an audio resource. No sound will be heard until
  69   * StartPlayback() is called. The callback is called with the buffer address
  70   * and given user data whenever the buffer needs to be filled. From within the
  71   * callback, you should not call <code>PPB_Audio</code> functions. The
  72   * callback will be called on a different thread than the one which created
  73   * the interface. For performance-critical applications (i.e. low-latency
  74   * audio), the callback should avoid blocking or calling functions that can
  75   * obtain locks, such as malloc. The layout and the size of the buffer passed
  76   * to the audio callback will be determined by the device configuration and is
  77   * specified in the <code>AudioConfig</code> documentation.
  78   *
  79   * @param[in] instance A <code>PP_Instance</code> identifying one instance
  80   * of a module.
  81   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
  82   * config resource.
  83   * @param[in] audio_callback A <code>PPB_Audio_Callback</code> callback
  84   * function that the browser calls when it needs more samples to play.
  85   * @param[in] user_data A pointer to user data used in the callback function.
  86   *
  87   * @return A <code>PP_Resource</code> containing the audio resource if
  88   * successful or 0 if the configuration cannot be honored or the callback is
  89   * null.
  90   */
  91   PP_Resource Create(
  92       [in] PP_Instance instance,
  93       [in] PP_Resource config,
  94       [in] PPB_Audio_Callback audio_callback,
  95       [inout] mem_t user_data);
  96
  97   /**
  98    * IsAudio() determines if the provided resource is an audio resource.
  99    *
 100    * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
 101    * resource.
 102    *
 103    * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
 104    * if the given resource is an Audio resource, otherwise
 105    * <code>PP_FALSE</code>.
 106    */
 107   PP_Bool IsAudio(
 108       [in] PP_Resource resource);
 109
 110   /**
 111    * GetCurrrentConfig() returns an audio config resource for the given audio
 112    * resource.
 113    *
 114    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 115    * resource.
 116    *
 117    * @return A <code>PP_Resource</code> containing the audio config resource if
 118    * successful.
 119    */
 120   PP_Resource GetCurrentConfig(
 121       [in] PP_Resource audio);
 122
 123   /**
 124    * StartPlayback() starts the playback of the audio resource and begins
 125   * periodically calling the callback.
 126    *
 127    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 128    * resource.
 129    *
 130    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 131    * successful, otherwise <code>PP_FALSE</code>. Also returns
 132    * <code>PP_TRUE</code> (and be a no-op) if called while playback is already
 133    * in progress.
 134    */
 135   PP_Bool StartPlayback(
 136       [in] PP_Resource audio);
 137
 138   /**
 139    * StopPlayback() stops the playback of the audio resource.
 140    *
 141    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 142    * resource.
 143    *
 144    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 145    * successful, otherwise <code>PP_FALSE</code>. Also returns
 146    * <code>PP_TRUE</code> (and is a no-op) if called while playback is already
 147    * stopped. If a callback is in progress, StopPlayback() will block until the
 148    * callback completes.
 149    */
 150   PP_Bool StopPlayback(
 151       [in] PP_Resource audio);
 152 };
 153