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.
5 #ifndef MEDIA_BASE_PIPELINE_H_
6 #define MEDIA_BASE_PIPELINE_H_
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"
25 #if defined(TIZEN_VIDEO_HOLE)
26 #include "ui/gfx/geometry/rect_f.h"
34 enum TRACKCMD { SETTEXT, SETAUDIO, SETVIDEO, SETINBAND, SETCUE };
36 struct InbandTextInfo {
50 struct InbandCueInfo {
58 struct MediaTrackInfo {
63 class MEDIA_EXPORT Pipeline {
67 // Executed whenever an error occurs except when the error occurs during
68 // Start/Seek/Resume or Suspend. Those errors are reported via |seek_cb|
69 // and |suspend_cb| respectively.
70 // NOTE: The client is responsible for calling Pipeline::Stop().
71 virtual void OnError(PipelineStatus status) = 0;
73 // Executed whenever some fallback-enabled portion of the pipeline (Just
74 // Decoders and Renderers for now) fails in such a way that a fallback
75 // is still possible without a fatal pipeline error.
76 virtual void OnFallback(PipelineStatus status) = 0;
78 // Executed whenever the media reaches the end.
79 virtual void OnEnded() = 0;
81 // Executed when the content duration, container video size, start time,
82 // and whether the content has audio and/or video in supported formats are
84 virtual void OnMetadata(const PipelineMetadata& metadata) = 0;
86 // Executed whenever there are changes in the buffering state of the
87 // pipeline. |reason| indicates the cause of the state change, when known.
88 virtual void OnBufferingStateChange(BufferingState state,
89 BufferingStateChangeReason reason) = 0;
91 #if BUILDFLAG(IS_TIZEN_TV)
92 virtual void NotifyTrackInfoToBrowser(int active_track_id) {}
93 virtual void AddTrackInfo(MediaTrackInfo trackinfo) {}
96 // Executed whenever the presentation duration changes.
97 virtual void OnDurationChange() = 0;
99 // Executed whenever the pipeline is waiting because of |reason|.
100 virtual void OnWaiting(WaitingReason reason) = 0;
102 // Executed for the first video frame and whenever natural size changes.
103 virtual void OnVideoNaturalSizeChange(const gfx::Size& size) = 0;
105 // Executed for the first video frame and whenever opacity changes.
106 virtual void OnVideoOpacityChange(bool opaque) = 0;
108 // Executed when the average keyframe distance for the video changes.
109 virtual void OnVideoAverageKeyframeDistanceUpdate() = 0;
111 // Executed whenever DemuxerStream status returns kConfigChange. Initial
112 // configs provided by OnMetadata.
113 virtual void OnAudioConfigChange(const AudioDecoderConfig& config) = 0;
114 virtual void OnVideoConfigChange(const VideoDecoderConfig& config) = 0;
116 // Executed whenever the underlying AudioDecoder or VideoDecoder changes
118 virtual void OnAudioPipelineInfoChange(const AudioPipelineInfo& info) = 0;
119 virtual void OnVideoPipelineInfoChange(const VideoPipelineInfo& info) = 0;
121 // Executed whenever the video frame rate changes. |fps| will be unset if
122 // the frame rate is unstable. The duration used for the frame rate is
123 // based on wall clock time, not media time.
124 virtual void OnVideoFrameRateChange(absl::optional<int> fps) = 0;
126 #if defined(TIZEN_MULTIMEDIA)
127 virtual void OnRequestSuspend(bool resource_conflicted) = 0;
128 virtual void OnSeekableTimeChange(base::TimeDelta min_time,
129 base::TimeDelta max_time,
131 virtual void OnLivePlaybackComplete() = 0;
135 virtual ~Pipeline() {}
137 // StartType provides the option to start the pipeline without a renderer;
138 // pipeline initialization will stop once metadata has been retrieved. The
139 // flags below indicate when suspended start will be invoked.
140 enum class StartType {
141 kNormal, // Follow the normal startup path.
142 kSuspendAfterMetadataForAudioOnly, // Suspend after metadata for audio
144 kSuspendAfterMetadata, // Always suspend after metadata.
147 // Build a pipeline to using the given |demuxer| to construct a filter chain,
148 // executing |seek_cb| when the initial seek has completed. Methods on
149 // PipelineClient may be called up until Stop() has completed. It is an error
150 // to call this method after the pipeline has already started.
152 // If a |start_type| is specified which allows suspension, pipeline startup
153 // will halt after metadata has been retrieved and the pipeline will be in a
155 virtual void Start(StartType start_type,
158 PipelineStatusCallback seek_cb) = 0;
160 // Track switching works similarly for both audio and video. Callbacks are
161 // used to notify when it is time to procede to the next step, since many of
162 // the operations are asynchronous.
163 // ──────────────────── Track Switch Control Flow ───────────────────────
164 // pipeline | demuxer | demuxer_stream | renderer | video/audio_renderer
168 // switch track | | |
170 // | disable/enable stream | |
171 // | -----------> | |
172 // active streams | | |
174 // | switch track | |
175 // --------------------------------------> |
176 // | | | Flush/Restart/Reset
177 // | | | --------------->
178 // Notify pipeline of completed track change (via callback)
179 // <-----------------------------------------------------
180 // ──────────────────── Sometime in the future ──────────────────────────
181 // | | | OnBufferingStateChange
182 // | | | <----------------
183 // | OnBufferingStateChange | |
184 // <-------------------------------------- |
187 // |enabled_track_ids| contains track ids of enabled audio tracks.
188 virtual void OnEnabledAudioTracksChanged(
189 const std::vector<MediaTrack::Id>& enabled_track_ids,
190 base::OnceClosure change_completed_cb) = 0;
192 // |selected_track_id| is either empty, which means no video track is
193 // selected, or contains the selected video track id.
194 virtual void OnSelectedVideoTrackChanged(
195 absl::optional<MediaTrack::Id> selected_track_id,
196 base::OnceClosure change_completed_cb) = 0;
198 // Signal to the pipeline that there has been a client request to access
200 virtual void OnExternalVideoFrameRequest() = 0;
202 // Stops the pipeline. This is a blocking function.
203 // If the pipeline is started, it must be stopped before destroying it.
204 // It it permissible to call Stop() at any point during the lifetime of the
207 // Once Stop is called any outstanding completion callbacks
208 // for Start/Seek/Suspend/Resume or Client methods will *not* be called.
209 virtual void Stop() = 0;
211 // Attempt to seek to the position specified by time. |seek_cb| will be
212 // executed when the all filters in the pipeline have processed the seek.
214 // Clients are expected to call GetMediaTime() to check whether the seek
217 // It is an error to call this method if the pipeline has not started or
218 // has been suspended.
219 virtual void Seek(base::TimeDelta time, PipelineStatusCallback seek_cb) = 0;
221 // Suspends the pipeline, discarding the current renderer.
223 // While suspended, GetMediaTime() returns the presentation timestamp of the
224 // last rendered frame.
226 // It is an error to call this method if the pipeline has not started or is
228 virtual void Suspend(PipelineStatusCallback suspend_cb) = 0;
230 // Resume the pipeline and seek to |timestamp|.
232 // It is an error to call this method if the pipeline has not finished
234 virtual void Resume(base::TimeDelta timestamp,
235 PipelineStatusCallback seek_cb) = 0;
237 // Returns true if the pipeline has been started via Start(). If IsRunning()
238 // returns true, it is expected that Stop() will be called before destroying
240 virtual bool IsRunning() const = 0;
242 // Returns true if the pipeline has been suspended via Suspend() or during
243 // Start(). If IsSuspended() returns true, it is expected that Resume() will
244 // be called to resume playback.
245 virtual bool IsSuspended() const = 0;
247 // Gets the current playback rate of the pipeline. When the pipeline is
248 // started, the playback rate will be 0.0. A rate of 1.0 indicates
249 // that the pipeline is rendering the media at the standard rate. Valid
250 // values for playback rate are >= 0.0.
251 virtual double GetPlaybackRate() const = 0;
253 // Attempt to adjust the playback rate. Setting a playback rate of 0.0 pauses
254 // all rendering of the media. A rate of 1.0 indicates a normal playback
255 // rate. Values for the playback rate must be greater than or equal to 0.0.
257 // TODO(scherkus): What about maximum rate? Does HTML5 specify a max?
258 virtual void SetPlaybackRate(double playback_rate) = 0;
260 // Gets the current volume setting being used by the audio renderer. When
261 // the pipeline is started, this value will be 1.0f. Valid values range
262 // from 0.0f to 1.0f.
263 virtual float GetVolume() const = 0;
265 // Attempt to set the volume of the audio renderer. Valid values for volume
266 // range from 0.0f (muted) to 1.0f (full volume). This value affects all
267 // channels proportionately for multi-channel audio streams.
268 virtual void SetVolume(float volume) = 0;
270 // Hint from player about target latency as a guide for the desired amount of
271 // post-decode buffering required to start playback or resume from
272 // seek/underflow. A null option indicates the hint is unset and the pipeline
273 // can choose its own default.
274 virtual void SetLatencyHint(absl::optional<base::TimeDelta> latency_hint) = 0;
276 // Sets whether pitch adjustment should be applied when the playback rate is
277 // different than 1.0.
278 virtual void SetPreservesPitch(bool preserves_pitch) = 0;
280 // Sets a flag indicating whether the audio stream was played with user
282 virtual void SetWasPlayedWithUserActivation(
283 bool was_played_with_user_activation) = 0;
285 // Returns the current media playback time, which progresses from 0 until
286 // GetMediaDuration().
287 virtual base::TimeDelta GetMediaTime() const = 0;
289 // Get approximate time ranges of buffered media.
290 virtual Ranges<base::TimeDelta> GetBufferedTimeRanges() const = 0;
292 // Get the duration of the media in microseconds. If the duration has not
293 // been determined yet, then returns 0.
294 virtual base::TimeDelta GetMediaDuration() const = 0;
296 // Return true if loading progress has been made since the last time this
297 // method was called.
298 virtual bool DidLoadingProgress() = 0;
300 // Gets the current pipeline statistics.
301 virtual PipelineStatistics GetStatistics() const = 0;
303 using CdmAttachedCB = base::OnceCallback<void(bool)>;
304 virtual void SetCdm(CdmContext* cdm_context,
305 CdmAttachedCB cdm_attached_cb) = 0;
307 #if defined(TIZEN_MULTIMEDIA)
308 using ToggledFullscreenCB = base::OnceCallback<void()>;
309 virtual void ToggleFullscreenMode(bool is_fullscreen,
310 ToggledFullscreenCB cb) = 0;
313 #if defined(TIZEN_VIDEO_HOLE)
314 virtual void SetMediaGeometry(const gfx::RectF rect_f) = 0;
316 #if BUILDFLAG(IS_TIZEN_TV)
317 virtual void SetContentMimeType(const std::string& mime_type) = 0;
318 virtual void SetParentalRatingResult(bool is_pass) = 0;
319 virtual void SetActiveTextTrack(int id, bool is_in_band) = 0;
320 virtual void SetActiveAudioTrack(int index) = 0;
321 virtual void SetActiveVideoTrack(int index) = 0;
322 virtual void SetPreferTextLanguage(const std::string& lang) = 0;
323 virtual double GetStartDate() = 0;
324 virtual void DestroyPlayerSync(base::OnceClosure cb) = 0;
330 #endif // MEDIA_BASE_PIPELINE_H_