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
|
// 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/pp_stdint.h"
#include "ppapi/cpp/resource.h"
/// @file
/// This file defines the <code>MediaStreamAudioTrack</code> interface for an
/// audio source resource, which receives audio frames from a MediaStream audio
/// track in the browser.
namespace pp {
class AudioFrame;
template <typename T> class CompletionCallbackWithOutput;
/// The <code>MediaStreamAudioTrack</code> class contains methods for
/// receiving audio frames 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 frame buffers for incoming frames.
/// If the application doesn't want to drop frames, then the
/// <code>max_buffered_frames</code> should be chosen such that inter-frame
/// processing time variability won't overrun the input buffer. If the buffer
/// is overfilled, then frames will be dropped. The application can detect
/// this by examining the timestamp on returned frames.
/// If <code>Configure()</code> is not used, default settings will be used.
///
/// @param[in] samples_per_frame The number of audio samples in an audio
/// frame.
/// @param[in] max_buffered_frames The maximum number of audio frames to
/// hold in the input buffer.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t Configure(uint32_t samples_per_frame,
uint32_t max_buffered_frames);
/// Returns the track ID of the underlying MediaStream audio track.
std::string GetId() const;
/// Checks whether the underlying MediaStream track has ended.
/// Calls to GetFrame while the track has ended are safe to make and will
/// complete, but will fail.
bool HasEnded() const;
/// Gets the next audio frame from the MediaStream track.
/// If internal processing is slower than the incoming frame rate, new frames
/// will be dropped from the incoming stream. Once the input buffer is full,
/// frames will be dropped until <code>RecycleFrame()</code> is called to free
/// a spot for another frame to be buffered.
/// If there are no frames in the input buffer,
/// <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
/// <code>callback</code> will be called when a new frame is received or some
/// error happens.
///
/// @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
/// completion of <code>GetFrame()</code>. If success, an AudioFrame will be
/// passed into the completion callback function.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
/// Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames
/// buffer was not allocated successfully.
int32_t GetFrame(
const CompletionCallbackWithOutput<AudioFrame>& callback);
/// Recycles a frame returned by <code>GetFrame()</code>, so the track can
/// reuse the underlying buffer of this frame. And the frame will become
/// invalid. The caller should release all references it holds to
/// <code>frame</code> and not use it anymore.
///
/// @param[in] frame A AudioFrame returned by <code>GetFrame()</code>.
///
/// @return An int32_t containing a result code from <code>pp_errors.h</code>.
int32_t RecycleFrame(const AudioFrame& frame);
/// Closes the MediaStream audio track, and disconnects it from the audio
/// source.
/// After calling <code>Close()</code>, no new frames 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_
|
