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