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