audio_io.h 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  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_IO_H_
  5. #define MEDIA_AUDIO_AUDIO_IO_H_
  6. #include <stdint.h>
  7. #include "base/time/time.h"
  8. #include "media/base/audio_bus.h"
  9. #include "media/base/media_export.h"
  10. // Low-level audio output support. To make sound there are 3 objects involved:
  11. // - AudioSource : produces audio samples on a pull model. Implements
  12. // the AudioSourceCallback interface.
  13. // - AudioOutputStream : uses the AudioSource to render audio on a given
  14. // channel, format and sample frequency configuration. Data from the
  15. // AudioSource is delivered in a 'pull' model.
  16. // - AudioManager : factory for the AudioOutputStream objects, manager
  17. // of the hardware resources and mixer control.
  18. //
  19. // The number and configuration of AudioOutputStream does not need to match the
  20. // physically available hardware resources. For example you can have:
  21. //
  22. // MonoPCMSource1 --> MonoPCMStream1 --> | | --> audio left channel
  23. // StereoPCMSource -> StereoPCMStream -> | mixer |
  24. // MonoPCMSource2 --> MonoPCMStream2 --> | | --> audio right channel
  25. //
  26. // This facility's objective is mix and render audio with low overhead using
  27. // the OS basic audio support, abstracting as much as possible the
  28. // idiosyncrasies of each platform. Non-goals:
  29. // - Positional, 3d audio
  30. // - Dependence on non-default libraries such as DirectX 9, 10, XAudio
  31. // - Digital signal processing or effects
  32. // - Extra features if a specific hardware is installed (EAX, X-fi)
  33. //
  34. // The primary client of this facility is audio coming from several tabs.
  35. // Specifically for this case we avoid supporting complex formats such as MP3
  36. // or WMA. Complex format decoding should be done by the renderers.
  37. // Models an audio stream that gets rendered to the audio hardware output.
  38. // Because we support more audio streams than physically available channels
  39. // a given AudioOutputStream might or might not talk directly to hardware.
  40. // An audio stream allocates several buffers for audio data and calls
  41. // AudioSourceCallback::OnMoreData() periodically to fill these buffers,
  42. // as the data is written to the audio device. Size of each packet is determined
  43. // by |samples_per_packet| specified in AudioParameters when the stream is
  44. // created.
  45. namespace media {
  46. class MEDIA_EXPORT AudioOutputStream {
  47. public:
  48. // Audio sources must implement AudioSourceCallback. This interface will be
  49. // called in a random thread which very likely is a high priority thread. Do
  50. // not rely on using this thread TLS or make calls that alter the thread
  51. // itself such as creating Windows or initializing COM.
  52. class MEDIA_EXPORT AudioSourceCallback {
  53. public:
  54. virtual ~AudioSourceCallback() {}
  55. // Provide more data by fully filling |dest|. The source will return the
  56. // number of frames it filled. |delay| is the duration of audio written to
  57. // |dest| in prior calls to OnMoreData() that has not yet been played out,
  58. // and |delay_timestamp| is the time when |delay| was measured. The time
  59. // when the first sample added to |dest| is expected to be played out can be
  60. // calculated by adding |delay| to |delay_timestamp|. The accuracy of
  61. // |delay| and |delay_timestamp| may vary depending on the platform and
  62. // implementation. |prior_frames_skipped| is the number of frames skipped by
  63. // the consumer.
  64. virtual int OnMoreData(base::TimeDelta delay,
  65. base::TimeTicks delay_timestamp,
  66. int prior_frames_skipped,
  67. AudioBus* dest) = 0;
  68. virtual int OnMoreData(base::TimeDelta delay,
  69. base::TimeTicks delay_timestamp,
  70. int prior_frames_skipped,
  71. AudioBus* dest,
  72. bool is_mixing);
  73. // There was an error while playing a buffer. Audio source cannot be
  74. // destroyed yet. No direct action needed by the AudioStream, but it is
  75. // a good place to stop accumulating sound data since is is likely that
  76. // playback will not continue.
  77. //
  78. // An ErrorType may be provided with more information on what went wrong. An
  79. // unhandled kDeviceChange type error is likely to result in further errors;
  80. // so it's recommended that sources close their existing output stream and
  81. // request a new one when this error is sent.
  82. enum class ErrorType { kUnknown, kDeviceChange };
  83. virtual void OnError(ErrorType type) = 0;
  84. };
  85. virtual ~AudioOutputStream() {}
  86. // Open the stream. false is returned if the stream cannot be opened. Open()
  87. // must always be followed by a call to Close() even if Open() fails.
  88. virtual bool Open() = 0;
  89. // Starts playing audio and generating AudioSourceCallback::OnMoreData().
  90. // Since implementor of AudioOutputStream may have internal buffers, right
  91. // after calling this method initial buffers are fetched.
  92. //
  93. // The output stream does not take ownership of this callback.
  94. virtual void Start(AudioSourceCallback* callback) = 0;
  95. // Stops playing audio. The operation completes synchronously meaning that
  96. // once Stop() has completed executing, no further callbacks will be made to
  97. // the callback object that was supplied to Start() and it can be safely
  98. // deleted. Stop() may be called in any state, e.g. before Start() or after
  99. // Stop().
  100. virtual void Stop() = 0;
  101. // Sets the relative volume, with range [0.0, 1.0] inclusive.
  102. virtual void SetVolume(double volume) = 0;
  103. // Gets the relative volume, with range [0.0, 1.0] inclusive.
  104. virtual void GetVolume(double* volume) = 0;
  105. // Close the stream.
  106. // After calling this method, the object should not be used anymore.
  107. // After calling this method, no further AudioSourceCallback methods
  108. // should be called on the callback object that was supplied to Start()
  109. // by the AudioOutputStream implementation.
  110. virtual void Close() = 0;
  111. // Flushes the stream. This should only be called if the stream is not
  112. // playing. (i.e. called after Stop or Open)
  113. virtual void Flush() = 0;
  114. };
  115. // Models an audio sink receiving recorded audio from the audio driver.
  116. class MEDIA_EXPORT AudioInputStream {
  117. public:
  118. class MEDIA_EXPORT AudioInputCallback {
  119. public:
  120. // Called by the audio recorder when a full packet of audio data is
  121. // available. This is called from a special audio thread and the
  122. // implementation should return as soon as possible.
  123. //
  124. // |capture_time| is the time at which the first sample in |source| was
  125. // received. The age of the audio data may be calculated by subtracting
  126. // |capture_time| from base::TimeTicks::Now(). |capture_time| is always
  127. // monotonically increasing.
  128. virtual void OnData(const AudioBus* source,
  129. base::TimeTicks capture_time,
  130. double volume) = 0;
  131. // There was an error while recording audio. The audio sink cannot be
  132. // destroyed yet. No direct action needed by the AudioInputStream, but it
  133. // is a good place to stop accumulating sound data since is is likely that
  134. // recording will not continue.
  135. virtual void OnError() = 0;
  136. protected:
  137. virtual ~AudioInputCallback() {}
  138. };
  139. virtual ~AudioInputStream() {}
  140. enum class OpenOutcome {
  141. kSuccess,
  142. kAlreadyOpen,
  143. // Failed due to an unknown or unspecified reason.
  144. kFailed,
  145. // Failed to open due to OS-level System permissions.
  146. kFailedSystemPermissions,
  147. // Failed to open as the device is exclusively opened by another app.
  148. kFailedInUse,
  149. };
  150. // Open the stream and prepares it for recording. Call Start() to actually
  151. // begin recording.
  152. virtual OpenOutcome Open() = 0;
  153. // Starts recording audio and generating AudioInputCallback::OnData().
  154. // The input stream does not take ownership of this callback.
  155. virtual void Start(AudioInputCallback* callback) = 0;
  156. // Stops recording audio. Effect might not be instantaneous as there could be
  157. // pending audio callbacks in the queue which will be issued first before
  158. // recording stops.
  159. virtual void Stop() = 0;
  160. // Close the stream. This also generates AudioInputCallback::OnClose(). This
  161. // should be the last call made on this object.
  162. virtual void Close() = 0;
  163. // Returns the maximum microphone analog volume or 0.0 if device does not
  164. // have volume control.
  165. virtual double GetMaxVolume() = 0;
  166. // Sets the microphone analog volume, with range [0, max_volume] inclusive.
  167. virtual void SetVolume(double volume) = 0;
  168. // Returns the microphone analog volume, with range [0, max_volume] inclusive.
  169. virtual double GetVolume() = 0;
  170. // Sets the Automatic Gain Control (AGC) state.
  171. virtual bool SetAutomaticGainControl(bool enabled) = 0;
  172. // Returns the Automatic Gain Control (AGC) state.
  173. virtual bool GetAutomaticGainControl() = 0;
  174. // Returns the current muting state for the microphone.
  175. virtual bool IsMuted() = 0;
  176. // Sets the output device from which to cancel echo, if echo cancellation is
  177. // supported by this stream. E.g. called by WebRTC when it changes playback
  178. // devices.
  179. virtual void SetOutputDeviceForAec(const std::string& output_device_id) = 0;
  180. };
  181. } // namespace media
  182. #endif // MEDIA_AUDIO_AUDIO_IO_H_