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 17namespace base { 18class SingleThreadTaskRunner; 19} 20 21namespace media { 22 23class AudioInputStream; 24class AudioOutputStream; 25 26// Manages all audio resources. Provides some convenience functions that avoid 27// the need to provide iterators over the existing streams. 28class 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_ 195