Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 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 | |
| 19 | namespace pp { |
| 20 | |
| 21 | class AudioBuffer; |
| 22 | class CompletionCallback; |
| 23 | template <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. |
| 27 | class 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 |
Torne (Richard Coles) | 46d4c2b | 2014-06-09 12:00:27 +0100 | [diff] [blame] | 59 | /// settings will be used. Calls to Configure while the plugin holds |
| 60 | /// buffers will fail. |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 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_ |