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(bool resource_conflicted) = 0;
  94     virtual void OnSeekableTimeChange(base::TimeDelta min_time,
  95                                       base::TimeDelta max_time,
  96                                       bool is_live) = 0;
  97 #endif
  98   };
  99
 100   virtual ~Pipeline() {}
 101
 102   // StartType provides the option to start the pipeline without a renderer;
 103   // pipeline initialization will stop once metadata has been retrieved. The
 104   // flags below indicate when suspended start will be invoked.
 105   enum class StartType {
 106     kNormal,                            // Follow the normal startup path.
 107     kSuspendAfterMetadataForAudioOnly,  // Suspend after metadata for audio
 108                                         // only.
 109     kSuspendAfterMetadata,              // Always suspend after metadata.
 110   };
 111
 112   // Build a pipeline to using the given |demuxer| to construct a filter chain,
 113   // executing |seek_cb| when the initial seek has completed. Methods on
 114   // PipelineClient may be called up until Stop() has completed. It is an error
 115   // to call this method after the pipeline has already started.
 116   //
 117   // If a |start_type| is specified which allows suspension, pipeline startup
 118   // will halt after metadata has been retrieved and the pipeline will be in a
 119   // suspended state.
 120   virtual void Start(StartType start_type,
 121                      Demuxer* demuxer,
 122                      Client* client,
 123                      PipelineStatusCallback seek_cb) = 0;
 124
 125   // Track switching works similarly for both audio and video. Callbacks are
 126   // used to notify when it is time to procede to the next step, since many of
 127   // the operations are asynchronous.
 128   // ──────────────────── Track Switch Control Flow ───────────────────────
 129   //  pipeline | demuxer | demuxer_stream | renderer | video/audio_renderer
 130   //           |         |                |          |
 131   //           |         |                |          |
 132   //           |         |                |          |
 133   //     switch track    |                |          |
 134   //      --------->     |                |          |
 135   //           | disable/enable stream    |          |
 136   //           |      ----------->        |          |
 137   //    active streams   |                |          |
 138   //      <---------     |                |          |
 139   //           |        switch track      |          |
 140   //      -------------------------------------->    |
 141   //           |         |                |    Flush/Restart/Reset
 142   //           |         |                |     --------------->
 143   //     Notify pipeline of completed track change (via callback)
 144   //      <-----------------------------------------------------
 145   // ──────────────────── Sometime in the future ──────────────────────────
 146   //           |         |                | OnBufferingStateChange
 147   //           |         |                |    <----------------
 148   //           | OnBufferingStateChange   |          |
 149   //     <--------------------------------------     |
 150   //           |         |                |          |
 151   //           |         |                |          |
 152   // |enabled_track_ids| contains track ids of enabled audio tracks.
 153   virtual void OnEnabledAudioTracksChanged(
 154       const std::vector<MediaTrack::Id>& enabled_track_ids,
 155       base::OnceClosure change_completed_cb) = 0;
 156
 157   // |selected_track_id| is either empty, which means no video track is
 158   // selected, or contains the selected video track id.
 159   virtual void OnSelectedVideoTrackChanged(
 160       absl::optional<MediaTrack::Id> selected_track_id,
 161       base::OnceClosure change_completed_cb) = 0;
 162
 163   // Signal to the pipeline that there has been a client request to access
 164   // video frame data.
 165   virtual void OnExternalVideoFrameRequest() = 0;
 166
 167   // Stops the pipeline. This is a blocking function.
 168   // If the pipeline is started, it must be stopped before destroying it.
 169   // It it permissible to call Stop() at any point during the lifetime of the
 170   // pipeline.
 171   //
 172   // Once Stop is called any outstanding completion callbacks
 173   // for Start/Seek/Suspend/Resume or Client methods will *not* be called.
 174   virtual void Stop() = 0;
 175
 176   // Attempt to seek to the position specified by time.  |seek_cb| will be
 177   // executed when the all filters in the pipeline have processed the seek.
 178   //
 179   // Clients are expected to call GetMediaTime() to check whether the seek
 180   // succeeded.
 181   //
 182   // It is an error to call this method if the pipeline has not started or
 183   // has been suspended.
 184   virtual void Seek(base::TimeDelta time, PipelineStatusCallback seek_cb) = 0;
 185
 186   // Suspends the pipeline, discarding the current renderer.
 187   //
 188   // While suspended, GetMediaTime() returns the presentation timestamp of the
 189   // last rendered frame.
 190   //
 191   // It is an error to call this method if the pipeline has not started or is
 192   // seeking.
 193   virtual void Suspend(PipelineStatusCallback suspend_cb) = 0;
 194
 195   // Resume the pipeline and seek to |timestamp|.
 196   //
 197   // It is an error to call this method if the pipeline has not finished
 198   // suspending.
 199   virtual void Resume(base::TimeDelta timestamp,
 200                       PipelineStatusCallback seek_cb) = 0;
 201
 202   // Returns true if the pipeline has been started via Start().  If IsRunning()
 203   // returns true, it is expected that Stop() will be called before destroying
 204   // the pipeline.
 205   virtual bool IsRunning() const = 0;
 206
 207   // Returns true if the pipeline has been suspended via Suspend() or during
 208   // Start(). If IsSuspended() returns true, it is expected that Resume() will
 209   // be called to resume playback.
 210   virtual bool IsSuspended() const = 0;
 211
 212   // Gets the current playback rate of the pipeline.  When the pipeline is
 213   // started, the playback rate will be 0.0.  A rate of 1.0 indicates
 214   // that the pipeline is rendering the media at the standard rate.  Valid
 215   // values for playback rate are >= 0.0.
 216   virtual double GetPlaybackRate() const = 0;
 217
 218   // Attempt to adjust the playback rate. Setting a playback rate of 0.0 pauses
 219   // all rendering of the media.  A rate of 1.0 indicates a normal playback
 220   // rate.  Values for the playback rate must be greater than or equal to 0.0.
 221   //
 222   // TODO(scherkus): What about maximum rate?  Does HTML5 specify a max?
 223   virtual void SetPlaybackRate(double playback_rate) = 0;
 224
 225   // Gets the current volume setting being used by the audio renderer.  When
 226   // the pipeline is started, this value will be 1.0f.  Valid values range
 227   // from 0.0f to 1.0f.
 228   virtual float GetVolume() const = 0;
 229
 230   // Attempt to set the volume of the audio renderer.  Valid values for volume
 231   // range from 0.0f (muted) to 1.0f (full volume).  This value affects all
 232   // channels proportionately for multi-channel audio streams.
 233   virtual void SetVolume(float volume) = 0;
 234
 235   // Hint from player about target latency as a guide for the desired amount of
 236   // post-decode buffering required to start playback or resume from
 237   // seek/underflow. A null option indicates the hint is unset and the pipeline
 238   // can choose its own default.
 239   virtual void SetLatencyHint(absl::optional<base::TimeDelta> latency_hint) = 0;
 240
 241   // Sets whether pitch adjustment should be applied when the playback rate is
 242   // different than 1.0.
 243   virtual void SetPreservesPitch(bool preserves_pitch) = 0;
 244
 245   // Sets a flag indicating whether the audio stream was played with user
 246   // activation.
 247   virtual void SetWasPlayedWithUserActivation(
 248       bool was_played_with_user_activation) = 0;
 249
 250   // Returns the current media playback time, which progresses from 0 until
 251   // GetMediaDuration().
 252   virtual base::TimeDelta GetMediaTime() const = 0;
 253
 254   // Get approximate time ranges of buffered media.
 255   virtual Ranges<base::TimeDelta> GetBufferedTimeRanges() const = 0;
 256
 257   // Get the duration of the media in microseconds.  If the duration has not
 258   // been determined yet, then returns 0.
 259   virtual base::TimeDelta GetMediaDuration() const = 0;
 260
 261   // Return true if loading progress has been made since the last time this
 262   // method was called.
 263   virtual bool DidLoadingProgress() = 0;
 264
 265   // Gets the current pipeline statistics.
 266   virtual PipelineStatistics GetStatistics() const = 0;
 267
 268   using CdmAttachedCB = base::OnceCallback<void(bool)>;
 269   virtual void SetCdm(CdmContext* cdm_context,
 270                       CdmAttachedCB cdm_attached_cb) = 0;
 271
 272 #if defined(TIZEN_MULTIMEDIA)
 273   using ToggledFullscreenCB = base::OnceCallback<void()>;
 274   virtual void ToggleFullscreenMode(bool is_fullscreen,
 275                                     ToggledFullscreenCB cb) = 0;
 276 #endif
 277
 278 #if defined(TIZEN_VIDEO_HOLE)
 279   virtual void SetMediaGeometry(const gfx::RectF rect_f) = 0;
 280 #endif
 281 #if BUILDFLAG(IS_TIZEN_TV)
 282   virtual void SetContentMimeType(const std::string& mime_type) = 0;
 283   virtual void SetParentalRatingResult(bool is_pass) = 0;
 284 #endif
 285 };
 286
 287 }  // namespace media
 288
 289 #endif  // MEDIA_BASE_PIPELINE_H_