MediaStream audio sourcing: Bypass audio processing for non-WebRTC cases.

content/renderer/media/media_stream_audio_source.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_SOURCE_H_
 #define CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_SOURCE_H_
 
+#include <string>
+#include <vector>
+
 #include "base/compiler_specific.h"
 #include "base/macros.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/weak_ptr.h"
+#include "base/synchronization/lock.h"
+#include "base/threading/thread_checker.h"
 #include "content/common/content_export.h"
 #include "content/renderer/media/media_stream_source.h"
-#include "content/renderer/media/webrtc/peer_connection_dependency_factory.h"
-#include "content/renderer/media/webrtc_audio_capturer.h"
-#include "third_party/webrtc/api/mediastreaminterface.h"
+#include "media/audio/audio_parameters.h"
+#include "third_party/WebKit/public/platform/WebMediaStreamSource.h"
+#include "third_party/WebKit/public/platform/WebMediaStreamTrack.h"
 
 namespace content {
 
+class MediaStreamAudioTrack;
+
+// Represents a source of audio, and manages the delivery of audio data between
+// the source implementation and one or more MediaStreamAudioTracks.  This is
+// a base class providing all the necessary functionality to connect tracks and
+// have audio data delivered to them.  Subclasses provide the actual audio
+// source implementation (e.g., media::AudioCapturerSource), and should
+// implement the DoStopSource() and EnsureSourceIsStarted() methods, and call
+// DeliverDataToTracks().
+//
+// This base class can be instantiated, to be used as a place-holder or a "null"
+// source of audio.  This can be useful for unit testing, wherever a mock is
+// needed, and/or calls to DeliverDataToTracks() must be made at very specific
+// times.
+//
+// An instance of this class is owned by blink::WebMediaStreamSource.
+//
+// Usage example:
+//
+//   class MyAudioSource : public MediaStreamSource { ... };
+//
+//   blink::WebMediaStreamSource blink_source = ...;
+//   blink::WebMediaStreamTrack blink_track = ...;
+//   blink_source.setExtraData(new MyAudioSource());  // Takes ownership.
+//   if (MediaStreamAudioSource::Get(blink_source)->ConnectToTrack(blink_track))
+//     LOG(INFO) << "Success!";
+//   else
+//     LOG(ERROR) << "Failed!";
 class CONTENT_EXPORT MediaStreamAudioSource
     : NON_EXPORTED_BASE(public MediaStreamSource) {
  public:
-  MediaStreamAudioSource(int render_frame_id,
-                         const StreamDeviceInfo& device_info,
-                         const SourceStoppedCallback& stop_callback,
-                         PeerConnectionDependencyFactory* factory);
-  MediaStreamAudioSource();
+  explicit MediaStreamAudioSource(bool is_local_source);
+
   ~MediaStreamAudioSource() override;
 
-  void AddTrack(const blink::WebMediaStreamTrack& track,
-                const blink::WebMediaConstraints& constraints,
-                const ConstraintsCallback& callback);
+  // Accessor to the MediaStreamAudioSource instance owned (as extraData) by the
+  // given WebMediaStreamTrack.
+  static MediaStreamAudioSource* Get(const blink::WebMediaStreamSource& source);
 
-  void SetLocalAudioSource(webrtc::AudioSourceInterface* source) {
-    local_audio_source_ = source;
-  }
+  // Returns true if the source of audio is local to the application (e.g.,
+  // microphone input or loopback audio capture) as opposed to audio being
+  // streamed-in from outside the application.
+  bool is_local_source() const { return is_local_source_; }
 
-  void SetAudioCapturer(const scoped_refptr<WebRtcAudioCapturer>& capturer) {
-    DCHECK(!audio_capturer_.get());
-    audio_capturer_ = capturer;
-  }
+  // Connects this source to the given |track|, creating the appropriate
+  // implementation of the content::MediaStreamAudioTrack interface, which
+  // becomes associated with and owned by |track|.
+  //
+  // Returns true if the source was successfully started and the
+  // MediaStreamAudioTrack assigned to |track.extraData()|.
+  bool ConnectToTrack(const blink::WebMediaStreamTrack& track);
 
-  const scoped_refptr<WebRtcAudioCapturer>& GetAudioCapturer() {
-    return audio_capturer_;
-  }
+  // Returns the current format of the audio passing through this source to the
+  // sinks.  This can return invalid parameters if the source has not yet been
+  // started.  This method is thread-safe.
+  media::AudioParameters GetAudioParameters() const;
 
-  webrtc::AudioSourceInterface* local_audio_source() {
-    return local_audio_source_.get();
-  }
+  // Returns a unique class identifier.  Some subclasses override and use this
+  // method to provide safe down-casting to their type.
+  virtual void* GetClassIdentifier() const;
+
+  // Called by unit tests to start the source (without connecting to a track
+  // yet).
+  void StartSourceForTesting(); ////////// CAN REMOVE THIS AND JUST FRIEND FOR
+                                ////////// CALLING EnsureSourceIsStarted()?? /////////////
 
  protected:
+  // Returns a new MediaStreamAudioTrack.  |id| is the blink track's ID in
+  // UTF-8.  Subclasses may override this to provide an extended implementation.
+  virtual scoped_ptr<MediaStreamAudioTrack> CreateMediaStreamAudioTrack(
+      const std::string& id);
+
+  // Default "no-op" MediaStreamAudioSource implementation that just sets
+  // |is_stopped_| to true.  Subclasses should override this method.
   void DoStopSource() override;
 
+  // Returns true if the source has already been started and has not yet been
+  // stopped.  Otherwise, attempts to start the source and returns true if
+  // successful.  Subclasses should override this method.
+  virtual bool EnsureSourceIsStarted();
+
+  // Called by subclasses to update the format of the audio passing through this
+  // source to the sinks.  This method is thread-safe.
+  void SetFormat(const media::AudioParameters& params);
+
+  // Called by subclasses to deliver audio data to the currently-connected
+  // tracks.  This method is thread-safe.
+  void DeliverDataToTracks(const media::AudioBus& audio_bus,
+                           base::TimeTicks reference_time);
+
+  // Set to false by DoStopSource() once the source has been permanently
+  // stopped and no further calls to DeliverDataToTracks() will be made.
+  bool is_stopped_;
+
+  // In debug builds, check that all methods that could cause object graph
+  // or data flow changes are being called on the same thread.
+  base::ThreadChecker thread_checker_;
+
  private:
-  const int render_frame_id_;
-  PeerConnectionDependencyFactory* const factory_;
+  // Instantiates the appropriate MediaStreamAudioTrack implementation and sets
+  // it as |track|'s extraData.  This is called by ConnectToTrack() after all
+  // preconditions have been met: 1) A prior call to EnsureSourceIsStarted()
+  // returned true; 2) |track| does not already hold a MediaStreamAudioTrack
+  // instance.
+  void ConnectStartedSourceToTrack(const blink::WebMediaStreamTrack& track);
 
-  // This member holds an instance of webrtc::LocalAudioSource. This is used
-  // as a container for audio options.
-  scoped_refptr<webrtc::AudioSourceInterface> local_audio_source_;
+  // Removes |track| from the list of instances that get a copy of the source
+  // audio data.
+  void StopAudioDeliveryTo(MediaStreamAudioTrack* track);
 
-  scoped_refptr<WebRtcAudioCapturer> audio_capturer_;
+  // True if the source of audio is a local device.  False if the source is
+  // remote (e.g., streamed-in from a server).
+  const bool is_local_source_;
+
+  // Protects concurrent access to |params_| and |tracks_|.
+  mutable base::Lock lock_;
+
+  // Specifies the current format of the audio passing through the pipeline.
+  media::AudioParameters params_;
+
+  // List of currently-connected MediaStreamAudioTracks.  While
+  // MediaStreamAudioSource creates these instances, blink::WebMediaStreamTrack
+  // instances own the objects.
+  std::vector<MediaStreamAudioTrack*> tracks_;
+
+  // Provides weak pointers so that MediaStreamAudioTracks can call
+  // StopAudioDeliveryTo() safely.
+  base::WeakPtrFactory<MediaStreamAudioSource> weak_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(MediaStreamAudioSource);
 };
 
 }  // namespace content
 
 #endif  // CONTENT_RENDERER_MEDIA_MEDIA_STREAM_AUDIO_SOURCE_H_