media/base/demuxer.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_DEMUXER_H_
   6 #define MEDIA_BASE_DEMUXER_H_
   7
   8 #include <stdint.h>
   9
  10 #include <memory>
  11 #include <vector>
  12
  13 #include "base/time/time.h"
  14 #include "media/base/container_names.h"
  15 #include "media/base/data_source.h"
  16 #include "media/base/demuxer_stream.h"
  17 #include "media/base/eme_constants.h"
  18 #include "media/base/media_export.h"
  19 #include "media/base/media_resource.h"
  20 #include "media/base/media_track.h"
  21 #include "media/base/pipeline_status.h"
  22 #include "media/base/ranges.h"
  23 #include "third_party/abseil-cpp/absl/types/optional.h"
  24
  25 namespace media {
  26
  27 class MediaTracks;
  28
  29 enum class DemuxerType {
  30   kMockDemuxer,
  31   kFFmpegDemuxer,
  32   kChunkDemuxer,
  33   kMediaUrlDemuxer,
  34   kFrameInjectingDemuxer,
  35   kStreamProviderDemuxer,
  36   kManifestDemuxer,
  37 };
  38
  39 class MEDIA_EXPORT DemuxerHost {
  40  public:
  41   // Notify the host that buffered time ranges have changed. Note that buffered
  42   // time ranges can grow (when new media data is appended), but they can also
  43   // shrink (when buffering reaches limit capacity and some buffered data
  44   // becomes evicted, e.g. due to MSE GC algorithm, or by explicit removal of
  45   // ranges directed by MSE web app).
  46   virtual void OnBufferedTimeRangesChanged(
  47       const Ranges<base::TimeDelta>& ranges) = 0;
  48
  49   // Sets the duration of the media in microseconds.
  50   // Duration may be kInfiniteDuration if the duration is not known.
  51   virtual void SetDuration(base::TimeDelta duration) = 0;
  52
  53   // Stops execution of the pipeline due to a fatal error. Do not call this
  54   // method with PIPELINE_OK. Stopping is not immediate so demuxers must be
  55   // prepared to soft fail on subsequent calls. E.g., if Demuxer::Seek() is
  56   // called after an unrecoverable error the provided PipelineStatusCallback
  57   // must be called with an error.
  58   virtual void OnDemuxerError(PipelineStatus error) = 0;
  59
  60  protected:
  61   virtual ~DemuxerHost();
  62 };
  63
  64 class MEDIA_EXPORT Demuxer : public MediaResource {
  65  public:
  66   // A new potentially encrypted stream has been parsed.
  67   // First parameter - The type of initialization data.
  68   // Second parameter - The initialization data associated with the stream.
  69   using EncryptedMediaInitDataCB =
  70       base::RepeatingCallback<void(EmeInitDataType type,
  71                                    const std::vector<uint8_t>& init_data)>;
  72
  73   // Notifies demuxer clients that media track configuration has been updated
  74   // (e.g. the initial stream metadata has been parsed successfully, or a new
  75   // init segment has been parsed successfully in MSE case).
  76   using MediaTracksUpdatedCB =
  77       base::RepeatingCallback<void(std::unique_ptr<MediaTracks>)>;
  78
  79   // Called once the demuxer has finished enabling or disabling tracks. The type
  80   // argument is required because the vector may be empty.
  81   using TrackChangeCB =
  82       base::OnceCallback<void(DemuxerStream::Type type,
  83                               const std::vector<DemuxerStream*>&)>;
  84
  85   enum DemuxerTypes {
  86     kChunkDemuxer,
  87     kFFmpegDemuxer,
  88     kMediaUrlDemuxer,
  89   };
  90
  91   Demuxer();
  92
  93   Demuxer(const Demuxer&) = delete;
  94   Demuxer& operator=(const Demuxer&) = delete;
  95
  96   ~Demuxer() override;
  97
  98   // Returns the name of the demuxer for logging purpose.
  99   virtual std::string GetDisplayName() const = 0;
 100
 101   // Get the demuxer type for identification purposes.
 102   virtual DemuxerType GetDemuxerType() const = 0;
 103
 104   // Completes initialization of the demuxer.
 105   //
 106   // The demuxer does not own |host| as it is guaranteed to outlive the
 107   // lifetime of the demuxer. Don't delete it!  |status_cb| must only be run
 108   // after this method has returned.
 109   virtual void Initialize(DemuxerHost* host,
 110                           PipelineStatusCallback status_cb) = 0;
 111
 112   // Aborts any pending read operations that the demuxer is involved with; any
 113   // read aborted will be aborted with a status of kAborted. Future reads will
 114   // also be aborted until Seek() is called.
 115   virtual void AbortPendingReads() = 0;
 116
 117   // Indicates that a new Seek() call is on its way. Implementations may abort
 118   // pending reads and future Read() calls may return kAborted until Seek() is
 119   // executed. |seek_time| is the presentation timestamp of the new Seek() call.
 120   //
 121   // In actual use, this call occurs on the main thread while Seek() is called
 122   // on the media thread. StartWaitingForSeek() can be used to synchronize the
 123   // two.
 124   //
 125   // StartWaitingForSeek() MUST be called before Seek().
 126   virtual void StartWaitingForSeek(base::TimeDelta seek_time) = 0;
 127
 128   // Indicates that the current Seek() operation is obsoleted by a new one.
 129   // Implementations can expect that StartWaitingForSeek() will be called
 130   // when the current seek operation completes.
 131   //
 132   // Like StartWaitingForSeek(), CancelPendingSeek() is called on the main
 133   // thread. Ordering with respect to the to-be-canceled Seek() is not
 134   // guaranteed. Regardless of ordering, implementations may abort pending reads
 135   // and may return kAborted from future Read() calls, until after
 136   // StartWaitingForSeek() and the following Seek() call occurs.
 137   //
 138   // |seek_time| should match that passed to the next StartWaitingForSeek(), but
 139   // may not if the seek target changes again before the current seek operation
 140   // completes or is aborted.
 141   virtual void CancelPendingSeek(base::TimeDelta seek_time) = 0;
 142
 143   // Carry out any actions required to seek to the given time, executing the
 144   // callback upon completion.
 145   virtual void Seek(base::TimeDelta time, PipelineStatusCallback status_cb) = 0;
 146
 147   // Returns whether this demuxer supports seeking and has a timeline. If false,
 148   // Seek(), CancelPendingSeek(), StartWaitingForSeek(), and GetTimelineOffset()
 149   // should be noops.
 150   virtual bool IsSeekable() const = 0;
 151
 152   // Stops this demuxer.
 153   //
 154   // After this call the demuxer may be destroyed. It is illegal to call any
 155   // method (including Stop()) after a demuxer has stopped.
 156   virtual void Stop() = 0;
 157
 158   // Returns the starting time for the media file; it's always positive.
 159   virtual base::TimeDelta GetStartTime() const = 0;
 160
 161   // Returns Time represented by presentation timestamp 0.
 162   // If the timstamps are not associated with a Time, then
 163   // a null Time is returned.
 164   virtual base::Time GetTimelineOffset() const = 0;
 165
 166   // Returns the memory usage in bytes for the demuxer.
 167   virtual int64_t GetMemoryUsage() const = 0;
 168
 169   // Returns the container name to use for metrics.
 170   // Implementations where this is not meaningful will return an empty value.
 171   // Implementations that do provide values should always provide a value,
 172   // returning CONTAINER_UNKNOWN in cases where the container is not known.
 173   virtual absl::optional<container_names::MediaContainerName>
 174   GetContainerForMetrics() const = 0;
 175
 176   // The |track_ids| vector has either 1 track, or is empty, indicating that
 177   // all tracks should be disabled. |change_completed_cb| is fired after the
 178   // demuxer streams are disabled, however this callback should then notify
 179   // the appropriate renderer in order for tracks to be switched fully.
 180   virtual void OnEnabledAudioTracksChanged(
 181       const std::vector<MediaTrack::Id>& track_ids,
 182       base::TimeDelta curr_time,
 183       TrackChangeCB change_completed_cb) = 0;
 184
 185   virtual void OnSelectedVideoTrackChanged(
 186       const std::vector<MediaTrack::Id>& track_ids,
 187       base::TimeDelta curr_time,
 188       TrackChangeCB change_completed_cb) = 0;
 189
 190   // Allows a demuxer to change behavior based on the playback rate, including
 191   // but not limited to changing the amount of buffer space.
 192   virtual void SetPlaybackRate(double rate) = 0;
 193
 194   // Allow canChangeType to be disabled.
 195   virtual void DisableCanChangeType();
 196 };
 197
 198 }  // namespace media
 199
 200 #endif  // MEDIA_BASE_DEMUXER_H_