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