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.
5 #ifndef PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_
6 #define PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_
10 #include "ppapi/c/ppb_media_stream_audio_track.h"
11 #include "ppapi/cpp/resource.h"
12 #include "ppapi/cpp/var.h"
15 /// This file defines the <code>MediaStreamAudioTrack</code> interface for an
16 /// audio source resource, which receives audio frames from a MediaStream audio
17 /// track in the browser.
22 class CompletionCallback;
23 template <typename T> class CompletionCallbackWithOutput;
25 /// The <code>MediaStreamAudioTrack</code> class contains methods for
26 /// receiving audio frames from a MediaStream audio track in the browser.
27 class MediaStreamAudioTrack : public Resource {
29 /// Default constructor for creating an is_null()
30 /// <code>MediaStreamAudioTrack</code> object.
31 MediaStreamAudioTrack();
33 /// The copy constructor for <code>MediaStreamAudioTrack</code>.
35 /// @param[in] other A reference to a <code>MediaStreamAudioTrack</code>.
36 MediaStreamAudioTrack(const MediaStreamAudioTrack& other);
38 /// Constructs a <code>MediaStreamAudioTrack</code> from
39 /// a <code>Resource</code>.
41 /// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource.
42 explicit MediaStreamAudioTrack(const Resource& resource);
44 /// A constructor used when you have received a <code>PP_Resource</code> as a
45 /// return value that has had 1 ref added for you.
47 /// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource.
48 MediaStreamAudioTrack(PassRef, PP_Resource resource);
50 ~MediaStreamAudioTrack();
52 /// Configures underlying frame buffers for incoming frames.
53 /// If the application doesn't want to drop frames, then the
54 /// <code>PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERED_FRAMES</code> should be
55 /// chosen such that inter-frame processing time variability won't overrun the
56 /// input buffer. If the buffer is overfilled, then frames will be dropped.
57 /// The application can detect this by examining the timestamp on returned
58 /// frames. If <code>Configure()</code> is not called, default settings will
60 /// Example usage from plugin code:
62 /// int32_t attribs[] = {
63 /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERED_FRAMES, 4,
64 /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_DURATION, 10,
65 /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE};
66 /// track.Configure(attribs, callback);
69 /// @param[in] attrib_list A list of attribute name-value pairs in which each
70 /// attribute is immediately followed by the corresponding desired value.
71 /// The list is terminated by
72 /// <code>PP_MEDIASTREAMAUDIOTRACK_AUDIO_NONE</code>.
73 /// @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
74 /// completion of <code>Configure()</code>.
76 /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
77 int32_t Configure(const int32_t attributes[],
78 const CompletionCallback& callback);
80 /// Gets attribute value for a given attribute name.
82 /// @param[in] attrib A <code>PP_MediaStreamAudioTrack_Attrib</code> for
84 /// @param[out] value A int32_t for storing the attribute value.
86 /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
87 int32_t GetAttrib(PP_MediaStreamAudioTrack_Attrib attrib,
90 /// Returns the track ID of the underlying MediaStream audio track.
91 std::string GetId() const;
93 /// Checks whether the underlying MediaStream track has ended.
94 /// Calls to GetFrame while the track has ended are safe to make and will
95 /// complete, but will fail.
96 bool HasEnded() const;
98 /// Gets the next audio frame from the MediaStream track.
99 /// If internal processing is slower than the incoming frame rate, new frames
100 /// will be dropped from the incoming stream. Once the input buffer is full,
101 /// frames will be dropped until <code>RecycleFrame()</code> is called to free
102 /// a spot for another frame to be buffered.
103 /// If there are no frames in the input buffer,
104 /// <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
105 /// <code>callback</code> will be called when a new frame is received or some
108 /// @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
109 /// completion of <code>GetFrame()</code>. If success, an AudioFrame will be
110 /// passed into the completion callback function.
112 /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
113 /// Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames
114 /// buffer was not allocated successfully.
116 const CompletionCallbackWithOutput<AudioFrame>& callback);
118 /// Recycles a frame returned by <code>GetFrame()</code>, so the track can
119 /// reuse the underlying buffer of this frame. And the frame will become
120 /// invalid. The caller should release all references it holds to
121 /// <code>frame</code> and not use it anymore.
123 /// @param[in] frame A AudioFrame returned by <code>GetFrame()</code>.
125 /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
126 int32_t RecycleFrame(const AudioFrame& frame);
128 /// Closes the MediaStream audio track, and disconnects it from the audio
130 /// After calling <code>Close()</code>, no new frames will be received.
133 /// Checks whether a <code>Resource</code> is a MediaStream audio track,
134 /// to test whether it is appropriate for use with the
135 /// <code>MediaStreamAudioTrack</code> constructor.
137 /// @param[in] resource A <code>Resource</code> to test.
139 /// @return True if <code>resource</code> is a MediaStream audio track.
140 static bool IsMediaStreamAudioTrack(const Resource& resource);
145 #endif // PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_