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 worker thread (see GetWorkerTaskRunner()).
  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 worker thread (see GetWorkerTaskRunner()).
  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   // Returns NULL if the combination of the parameters is not supported, or if
  92   // we have reached some other platform specific limit.
  93   //
  94   // |params.format| can be set to AUDIO_PCM_LOW_LATENCY and that has two
  95   // effects:
  96   // 1- Instead of triple buffered the audio will be double buffered.
  97   // 2- A low latency driver or alternative audio subsystem will be used when
  98   //    available.
  99   //
 100   // Do not free the returned AudioOutputStream. It is owned by AudioManager.
 101   virtual AudioOutputStream* MakeAudioOutputStream(
 102       const AudioParameters& params,
 103       const std::string& device_id) = 0;
 104
 105   // Creates new audio output proxy. A proxy implements
 106   // AudioOutputStream interface, but unlike regular output stream
 107   // created with MakeAudioOutputStream() it opens device only when a
 108   // sound is actually playing.
 109   virtual AudioOutputStream* MakeAudioOutputStreamProxy(
 110       const AudioParameters& params,
 111       const std::string& device_id) = 0;
 112
 113   // Factory to create audio recording streams.
 114   // |channels| can be 1 or 2.
 115   // |sample_rate| is in hertz and can be any value supported by the platform.
 116   // |bits_per_sample| can be any value supported by the platform.
 117   // |samples_per_packet| is in hertz as well and can be 0 to |sample_rate|,
 118   // with 0 suggesting that the implementation use a default value for that
 119   // platform.
 120   // Returns NULL if the combination of the parameters is not supported, or if
 121   // we have reached some other platform specific limit.
 122   //
 123   // Do not free the returned AudioInputStream. It is owned by AudioManager.
 124   // When you are done with it, call |Stop()| and |Close()| to release it.
 125   virtual AudioInputStream* MakeAudioInputStream(
 126       const AudioParameters& params, const std::string& device_id) = 0;
 127
 128   // Returns the task runner used for audio IO.
 129   virtual scoped_refptr<base::SingleThreadTaskRunner> GetTaskRunner() = 0;
 130
 131   // Heavyweight tasks should use GetWorkerTaskRunner() instead of
 132   // GetTaskRunner(). On most platforms they are the same, but some share the
 133   // UI loop with the audio IO loop.
 134   virtual scoped_refptr<base::SingleThreadTaskRunner> GetWorkerTaskRunner() = 0;
 135
 136   // Allows clients to listen for device state changes; e.g. preferred sample
 137   // rate or channel layout changes.  The typical response to receiving this
 138   // callback is to recreate the stream.
 139   class AudioDeviceListener {
 140    public:
 141     virtual void OnDeviceChange() = 0;
 142   };
 143
 144   virtual void AddOutputDeviceChangeListener(AudioDeviceListener* listener) = 0;
 145   virtual void RemoveOutputDeviceChangeListener(
 146       AudioDeviceListener* listener) = 0;
 147
 148   // Returns the default output hardware audio parameters for opening output
 149   // streams. It is a convenience interface to
 150   // AudioManagerBase::GetPreferredOutputStreamParameters and each AudioManager
 151   // does not need their own implementation to this interface.
 152   // TODO(tommi): Remove this method and use GetOutputStreamParameteres instead.
 153   virtual AudioParameters GetDefaultOutputStreamParameters() = 0;
 154
 155   // Returns the output hardware audio parameters for a specific output device.
 156   virtual AudioParameters GetOutputStreamParameters(
 157       const std::string& device_id) = 0;
 158
 159   // Returns the input hardware audio parameters of the specific device
 160   // for opening input streams. Each AudioManager needs to implement their own
 161   // version of this interface.
 162   virtual AudioParameters GetInputStreamParameters(
 163       const std::string& device_id) = 0;
 164
 165   // Returns the device id of an output device that belongs to the same hardware
 166   // as the specified input device.
 167   // If the hardware has only an input device (e.g. a webcam), the return value
 168   // will be empty (which the caller can then interpret to be the default output
 169   // device).  Implementations that don't yet support this feature, must return
 170   // an empty string. Must be called on the audio worker thread (see
 171   // GetWorkerTaskRunner()).
 172   virtual std::string GetAssociatedOutputDeviceID(
 173       const std::string& input_device_id) = 0;
 174
 175   // Create a new AudioLog object for tracking the behavior for one or more
 176   // instances of the given component.  See AudioLogFactory for more details.
 177   virtual scoped_ptr<AudioLog> CreateAudioLog(
 178       AudioLogFactory::AudioComponent component) = 0;
 179
 180   // Informs the audio manager that the system has support for a keyboard mic.
 181   // This information will be passed on in the return value of
 182   // GetInputStreamParameters as an effect. Only supported on ChromeOS.
 183   virtual void SetHasKeyboardMic() = 0;
 184
 185  protected:
 186   AudioManager();
 187
 188  private:
 189   DISALLOW_COPY_AND_ASSIGN(AudioManager);
 190 };
 191
 192 }  // namespace media
 193
 194 #endif  // MEDIA_AUDIO_AUDIO_MANAGER_H_