src/media/audio/audio_manager.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_MANAGER_H_
   6 #define MEDIA_AUDIO_AUDIO_MANAGER_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/strings/string16.h"
  13 #include "media/audio/audio_device_name.h"
  14 #include "media/audio/audio_logging.h"
  15 #include "media/audio/audio_parameters.h"
  16
  17 namespace base {
  18 class SingleThreadTaskRunner;
  19 }
  20
  21 namespace media {
  22
  23 class AudioInputStream;
  24 class AudioOutputStream;
  25
  26 // Manages all audio resources.  Provides some convenience functions that avoid
  27 // the need to provide iterators over the existing streams.
  28 class MEDIA_EXPORT AudioManager {
  29   public:
  30    virtual ~AudioManager();
  31
  32   // Construct the audio manager; only one instance is allowed.  The manager
  33   // will forward CreateAudioLog() calls to the provided AudioLogFactory; as
  34   // such |audio_log_factory| must outlive the AudioManager.
  35   static AudioManager* Create(AudioLogFactory* audio_log_factory);
  36
  37   // Similar to Create() except uses a FakeAudioLogFactory for testing.
  38   static AudioManager* CreateForTesting();
  39
  40   // Returns the pointer to the last created instance, or NULL if not yet
  41   // created. This is a utility method for the code outside of media directory,
  42   // like src/chrome.
  43   static AudioManager* Get();
  44
  45   // Returns true if the OS reports existence of audio devices. This does not
  46   // guarantee that the existing devices support all formats and sample rates.
  47   virtual bool HasAudioOutputDevices() = 0;
  48
  49   // Returns true if the OS reports existence of audio recording devices. This
  50   // does not guarantee that the existing devices support all formats and
  51   // sample rates.
  52   virtual bool HasAudioInputDevices() = 0;
  53
  54   // Returns a human readable string for the model/make of the active audio
  55   // input device for this computer.
  56   virtual base::string16 GetAudioInputDeviceModel() = 0;
  57
  58   // Opens the platform default audio input settings UI.
  59   // Note: This could invoke an external application/preferences pane, so
  60   // ideally must not be called from the UI thread or other time sensitive
  61   // threads to avoid blocking the rest of the application.
  62   virtual void ShowAudioInputSettings() = 0;
  63
  64   // Appends a list of available input devices to |device_names|,
  65   // which must initially be empty. It is not guaranteed that all the
  66   // devices in the list support all formats and sample rates for
  67   // recording.
  68   //
  69   // Not threadsafe; in production this should only be called from the
  70   // Audio IO thread (see GetTaskRunner()).
  71   virtual void GetAudioInputDeviceNames(AudioDeviceNames* device_names) = 0;
  72
  73   // Appends a list of available output devices to |device_names|,
  74   // which must initially be empty.
  75   //
  76   // Not threadsafe; in production this should only be called from the
  77   // Audio IO thread (see GetTaskRunner()).
  78   virtual void GetAudioOutputDeviceNames(AudioDeviceNames* device_names) = 0;
  79
  80   // Factory for all the supported stream formats. |params| defines parameters
  81   // of the audio stream to be created.
  82   //
  83   // |params.sample_per_packet| is the requested buffer allocation which the
  84   // audio source thinks it can usually fill without blocking. Internally two
  85   // or three buffers are created, one will be locked for playback and one will
  86   // be ready to be filled in the call to AudioSourceCallback::OnMoreData().
  87   //
  88   // To create a stream for the default output device, pass an empty string
  89   // for |device_id|, otherwise the specified audio device will be opened.
  90   //
  91   // The |input_device_id| is used for low-latency unified streams
  92   // (input+output) only and then only if the audio parameters specify a >0
  93   // input channel count.  In other cases this id is ignored and should be
  94   // empty.
  95   //
  96   // Returns NULL if the combination of the parameters is not supported, or if
  97   // we have reached some other platform specific limit.
  98   //
  99   // |params.format| can be set to AUDIO_PCM_LOW_LATENCY and that has two
 100   // effects:
 101   // 1- Instead of triple buffered the audio will be double buffered.
 102   // 2- A low latency driver or alternative audio subsystem will be used when
 103   //    available.
 104   //
 105   // Do not free the returned AudioOutputStream. It is owned by AudioManager.
 106   virtual AudioOutputStream* MakeAudioOutputStream(
 107       const AudioParameters& params,
 108       const std::string& device_id,
 109       const std::string& input_device_id) = 0;
 110
 111   // Creates new audio output proxy. A proxy implements
 112   // AudioOutputStream interface, but unlike regular output stream
 113   // created with MakeAudioOutputStream() it opens device only when a
 114   // sound is actually playing.
 115   virtual AudioOutputStream* MakeAudioOutputStreamProxy(
 116       const AudioParameters& params,
 117       const std::string& device_id,
 118       const std::string& input_device_id) = 0;
 119
 120   // Factory to create audio recording streams.
 121   // |channels| can be 1 or 2.
 122   // |sample_rate| is in hertz and can be any value supported by the platform.
 123   // |bits_per_sample| can be any value supported by the platform.
 124   // |samples_per_packet| is in hertz as well and can be 0 to |sample_rate|,
 125   // with 0 suggesting that the implementation use a default value for that
 126   // platform.
 127   // Returns NULL if the combination of the parameters is not supported, or if
 128   // we have reached some other platform specific limit.
 129   //
 130   // Do not free the returned AudioInputStream. It is owned by AudioManager.
 131   // When you are done with it, call |Stop()| and |Close()| to release it.
 132   virtual AudioInputStream* MakeAudioInputStream(
 133       const AudioParameters& params, const std::string& device_id) = 0;
 134
 135   // Returns the task runner used for audio IO.
 136   virtual scoped_refptr<base::SingleThreadTaskRunner> GetTaskRunner() = 0;
 137
 138   // Heavyweight tasks should use GetWorkerTaskRunner() instead of
 139   // GetTaskRunner(). On most platforms they are the same, but some share the
 140   // UI loop with the audio IO loop.
 141   virtual scoped_refptr<base::SingleThreadTaskRunner> GetWorkerTaskRunner() = 0;
 142
 143   // Allows clients to listen for device state changes; e.g. preferred sample
 144   // rate or channel layout changes.  The typical response to receiving this
 145   // callback is to recreate the stream.
 146   class AudioDeviceListener {
 147    public:
 148     virtual void OnDeviceChange() = 0;
 149   };
 150
 151   virtual void AddOutputDeviceChangeListener(AudioDeviceListener* listener) = 0;
 152   virtual void RemoveOutputDeviceChangeListener(
 153       AudioDeviceListener* listener) = 0;
 154
 155   // Returns the default output hardware audio parameters for opening output
 156   // streams. It is a convenience interface to
 157   // AudioManagerBase::GetPreferredOutputStreamParameters and each AudioManager
 158   // does not need their own implementation to this interface.
 159   // TODO(tommi): Remove this method and use GetOutputStreamParameteres instead.
 160   virtual AudioParameters GetDefaultOutputStreamParameters() = 0;
 161
 162   // Returns the output hardware audio parameters for a specific output device.
 163   virtual AudioParameters GetOutputStreamParameters(
 164       const std::string& device_id) = 0;
 165
 166   // Returns the input hardware audio parameters of the specific device
 167   // for opening input streams. Each AudioManager needs to implement their own
 168   // version of this interface.
 169   virtual AudioParameters GetInputStreamParameters(
 170       const std::string& device_id) = 0;
 171
 172   // Returns the device id of an output device that belongs to the same hardware
 173   // as the specified input device.
 174   // If the hardware has only an input device (e.g. a webcam), the return value
 175   // will be empty (which the caller can then interpret to be the default output
 176   // device).  Implementations that don't yet support this feature, must return
 177   // an empty string.
 178   virtual std::string GetAssociatedOutputDeviceID(
 179       const std::string& input_device_id) = 0;
 180
 181   // Create a new AudioLog object for tracking the behavior for one or more
 182   // instances of the given component.  See AudioLogFactory for more details.
 183   virtual scoped_ptr<AudioLog> CreateAudioLog(
 184       AudioLogFactory::AudioComponent component) = 0;
 185
 186   // Called when a component has detected a OS level audio wedge.  Shuts down
 187   // all active audio streams and then restarts them transparently.  See
 188   // http://crbug.com/160920
 189   virtual void FixWedgedAudio() = 0;
 190
 191  protected:
 192   AudioManager();
 193
 194  private:
 195   DISALLOW_COPY_AND_ASSIGN(AudioManager);
 196 };
 197
 198 }  // namespace media
 199
 200 #endif  // MEDIA_AUDIO_AUDIO_MANAGER_H_