1 /* Copyright 2014 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 /* From ppb_media_stream_audio_track.idl modified Wed May 28 09:36:15 2014. */ 7 8 #ifndef PPAPI_C_PPB_MEDIA_STREAM_AUDIO_TRACK_H_ 9 #define PPAPI_C_PPB_MEDIA_STREAM_AUDIO_TRACK_H_ 10 11 #include "ppapi/c/pp_bool.h" 12 #include "ppapi/c/pp_completion_callback.h" 13 #include "ppapi/c/pp_macros.h" 14 #include "ppapi/c/pp_resource.h" 15 #include "ppapi/c/pp_stdint.h" 16 #include "ppapi/c/pp_var.h" 17 18 #define PPB_MEDIASTREAMAUDIOTRACK_INTERFACE_0_1 "PPB_MediaStreamAudioTrack;0.1" 19 #define PPB_MEDIASTREAMAUDIOTRACK_INTERFACE \ 20 PPB_MEDIASTREAMAUDIOTRACK_INTERFACE_0_1 21 22 /** 23 * @file 24 * Defines the <code>PPB_MediaStreamAudioTrack</code> interface. Used for 25 * receiving audio samples from a MediaStream audio track in the browser. 26 */ 27 28 29 /** 30 * @addtogroup Enums 31 * @{ 32 */ 33 /** 34 * This enumeration contains audio track attributes which are used by 35 * <code>Configure()</code>. 36 */ 37 typedef enum { 38 /** 39 * Attribute list terminator. 40 */ 41 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE = 0, 42 /** 43 * The maximum number of buffers to hold audio samples. 44 * Note: this is only used as advisory; the browser may allocate more or fewer 45 * based on available resources. How many buffers depends on usage - 46 * request at least 2 to make sure latency doesn't cause lost samples. If 47 * the plugin expects to hold on to more than one buffer at a time (e.g. to do 48 * multi-buffer processing), it should request that many more. 49 */ 50 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS = 1, 51 /** 52 * The sample rate of audio data in buffers. The attribute value is a 53 * <code>PP_AudioBuffer_SampleRate</code>. 54 */ 55 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_SAMPLE_RATE = 2, 56 /** 57 * The sample size of audio data in buffers in bytes. The attribute value is a 58 * <code>PP_AudioBuffer_SampleSize</code>. 59 */ 60 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_SAMPLE_SIZE = 3, 61 /** 62 * The number of channels in audio buffers. 63 * 64 * Supported values: 1, 2 65 */ 66 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_CHANNELS = 4, 67 /** 68 * The duration of an audio buffer in milliseconds. 69 * 70 * Valid range: 10 to 10000 71 */ 72 PP_MEDIASTREAMAUDIOTRACK_ATTRIB_DURATION = 5 73 } PP_MediaStreamAudioTrack_Attrib; 74 /** 75 * @} 76 */ 77 78 /** 79 * @addtogroup Interfaces 80 * @{ 81 */ 82 struct PPB_MediaStreamAudioTrack_0_1 { 83 /** 84 * Determines if a resource is a MediaStream audio track resource. 85 * 86 * @param[in] resource The <code>PP_Resource</code> to test. 87 * 88 * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given 89 * resource is a Mediastream audio track resource or <code>PP_FALSE</code> 90 * otherwise. 91 */ 92 PP_Bool (*IsMediaStreamAudioTrack)(PP_Resource resource); 93 /** 94 * Configures underlying buffers for incoming audio samples. 95 * If the application doesn't want to drop samples, then the 96 * <code>PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS</code> should be 97 * chosen such that inter-buffer processing time variability won't overrun all 98 * the input buffers. If all buffers are filled, then samples will be 99 * dropped. The application can detect this by examining the timestamp on 100 * returned buffers. If <code>Configure()</code> is not called, default 101 * settings will be used. Calls to Configure while the plugin holds 102 * buffers will fail. 103 * Example usage from plugin code: 104 * @code 105 * int32_t attribs[] = { 106 * PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS, 4, 107 * PP_MEDIASTREAMAUDIOTRACK_ATTRIB_DURATION, 10, 108 * PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE}; 109 * track_if->Configure(track, attribs, callback); 110 * @endcode 111 * 112 * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio 113 * resource. 114 * @param[in] attrib_list A list of attribute name-value pairs in which each 115 * attribute is immediately followed by the corresponding desired value. 116 * The list is terminated by 117 * <code>PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE</code>. 118 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 119 * completion of <code>Configure()</code>. 120 * 121 * @return An int32_t containing a result code from <code>pp_errors.h</code>. 122 */ 123 int32_t (*Configure)(PP_Resource audio_track, 124 const int32_t attrib_list[], 125 struct PP_CompletionCallback callback); 126 /** 127 * Gets attribute value for a given attribute name. 128 * 129 * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio 130 * resource. 131 * @param[in] attrib A <code>PP_MediaStreamAudioTrack_Attrib</code> for 132 * querying. 133 * @param[out] value A int32_t for storing the attribute value on success. 134 * Otherwise, the value will not be changed. 135 * 136 * @return An int32_t containing a result code from <code>pp_errors.h</code>. 137 */ 138 int32_t (*GetAttrib)(PP_Resource audio_track, 139 PP_MediaStreamAudioTrack_Attrib attrib, 140 int32_t* value); 141 /** 142 * Returns the track ID of the underlying MediaStream audio track. 143 * 144 * @param[in] audio_track The <code>PP_Resource</code> to check. 145 * 146 * @return A <code>PP_Var</code> containing the MediaStream track ID as 147 * a string. 148 */ 149 struct PP_Var (*GetId)(PP_Resource audio_track); 150 /** 151 * Checks whether the underlying MediaStream track has ended. 152 * Calls to GetBuffer while the track has ended are safe to make and will 153 * complete, but will fail. 154 * 155 * @param[in] audio_track The <code>PP_Resource</code> to check. 156 * 157 * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given 158 * MediaStream track has ended or <code>PP_FALSE</code> otherwise. 159 */ 160 PP_Bool (*HasEnded)(PP_Resource audio_track); 161 /** 162 * Gets the next audio buffer from the MediaStream track. 163 * If internal processing is slower than the incoming buffer rate, new buffers 164 * will be dropped from the incoming stream. Once all buffers are full, 165 * audio samples will be dropped until <code>RecycleBuffer()</code> is called 166 * to free a slot for another buffer. 167 * If there are no audio data in the input buffer, 168 * <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the 169 * <code>callback</code> will be called, when a new buffer of audio samples 170 * is received or an error happens. 171 * 172 * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio 173 * resource. 174 * @param[out] buffer A <code>PP_Resource</code> corresponding to 175 * an AudioBuffer resource. 176 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 177 * completion of GetBuffer(). 178 * 179 * @return An int32_t containing a result code from <code>pp_errors.h</code>. 180 */ 181 int32_t (*GetBuffer)(PP_Resource audio_track, 182 PP_Resource* buffer, 183 struct PP_CompletionCallback callback); 184 /** 185 * Recycles a buffer returned by <code>GetBuffer()</code>, so the track can 186 * reuse the buffer. And the buffer will become invalid. The caller should 187 * release all references it holds to <code>buffer</code> and not use it 188 * anymore. 189 * 190 * @param[in] audio_track A <code>PP_Resource</code> corresponding to an audio 191 * resource. 192 * @param[in] buffer A <code>PP_Resource</code> corresponding to 193 * an AudioBuffer resource returned by <code>GetBuffer()</code>. 194 * 195 * @return An int32_t containing a result code from <code>pp_errors.h</code>. 196 */ 197 int32_t (*RecycleBuffer)(PP_Resource audio_track, PP_Resource buffer); 198 /** 199 * Closes the MediaStream audio track and disconnects it from the audio 200 * source. After calling <code>Close()</code>, no new buffers will be 201 * received. 202 * 203 * @param[in] audio_track A <code>PP_Resource</code> corresponding to a 204 * MediaStream audio track resource. 205 */ 206 void (*Close)(PP_Resource audio_track); 207 }; 208 209 typedef struct PPB_MediaStreamAudioTrack_0_1 PPB_MediaStreamAudioTrack; 210 /** 211 * @} 212 */ 213 214 #endif /* PPAPI_C_PPB_MEDIA_STREAM_AUDIO_TRACK_H_ */ 215 216