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