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. It is not guaranteed that
  62   // all the devices in the list support all formats and sample rates for
  63   // recording.
  64   virtual void GetAudioInputDeviceNames(AudioDeviceNames* device_names) = 0;
  65
  66   // Factory for all the supported stream formats. |params| defines parameters
  67   // of the audio stream to be created.
  68   //
  69   // |params.sample_per_packet| is the requested buffer allocation which the
  70   // audio source thinks it can usually fill without blocking. Internally two
  71   // or three buffers are created, one will be locked for playback and one will
  72   // be ready to be filled in the call to AudioSourceCallback::OnMoreData().
  73   //
  74   // Returns NULL if the combination of the parameters is not supported, or if
  75   // we have reached some other platform specific limit.
  76   //
  77   // |params.format| can be set to AUDIO_PCM_LOW_LATENCY and that has two
  78   // effects:
  79   // 1- Instead of triple buffered the audio will be double buffered.
  80   // 2- A low latency driver or alternative audio subsystem will be used when
  81   //    available.
  82   //
  83   // Do not free the returned AudioOutputStream. It is owned by AudioManager.
  84   virtual AudioOutputStream* MakeAudioOutputStream(
  85       const AudioParameters& params, const std::string& input_device_id) = 0;
  86
  87   // Creates new audio output proxy. A proxy implements
  88   // AudioOutputStream interface, but unlike regular output stream
  89   // created with MakeAudioOutputStream() it opens device only when a
  90   // sound is actually playing.
  91   virtual AudioOutputStream* MakeAudioOutputStreamProxy(
  92       const AudioParameters& params, const std::string& input_device_id) = 0;
  93
  94   // Factory to create audio recording streams.
  95   // |channels| can be 1 or 2.
  96   // |sample_rate| is in hertz and can be any value supported by the platform.
  97   // |bits_per_sample| can be any value supported by the platform.
  98   // |samples_per_packet| is in hertz as well and can be 0 to |sample_rate|,
  99   // with 0 suggesting that the implementation use a default value for that
 100   // platform.
 101   // Returns NULL if the combination of the parameters is not supported, or if
 102   // we have reached some other platform specific limit.
 103   //
 104   // Do not free the returned AudioInputStream. It is owned by AudioManager.
 105   // When you are done with it, call |Stop()| and |Close()| to release it.
 106   virtual AudioInputStream* MakeAudioInputStream(
 107       const AudioParameters& params, const std::string& device_id) = 0;
 108
 109   // Returns message loop used for audio IO.
 110   virtual scoped_refptr<base::MessageLoopProxy> GetMessageLoop() = 0;
 111
 112   // Heavyweight tasks should use GetWorkerLoop() instead of GetMessageLoop().
 113   // On most platforms they are the same, but some share the UI loop with the
 114   // audio IO loop.
 115   virtual scoped_refptr<base::MessageLoopProxy> GetWorkerLoop() = 0;
 116
 117   // Allows clients to listen for device state changes; e.g. preferred sample
 118   // rate or channel layout changes.  The typical response to receiving this
 119   // callback is to recreate the stream.
 120   class AudioDeviceListener {
 121    public:
 122     virtual void OnDeviceChange() = 0;
 123   };
 124
 125   virtual void AddOutputDeviceChangeListener(AudioDeviceListener* listener) = 0;
 126   virtual void RemoveOutputDeviceChangeListener(
 127       AudioDeviceListener* listener) = 0;
 128
 129   // Returns the default output hardware audio parameters for opening output
 130   // streams. It is a convenience interface to
 131   // AudioManagerBase::GetPreferredOutputStreamParameters and each AudioManager
 132   // does not need their own implementation to this interface.
 133   virtual AudioParameters GetDefaultOutputStreamParameters() = 0;
 134
 135   // Returns the input hardware audio parameters of the specific device
 136   // for opening input streams. Each AudioManager needs to implement their own
 137   // version of this interface.
 138   virtual AudioParameters GetInputStreamParameters(
 139       const std::string& device_id) = 0;
 140
 141  protected:
 142   AudioManager();
 143
 144  private:
 145   DISALLOW_COPY_AND_ASSIGN(AudioManager);
 146 };
 147
 148 }  // namespace media
 149
 150 #endif  // MEDIA_AUDIO_AUDIO_MANAGER_H_