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/callback.h"
   9 #include "base/memory/ref_counted.h"
  10 #include "base/memory/weak_ptr.h"
  11 #include "base/synchronization/lock.h"
  12 #include "media/audio/audio_buffers_state.h"
  13 #include "media/audio/audio_io.h"
  14 #include "media/audio/audio_manager.h"
  15 #include "media/audio/simple_sources.h"
  16 #include "media/base/media_export.h"
  17
  18 namespace base {
  19 class WaitableEvent;
  20 }  // namespace base
  21
  22 class MessageLoop;
  23
  24 // An AudioOutputController controls an AudioOutputStream and provides data
  25 // to this output stream. It has an important function that it executes
  26 // audio operations like play, pause, stop, etc. on a separate thread,
  27 // namely the audio manager thread.
  28 //
  29 // All the public methods of AudioOutputController are non-blocking.
  30 // The actual operations are performed on the audio manager thread.
  31 //
  32 // Here is a state diagram for the AudioOutputController:
  33 //
  34 //             .----------------------->  [ Closed / Error ]  <------.
  35 //             |                                   ^                 |
  36 //             |                                   |                 |
  37 //        [ Created ]  -->  [ Starting ]  -->  [ Playing ]  -->  [ Paused ]
  38 //             ^                 |                 ^                |  ^
  39 //             |                 |                 |                |  |
  40 //             |                 |                 `----------------'  |
  41 //             |                 V                                     |
  42 //             |        [ PausedWhenStarting ] ------------------------'
  43 //             |
  44 //       *[  Empty  ]
  45 //
  46 // * Initial state
  47 //
  48 // At any time after reaching the Created state but before Closed / Error, the
  49 // AudioOutputController may be notified of a device change via OnDeviceChange()
  50 // and transition to the Recreating state.  If OnDeviceChange() completes
  51 // successfully the state will transition back to an equivalent pre-call state.
  52 // E.g., if the state was Paused or PausedWhenStarting, the new state will be
  53 // Created, since these states are all functionally equivalent and require a
  54 // Play() call to continue to the next state.
  55 //
  56 // The AudioOutputStream can request data from the AudioOutputController via the
  57 // AudioSourceCallback interface. AudioOutputController uses the SyncReader
  58 // passed to it via construction to synchronously fulfill this read request.
  59 //
  60 // Since AudioOutputController uses AudioManager's message loop the controller
  61 // uses WeakPtr to allow safe cancellation of pending tasks.
  62 //
  63
  64 namespace media {
  65
  66 class MEDIA_EXPORT AudioOutputController
  67     : public base::RefCountedThreadSafe<AudioOutputController>,
  68       public AudioOutputStream::AudioSourceCallback,
  69       NON_EXPORTED_BASE(public AudioManager::AudioDeviceListener)  {
  70  public:
  71   // An event handler that receives events from the AudioOutputController. The
  72   // following methods are called on the audio manager thread.
  73   class MEDIA_EXPORT EventHandler {
  74    public:
  75     virtual void OnCreated(AudioOutputController* controller) = 0;
  76     virtual void OnPlaying(AudioOutputController* controller) = 0;
  77     virtual void OnPaused(AudioOutputController* controller) = 0;
  78     virtual void OnError(AudioOutputController* controller, int error_code) = 0;
  79
  80    protected:
  81     virtual ~EventHandler() {}
  82   };
  83
  84   // A synchronous reader interface used by AudioOutputController for
  85   // synchronous reading.
  86   // TODO(crogers): find a better name for this class and the Read() method
  87   // now that it can handle synchronized I/O.
  88   class SyncReader {
  89    public:
  90     virtual ~SyncReader() {}
  91
  92     // Notify the synchronous reader the number of bytes in the
  93     // AudioOutputController not yet played. This is used by SyncReader to
  94     // prepare more data and perform synchronization.
  95     virtual void UpdatePendingBytes(uint32 bytes) = 0;
  96
  97     // Attempt to completely fill |dest|, return the actual number of
  98     // frames that could be read.
  99     // |source| may optionally be provided for input data.
 100     virtual int Read(AudioBus* source, AudioBus* dest) = 0;
 101
 102     // Close this synchronous reader.
 103     virtual void Close() = 0;
 104
 105     // Check if data is ready.
 106     virtual bool DataReady() = 0;
 107   };
 108
 109   // Factory method for creating an AudioOutputController.
 110   // This also creates and opens an AudioOutputStream on the audio manager
 111   // thread, and if this is successful, the |event_handler| will receive an
 112   // OnCreated() call from the same audio manager thread.  |audio_manager| must
 113   // outlive AudioOutputController.
 114   static scoped_refptr<AudioOutputController> Create(
 115       AudioManager* audio_manager, EventHandler* event_handler,
 116       const AudioParameters& params, 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   // Discard all audio data buffered in this output stream. This method only
 127   // has effect when the stream is paused.
 128   void Flush();
 129
 130   // Closes the audio output stream. The state is changed and the resources
 131   // are freed on the audio manager thread. closed_task is executed after that.
 132   // Callbacks (EventHandler and SyncReader) must exist until closed_task is
 133   // called.
 134   //
 135   // It is safe to call this method more than once. Calls after the first one
 136   // will have no effect.
 137   void Close(const base::Closure& closed_task);
 138
 139   // Sets the volume of the audio output stream.
 140   void SetVolume(double volume);
 141
 142   // AudioSourceCallback implementation.
 143   virtual int OnMoreData(AudioBus* dest,
 144                          AudioBuffersState buffers_state) OVERRIDE;
 145   virtual int OnMoreIOData(AudioBus* source,
 146                            AudioBus* dest,
 147                            AudioBuffersState buffers_state) OVERRIDE;
 148   virtual void OnError(AudioOutputStream* stream, int code) OVERRIDE;
 149   virtual void WaitTillDataReady() OVERRIDE;
 150
 151   // AudioDeviceListener implementation.  When called AudioOutputController will
 152   // shutdown the existing |stream_|, transition to the kRecreating state,
 153   // create a new stream, and then transition back to an equivalent state prior
 154   // to being called.
 155   virtual void OnDeviceChange() OVERRIDE;
 156
 157  protected:
 158     // Internal state of the source.
 159   enum State {
 160     kEmpty,
 161     kCreated,
 162     kPlaying,
 163     kStarting,
 164     kPausedWhenStarting,
 165     kPaused,
 166     kClosed,
 167     kError,
 168     kRecreating,
 169   };
 170
 171   friend class base::RefCountedThreadSafe<AudioOutputController>;
 172   virtual ~AudioOutputController();
 173
 174  private:
 175   // We are polling sync reader if data became available.
 176   static const int kPollNumAttempts;
 177   static const int kPollPauseInMilliseconds;
 178
 179   AudioOutputController(AudioManager* audio_manager, EventHandler* handler,
 180                         const AudioParameters& params, SyncReader* sync_reader);
 181
 182   // The following methods are executed on the audio manager thread.
 183   void DoCreate();
 184   void DoPlay();
 185   void PollAndStartIfDataReady();
 186   void DoPause();
 187   void DoFlush();
 188   void DoClose();
 189   void DoSetVolume(double volume);
 190   void DoReportError(int code);
 191
 192   // Helper method that starts physical stream.
 193   void StartStream();
 194
 195   // Helper method that stops, closes, and NULLs |*stream_|.
 196   // Signals event when done if it is not NULL.
 197   void DoStopCloseAndClearStream(base::WaitableEvent *done);
 198
 199   AudioManager* const audio_manager_;
 200
 201   // |handler_| may be called only if |state_| is not kClosed.
 202   EventHandler* handler_;
 203
 204   // Note: It's important to invalidate the weak pointers whenever stream_ is
 205   // changed.  See comment for weak_this_.
 206   AudioOutputStream* stream_;
 207
 208   // The current volume of the audio stream.
 209   double volume_;
 210
 211   // |state_| is written on the audio manager thread and is read on the
 212   // hardware audio thread. These operations need to be locked. But lock
 213   // is not required for reading on the audio manager thread.
 214   State state_;
 215
 216   // The |lock_| must be acquired whenever we access |state_| from a thread
 217   // other than the audio manager thread.
 218   base::Lock lock_;
 219
 220   // SyncReader is used only in low latency mode for synchronous reading.
 221   SyncReader* sync_reader_;
 222
 223   // The message loop of audio manager thread that this object runs on.
 224   scoped_refptr<base::MessageLoopProxy> message_loop_;
 225
 226   // When starting stream we wait for data to become available.
 227   // Number of times left.
 228   int number_polling_attempts_left_;
 229
 230   AudioParameters params_;
 231
 232   // Used to auto-cancel the delayed tasks that are created to poll for data
 233   // (when starting-up a stream).
 234   base::WeakPtrFactory<AudioOutputController> weak_this_;
 235
 236   DISALLOW_COPY_AND_ASSIGN(AudioOutputController);
 237 };
 238
 239 }  // namespace media
 240
 241 #endif  // MEDIA_AUDIO_AUDIO_OUTPUT_CONTROLLER_H_