1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_
#define PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_
#include <string>
#include "ppapi/c/ppb_media_stream_audio_track.h"
#include "ppapi/cpp/resource.h"
#include "ppapi/cpp/var.h"
/// @file
/// This file defines the <code>MediaStreamAudioTrack</code> interface for an
/// audio source resource, which receives audio buffers from a MediaStream audio
/// track in the browser.
namespace pp {
class AudioBuffer;
class CompletionCallback;
template <typename T> class CompletionCallbackWithOutput;
/// The <code>MediaStreamAudioTrack</code> class contains methods for
/// receiving audio buffers from a MediaStream audio track in the browser.
class MediaStreamAudioTrack : public Resource {
public:
/// Default constructor for creating an is_null()
/// <code>MediaStreamAudioTrack</code> object.
MediaStreamAudioTrack();
/// The copy constructor for <code>MediaStreamAudioTrack</code>.
///
/// @param[in] other A reference to a <code>MediaStreamAudioTrack</code>.
MediaStreamAudioTrack(const MediaStreamAudioTrack& other);
/// Constructs a <code>MediaStreamAudioTrack</code> from
/// a <code>Resource</code>.
///
/// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource.
explicit MediaStreamAudioTrack(const Resource& resource);
/// A constructor used when you have received a <code>PP_Resource</code> as a
/// return value that has had 1 ref added for you.
///
/// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource.
MediaStreamAudioTrack(PassRef, PP_Resource resource);
~MediaStreamAudioTrack();
/// Configures underlying buffer buffers for incoming audio samples.
/// If the application doesn't want to drop samples, then the
/// <code>PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS</code> should be
/// chosen such that inter-buffer processing time variability won't overrun
/// all input buffers. If all buffers are filled, then samples will be
/// dropped. The application can detect this by examining the timestamp on
/// returned buffers. If <code>Configure()</code> is not called, default
/// settings will be used. Calls to Configure while the plugin holds
/// buffers will fail.
/// Example usage from plugin code:
/// @code
/// int32_t attribs[] = {
/// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS, 4,
/// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_DURATION, 10,
/// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE};
/// track.Configure(attribs, callback);
/// @endcode
///
/// @param[in] attrib_list A list of attribute name-value pairs in which each
/// attribute is immediately followed by the corresponding desired value.
/// The list is terminated by
/// <code>PP_MEDIASTREAMAUDIOTRACK_AUDIO_NONE</code>.
/// @param[in] callback A <code>CompletionCallback</code> to be called upon
/// completion of <code>Configure()</code>.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t Configure(const int32_t attributes[],
const CompletionCallback& callback);
/// Gets attribute value for a given attribute name.
///
/// @param[in] attrib A <code>PP_MediaStreamAudioTrack_Attrib</code> for
/// querying.
/// @param[out] value A int32_t for storing the attribute value.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t GetAttrib(PP_MediaStreamAudioTrack_Attrib attrib,
int32_t* value);
/// Returns the track ID of the underlying MediaStream audio track.
std::string GetId() const;
/// Checks whether the underlying MediaStream track has ended.
/// Calls to GetBuffer while the track has ended are safe to make and will
/// complete, but will fail.
bool HasEnded() const;
/// Gets the next audio buffer from the MediaStream track.
/// If internal processing is slower than the incoming buffer rate,
/// new buffers will be dropped from the incoming stream. Once all buffers
/// are full, audio samples will be dropped until <code>RecycleBuffer()</code>
/// is called to free a spot for another buffer.
/// If there are no audio data in the input buffer,
/// <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
/// <code>callback</code> will be called when a new buffer of audio samples
/// is received or some error happens.
///
/// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
/// called upon completion of <code>GetBuffer()</code>. If success,
/// an AudioBuffer will be passed into the completion callback function.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t GetBuffer(
const CompletionCallbackWithOutput<AudioBuffer>& callback);
/// Recycles a buffer returned by <code>GetBuffer()</code>, so the track can
/// reuse the buffer. And the buffer will become invalid. The caller should
/// release all references it holds to <code>buffer</code> and not use it
/// anymore.
///
/// @param[in] buffer A AudioBuffer returned by <code>GetBuffer()</code>.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t RecycleBuffer(const AudioBuffer& buffer);
/// Closes the MediaStream audio track, and disconnects it from the audio
/// source.
/// After calling <code>Close()</code>, no new buffers will be received.
void Close();
/// Checks whether a <code>Resource</code> is a MediaStream audio track,
/// to test whether it is appropriate for use with the
/// <code>MediaStreamAudioTrack</code> constructor.
///
/// @param[in] resource A <code>Resource</code> to test.
///
/// @return True if <code>resource</code> is a MediaStream audio track.
static bool IsMediaStreamAudioTrack(const Resource& resource);
};
} // namespace pp
#endif // PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_
|
