audio_manager.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266
  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. #ifndef MEDIA_AUDIO_AUDIO_MANAGER_H_
  5. #define MEDIA_AUDIO_AUDIO_MANAGER_H_
  6. #include <memory>
  7. #include <string>
  8. #include "base/callback.h"
  9. #include "base/gtest_prod_util.h"
  10. #include "base/memory/ref_counted.h"
  11. #include "base/threading/thread_checker.h"
  12. #include "build/build_config.h"
  13. #include "media/audio/audio_device_description.h"
  14. #include "media/audio/audio_logging.h"
  15. #include "media/audio/audio_thread.h"
  16. #include "media/base/audio_parameters.h"
  17. namespace base {
  18. class SingleThreadTaskRunner;
  19. }
  20. namespace audio {
  21. class AudioManagerPowerUser;
  22. } // namespace audio
  23. namespace media {
  24. class AudioDebugRecordingManager;
  25. class AudioInputStream;
  26. class AudioManager;
  27. class AudioOutputStream;
  28. // Manages all audio resources. Provides some convenience functions that avoid
  29. // the need to provide iterators over the existing streams.
  30. class MEDIA_EXPORT AudioManager {
  31. public:
  32. AudioManager(const AudioManager&) = delete;
  33. AudioManager& operator=(const AudioManager&) = delete;
  34. virtual ~AudioManager();
  35. // Construct the audio manager; only one instance is allowed.
  36. //
  37. // The manager will forward CreateAudioLog() calls to the provided
  38. // AudioLogFactory; as such |audio_log_factory| must outlive the AudioManager.
  39. //
  40. // The manager will use |audio_thread->GetTaskRunner()| for audio IO.
  41. // On OS_MAC, CoreAudio requires that |audio_thread->GetTaskRunner()|
  42. // must belong to the main thread of the process, which in our case is sadly
  43. // the browser UI thread. Failure to execute calls on the right thread leads
  44. // to crashes and odd behavior. See http://crbug.com/158170.
  45. //
  46. // The manager will use |audio_thread->GetWorkerTaskRunner()| for heavyweight
  47. // tasks. The |audio_thread->GetWorkerTaskRunner()| may be the same as
  48. // |audio_thread->GetTaskRunner()|.
  49. static std::unique_ptr<AudioManager> Create(
  50. std::unique_ptr<AudioThread> audio_thread,
  51. AudioLogFactory* audio_log_factory);
  52. // A convenience wrapper of AudioManager::Create for testing.
  53. static std::unique_ptr<AudioManager> CreateForTesting(
  54. std::unique_ptr<AudioThread> audio_thread);
  55. // Sets the name of the audio source as seen by external apps.
  56. static void SetGlobalAppName(const std::string& app_name);
  57. // Returns the app name or an empty string if it is not set.
  58. static const std::string& GetGlobalAppName();
  59. // Returns the pointer to the last created instance, or NULL if not yet
  60. // created. This is a utility method for the code outside of media directory,
  61. // like src/chrome.
  62. static AudioManager* Get();
  63. // Synchronously releases all audio resources.
  64. // Must be called before deletion and on the same thread as AudioManager
  65. // was created.
  66. // Returns true on success but false if AudioManager could not be shutdown.
  67. // AudioManager instance must not be deleted if shutdown failed.
  68. virtual bool Shutdown();
  69. // Log callback used for sending log messages from a stream to the object
  70. // that manages the stream.
  71. using LogCallback = base::RepeatingCallback<void(const std::string&)>;
  72. // Factory for all the supported stream formats. |params| defines parameters
  73. // of the audio stream to be created.
  74. //
  75. // |params.sample_per_packet| is the requested buffer allocation which the
  76. // audio source thinks it can usually fill without blocking. Internally two
  77. // or three buffers are created, one will be locked for playback and one will
  78. // be ready to be filled in the call to AudioSourceCallback::OnMoreData().
  79. //
  80. // To create a stream for the default output device, pass an empty string
  81. // for |device_id|, otherwise the specified audio device will be opened.
  82. //
  83. // Returns NULL if the combination of the parameters is not supported, or if
  84. // we have reached some other platform specific limit.
  85. //
  86. // |params.format| can be set to AUDIO_PCM_LOW_LATENCY and that has two
  87. // effects:
  88. // 1- Instead of triple buffered the audio will be double buffered.
  89. // 2- A low latency driver or alternative audio subsystem will be used when
  90. // available.
  91. //
  92. // Do not free the returned AudioOutputStream. It is owned by AudioManager.
  93. virtual AudioOutputStream* MakeAudioOutputStream(
  94. const AudioParameters& params,
  95. const std::string& device_id,
  96. const LogCallback& log_callback) = 0;
  97. // Creates new audio output proxy. A proxy implements
  98. // AudioOutputStream interface, but unlike regular output stream
  99. // created with MakeAudioOutputStream() it opens device only when a
  100. // sound is actually playing.
  101. virtual AudioOutputStream* MakeAudioOutputStreamProxy(
  102. const AudioParameters& params,
  103. const std::string& device_id) = 0;
  104. // Factory to create audio recording streams.
  105. // |channels| can be 1 or 2.
  106. // |sample_rate| is in hertz and can be any value supported by the platform.
  107. // |samples_per_packet| is in hertz as well and can be 0 to |sample_rate|,
  108. // with 0 suggesting that the implementation use a default value for that
  109. // platform.
  110. // Returns NULL if the combination of the parameters is not supported, or if
  111. // we have reached some other platform specific limit.
  112. //
  113. // Do not free the returned AudioInputStream. It is owned by AudioManager.
  114. // When you are done with it, call |Stop()| and |Close()| to release it.
  115. virtual AudioInputStream* MakeAudioInputStream(
  116. const AudioParameters& params,
  117. const std::string& device_id,
  118. const LogCallback& log_callback) = 0;
  119. // Returns the task runner used for audio IO.
  120. base::SingleThreadTaskRunner* GetTaskRunner() const {
  121. return audio_thread_->GetTaskRunner();
  122. }
  123. // Heavyweight tasks should use GetWorkerTaskRunner() instead of
  124. // GetTaskRunner(). On most platforms they are the same, but some share the
  125. // UI loop with the audio IO loop.
  126. base::SingleThreadTaskRunner* GetWorkerTaskRunner() const {
  127. return audio_thread_->GetWorkerTaskRunner();
  128. }
  129. // Allows clients to listen for device state changes; e.g. preferred sample
  130. // rate or channel layout changes. The typical response to receiving this
  131. // callback is to recreate the stream.
  132. class AudioDeviceListener {
  133. public:
  134. virtual void OnDeviceChange() = 0;
  135. };
  136. virtual void AddOutputDeviceChangeListener(AudioDeviceListener* listener) = 0;
  137. virtual void RemoveOutputDeviceChangeListener(
  138. AudioDeviceListener* listener) = 0;
  139. // Create a new AudioLog object for tracking the behavior for one or more
  140. // instances of the given component. See AudioLogFactory for more details.
  141. virtual std::unique_ptr<AudioLog> CreateAudioLog(
  142. AudioLogFactory::AudioComponent component,
  143. int component_id) = 0;
  144. // Get debug recording manager. This can only be called on AudioManager's
  145. // thread (GetTaskRunner()).
  146. virtual AudioDebugRecordingManager* GetAudioDebugRecordingManager() = 0;
  147. // Gets the name of the audio manager (e.g., Windows, Mac, PulseAudio).
  148. virtual const char* GetName() = 0;
  149. // Limits the number of streams that can be created for testing purposes.
  150. virtual void SetMaxStreamCountForTesting(int max_input, int max_output);
  151. protected:
  152. FRIEND_TEST_ALL_PREFIXES(AudioManagerTest, AudioDebugRecording);
  153. friend class AudioDeviceInfoAccessorForTests;
  154. friend class audio::AudioManagerPowerUser;
  155. explicit AudioManager(std::unique_ptr<AudioThread> audio_thread);
  156. virtual void ShutdownOnAudioThread() = 0;
  157. // Initializes debug recording. Can be called on any thread; will post to the
  158. // audio thread if not called on it.
  159. virtual void InitializeDebugRecording() = 0;
  160. // Returns true if the OS reports existence of audio devices. This does not
  161. // guarantee that the existing devices support all formats and sample rates.
  162. virtual bool HasAudioOutputDevices() = 0;
  163. // Returns true if the OS reports existence of audio recording devices. This
  164. // does not guarantee that the existing devices support all formats and
  165. // sample rates.
  166. virtual bool HasAudioInputDevices() = 0;
  167. // Appends a list of available input devices to |device_descriptions|,
  168. // which must initially be empty. It is not guaranteed that all the
  169. // devices in the list support all formats and sample rates for
  170. // recording.
  171. //
  172. // Not threadsafe; in production this should only be called from the
  173. // Audio worker thread (see GetTaskRunner()).
  174. virtual void GetAudioInputDeviceDescriptions(
  175. AudioDeviceDescriptions* device_descriptions) = 0;
  176. // Appends a list of available output devices to |device_descriptions|,
  177. // which must initially be empty.
  178. //
  179. // Not threadsafe; in production this should only be called from the
  180. // Audio worker thread (see GetTaskRunner()).
  181. virtual void GetAudioOutputDeviceDescriptions(
  182. AudioDeviceDescriptions* device_descriptions) = 0;
  183. // Returns the default output hardware audio parameters for opening output
  184. // streams. It is a convenience interface to
  185. // AudioManagerBase::GetPreferredOutputStreamParameters and each AudioManager
  186. // does not need their own implementation to this interface.
  187. // TODO(tommi): Remove this method and use GetOutputStreamParameteres instead.
  188. virtual AudioParameters GetDefaultOutputStreamParameters() = 0;
  189. // Returns the output hardware audio parameters for a specific output device.
  190. virtual AudioParameters GetOutputStreamParameters(
  191. const std::string& device_id) = 0;
  192. // Returns the input hardware audio parameters of the specific device
  193. // for opening input streams. Each AudioManager needs to implement their own
  194. // version of this interface.
  195. virtual AudioParameters GetInputStreamParameters(
  196. const std::string& device_id) = 0;
  197. // Returns the device id of an output device that belongs to the same hardware
  198. // as the specified input device.
  199. // If the hardware has only an input device (e.g. a webcam), the return value
  200. // will be empty (which the caller can then interpret to be the default output
  201. // device). Implementations that don't yet support this feature, must return
  202. // an empty string. Must be called on the audio worker thread (see
  203. // GetTaskRunner()).
  204. virtual std::string GetAssociatedOutputDeviceID(
  205. const std::string& input_device_id) = 0;
  206. // These functions return the ID of the default/communications audio
  207. // input/output devices respectively.
  208. // Implementations that do not support this functionality should return an
  209. // empty string.
  210. virtual std::string GetDefaultInputDeviceID() = 0;
  211. virtual std::string GetDefaultOutputDeviceID() = 0;
  212. virtual std::string GetCommunicationsInputDeviceID() = 0;
  213. virtual std::string GetCommunicationsOutputDeviceID() = 0;
  214. private:
  215. friend class AudioSystemHelper;
  216. std::unique_ptr<AudioThread> audio_thread_;
  217. bool shutdown_ = false; // True after |this| has been shutdown.
  218. THREAD_CHECKER(thread_checker_);
  219. };
  220. } // namespace media
  221. #endif // MEDIA_AUDIO_AUDIO_MANAGER_H_