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