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