ppapi/api/dev/ppb_audio_input_dev.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_AudioInput_Dev</code> interface, which
   8  * provides realtime audio input capture.
   9  */
  10
  11 label Chrome {
  12   M19 = 0.2,
  13   M25 = 0.3,
  14   M30 = 0.4
  15 };
  16
  17 /**
  18  * <code>PPB_AudioInput_Callback</code> defines the type of an audio callback
  19  * function used to provide the audio buffer with data. This callback will be
  20  * called on a separate thread from the creation thread.
  21  *
  22  * @param[in] sample_buffer A buffer providing audio input data.
  23  * @param[in] buffer_size_in_bytes The size of the buffer in bytes.
  24  * @param[in] latency The time that has elapsed since the data was recorded.
  25  * @param[inout] user_data An opaque pointer that was passed into
  26  * <code>PPB_AudioInput_Dev.Open()</code>.
  27  */
  28 typedef void PPB_AudioInput_Callback([in] mem_t sample_buffer,
  29                                      [in] uint32_t buffer_size_in_bytes,
  30                                      [in, version=0.4] PP_TimeDelta latency,
  31                                      [inout] mem_t user_data);
  32
  33 /**
  34  * The <code>PPB_AudioInput_Dev</code> interface contains pointers to several
  35  * functions for handling audio input resources.
  36  *
  37  * TODO(brettw) before moving out of dev, we need to resolve the issue of
  38  * the mismatch between the current audio config interface and this one.
  39  *
  40  * In particular, the params for input assume stereo, but this class takes
  41  * everything as mono. We either need to not use an audio config resource, or
  42  * add mono support.
  43  *
  44  * In addition, RecommendSampleFrameCount is completely wrong for audio input.
  45  * RecommendSampleFrameCount returns the frame count for the current
  46  * low-latency output device, which is likely inappropriate for a random input
  47  * device. We may want to move the "recommend" functions to the input or output
  48  * classes rather than the config.
  49  */
  50 [macro="PPB_AUDIO_INPUT_DEV_INTERFACE"]
  51 interface PPB_AudioInput_Dev {
  52   /**
  53    * Creates an audio input resource.
  54    *
  55    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  56    * a module.
  57    *
  58    * @return A <code>PP_Resource</code> corresponding to an audio input resource
  59    * if successful, 0 if failed.
  60    */
  61   PP_Resource Create(
  62       [in] PP_Instance instance);
  63
  64   /**
  65    * Determines if the given resource is an audio input resource.
  66    *
  67    * @param[in] resource A <code>PP_Resource</code> containing a resource.
  68    *
  69    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
  70    * resource is an audio input resource, otherwise <code>PP_FALSE</code>.
  71    */
  72   PP_Bool IsAudioInput(
  73       [in] PP_Resource resource);
  74
  75   /**
  76    * Enumerates audio input devices.
  77    *
  78    * Please note that:
  79    * - this method ignores the previous value pointed to by <code>devices</code>
  80    *   (won't release reference even if it is not 0);
  81    * - <code>devices</code> must be valid until <code>callback</code> is called,
  82    *   if the method returns <code>PP_OK_COMPLETIONPENDING</code>;
  83    * - the ref count of the returned <code>devices</code> has already been
  84    *   increased by 1 for the caller.
  85    *
  86    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
  87    * input resource.
  88    * @param[out] devices Once the operation is completed successfully,
  89    * <code>devices</code> will be set to a <code>PPB_ResourceArray_Dev</code>
  90    * resource, which holds a list of <code>PPB_DeviceRef_Dev</code> resources.
  91    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
  92    * completion.
  93    *
  94    * @return An error code from <code>pp_errors.h</code>.
  95    */
  96   [deprecate=0.3]
  97   int32_t EnumerateDevices(
  98       [in] PP_Resource audio_input,
  99       [out] PP_Resource devices,
 100       [in] PP_CompletionCallback callback);
 101
 102   /**
 103    * Enumerates audio input devices.
 104    *
 105    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 106    * input resource.
 107    * @param[in] output An output array which will receive
 108    * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
 109    * ref count of those resources has already been increased by 1 for the
 110    * caller.
 111    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 112    * completion.
 113    *
 114    * @return An error code from <code>pp_errors.h</code>.
 115    */
 116   [version=0.3]
 117   int32_t EnumerateDevices(
 118       [in] PP_Resource audio_input,
 119       [in] PP_ArrayOutput output,
 120       [in] PP_CompletionCallback callback);
 121
 122   /**
 123    * Requests device change notifications.
 124    *
 125    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 126    * input resource.
 127    * @param[in] callback The callback to receive notifications. If not NULL, it
 128    * will be called once for the currently available devices, and then every
 129    * time the list of available devices changes. All calls will happen on the
 130    * same thread as the one on which MonitorDeviceChange() is called. It will
 131    * receive notifications until <code>audio_input</code> is destroyed or
 132    * <code>MonitorDeviceChange()</code> is called to set a new callback for
 133    * <code>audio_input</code>. You can pass NULL to cancel sending
 134    * notifications.
 135    * @param[inout] user_data An opaque pointer that will be passed to
 136    * <code>callback</code>.
 137    *
 138    * @return An error code from <code>pp_errors.h</code>.
 139    */
 140   [version=0.3]
 141   int32_t MonitorDeviceChange(
 142       [in] PP_Resource audio_input,
 143       [in] PP_MonitorDeviceChangeCallback callback,
 144       [inout] mem_t user_data);
 145
 146   /**
 147    * Opens an audio input device. No sound will be captured until
 148    * StartCapture() is called.
 149    *
 150    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 151    * input resource.
 152    * @param[in] device_ref Identifies an audio input device. It could be one of
 153    * the resource in the array returned by EnumerateDevices(), or 0 which means
 154    * the default device.
 155    * @param[in] config A <code>PPB_AudioConfig</code> audio configuration
 156    * resource.
 157    * @param[in] audio_input_callback A <code>PPB_AudioInput_Callback</code>
 158    * function that will be called when data is available.
 159    * @param[inout] user_data An opaque pointer that will be passed into
 160    * <code>audio_input_callback</code>.
 161    * @param[in] callback A <code>PP_CompletionCallback</code> to run when this
 162    * open operation is completed.
 163    *
 164    * @return An error code from <code>pp_errors.h</code>.
 165    */
 166   int32_t Open(
 167       [in] PP_Resource audio_input,
 168       [in] PP_Resource device_ref,
 169       [in] PP_Resource config,
 170       [in] PPB_AudioInput_Callback audio_input_callback,
 171       [inout] mem_t user_data,
 172       [in] PP_CompletionCallback callback);
 173
 174   /**
 175    * Returns an audio config resource for the given audio input resource.
 176    *
 177    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 178    * input resource.
 179    *
 180    * @return A <code>PP_Resource</code> containing the audio config resource if
 181    * successful.
 182    */
 183   PP_Resource GetCurrentConfig(
 184       [in] PP_Resource audio_input);
 185
 186   /**
 187    * Starts the capture of the audio input resource and begins periodically
 188    * calling the callback.
 189    *
 190    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 191    * input resource.
 192    *
 193    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 194    * successful, otherwise <code>PP_FALSE</code>.
 195    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 196    * is already started.
 197    */
 198   PP_Bool StartCapture(
 199       [in] PP_Resource audio_input);
 200
 201   /**
 202    * Stops the capture of the audio input resource.
 203    *
 204    * @param[in] audio_input A PP_Resource containing the audio input resource.
 205    *
 206    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 207    * successful, otherwise <code>PP_FALSE</code>.
 208    * Also returns <code>PP_TRUE</code> (and is a no-op) if called while capture
 209    * is already stopped. If a buffer is being captured, StopCapture will block
 210    * until the call completes.
 211    */
 212   PP_Bool StopCapture(
 213       [in] PP_Resource audio_input);
 214
 215   /**
 216    * Closes the audio input device, and stops capturing if necessary. It is
 217    * not valid to call Open() again after a call to this method.
 218    * If an audio input resource is destroyed while a device is still open, then
 219    * it will be implicitly closed, so you are not required to call this method.
 220    *
 221    * @param[in] audio_input A <code>PP_Resource</code> corresponding to an audio
 222    * input resource.
 223    */
 224   void Close(
 225       [in] PP_Resource audio_input);
 226 };