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