Pepper_47_C_interfaces
ppb_media_stream_audio_track.h
Go to the documentation of this file.
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 Thu Oct 20 13:57:04 2016. */
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"
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  */
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  */
51  /**
52  * The sample rate of audio data in buffers. The attribute value is a
53  * <code>PP_AudioBuffer_SampleRate</code>.
54  */
56  /**
57  * The sample size of audio data in buffers in bytes. The attribute value is a
58  * <code>PP_AudioBuffer_SampleSize</code>.
59  */
61  /**
62  * The number of channels in audio buffers.
63  *
64  * Supported values: 1, 2
65  */
67  /**
68  * The duration of an audio buffer in milliseconds.
69  *
70  * Valid range: 10 to 10000
71  */
74 /**
75  * @}
76  */
77 
78 /**
79  * @addtogroup Interfaces
80  * @{
81  */
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  */
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,
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 
210 /**
211  * @}
212  */
213 
214 #endif /* PPAPI_C_PPB_MEDIA_STREAM_AUDIO_TRACK_H_ */
215 
int32_t(* Configure)(PP_Resource audio_track, const int32_t attrib_list[], struct PP_CompletionCallback callback)
int32_t(* GetAttrib)(PP_Resource audio_track, PP_MediaStreamAudioTrack_Attrib attrib, int32_t *value)
PP_Bool(* IsMediaStreamAudioTrack)(PP_Resource resource)
int32_t PP_Resource
Definition: pp_resource.h:40
PP_Bool(* HasEnded)(PP_Resource audio_track)
PP_MediaStreamAudioTrack_Attrib
void(* Close)(PP_Resource audio_track)
Definition: pp_var.h:166
int32_t(* GetBuffer)(PP_Resource audio_track, PP_Resource *buffer, struct PP_CompletionCallback callback)
int32_t(* RecycleBuffer)(PP_Resource audio_track, PP_Resource buffer)
PP_Bool
Definition: pp_bool.h:30
struct PP_Var(* GetId)(PP_Resource audio_track)