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