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