1 // Copyright 2014 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_FILTERS_DECODER_STREAM_H_
6 #define MEDIA_FILTERS_DECODER_STREAM_H_
11 #include "base/compiler_specific.h"
12 #include "base/containers/circular_deque.h"
13 #include "base/functional/callback.h"
14 #include "base/memory/raw_ptr.h"
15 #include "base/memory/scoped_refptr.h"
16 #include "base/memory/weak_ptr.h"
17 #include "base/moving_window.h"
18 #include "base/time/time.h"
19 #include "base/types/pass_key.h"
20 #include "media/base/audio_decoder.h"
21 #include "media/base/audio_timestamp_helper.h"
22 #include "media/base/decoder_status.h"
23 #include "media/base/demuxer_stream.h"
24 #include "media/base/media_export.h"
25 #include "media/base/media_log.h"
26 #include "media/base/pipeline_status.h"
27 #include "media/base/timestamp_constants.h"
28 #include "media/base/waiting.h"
29 #include "media/filters/decoder_selector.h"
30 #include "media/filters/decoder_stream_traits.h"
33 class SequencedTaskRunner;
39 class DecryptingDemuxerStream;
41 // Wraps a DemuxerStream and a list of Decoders and provides decoded
42 // output to its client (e.g. Audio/VideoRendererImpl).
43 template <DemuxerStream::Type StreamType>
44 class MEDIA_EXPORT DecoderStream {
46 using StreamTraits = DecoderStreamTraits<StreamType>;
47 using Decoder = typename StreamTraits::DecoderType;
48 using Output = typename StreamTraits::OutputType;
49 using DecoderConfig = typename StreamTraits::DecoderConfigType;
51 // Callback to create a list of decoders.
52 using CreateDecodersCB =
53 base::RepeatingCallback<std::vector<std::unique_ptr<Decoder>>()>;
55 // Indicates completion of a DecoderStream initialization.
56 using InitCB = base::OnceCallback<void(bool success)>;
58 // Indicates completion of a DecoderStream read.
59 using ReadResult = DecoderStatus::Or<scoped_refptr<Output>>;
60 using ReadCB = base::OnceCallback<void(ReadResult)>;
62 DecoderStream(std::unique_ptr<DecoderStreamTraits<StreamType>> traits,
63 scoped_refptr<base::SequencedTaskRunner> task_runner,
64 CreateDecodersCB create_decoders_cb,
66 virtual ~DecoderStream();
68 // Initializes the DecoderStream and returns the initialization result
69 // through |init_cb|. Note that |init_cb| is always called asynchronously.
70 // |cdm_context| can be used to handle encrypted stream. Can be null if the
71 // stream is not encrypted.
72 void Initialize(DemuxerStream* stream,
74 CdmContext* cdm_context,
75 StatisticsCB statistics_cb,
76 WaitingCB waiting_cb);
78 // Reads a decoded Output and returns it via the |read_cb|. Note that
79 // |read_cb| is always called asynchronously. This method should only be
80 // called after initialization has succeeded and must not be called during
82 void Read(ReadCB read_cb);
84 // Resets the decoder, flushes all decoded outputs and/or internal buffers,
85 // fires any existing pending read callback and calls |closure| on completion.
86 // Note that |closure| is always called asynchronously. This method should
87 // only be called after initialization has succeeded and must not be called
88 // during pending Reset().
89 // N.B: If the decoder stream has run into an error, calling this method does
90 // not 'reset' it to a normal state.
91 void Reset(base::OnceClosure closure);
93 // Returns true if the decoder currently has the ability to decode and return
95 bool CanReadWithoutStalling() const;
97 base::TimeDelta AverageDuration() const;
99 // Indicates that outputs need preparation (e.g., copying into GPU buffers)
100 // before being marked as ready. When an output is given by the decoder it
101 // will be added to |unprepared_outputs_| if a PrepareCB has been specified.
102 // If the size of |ready_outputs_| is less than
103 // Decoder::GetMaxDecodeRequests(), the provided PrepareCB will be called for
104 // the output. Once an output has been prepared by the PrepareCB it must call
105 // the given OutputReadyCB with the prepared output.
107 // This process is structured such that only a fixed number of outputs are
108 // prepared at any one time; this alleviates resource usage issues incurred by
109 // the preparation process when a decoder has a burst of outputs after on
110 // Decode(). For more context on why, see https://crbug.com/820167.
111 using OutputReadyCB = base::OnceCallback<void(scoped_refptr<Output>)>;
113 base::RepeatingCallback<void(scoped_refptr<Output>, OutputReadyCB)>;
114 void SetPrepareCB(PrepareCB prepare_cb);
116 // Indicates that we won't need to prepare outputs before |start_timestamp|,
117 // so that the preparation step (which is generally expensive) can be skipped.
118 void SkipPrepareUntil(base::TimeDelta start_timestamp);
120 // Allows callers to register for notification of config changes; this is
121 // called immediately after receiving the 'kConfigChanged' status from the
122 // DemuxerStream, before any action is taken to handle the config change.
123 using ConfigChangeObserverCB =
124 base::RepeatingCallback<void(const DecoderConfig&)>;
125 void set_config_change_observer(
126 ConfigChangeObserverCB config_change_observer) {
127 config_change_observer_cb_ = config_change_observer;
130 // Allow interested folks to keep track the currently selected decoder. The
131 // provided decoder is valid only during the scope of the callback.
132 using DecoderChangeObserverCB = base::RepeatingCallback<void(Decoder*)>;
133 void set_decoder_change_observer(
134 DecoderChangeObserverCB decoder_change_observer_cb) {
135 decoder_change_observer_cb_ = std::move(decoder_change_observer_cb);
138 void set_fallback_observer(PipelineStatusCB fallback_cb) {
139 fallback_cb_ = std::move(fallback_cb);
142 int get_pending_buffers_size_for_testing() const {
143 return pending_buffers_.size();
146 int get_fallback_buffers_size_for_testing() const {
147 return fallback_buffers_.size();
150 bool is_demuxer_read_pending() const { return pending_demuxer_read_; }
152 DecoderSelector<StreamType>& GetDecoderSelectorForTesting(
153 base::PassKey<class VideoDecoderStreamTest>) {
154 return decoder_selector_;
161 STATE_NORMAL, // Includes idle, pending decoder decode/reset.
162 STATE_FLUSHING_DECODER,
163 STATE_REINITIALIZING_DECODER,
164 STATE_END_OF_STREAM, // End of stream reached; returns EOS on all reads.
168 // Returns the string representation of the StreamType for logging purpose.
169 std::string GetStreamTypeString();
171 // Returns maximum concurrent decode requests for the current |decoder_|.
172 int GetMaxDecodeRequests() const;
174 // Returns the maximum number of outputs we should keep ready at any one time.
175 int GetMaxReadyOutputs() const;
177 // Returns true if one more decode request can be submitted to the decoder.
178 bool CanDecodeMore() const;
180 void BeginDecoderSelection();
181 void ResumeDecoderSelection(DecoderStatus&& reinit_cause);
183 // Called when |decoder_selector| selected the |selected_decoder|.
184 // |decrypting_demuxer_stream| was also populated if a DecryptingDemuxerStream
185 // is created to help decrypt the encrypted stream.
186 void OnDecoderSelected(
187 DecoderStatus::Or<std::unique_ptr<Decoder>> decoder_or_error,
188 std::unique_ptr<DecryptingDemuxerStream> decrypting_demuxer_stream);
190 // Satisfy pending |read_cb_| with |result|.
191 void SatisfyRead(ReadResult result);
193 // Decodes |buffer| and returns the result via OnDecodeOutputReady().
194 // Saves |buffer| into |pending_buffers_| if appropriate.
195 void Decode(scoped_refptr<DecoderBuffer> buffer);
197 // Performs the heavy lifting of the decode call.
198 void DecodeInternal(scoped_refptr<DecoderBuffer> buffer);
200 // Flushes the decoder with an EOS buffer to retrieve internally buffered
204 // Callback for Decoder::Decode().
205 void OnDecodeDone(int buffer_size,
207 std::unique_ptr<ScopedDecodeTrace> trace_event,
208 DecoderStatus status);
210 // Output callback passed to Decoder::Initialize().
211 void OnDecodeOutputReady(scoped_refptr<Output> output);
213 // Reads a buffer from |stream_| and returns the result via OnBufferReady().
214 void ReadFromDemuxerStream();
216 void OnBuffersReady(DemuxerStream::Status status,
217 DemuxerStream::DecoderBufferVector buffers);
219 void ReinitializeDecoder();
221 void CompleteDecoderReinitialization(DecoderStatus status);
224 void OnDecoderReset();
227 void MaybePrepareAnotherOutput();
228 void OnPreparedOutputReady(scoped_refptr<Output> frame);
229 void CompletePrepare(const Output* output);
231 void ReportEncryptionType(const scoped_refptr<DecoderBuffer>& buffer);
233 std::unique_ptr<DecoderStreamTraits<StreamType>> traits_;
235 scoped_refptr<base::SequencedTaskRunner> task_runner_;
236 raw_ptr<MediaLog> media_log_;
240 StatisticsCB statistics_cb_;
242 WaitingCB waiting_cb_;
243 PipelineStatusCB fallback_cb_;
246 base::OnceClosure reset_cb_;
248 raw_ptr<DemuxerStream, DanglingUntriaged> stream_;
250 raw_ptr<CdmContext> cdm_context_;
252 std::unique_ptr<Decoder> decoder_;
254 // Whether |decoder_| has produced a frame yet. Reset on fallback.
255 bool decoder_produced_a_frame_;
257 std::unique_ptr<DecryptingDemuxerStream> decrypting_demuxer_stream_;
259 // Note: Holds pointers to |traits_|, |stream_|, |decrypting_demuxer_stream_|,
260 // and |cdm_context_|.
261 DecoderSelector<StreamType> decoder_selector_;
263 ConfigChangeObserverCB config_change_observer_cb_;
264 DecoderChangeObserverCB decoder_change_observer_cb_;
266 // An end-of-stream buffer has been sent for decoding, no more buffers should
267 // be sent for decoding until it completes.
268 // TODO(sandersd): Turn this into a State. http://crbug.com/408316
271 PrepareCB prepare_cb_;
272 bool preparing_output_;
274 // Decoded buffers that haven't been read yet. If |prepare_cb_| has been set
275 // |unprepared_outputs_| will contain buffers which haven't been prepared yet.
276 // Once prepared or if preparation is not required, outputs will be put into
278 base::circular_deque<scoped_refptr<Output>> unprepared_outputs_;
279 base::circular_deque<scoped_refptr<Output>> ready_outputs_;
281 // Number of outstanding decode requests sent to the |decoder_|.
282 int pending_decode_requests_;
284 // Tracks the duration of incoming packets over time.
285 base::MovingAverage<base::TimeDelta, base::TimeDelta> duration_tracker_;
287 // Stores buffers that might be reused if the decoder fails right after
289 base::circular_deque<scoped_refptr<DecoderBuffer>> pending_buffers_;
291 // Stores buffers that are guaranteed to be fed to the decoder before fetching
292 // more from the demuxer stream. All buffers in this queue first were in
293 // |pending_buffers_|.
294 base::circular_deque<scoped_refptr<DecoderBuffer>> fallback_buffers_;
296 // TODO(tguilbert): support config changes during decoder fallback, see
298 bool received_config_change_during_reinit_;
300 // Used to track read requests; not rolled into |state_| since that is
301 // overwritten in many cases.
302 bool pending_demuxer_read_;
304 // Timestamp after which all outputs need to be prepared.
305 base::TimeDelta skip_prepare_until_timestamp_;
307 bool encryption_type_reported_ = false;
309 int fallback_buffers_being_decoded_ = 0;
311 // NOTE: Weak pointers must be invalidated before all other member variables.
312 base::WeakPtrFactory<DecoderStream<StreamType>> weak_factory_{this};
314 // Used to invalidate pending decode requests and output callbacks.
315 base::WeakPtrFactory<DecoderStream<StreamType>> fallback_weak_factory_{this};
317 // Used to invalidate outputs awaiting preparation. This can't use either of
318 // the above factories since they are used to bind one time callbacks given
319 // to decoders that may not be reinitialized after Reset().
320 base::WeakPtrFactory<DecoderStream<StreamType>> prepare_weak_factory_{this};
324 bool DecoderStream<DemuxerStream::AUDIO>::CanReadWithoutStalling() const;
327 int DecoderStream<DemuxerStream::AUDIO>::GetMaxDecodeRequests() const;
329 using VideoDecoderStream = DecoderStream<DemuxerStream::VIDEO>;
330 using AudioDecoderStream = DecoderStream<DemuxerStream::AUDIO>;
334 #endif // MEDIA_FILTERS_DECODER_STREAM_H_