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 }; 227
