1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Audio rendering unit utilizing an AudioRendererSink to output data.
7 // This class lives inside three threads during it's lifetime, namely:
9 // Where the object is created.
10 // 2. Media thread (provided via constructor)
11 // All AudioDecoder methods are called on this thread.
12 // 3. Audio thread created by the AudioRendererSink.
13 // Render() is called here where audio data is decoded into raw PCM data.
15 // AudioRendererImpl talks to an AudioRendererAlgorithm that takes care of
16 // queueing audio data and stretching/shrinking audio data when playback rate !=
19 #ifndef MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_
20 #define MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_
24 #include "base/gtest_prod_util.h"
25 #include "base/memory/weak_ptr.h"
26 #include "base/synchronization/lock.h"
27 #include "media/base/audio_decoder.h"
28 #include "media/base/audio_renderer.h"
29 #include "media/base/audio_renderer_sink.h"
30 #include "media/base/decryptor.h"
31 #include "media/filters/audio_renderer_algorithm.h"
32 #include "media/filters/decoder_selector.h"
35 class SingleThreadTaskRunner
;
42 class DecryptingDemuxerStream
;
44 class MEDIA_EXPORT AudioRendererImpl
45 : public AudioRenderer
,
46 NON_EXPORTED_BASE(public AudioRendererSink::RenderCallback
) {
48 // |task_runner| is the thread on which AudioRendererImpl will execute.
50 // |sink| is used as the destination for the rendered audio.
52 // |decoders| contains the AudioDecoders to use when initializing.
54 // |set_decryptor_ready_cb| is fired when the audio decryptor is available
55 // (only applicable if the stream is encrypted and we have a decryptor).
57 const scoped_refptr
<base::SingleThreadTaskRunner
>& task_runner
,
58 AudioRendererSink
* sink
,
59 ScopedVector
<AudioDecoder
> decoders
,
60 const SetDecryptorReadyCB
& set_decryptor_ready_cb
);
61 virtual ~AudioRendererImpl();
63 // AudioRenderer implementation.
64 virtual void Initialize(DemuxerStream
* stream
,
65 const PipelineStatusCB
& init_cb
,
66 const StatisticsCB
& statistics_cb
,
67 const base::Closure
& underflow_cb
,
68 const TimeCB
& time_cb
,
69 const base::Closure
& ended_cb
,
70 const base::Closure
& disabled_cb
,
71 const PipelineStatusCB
& error_cb
) OVERRIDE
;
72 virtual void Play(const base::Closure
& callback
) OVERRIDE
;
73 virtual void Pause(const base::Closure
& callback
) OVERRIDE
;
74 virtual void Flush(const base::Closure
& callback
) OVERRIDE
;
75 virtual void Stop(const base::Closure
& callback
) OVERRIDE
;
76 virtual void SetPlaybackRate(float rate
) OVERRIDE
;
77 virtual void Preroll(base::TimeDelta time
,
78 const PipelineStatusCB
& cb
) OVERRIDE
;
79 virtual void ResumeAfterUnderflow() OVERRIDE
;
80 virtual void SetVolume(float volume
) OVERRIDE
;
82 // Disables underflow support. When used, |state_| will never transition to
83 // kUnderflow resulting in Render calls that underflow returning 0 frames
84 // instead of some number of silence frames. Must be called prior to
86 void DisableUnderflowForTesting();
88 // Allows injection of a custom time callback for non-realtime testing.
89 typedef base::Callback
<base::TimeTicks()> NowCB
;
90 void set_now_cb_for_testing(const NowCB
& now_cb
) {
95 friend class AudioRendererImplTest
;
97 // TODO(acolwell): Add a state machine graph.
110 // Callback from the audio decoder delivering decoded audio samples.
111 void DecodedAudioReady(AudioDecoder::Status status
,
112 const scoped_refptr
<AudioBuffer
>& buffer
);
114 // Handles buffers that come out of |splicer_|.
115 // Returns true if more buffers are needed.
116 bool HandleSplicerBuffer(const scoped_refptr
<AudioBuffer
>& buffer
);
118 // Helper functions for AudioDecoder::Status values passed to
119 // DecodedAudioReady().
120 void HandleAbortedReadOrDecodeError(bool is_decode_error
);
122 // Estimate earliest time when current buffer can stop playing.
123 void UpdateEarliestEndTime_Locked(int frames_filled
,
124 const base::TimeDelta
& playback_delay
,
125 const base::TimeTicks
& time_now
);
127 void DoPlay_Locked();
128 void DoPause_Locked();
130 // AudioRendererSink::RenderCallback implementation.
132 // NOTE: These are called on the audio callback thread!
134 // Render() fills the given buffer with audio data by delegating to its
135 // |algorithm_|. Render() also takes care of updating the clock.
136 // Returns the number of frames copied into |audio_bus|, which may be less
137 // than or equal to the initial number of frames in |audio_bus|
139 // If this method returns fewer frames than the initial number of frames in
140 // |audio_bus|, it could be a sign that the pipeline is stalled or unable to
141 // stream the data fast enough. In such scenarios, the callee should zero out
142 // unused portions of their buffer to play back silence.
144 // Render() updates the pipeline's playback timestamp. If Render() is
145 // not called at the same rate as audio samples are played, then the reported
146 // timestamp in the pipeline will be ahead of the actual audio playback. In
147 // this case |audio_delay_milliseconds| should be used to indicate when in the
148 // future should the filled buffer be played.
149 virtual int Render(AudioBus
* audio_bus
,
150 int audio_delay_milliseconds
) OVERRIDE
;
151 virtual void OnRenderError() OVERRIDE
;
153 // Helper methods that schedule an asynchronous read from the decoder as long
154 // as there isn't a pending read.
156 // Must be called on |task_runner_|.
158 void AttemptRead_Locked();
159 bool CanRead_Locked();
160 void ChangeState_Locked(State new_state
);
162 // Returns true if the data in the buffer is all before
163 // |preroll_timestamp_|. This can only return true while
164 // in the kPrerolling state.
165 bool IsBeforePrerollTime(const scoped_refptr
<AudioBuffer
>& buffer
);
167 // Called when |decoder_selector_| has selected |decoder| or is null if no
168 // decoder could be selected.
170 // |decrypting_demuxer_stream| is non-null if a DecryptingDemuxerStream was
171 // created to help decrypt the encrypted stream.
172 void OnDecoderSelected(
173 scoped_ptr
<AudioDecoder
> decoder
,
174 scoped_ptr
<DecryptingDemuxerStream
> decrypting_demuxer_stream
);
176 // Used to initiate the flush operation once all pending reads have
178 void DoFlush_Locked();
180 // Calls |decoder_|.Reset() and arranges for ResetDecoderDone() to get
181 // called when the reset completes.
184 // Called when the |decoder_|.Reset() has completed.
185 void ResetDecoderDone();
187 // Stops the |decoder_| if present. Ensures |stop_cb_| is called.
190 scoped_refptr
<base::SingleThreadTaskRunner
> task_runner_
;
191 base::WeakPtrFactory
<AudioRendererImpl
> weak_factory_
;
192 base::WeakPtr
<AudioRendererImpl
> weak_this_
;
194 scoped_ptr
<AudioSplicer
> splicer_
;
196 // The sink (destination) for rendered audio. |sink_| must only be accessed
197 // on |task_runner_|. |sink_| must never be called under |lock_| or else we
198 // may deadlock between |task_runner_| and the audio callback thread.
199 scoped_refptr
<media::AudioRendererSink
> sink_
;
201 scoped_ptr
<AudioDecoderSelector
> decoder_selector_
;
203 // These two will be set by AudioDecoderSelector::SelectAudioDecoder().
204 scoped_ptr
<AudioDecoder
> decoder_
;
205 scoped_ptr
<DecryptingDemuxerStream
> decrypting_demuxer_stream_
;
207 // AudioParameters constructed during Initialize() based on |decoder_|.
208 AudioParameters audio_parameters_
;
210 // Callbacks provided during Initialize().
211 PipelineStatusCB init_cb_
;
212 StatisticsCB statistics_cb_
;
213 base::Closure underflow_cb_
;
215 base::Closure ended_cb_
;
216 base::Closure disabled_cb_
;
217 PipelineStatusCB error_cb_
;
219 // Callback provided to Flush().
220 base::Closure flush_cb_
;
222 // Callback provided to Stop().
223 base::Closure stop_cb_
;
225 // Callback provided to Preroll().
226 PipelineStatusCB preroll_cb_
;
228 // Typically calls base::TimeTicks::Now() but can be overridden by a test.
231 // After Initialize() has completed, all variables below must be accessed
232 // under |lock_|. ------------------------------------------------------------
235 // Algorithm for scaling audio.
236 scoped_ptr
<AudioRendererAlgorithm
> algorithm_
;
238 // Simple state tracking variable.
241 // Keep track of whether or not the sink is playing.
244 // Keep track of our outstanding read to |decoder_|.
247 // Keeps track of whether we received and rendered the end of stream buffer.
248 bool received_end_of_stream_
;
249 bool rendered_end_of_stream_
;
251 // The timestamp of the last frame (i.e. furthest in the future) buffered as
252 // well as the current time that takes current playback delay into account.
253 base::TimeDelta audio_time_buffered_
;
254 base::TimeDelta current_time_
;
256 base::TimeDelta preroll_timestamp_
;
258 // We're supposed to know amount of audio data OS or hardware buffered, but
259 // that is not always so -- on my Linux box
260 // AudioBuffersState::hardware_delay_bytes never reaches 0.
262 // As a result we cannot use it to find when stream ends. If we just ignore
263 // buffered data we will notify host that stream ended before it is actually
264 // did so, I've seen it done ~140ms too early when playing ~150ms file.
266 // Instead of trying to invent OS-specific solution for each and every OS we
267 // are supporting, use simple workaround: every time we fill the buffer we
268 // remember when it should stop playing, and do not assume that buffer is
269 // empty till that time. Workaround is not bulletproof, as we don't exactly
270 // know when that particular data would start playing, but it is much better
272 base::TimeTicks earliest_end_time_
;
273 size_t total_frames_filled_
;
275 bool underflow_disabled_
;
277 // True if the renderer receives a buffer with kAborted status during preroll,
278 // false otherwise. This flag is cleared on the next Preroll() call.
279 bool preroll_aborted_
;
281 // End variables which must be accessed under |lock_|. ----------------------
283 DISALLOW_COPY_AND_ASSIGN(AudioRendererImpl
);
288 #endif // MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_