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.
4
5// Audio rendering unit utilizing an AudioRendererSink to output data.
6//
7// This class lives inside three threads during it's lifetime, namely:
8// 1. Render thread
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.
14//
15// AudioRendererImpl talks to an AudioRendererAlgorithm that takes care of
16// queueing audio data and stretching/shrinking audio data when playback rate !=
17// 1.0 or 0.0.
18
19#ifndef MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_
20#define MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_
21
22#include <deque>
23
24#include "base/gtest_prod_util.h"
25#include "base/memory/scoped_ptr.h"
26#include "base/memory/weak_ptr.h"
27#include "base/synchronization/lock.h"
28#include "media/base/audio_decoder.h"
29#include "media/base/audio_renderer.h"
30#include "media/base/audio_renderer_sink.h"
31#include "media/base/decryptor.h"
32#include "media/base/media_log.h"
33#include "media/base/time_source.h"
34#include "media/filters/audio_renderer_algorithm.h"
35#include "media/filters/decoder_stream.h"
36
37namespace base {
38class SingleThreadTaskRunner;
39}
40
41namespace media {
42
43class AudioBufferConverter;
44class AudioBus;
45class AudioClock;
46class AudioHardwareConfig;
47class AudioSplicer;
48class DecryptingDemuxerStream;
49
50class MEDIA_EXPORT AudioRendererImpl
51    : public AudioRenderer,
52      public TimeSource,
53      NON_EXPORTED_BASE(public AudioRendererSink::RenderCallback) {
54 public:
55  // |task_runner| is the thread on which AudioRendererImpl will execute.
56  //
57  // |sink| is used as the destination for the rendered audio.
58  //
59  // |decoders| contains the AudioDecoders to use when initializing.
60  //
61  // |set_decryptor_ready_cb| is fired when the audio decryptor is available
62  // (only applicable if the stream is encrypted and we have a decryptor).
63  AudioRendererImpl(
64      const scoped_refptr<base::SingleThreadTaskRunner>& task_runner,
65      AudioRendererSink* sink,
66      ScopedVector<AudioDecoder> decoders,
67      const SetDecryptorReadyCB& set_decryptor_ready_cb,
68      const AudioHardwareConfig& hardware_params,
69      const scoped_refptr<MediaLog>& media_log);
70  virtual ~AudioRendererImpl();
71
72  // TimeSource implementation.
73  virtual void StartTicking() OVERRIDE;
74  virtual void StopTicking() OVERRIDE;
75  virtual void SetPlaybackRate(float rate) OVERRIDE;
76  virtual void SetMediaTime(base::TimeDelta time) OVERRIDE;
77  virtual base::TimeDelta CurrentMediaTime() OVERRIDE;
78  virtual base::TimeDelta CurrentMediaTimeForSyncingVideo() OVERRIDE;
79
80  // AudioRenderer implementation.
81  virtual void Initialize(DemuxerStream* stream,
82                          const PipelineStatusCB& init_cb,
83                          const StatisticsCB& statistics_cb,
84                          const BufferingStateCB& buffering_state_cb,
85                          const base::Closure& ended_cb,
86                          const PipelineStatusCB& error_cb) OVERRIDE;
87  virtual TimeSource* GetTimeSource() OVERRIDE;
88  virtual void Flush(const base::Closure& callback) OVERRIDE;
89  virtual void StartPlaying() OVERRIDE;
90  virtual void SetVolume(float volume) OVERRIDE;
91
92 private:
93  friend class AudioRendererImplTest;
94
95  // Important detail: being in kPlaying doesn't imply that audio is being
96  // rendered. Rather, it means that the renderer is ready to go. The actual
97  // rendering of audio is controlled via Start/StopRendering().
98  //
99  //   kUninitialized
100  //         | Initialize()
101  //         |
102  //         V
103  //    kInitializing
104  //         | Decoders initialized
105  //         |
106  //         V            Decoders reset
107  //      kFlushed <------------------ kFlushing
108  //         | StartPlaying()             ^
109  //         |                            |
110  //         |                            | Flush()
111  //         `---------> kPlaying --------'
112  enum State {
113    kUninitialized,
114    kInitializing,
115    kFlushing,
116    kFlushed,
117    kPlaying
118  };
119
120  // Callback from the audio decoder delivering decoded audio samples.
121  void DecodedAudioReady(AudioBufferStream::Status status,
122                         const scoped_refptr<AudioBuffer>& buffer);
123
124  // Handles buffers that come out of |splicer_|.
125  // Returns true if more buffers are needed.
126  bool HandleSplicerBuffer_Locked(const scoped_refptr<AudioBuffer>& buffer);
127
128  // Helper functions for AudioDecoder::Status values passed to
129  // DecodedAudioReady().
130  void HandleAbortedReadOrDecodeError(bool is_decode_error);
131
132  void StartRendering_Locked();
133  void StopRendering_Locked();
134
135  // AudioRendererSink::RenderCallback implementation.
136  //
137  // NOTE: These are called on the audio callback thread!
138  //
139  // Render() fills the given buffer with audio data by delegating to its
140  // |algorithm_|. Render() also takes care of updating the clock.
141  // Returns the number of frames copied into |audio_bus|, which may be less
142  // than or equal to the initial number of frames in |audio_bus|
143  //
144  // If this method returns fewer frames than the initial number of frames in
145  // |audio_bus|, it could be a sign that the pipeline is stalled or unable to
146  // stream the data fast enough.  In such scenarios, the callee should zero out
147  // unused portions of their buffer to play back silence.
148  //
149  // Render() updates the pipeline's playback timestamp. If Render() is
150  // not called at the same rate as audio samples are played, then the reported
151  // timestamp in the pipeline will be ahead of the actual audio playback. In
152  // this case |audio_delay_milliseconds| should be used to indicate when in the
153  // future should the filled buffer be played.
154  virtual int Render(AudioBus* audio_bus,
155                     int audio_delay_milliseconds) OVERRIDE;
156  virtual void OnRenderError() OVERRIDE;
157
158  // Helper methods that schedule an asynchronous read from the decoder as long
159  // as there isn't a pending read.
160  //
161  // Must be called on |task_runner_|.
162  void AttemptRead();
163  void AttemptRead_Locked();
164  bool CanRead_Locked();
165  void ChangeState_Locked(State new_state);
166
167  // Returns true if the data in the buffer is all before |start_timestamp_|.
168  // This can only return true while in the kPlaying state.
169  bool IsBeforeStartTime(const scoped_refptr<AudioBuffer>& buffer);
170
171  // Called upon AudioBufferStream initialization, or failure thereof (indicated
172  // by the value of |success|).
173  void OnAudioBufferStreamInitialized(bool succes);
174
175  // Used to initiate the flush operation once all pending reads have
176  // completed.
177  void DoFlush_Locked();
178
179  // Calls |decoder_|.Reset() and arranges for ResetDecoderDone() to get
180  // called when the reset completes.
181  void ResetDecoder();
182
183  // Called when the |decoder_|.Reset() has completed.
184  void ResetDecoderDone();
185
186  // Called by the AudioBufferStream when a splice buffer is demuxed.
187  void OnNewSpliceBuffer(base::TimeDelta);
188
189  // Called by the AudioBufferStream when a config change occurs.
190  void OnConfigChange();
191
192  // Updates |buffering_state_| and fires |buffering_state_cb_|.
193  void SetBufferingState_Locked(BufferingState buffering_state);
194
195  scoped_refptr<base::SingleThreadTaskRunner> task_runner_;
196
197  scoped_ptr<AudioSplicer> splicer_;
198  scoped_ptr<AudioBufferConverter> buffer_converter_;
199
200  // Whether or not we expect to handle config changes.
201  bool expecting_config_changes_;
202
203  // The sink (destination) for rendered audio. |sink_| must only be accessed
204  // on |task_runner_|. |sink_| must never be called under |lock_| or else we
205  // may deadlock between |task_runner_| and the audio callback thread.
206  scoped_refptr<media::AudioRendererSink> sink_;
207
208  scoped_ptr<AudioBufferStream> audio_buffer_stream_;
209
210  // Interface to the hardware audio params.
211  const AudioHardwareConfig& hardware_config_;
212
213  // Cached copy of hardware params from |hardware_config_|.
214  AudioParameters audio_parameters_;
215
216  // Callbacks provided during Initialize().
217  PipelineStatusCB init_cb_;
218  BufferingStateCB buffering_state_cb_;
219  base::Closure ended_cb_;
220  PipelineStatusCB error_cb_;
221
222  // Callback provided to Flush().
223  base::Closure flush_cb_;
224
225  // After Initialize() has completed, all variables below must be accessed
226  // under |lock_|. ------------------------------------------------------------
227  base::Lock lock_;
228
229  // Algorithm for scaling audio.
230  float playback_rate_;
231  scoped_ptr<AudioRendererAlgorithm> algorithm_;
232
233  // Simple state tracking variable.
234  State state_;
235
236  BufferingState buffering_state_;
237
238  // Keep track of whether or not the sink is playing and whether we should be
239  // rendering.
240  bool rendering_;
241  bool sink_playing_;
242
243  // Keep track of our outstanding read to |decoder_|.
244  bool pending_read_;
245
246  // Keeps track of whether we received and rendered the end of stream buffer.
247  bool received_end_of_stream_;
248  bool rendered_end_of_stream_;
249
250  scoped_ptr<AudioClock> audio_clock_;
251
252  // The media timestamp to begin playback at after seeking. Set via
253  // SetMediaTime().
254  base::TimeDelta start_timestamp_;
255
256  // The media timestamp to signal end of audio playback. Determined during
257  // Render() when writing the final frames of decoded audio data.
258  base::TimeDelta ended_timestamp_;
259
260  // Set every Render() and used to provide an interpolated time value to
261  // CurrentMediaTimeForSyncingVideo().
262  base::TimeTicks last_render_ticks_;
263
264  // End variables which must be accessed under |lock_|. ----------------------
265
266  // NOTE: Weak pointers must be invalidated before all other member variables.
267  base::WeakPtrFactory<AudioRendererImpl> weak_factory_;
268
269  DISALLOW_COPY_AND_ASSIGN(AudioRendererImpl);
270};
271
272}  // namespace media
273
274#endif  // MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_
275