media/audio/audio_output_controller.h

   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 #ifndef MEDIA_AUDIO_AUDIO_OUTPUT_CONTROLLER_H_
   6 #define MEDIA_AUDIO_AUDIO_OUTPUT_CONTROLLER_H_
   7
   8 #include "base/atomic_ref_count.h"
   9 #include "base/callback.h"
  10 #include "base/cancelable_callback.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "media/audio/audio_io.h"
  13 #include "media/audio/audio_manager.h"
  14 #include "media/audio/audio_power_monitor.h"
  15 #include "media/audio/audio_source_diverter.h"
  16 #include "media/audio/simple_sources.h"
  17 #include "media/base/media_export.h"
  18
  19 // An AudioOutputController controls an AudioOutputStream and provides data
  20 // to this output stream. It has an important function that it executes
  21 // audio operations like play, pause, stop, etc. on a separate thread,
  22 // namely the audio manager thread.
  23 //
  24 // All the public methods of AudioOutputController are non-blocking.
  25 // The actual operations are performed on the audio manager thread.
  26 //
  27 // Here is a state transition diagram for the AudioOutputController:
  28 //
  29 //   *[ Empty ]  -->  [ Created ]  -->  [ Playing ]  -------.
  30 //        |                |               |    ^           |
  31 //        |                |               |    |           |
  32 //        |                |               |    |           v
  33 //        |                |               |    `-----  [ Paused ]
  34 //        |                |               |                |
  35 //        |                v               v                |
  36 //        `----------->  [      Closed       ]  <-----------'
  37 //
  38 // * Initial state
  39 //
  40 // At any time after reaching the Created state but before Closed, the
  41 // AudioOutputController may be notified of a device change via
  42 // OnDeviceChange().  As the OnDeviceChange() is processed, state transitions
  43 // will occur, ultimately ending up in an equivalent pre-call state.  E.g., if
  44 // the state was Paused, the new state will be Created, since these states are
  45 // all functionally equivalent and require a Play() call to continue to the next
  46 // state.
  47 //
  48 // The AudioOutputStream can request data from the AudioOutputController via the
  49 // AudioSourceCallback interface. AudioOutputController uses the SyncReader
  50 // passed to it via construction to synchronously fulfill this read request.
  51 //
  52
  53 namespace media {
  54
  55 class MEDIA_EXPORT AudioOutputController
  56     : public base::RefCountedThreadSafe<AudioOutputController>,
  57       public AudioOutputStream::AudioSourceCallback,
  58       public AudioSourceDiverter,
  59       NON_EXPORTED_BASE(public AudioManager::AudioDeviceListener)  {
  60  public:
  61   // An event handler that receives events from the AudioOutputController. The
  62   // following methods are called on the audio manager thread.
  63   class MEDIA_EXPORT EventHandler {
  64    public:
  65     virtual void OnCreated() = 0;
  66     virtual void OnPlaying() = 0;
  67     virtual void OnPowerMeasured(float power_dbfs, bool clipped) = 0;
  68     virtual void OnPaused() = 0;
  69     virtual void OnError() = 0;
  70     virtual void OnDeviceChange(int new_buffer_size, int new_sample_rate) = 0;
  71
  72    protected:
  73     virtual ~EventHandler() {}
  74   };
  75
  76   // A synchronous reader interface used by AudioOutputController for
  77   // synchronous reading.
  78   // TODO(crogers): find a better name for this class and the Read() method
  79   // now that it can handle synchronized I/O.
  80   class SyncReader {
  81    public:
  82     virtual ~SyncReader() {}
  83
  84     // Notify the synchronous reader the number of bytes in the
  85     // AudioOutputController not yet played. This is used by SyncReader to
  86     // prepare more data and perform synchronization.
  87     virtual void UpdatePendingBytes(uint32 bytes) = 0;
  88
  89     // Attempt to completely fill |dest|, return the actual number of frames
  90     // that could be read.  |source| may optionally be provided for input data.
  91     // If |block| is specified, the Read() will block until data is available
  92     // or a timeout is reached.
  93     virtual int Read(bool block, const AudioBus* source, AudioBus* dest) = 0;
  94
  95     // Close this synchronous reader.
  96     virtual void Close() = 0;
  97   };
  98
  99   // Factory method for creating an AudioOutputController.
 100   // This also creates and opens an AudioOutputStream on the audio manager
 101   // thread, and if this is successful, the |event_handler| will receive an
 102   // OnCreated() call from the same audio manager thread.  |audio_manager| must
 103   // outlive AudioOutputController.
 104   static scoped_refptr<AudioOutputController> Create(
 105       AudioManager* audio_manager, EventHandler* event_handler,
 106       const AudioParameters& params, const std::string& input_device_id,
 107       SyncReader* sync_reader);
 108
 109   // Methods to control playback of the stream.
 110
 111   // Starts the playback of this audio output stream.
 112   void Play();
 113
 114   // Pause this audio output stream.
 115   void Pause();
 116
 117   // Closes the audio output stream. The state is changed and the resources
 118   // are freed on the audio manager thread. closed_task is executed after that.
 119   // Callbacks (EventHandler and SyncReader) must exist until closed_task is
 120   // called.
 121   //
 122   // It is safe to call this method more than once. Calls after the first one
 123   // will have no effect.
 124   void Close(const base::Closure& closed_task);
 125
 126   // Sets the volume of the audio output stream.
 127   void SetVolume(double volume);
 128
 129   // AudioSourceCallback implementation.
 130   virtual int OnMoreData(AudioBus* dest,
 131                          AudioBuffersState buffers_state) OVERRIDE;
 132   virtual int OnMoreIOData(AudioBus* source,
 133                            AudioBus* dest,
 134                            AudioBuffersState buffers_state) OVERRIDE;
 135   virtual void OnError(AudioOutputStream* stream) OVERRIDE;
 136
 137   // AudioDeviceListener implementation.  When called AudioOutputController will
 138   // shutdown the existing |stream_|, transition to the kRecreating state,
 139   // create a new stream, and then transition back to an equivalent state prior
 140   // to being called.
 141   virtual void OnDeviceChange() OVERRIDE;
 142
 143   // AudioSourceDiverter implementation.
 144   virtual const AudioParameters& GetAudioParameters() OVERRIDE;
 145   virtual void StartDiverting(AudioOutputStream* to_stream) OVERRIDE;
 146   virtual void StopDiverting() OVERRIDE;
 147
 148  protected:
 149   // Internal state of the source.
 150   enum State {
 151     kEmpty,
 152     kCreated,
 153     kPlaying,
 154     kPaused,
 155     kClosed,
 156     kError,
 157   };
 158
 159   friend class base::RefCountedThreadSafe<AudioOutputController>;
 160   virtual ~AudioOutputController();
 161
 162  private:
 163   // We are polling sync reader if data became available.
 164   static const int kPollNumAttempts;
 165   static const int kPollPauseInMilliseconds;
 166
 167   AudioOutputController(AudioManager* audio_manager, EventHandler* handler,
 168                         const AudioParameters& params,
 169                         const std::string& input_device_id,
 170                         SyncReader* sync_reader);
 171
 172   // The following methods are executed on the audio manager thread.
 173   void DoCreate(bool is_for_device_change);
 174   void DoPlay();
 175   void DoPause();
 176   void DoClose();
 177   void DoSetVolume(double volume);
 178   void DoReportError();
 179   void DoStartDiverting(AudioOutputStream* to_stream);
 180   void DoStopDiverting();
 181
 182   // Calls EventHandler::OnPowerMeasured() with the current power level and then
 183   // schedules itself to be called again later.
 184   void ReportPowerMeasurementPeriodically();
 185
 186   // Helper method that stops the physical stream.
 187   void StopStream();
 188
 189   // Helper method that stops, closes, and NULLs |*stream_|.
 190   void DoStopCloseAndClearStream();
 191
 192   // Sanity-check that entry/exit to OnMoreIOData() by the hardware audio thread
 193   // happens only between AudioOutputStream::Start() and Stop().
 194   void AllowEntryToOnMoreIOData();
 195   void DisallowEntryToOnMoreIOData();
 196
 197   AudioManager* const audio_manager_;
 198   const AudioParameters params_;
 199   EventHandler* const handler_;
 200
 201   // Used by the unified IO to open the correct input device.
 202   std::string input_device_id_;
 203
 204   AudioOutputStream* stream_;
 205
 206   // When non-NULL, audio is being diverted to this stream.
 207   AudioOutputStream* diverting_to_stream_;
 208
 209   // The current volume of the audio stream.
 210   double volume_;
 211
 212   // |state_| is written on the audio manager thread and is read on the
 213   // hardware audio thread. These operations need to be locked. But lock
 214   // is not required for reading on the audio manager thread.
 215   State state_;
 216
 217   // Binary semaphore, used to ensure that only one thread enters the
 218   // OnMoreIOData() method, and only when it is valid to do so.  This is for
 219   // sanity-checking the behavior of platform implementations of
 220   // AudioOutputStream.  In other words, multiple contention is not expected,
 221   // nor in the design here.
 222   base::AtomicRefCount num_allowed_io_;
 223
 224   // SyncReader is used only in low latency mode for synchronous reading.
 225   SyncReader* const sync_reader_;
 226
 227   // The message loop of audio manager thread that this object runs on.
 228   const scoped_refptr<base::MessageLoopProxy> message_loop_;
 229
 230   // When starting stream we wait for data to become available.
 231   // Number of times left.
 232   int number_polling_attempts_left_;
 233
 234   // Scans audio samples from OnMoreIOData() as input to compute power levels.
 235   AudioPowerMonitor power_monitor_;
 236
 237   // Periodic callback to report power levels during playback.
 238   base::CancelableClosure power_poll_callback_;
 239
 240   DISALLOW_COPY_AND_ASSIGN(AudioOutputController);
 241 };
 242
 243 }  // namespace media
 244
 245 #endif  // MEDIA_AUDIO_AUDIO_OUTPUT_CONTROLLER_H_