Home | History | Annotate | Download | only in audio 
      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_
    151