media/base/pipeline.h

   1 // Copyright 2012 The Chromium Authors
   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 MEDIA_BASE_PIPELINE_H_
   6 #define MEDIA_BASE_PIPELINE_H_
   7
   8 #include <memory>
   9
  10 #include "base/time/time.h"
  11 #include "media/base/audio_decoder_config.h"
  12 #include "media/base/buffering_state.h"
  13 #include "media/base/media_export.h"
  14 #include "media/base/media_status.h"
  15 #include "media/base/media_track.h"
  16 #include "media/base/pipeline_metadata.h"
  17 #include "media/base/pipeline_status.h"
  18 #include "media/base/ranges.h"
  19 #include "media/base/video_decoder_config.h"
  20 #include "media/base/video_transformation.h"
  21 #include "media/base/waiting.h"
  22 #include "third_party/abseil-cpp/absl/types/optional.h"
  23 #include "ui/gfx/geometry/size.h"
  24
  25 #if defined(TIZEN_VIDEO_HOLE)
  26 #include "ui/gfx/geometry/rect_f.h"
  27 #endif
  28
  29 namespace media {
  30
  31 class CdmContext;
  32 class Demuxer;
  33
  34 class MEDIA_EXPORT Pipeline {
  35  public:
  36   class Client {
  37    public:
  38     // Executed whenever an error occurs except when the error occurs during
  39     // Start/Seek/Resume or Suspend. Those errors are reported via |seek_cb|
  40     // and |suspend_cb| respectively.
  41     // NOTE: The client is responsible for calling Pipeline::Stop().
  42     virtual void OnError(PipelineStatus status) = 0;
  43
  44     // Executed whenever some fallback-enabled portion of the pipeline (Just
  45     // Decoders and Renderers for now) fails in such a way that a fallback
  46     // is still possible without a fatal pipeline error.
  47     virtual void OnFallback(PipelineStatus status) = 0;
  48
  49     // Executed whenever the media reaches the end.
  50     virtual void OnEnded() = 0;
  51
  52     // Executed when the content duration, container video size, start time,
  53     // and whether the content has audio and/or video in supported formats are
  54     // known.
  55     virtual void OnMetadata(const PipelineMetadata& metadata) = 0;
  56
  57     // Executed whenever there are changes in the buffering state of the
  58     // pipeline. |reason| indicates the cause of the state change, when known.
  59     virtual void OnBufferingStateChange(BufferingState state,
  60                                         BufferingStateChangeReason reason) = 0;
  61
  62     // Executed whenever the presentation duration changes.
  63     virtual void OnDurationChange() = 0;
  64
  65     // Executed whenever the pipeline is waiting because of |reason|.
  66     virtual void OnWaiting(WaitingReason reason) = 0;
  67
  68     // Executed for the first video frame and whenever natural size changes.
  69     virtual void OnVideoNaturalSizeChange(const gfx::Size& size) = 0;
  70
  71     // Executed for the first video frame and whenever opacity changes.
  72     virtual void OnVideoOpacityChange(bool opaque) = 0;
  73
  74     // Executed when the average keyframe distance for the video changes.
  75     virtual void OnVideoAverageKeyframeDistanceUpdate() = 0;
  76
  77     // Executed whenever DemuxerStream status returns kConfigChange. Initial
  78     // configs provided by OnMetadata.
  79     virtual void OnAudioConfigChange(const AudioDecoderConfig& config) = 0;
  80     virtual void OnVideoConfigChange(const VideoDecoderConfig& config) = 0;
  81
  82     // Executed whenever the underlying AudioDecoder or VideoDecoder changes
  83     // during playback.
  84     virtual void OnAudioPipelineInfoChange(const AudioPipelineInfo& info) = 0;
  85     virtual void OnVideoPipelineInfoChange(const VideoPipelineInfo& info) = 0;
  86
  87     // Executed whenever the video frame rate changes.  |fps| will be unset if
  88     // the frame rate is unstable.  The duration used for the frame rate is
  89     // based on wall clock time, not media time.
  90     virtual void OnVideoFrameRateChange(absl::optional<int> fps) = 0;
  91
  92 #if defined(TIZEN_MULTIMEDIA)
  93     virtual void OnRequestSuspend() = 0;
  94 #endif
  95   };
  96
  97   virtual ~Pipeline() {}
  98
  99   // StartType provides the option to start the pipeline without a renderer;
 100   // pipeline initialization will stop once metadata has been retrieved. The
 101   // flags below indicate when suspended start will be invoked.
 102   enum class StartType {
 103     kNormal,                            // Follow the normal startup path.
 104     kSuspendAfterMetadataForAudioOnly,  // Suspend after metadata for audio
 105                                         // only.
 106     kSuspendAfterMetadata,              // Always suspend after metadata.
 107   };
 108
 109   // Build a pipeline to using the given |demuxer| to construct a filter chain,
 110   // executing |seek_cb| when the initial seek has completed. Methods on
 111   // PipelineClient may be called up until Stop() has completed. It is an error
 112   // to call this method after the pipeline has already started.
 113   //
 114   // If a |start_type| is specified which allows suspension, pipeline startup
 115   // will halt after metadata has been retrieved and the pipeline will be in a
 116   // suspended state.
 117   virtual void Start(StartType start_type,
 118                      Demuxer* demuxer,
 119                      Client* client,
 120                      PipelineStatusCallback seek_cb) = 0;
 121
 122   // Track switching works similarly for both audio and video. Callbacks are
 123   // used to notify when it is time to procede to the next step, since many of
 124   // the operations are asynchronous.
 125   // ──────────────────── Track Switch Control Flow ───────────────────────
 126   //  pipeline | demuxer | demuxer_stream | renderer | video/audio_renderer
 127   //           |         |                |          |
 128   //           |         |                |          |
 129   //           |         |                |          |
 130   //     switch track    |                |          |
 131   //      --------->     |                |          |
 132   //           | disable/enable stream    |          |
 133   //           |      ----------->        |          |
 134   //    active streams   |                |          |
 135   //      <---------     |                |          |
 136   //           |        switch track      |          |
 137   //      -------------------------------------->    |
 138   //           |         |                |    Flush/Restart/Reset
 139   //           |         |                |     --------------->
 140   //     Notify pipeline of completed track change (via callback)
 141   //      <-----------------------------------------------------
 142   // ──────────────────── Sometime in the future ──────────────────────────
 143   //           |         |                | OnBufferingStateChange
 144   //           |         |                |    <----------------
 145   //           | OnBufferingStateChange   |          |
 146   //     <--------------------------------------     |
 147   //           |         |                |          |
 148   //           |         |                |          |
 149   // |enabled_track_ids| contains track ids of enabled audio tracks.
 150   virtual void OnEnabledAudioTracksChanged(
 151       const std::vector<MediaTrack::Id>& enabled_track_ids,
 152       base::OnceClosure change_completed_cb) = 0;
 153
 154   // |selected_track_id| is either empty, which means no video track is
 155   // selected, or contains the selected video track id.
 156   virtual void OnSelectedVideoTrackChanged(
 157       absl::optional<MediaTrack::Id> selected_track_id,
 158       base::OnceClosure change_completed_cb) = 0;
 159
 160   // Signal to the pipeline that there has been a client request to access
 161   // video frame data.
 162   virtual void OnExternalVideoFrameRequest() = 0;
 163
 164   // Stops the pipeline. This is a blocking function.
 165   // If the pipeline is started, it must be stopped before destroying it.
 166   // It it permissible to call Stop() at any point during the lifetime of the
 167   // pipeline.
 168   //
 169   // Once Stop is called any outstanding completion callbacks
 170   // for Start/Seek/Suspend/Resume or Client methods will *not* be called.
 171   virtual void Stop() = 0;
 172
 173   // Attempt to seek to the position specified by time.  |seek_cb| will be
 174   // executed when the all filters in the pipeline have processed the seek.
 175   //
 176   // Clients are expected to call GetMediaTime() to check whether the seek
 177   // succeeded.
 178   //
 179   // It is an error to call this method if the pipeline has not started or
 180   // has been suspended.
 181   virtual void Seek(base::TimeDelta time, PipelineStatusCallback seek_cb) = 0;
 182
 183   // Suspends the pipeline, discarding the current renderer.
 184   //
 185   // While suspended, GetMediaTime() returns the presentation timestamp of the
 186   // last rendered frame.
 187   //
 188   // It is an error to call this method if the pipeline has not started or is
 189   // seeking.
 190   virtual void Suspend(PipelineStatusCallback suspend_cb) = 0;
 191
 192   // Resume the pipeline and seek to |timestamp|.
 193   //
 194   // It is an error to call this method if the pipeline has not finished
 195   // suspending.
 196   virtual void Resume(base::TimeDelta timestamp,
 197                       PipelineStatusCallback seek_cb) = 0;
 198
 199   // Returns true if the pipeline has been started via Start().  If IsRunning()
 200   // returns true, it is expected that Stop() will be called before destroying
 201   // the pipeline.
 202   virtual bool IsRunning() const = 0;
 203
 204   // Returns true if the pipeline has been suspended via Suspend() or during
 205   // Start(). If IsSuspended() returns true, it is expected that Resume() will
 206   // be called to resume playback.
 207   virtual bool IsSuspended() const = 0;
 208
 209   // Gets the current playback rate of the pipeline.  When the pipeline is
 210   // started, the playback rate will be 0.0.  A rate of 1.0 indicates
 211   // that the pipeline is rendering the media at the standard rate.  Valid
 212   // values for playback rate are >= 0.0.
 213   virtual double GetPlaybackRate() const = 0;
 214
 215   // Attempt to adjust the playback rate. Setting a playback rate of 0.0 pauses
 216   // all rendering of the media.  A rate of 1.0 indicates a normal playback
 217   // rate.  Values for the playback rate must be greater than or equal to 0.0.
 218   //
 219   // TODO(scherkus): What about maximum rate?  Does HTML5 specify a max?
 220   virtual void SetPlaybackRate(double playback_rate) = 0;
 221
 222   // Gets the current volume setting being used by the audio renderer.  When
 223   // the pipeline is started, this value will be 1.0f.  Valid values range
 224   // from 0.0f to 1.0f.
 225   virtual float GetVolume() const = 0;
 226
 227   // Attempt to set the volume of the audio renderer.  Valid values for volume
 228   // range from 0.0f (muted) to 1.0f (full volume).  This value affects all
 229   // channels proportionately for multi-channel audio streams.
 230   virtual void SetVolume(float volume) = 0;
 231
 232   // Hint from player about target latency as a guide for the desired amount of
 233   // post-decode buffering required to start playback or resume from
 234   // seek/underflow. A null option indicates the hint is unset and the pipeline
 235   // can choose its own default.
 236   virtual void SetLatencyHint(absl::optional<base::TimeDelta> latency_hint) = 0;
 237
 238   // Sets whether pitch adjustment should be applied when the playback rate is
 239   // different than 1.0.
 240   virtual void SetPreservesPitch(bool preserves_pitch) = 0;
 241
 242   // Sets a flag indicating whether the audio stream was played with user
 243   // activation.
 244   virtual void SetWasPlayedWithUserActivation(
 245       bool was_played_with_user_activation) = 0;
 246
 247   // Returns the current media playback time, which progresses from 0 until
 248   // GetMediaDuration().
 249   virtual base::TimeDelta GetMediaTime() const = 0;
 250
 251   // Get approximate time ranges of buffered media.
 252   virtual Ranges<base::TimeDelta> GetBufferedTimeRanges() const = 0;
 253
 254   // Get the duration of the media in microseconds.  If the duration has not
 255   // been determined yet, then returns 0.
 256   virtual base::TimeDelta GetMediaDuration() const = 0;
 257
 258   // Return true if loading progress has been made since the last time this
 259   // method was called.
 260   virtual bool DidLoadingProgress() = 0;
 261
 262   // Gets the current pipeline statistics.
 263   virtual PipelineStatistics GetStatistics() const = 0;
 264
 265   using CdmAttachedCB = base::OnceCallback<void(bool)>;
 266   virtual void SetCdm(CdmContext* cdm_context,
 267                       CdmAttachedCB cdm_attached_cb) = 0;
 268
 269 #if defined(TIZEN_VIDEO_HOLE)
 270   virtual void SetMediaGeometry(const gfx::RectF rect_f) = 0;
 271 #endif
 272 };
 273
 274 }  // namespace media
 275
 276 #endif  // MEDIA_BASE_PIPELINE_H_