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