ppapi/cpp/media_stream_audio_track.h

   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
  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_