Create abstract interface for media::Pipeline.

media/base/pipeline.h

 // Copyright (c) 2012 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 MEDIA_BASE_PIPELINE_H_
 #define MEDIA_BASE_PIPELINE_H_
 
 #include "base/gtest_prod_util.h"
 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
@@ skipping 33 matching lines @@
 
   bool has_audio;
   bool has_video;
   gfx::Size natural_size;
   VideoRotation video_rotation;
   base::Time timeline_offset;
 };
 
 typedef base::Callback<void(PipelineMetadata)> PipelineMetadataCB;
 
-// Pipeline runs the media pipeline.  Filters are created and called on the
-// task runner injected into this object. Pipeline works like a state
-// machine to perform asynchronous initialization, pausing, seeking and playing.
-//
-// Here's a state diagram that describes the lifetime of this object.
-//
-//   [ *Created ]                       [ Any State ]
-//         | Start()                         | Stop() / SetError()
-//         V                                 V
-//   [ InitXXX (for each filter) ]      [ Stopping ]
-//         |                                 |
-//         V                                 V
-//   [ Playing ] <---------.            [ Stopped ]
-//     |     | Seek()      |
-//     |     V             |
-//     |   [ Seeking ] ----'
-//     |                   ^
-//     | Suspend()         |
-//     V                   |
-//   [ Suspending ]        |
-//     |                   |
-//     V                   |
-//   [ Suspended ]         |
-//     | Resume()          |
-//     V                   |
-//   [ Resuming ] ---------'
-//
-// Initialization is a series of state transitions from "Created" through each
-// filter initialization state.  When all filter initialization states have
-// completed, we simulate a Seek() to the beginning of the media to give filters
-// a chance to preroll. From then on the normal Seek() transitions are carried
-// out and we start playing the media.
-//
-// If any error ever happens, this object will transition to the "Error" state
-// from any state. If Stop() is ever called, this object will transition to
-// "Stopped" state.
-//
-// TODO(sandersd): It should be possible to pass through Suspended when going
-// from InitDemuxer to InitRenderer, thereby eliminating the Resuming state.
-// Some annoying differences between the two paths need to be removed first.
-class MEDIA_EXPORT Pipeline : public DemuxerHost {
+class MEDIA_EXPORT Pipeline {
  public:
   // Used to paint VideoFrame.
   typedef base::Callback<void(const scoped_refptr<VideoFrame>&)> PaintCB;
 
-  // Constructs a media pipeline that will execute on |task_runner|.
-  Pipeline(const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
-           MediaLog* media_log);
-  ~Pipeline() override;
-
   // Build a pipeline to using the given |demuxer| and |renderer| to construct
   // a filter chain, executing |seek_cb| when the initial seek has completed.

[xhwang, 2016/02/19 17:06:07]

Can we change the |seek_cb| to something like a |start_cb|? So the |start_cb|
will be fired after the pipeline is fully started (including initial seek
completed).

Hmm, I saw Resume() is using the |seek_cb| as well. So maybe this is okay.

   //
   // The following permanent callbacks will be executed as follows up until
   // Stop() has completed:
   //   |ended_cb| will be executed whenever the media reaches the end.
   //   |error_cb| will be executed whenever an error occurs but hasn't been
   //              reported already through another callback.
   //   |metadata_cb| will be executed when the content duration, container video
   //                 size, start time, and whether the content has audio and/or
   //                 video in supported formats are known.
   //   |buffering_state_cb| will be executed whenever there are changes in the
   //                        overall buffering state of the pipeline.
   //   |duration_change_cb| optional callback that will be executed whenever the
   //                        presentation duration changes.
   //   |add_text_track_cb| will be executed whenever a text track is added.
   //   |waiting_for_decryption_key_cb| will be executed whenever the key needed
   //                                   to decrypt the stream is not available.
   // It is an error to call this method after the pipeline has already started.
-  void Start(Demuxer* demuxer,
-             scoped_ptr<Renderer> renderer,
-             const base::Closure& ended_cb,
-             const PipelineStatusCB& error_cb,
-             const PipelineStatusCB& seek_cb,
-             const PipelineMetadataCB& metadata_cb,
-             const BufferingStateCB& buffering_state_cb,
-             const base::Closure& duration_change_cb,
-             const AddTextTrackCB& add_text_track_cb,
-             const base::Closure& waiting_for_decryption_key_cb);
+  virtual void Start(Demuxer* demuxer,
+                     scoped_ptr<Renderer> renderer,
+                     const base::Closure& ended_cb,
+                     const PipelineStatusCB& error_cb,
+                     const PipelineStatusCB& seek_cb,

[xhwang, 2016/02/19 17:06:07]

This callback is a special one time callback. Maybe move it up to be the first
callback (after |renderer|)?

+                     const PipelineMetadataCB& metadata_cb,
+                     const BufferingStateCB& buffering_state_cb,
+                     const base::Closure& duration_change_cb,
+                     const AddTextTrackCB& add_text_track_cb,
+                     const base::Closure& waiting_for_decryption_key_cb) = 0;
 
   // Asynchronously stops the pipeline, executing |stop_cb| when the pipeline
   // teardown has completed.
   //
   // Stop() must complete before destroying the pipeline. It it permissible to
   // call Stop() at any point during the lifetime of the pipeline.
   //
   // It is safe to delete the pipeline during the execution of |stop_cb|.
-  void Stop(const base::Closure& stop_cb);
+  virtual void Stop(const base::Closure& stop_cb) = 0;
 
   // Attempt to seek to the position specified by time.  |seek_cb| will be
   // executed when the all filters in the pipeline have processed the seek.
   //
   // Clients are expected to call GetMediaTime() to check whether the seek
   // succeeded.
   //
   // It is an error to call this method if the pipeline has not started or
   // is suspended.

[xhwang, 2016/02/19 17:06:07]

What if Suspend() has been called but |suspend_cb| isn't fired yet. Can we call
Seek() at that time?

Can we call Seek() while we are seeking? We should make this clear as well.

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

Done.

-  void Seek(base::TimeDelta time, const PipelineStatusCB& seek_cb);
-
-  // Returns true if the pipeline has been started via Start().  If IsRunning()
-  // returns true, it is expected that Stop() will be called before destroying
-  // the pipeline.
-  bool IsRunning() const;
-
-  // Gets the current playback rate of the pipeline.  When the pipeline is
-  // started, the playback rate will be 0.0.  A rate of 1.0 indicates
-  // that the pipeline is rendering the media at the standard rate.  Valid
-  // values for playback rate are >= 0.0.
-  double GetPlaybackRate() const;
-
-  // Attempt to adjust the playback rate. Setting a playback rate of 0.0 pauses
-  // all rendering of the media.  A rate of 1.0 indicates a normal playback
-  // rate.  Values for the playback rate must be greater than or equal to 0.0.
-  //
-  // TODO(scherkus): What about maximum rate?  Does HTML5 specify a max?
-  void SetPlaybackRate(double playback_rate);
+  virtual void Seek(base::TimeDelta time, const PipelineStatusCB& seek_cb) = 0;
 
   // Suspend the pipeline, discarding the current renderer.

[xhwang, 2016/02/19 17:06:07]

Suspend_s_, same everywhere else.

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

Done.

   //
   // While suspended, GetMediaTime() returns the presentation timestamp of the
   // last rendered frame.
   //
   // It is an error to call this method if the pipeline has not started or is
   // seeking.
-  void Suspend(const PipelineStatusCB& suspend_cb);
+  virtual void Suspend(const PipelineStatusCB& suspend_cb) = 0;
 
   // Resume the pipeline with a new renderer, and initialize it with a seek.

[xhwang, 2016/02/19 17:06:07]

When can you call resume?

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

Done.

-  void Resume(scoped_ptr<Renderer> renderer,
-              base::TimeDelta timestamp,
-              const PipelineStatusCB& seek_cb);
+  virtual void Resume(scoped_ptr<Renderer> renderer,
+                      base::TimeDelta timestamp,
+                      const PipelineStatusCB& seek_cb) = 0;
+
+  // Returns true if the pipeline has been started via Start().  If IsRunning()
+  // returns true, it is expected that Stop() will be called before destroying
+  // the pipeline.
+  virtual bool IsRunning() const = 0;

[xhwang, 2016/02/19 17:06:07]

The caller should know whether the pipeline is running since it is the caller of
Start()?

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

That's true, but this method is currently used in WMPI in the suspend logic.
That will be going away in the WMPI refactor CL, so if we also remove calls to
this method from tests we can get rid of it after that.

+
+  // Gets the current playback rate of the pipeline.  When the pipeline is
+  // started, the playback rate will be 0.0.  A rate of 1.0 indicates
+  // that the pipeline is rendering the media at the standard rate.  Valid
+  // values for playback rate are >= 0.0.
+  virtual double GetPlaybackRate() const = 0;

[xhwang, 2016/02/19 17:06:07]

The caller called SetPlaybackRate(), shouldn't it already know the rate? Or is
this just for convenience?

+
+  // Attempt to adjust the playback rate. Setting a playback rate of 0.0 pauses
+  // all rendering of the media.  A rate of 1.0 indicates a normal playback
+  // rate.  Values for the playback rate must be greater than or equal to 0.0.
+  //
+  // TODO(scherkus): What about maximum rate?  Does HTML5 specify a max?
+  virtual void SetPlaybackRate(double playback_rate) = 0;
 
   // Gets the current volume setting being used by the audio renderer.  When
   // the pipeline is started, this value will be 1.0f.  Valid values range
   // from 0.0f to 1.0f.
-  float GetVolume() const;
+  virtual float GetVolume() const = 0;
 
   // Attempt to set the volume of the audio renderer.  Valid values for volume
   // range from 0.0f (muted) to 1.0f (full volume).  This value affects all
   // channels proportionately for multi-channel audio streams.
-  void SetVolume(float volume);
+  virtual void SetVolume(float volume) = 0;
 
   // Returns the current media playback time, which progresses from 0 until
   // GetMediaDuration().
-  base::TimeDelta GetMediaTime() const;
+  virtual base::TimeDelta GetMediaTime() const = 0;
 
   // Get approximate time ranges of buffered media.
-  Ranges<base::TimeDelta> GetBufferedTimeRanges() const;
+  virtual Ranges<base::TimeDelta> GetBufferedTimeRanges() const = 0;
 
   // Get the duration of the media in microseconds.  If the duration has not
   // been determined yet, then returns 0.
-  base::TimeDelta GetMediaDuration() const;
+  virtual base::TimeDelta GetMediaDuration() const = 0;
 
   // Return true if loading progress has been made since the last time this
   // method was called.
-  bool DidLoadingProgress();
+  virtual bool DidLoadingProgress() = 0;
 
   // Gets the current pipeline statistics.
-  PipelineStatistics GetStatistics() const;
+  virtual PipelineStatistics GetStatistics() const = 0;
 
-  void SetCdm(CdmContext* cdm_context, const CdmAttachedCB& cdm_attached_cb);
+  virtual void SetCdm(CdmContext* cdm_context,
+                      const CdmAttachedCB& cdm_attached_cb) = 0;
+};
+
+// Pipeline runs the media pipeline.  Filters are created and called on the
+// task runner injected into this object. Pipeline works like a state
+// machine to perform asynchronous initialization, pausing, seeking and playing.
+//
+// Here's a state diagram that describes the lifetime of this object.
+//
+//   [ *Created ]                       [ Any State ]
+//         | Start()                         | Stop() / SetError()
+//         V                                 V
+//   [ InitXXX (for each filter) ]      [ Stopping ]
+//         |                                 |
+//         V                                 V
+//   [ Playing ] <---------.            [ Stopped ]
+//     |     | Seek()      |
+//     |     V             |
+//     |   [ Seeking ] ----'
+//     |                   ^
+//     | Suspend()         |
+//     V                   |
+//   [ Suspending ]        |
+//     |                   |
+//     V                   |
+//   [ Suspended ]         |
+//     | Resume()          |
+//     V                   |
+//   [ Resuming ] ---------'
+//
+// Initialization is a series of state transitions from "Created" through each
+// filter initialization state.  When all filter initialization states have
+// completed, we simulate a Seek() to the beginning of the media to give filters
+// a chance to preroll. From then on the normal Seek() transitions are carried
+// out and we start playing the media.
+//
+// If any error ever happens, this object will transition to the "Error" state
+// from any state. If Stop() is ever called, this object will transition to
+// "Stopped" state.
+//
+// TODO(sandersd): It should be possible to pass through Suspended when going
+// from InitDemuxer to InitRenderer, thereby eliminating the Resuming state.
+// Some annoying differences between the two paths need to be removed first.
+class MEDIA_EXPORT PipelineImpl : public Pipeline, public DemuxerHost {

[xhwang, 2016/02/19 17:06:07]

Should we put this in a different file?

[DaleCurtis, 2016/02/19 23:19:45]

+1

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

Done.

+ public:
+  // Constructs a media pipeline that will execute on |task_runner|.
+  PipelineImpl(const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
+               MediaLog* media_log);
+  ~PipelineImpl() override;
 
   void SetErrorForTesting(PipelineStatus status);
   bool HasWeakPtrsForTesting() const;
 
+  // PipelineInterface implementation.

[xhwang, 2016/02/19 17:06:07]

s/PipelineInterface/Pipeline/

[sandersd (OOO until July 31), 2016/02/22 22:32:57]

Done.

+  void Start(Demuxer* demuxer,
+             scoped_ptr<Renderer> renderer,
+             const base::Closure& ended_cb,
+             const PipelineStatusCB& error_cb,
+             const PipelineStatusCB& seek_cb,
+             const PipelineMetadataCB& metadata_cb,
+             const BufferingStateCB& buffering_state_cb,
+             const base::Closure& duration_change_cb,
+             const AddTextTrackCB& add_text_track_cb,
+             const base::Closure& waiting_for_decryption_key_cb) override;
+  void Stop(const base::Closure& stop_cb) override;
+  void Seek(base::TimeDelta time, const PipelineStatusCB& seek_cb) override;
+  bool IsRunning() const override;
+  double GetPlaybackRate() const override;
+  void SetPlaybackRate(double playback_rate) override;
+  void Suspend(const PipelineStatusCB& suspend_cb) override;
+  void Resume(scoped_ptr<Renderer> renderer,
+              base::TimeDelta timestamp,
+              const PipelineStatusCB& seek_cb) override;
+  float GetVolume() const override;
+  void SetVolume(float volume) override;
+  base::TimeDelta GetMediaTime() const override;
+  Ranges<base::TimeDelta> GetBufferedTimeRanges() const override;
+  base::TimeDelta GetMediaDuration() const override;
+  bool DidLoadingProgress() override;
+  PipelineStatistics GetStatistics() const override;
+  void SetCdm(CdmContext* cdm_context,
+              const CdmAttachedCB& cdm_attached_cb) override;
+
  private:
   FRIEND_TEST_ALL_PREFIXES(PipelineTest, GetBufferedTimeRanges);
   FRIEND_TEST_ALL_PREFIXES(PipelineTest, EndedCallback);
   FRIEND_TEST_ALL_PREFIXES(PipelineTest, AudioStreamShorterThanVideo);
   friend class MediaLog;
 
   // Pipeline states, as described above.
   enum State {
     kCreated,
     kInitDemuxer,
@@ skipping 194 matching lines @@
   scoped_ptr<SerialRunner> pending_callbacks_;
 
   // CdmContext to be used to decrypt (and decode) encrypted stream in this
   // pipeline. Non-null only when SetCdm() is called and the pipeline has not
   // been started. Then during Start(), this value will be set on |renderer_|.
   CdmContext* pending_cdm_context_;
 
   base::ThreadChecker thread_checker_;
 
   // NOTE: Weak pointers must be invalidated before all other member variables.
-  base::WeakPtrFactory<Pipeline> weak_factory_;
+  base::WeakPtrFactory<PipelineImpl> weak_factory_;
 
-  DISALLOW_COPY_AND_ASSIGN(Pipeline);
+  DISALLOW_COPY_AND_ASSIGN(PipelineImpl);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_PIPELINE_H_