audio_parameters.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339
  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_BASE_AUDIO_PARAMETERS_H_
  5. #define MEDIA_BASE_AUDIO_PARAMETERS_H_
  6. #include <stdint.h>
  7. #include <string>
  8. #include <vector>
  9. #include "base/compiler_specific.h"
  10. #include "base/numerics/checked_math.h"
  11. #include "base/time/time.h"
  12. #include "build/build_config.h"
  13. #include "media/base/audio_latency.h"
  14. #include "media/base/audio_point.h"
  15. #include "media/base/channel_layout.h"
  16. #include "media/base/media_shmem_export.h"
  17. #include "media/base/sample_format.h"
  18. #include "third_party/abseil-cpp/absl/types/optional.h"
  19. namespace media {
  20. // Use a struct-in-struct approach to ensure that we can calculate the required
  21. // size as sizeof(Audio{Input,Output}BufferParameters) + #(bytes in audio
  22. // buffer) without using packing. Also align Audio{Input,Output}BufferParameters
  23. // instead of in Audio{Input,Output}Buffer to be able to calculate size like so.
  24. // Use a constexpr for the alignment value that's the same as
  25. // AudioBus::kChannelAlignment, since MSVC doesn't accept the latter to be used.
  26. #if BUILDFLAG(IS_WIN)
  27. #pragma warning(push)
  28. #pragma warning(disable : 4324) // Disable warning for added padding.
  29. #endif
  30. constexpr int kParametersAlignment = 16;
  31. // ****WARNING****: Do not change the field types or ordering of these fields
  32. // without checking that alignment is correct. The structs may be concurrently
  33. // accessed by both 32bit and 64bit process in shmem. http://crbug.com/781095.
  34. struct MEDIA_SHMEM_EXPORT ALIGNAS(kParametersAlignment)
  35. AudioInputBufferParameters {
  36. double volume;
  37. int64_t capture_time_us; // base::TimeTicks in microseconds.
  38. uint32_t size;
  39. uint32_t id;
  40. bool key_pressed;
  41. };
  42. struct MEDIA_SHMEM_EXPORT ALIGNAS(kParametersAlignment)
  43. AudioOutputBufferParameters {
  44. int64_t delay_us; // base::TimeDelta in microseconds.
  45. int64_t delay_timestamp_us; // base::TimeTicks in microseconds.
  46. uint32_t frames_skipped;
  47. uint32_t bitstream_data_size;
  48. uint32_t bitstream_frames;
  49. };
  50. #if BUILDFLAG(IS_WIN)
  51. #pragma warning(pop)
  52. #endif
  53. struct MEDIA_SHMEM_EXPORT AudioInputBuffer {
  54. AudioInputBufferParameters params;
  55. int8_t audio[1];
  56. };
  57. struct MEDIA_SHMEM_EXPORT AudioOutputBuffer {
  58. AudioOutputBufferParameters params;
  59. int8_t audio[1];
  60. };
  61. struct MEDIA_SHMEM_EXPORT AudioRendererAlgorithmParameters {
  62. // The maximum size for the audio buffer.
  63. base::TimeDelta max_capacity;
  64. // The minimum size for the audio buffer.
  65. base::TimeDelta starting_capacity;
  66. // The minimum size for the audio buffer for encrypted streams.
  67. // Set this to be larger than |max_capacity| because the
  68. // performance of encrypted playback is always worse than clear playback, due
  69. // to decryption and potentially IPC overhead. For the context, see
  70. // https://crbug.com/403462, https://crbug.com/718161 and
  71. // https://crbug.com/879970.
  72. base::TimeDelta starting_capacity_for_encrypted;
  73. };
  74. class AudioParameters;
  75. // These convenience function safely computes the size required for
  76. // |shared_memory_count| AudioInputBuffers, with enough memory for AudioBus
  77. // data, using |paremeters| (or alternatively |channels| and |frames|). The
  78. // functions not returning a CheckedNumeric will CHECK on overflow.
  79. MEDIA_SHMEM_EXPORT base::CheckedNumeric<uint32_t>
  80. ComputeAudioInputBufferSizeChecked(const AudioParameters& parameters,
  81. uint32_t audio_bus_count);
  82. MEDIA_SHMEM_EXPORT uint32_t
  83. ComputeAudioInputBufferSize(const AudioParameters& parameters,
  84. uint32_t audio_bus_count);
  85. MEDIA_SHMEM_EXPORT uint32_t
  86. ComputeAudioInputBufferSize(int channels, int frames, uint32_t audio_bus_count);
  87. // These convenience functions safely computes the size required for an
  88. // AudioOutputBuffer with enough memory for AudioBus data using |parameters| (or
  89. // alternatively |channels| and |frames|). The functions not returning a
  90. // CheckedNumeric will CHECK on overflow.
  91. MEDIA_SHMEM_EXPORT base::CheckedNumeric<uint32_t>
  92. ComputeAudioOutputBufferSizeChecked(const AudioParameters& parameters);
  93. MEDIA_SHMEM_EXPORT uint32_t
  94. ComputeAudioOutputBufferSize(const AudioParameters& parameters);
  95. MEDIA_SHMEM_EXPORT uint32_t ComputeAudioOutputBufferSize(int channels,
  96. int frames);
  97. class MEDIA_SHMEM_EXPORT AudioParameters {
  98. public:
  99. // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.media
  100. // GENERATED_JAVA_CLASS_NAME_OVERRIDE: AudioEncodingFormat
  101. // GENERATED_JAVA_PREFIX_TO_STRIP: AUDIO_
  102. enum Format {
  103. AUDIO_FAKE = 0x00, // Creates a fake AudioOutputStream object
  104. AUDIO_PCM_LINEAR = 0x01, // PCM is 'raw' amplitude samples.
  105. AUDIO_PCM_LOW_LATENCY = 0x02, // Linear PCM, low latency requested.
  106. AUDIO_BITSTREAM_AC3 = 0x04, // Compressed AC3 bitstream.
  107. AUDIO_BITSTREAM_EAC3 = 0x08, // Compressed E-AC3 bitstream.
  108. AUDIO_BITSTREAM_DTS = 0x10, // Compressed DTS bitstream.
  109. AUDIO_BITSTREAM_DTS_HD = 0x20, // Compressed DTS-HD bitstream.
  110. AUDIO_BITSTREAM_DTSX_P2 = 0x40, // Compressed DTS-HD bitstream.
  111. AUDIO_BITSTREAM_IEC61937 = 0x80, // Compressed IEC61937 bitstream.
  112. AUDIO_FORMAT_LAST =
  113. AUDIO_BITSTREAM_IEC61937, // Only used for validation of format.
  114. };
  115. enum {
  116. // Telephone quality sample rate, mostly for speech-only audio.
  117. kTelephoneSampleRate = 8000,
  118. // CD sampling rate is 44.1 KHz or conveniently 2x2x3x3x5x5x7x7.
  119. kAudioCDSampleRate = 44100,
  120. };
  121. enum {
  122. // The maxmium number of PCM frames can be decoded out of a compressed
  123. // audio frame, e.g. MP3, AAC, AC-3.
  124. kMaxFramesPerCompressedAudioBuffer = 4096,
  125. };
  126. // Bitmasks to determine whether certain platform (typically hardware) audio
  127. // effects should be enabled.
  128. enum PlatformEffectsMask {
  129. NO_EFFECTS = 0x0,
  130. ECHO_CANCELLER = 1 << 0,
  131. DUCKING = 1 << 1, // Enables ducking if the OS supports it.
  132. // KEYBOARD_MIC used to hold 1 << 2, but has been deprecated.
  133. HOTWORD = 1 << 3,
  134. NOISE_SUPPRESSION = 1 << 4,
  135. AUTOMATIC_GAIN_CONTROL = 1 << 5,
  136. EXPERIMENTAL_ECHO_CANCELLER = 1 << 6, // Indicates an echo canceller is
  137. // available that should only
  138. // experimentally be enabled.
  139. MULTIZONE = 1 << 7,
  140. AUDIO_PREFETCH = 1 << 8,
  141. ALLOW_DSP_ECHO_CANCELLER = 1 << 9,
  142. ALLOW_DSP_NOISE_SUPPRESSION = 1 << 10,
  143. ALLOW_DSP_AUTOMATIC_GAIN_CONTROL = 1 << 11,
  144. };
  145. struct HardwareCapabilities {
  146. HardwareCapabilities(int min_frames_per_buffer, int max_frames_per_buffer)
  147. : min_frames_per_buffer(min_frames_per_buffer),
  148. max_frames_per_buffer(max_frames_per_buffer),
  149. bitstream_formats(0) {}
  150. explicit HardwareCapabilities(int bitstream_formats)
  151. : min_frames_per_buffer(0),
  152. max_frames_per_buffer(0),
  153. bitstream_formats(bitstream_formats) {}
  154. HardwareCapabilities()
  155. : min_frames_per_buffer(0),
  156. max_frames_per_buffer(0),
  157. bitstream_formats(0) {}
  158. // Minimum and maximum buffer sizes supported by the audio hardware. Opening
  159. // a device with frames_per_buffer set to a value between min and max should
  160. // result in the audio hardware running close to this buffer size, values
  161. // above or below will be clamped to the min or max by the audio system.
  162. // Either value can be 0 and means that the min or max is not known.
  163. int min_frames_per_buffer;
  164. int max_frames_per_buffer;
  165. int bitstream_formats;
  166. };
  167. AudioParameters();
  168. AudioParameters(Format format,
  169. ChannelLayout channel_layout,
  170. int sample_rate,
  171. int frames_per_buffer);
  172. AudioParameters(Format format,
  173. ChannelLayout channel_layout,
  174. int sample_rate,
  175. int frames_per_buffer,
  176. const HardwareCapabilities& hardware_capabilities);
  177. ~AudioParameters();
  178. // Re-initializes all members except for |hardware_capabilities_|.
  179. void Reset(Format format,
  180. ChannelLayout channel_layout,
  181. int sample_rate,
  182. int frames_per_buffer);
  183. // Checks that all values are in the expected range. All limits are specified
  184. // in media::Limits.
  185. bool IsValid() const;
  186. // Returns a human-readable string describing |*this|. For debugging & test
  187. // output only.
  188. std::string AsHumanReadableString() const;
  189. // Returns size of audio buffer in bytes when using |fmt| for samples.
  190. int GetBytesPerBuffer(SampleFormat fmt) const;
  191. // Returns the number of bytes representing a frame of audio when using |fmt|
  192. // for samples.
  193. int GetBytesPerFrame(SampleFormat fmt) const;
  194. // Returns the number of microseconds per frame of audio. Intentionally
  195. // reported as a double to surface of partial microseconds per frame, which
  196. // is common for many sample rates. Failing to account for these nanoseconds
  197. // can lead to audio/video sync drift.
  198. double GetMicrosecondsPerFrame() const;
  199. // Returns the duration of this buffer as calculated from frames_per_buffer()
  200. // and sample_rate().
  201. base::TimeDelta GetBufferDuration() const;
  202. // Comparison with other AudioParams.
  203. bool Equals(const AudioParameters& other) const;
  204. // Return true if |format_| is compressed bitstream.
  205. bool IsBitstreamFormat() const;
  206. bool IsFormatSupportedByHardware(Format format) const;
  207. void set_format(Format format) { format_ = format; }
  208. Format format() const { return format_; }
  209. // A setter for channel_layout_ is intentionally excluded.
  210. ChannelLayout channel_layout() const { return channel_layout_; }
  211. // The number of channels is usually computed from channel_layout_. Setting
  212. // this explicitly is only required with CHANNEL_LAYOUT_DISCRETE.
  213. void set_channels_for_discrete(int channels) {
  214. DCHECK(channel_layout_ == CHANNEL_LAYOUT_DISCRETE ||
  215. channel_layout_ == CHANNEL_LAYOUT_5_1_4_DOWNMIX ||
  216. channels == ChannelLayoutToChannelCount(channel_layout_));
  217. channels_ = channels;
  218. }
  219. int channels() const { return channels_; }
  220. void set_sample_rate(int sample_rate) { sample_rate_ = sample_rate; }
  221. int sample_rate() const { return sample_rate_; }
  222. void set_frames_per_buffer(int frames_per_buffer) {
  223. frames_per_buffer_ = frames_per_buffer;
  224. }
  225. int frames_per_buffer() const { return frames_per_buffer_; }
  226. absl::optional<HardwareCapabilities> hardware_capabilities() const {
  227. return hardware_capabilities_;
  228. }
  229. void set_hardware_capabilities(
  230. const absl::optional<HardwareCapabilities>& hwc) {
  231. hardware_capabilities_ = hwc;
  232. }
  233. void set_effects(int effects) { effects_ = effects; }
  234. int effects() const { return effects_; }
  235. void set_mic_positions(const std::vector<Point>& mic_positions) {
  236. mic_positions_ = mic_positions;
  237. }
  238. const std::vector<Point>& mic_positions() const { return mic_positions_; }
  239. void set_latency_tag(AudioLatency::LatencyType latency_tag) {
  240. latency_tag_ = latency_tag;
  241. }
  242. AudioLatency::LatencyType latency_tag() const { return latency_tag_; }
  243. AudioParameters(const AudioParameters&);
  244. AudioParameters& operator=(const AudioParameters&);
  245. // Creates reasonable dummy parameters in case no device is available.
  246. static AudioParameters UnavailableDeviceParams();
  247. private:
  248. Format format_; // Format of the stream.
  249. ChannelLayout channel_layout_; // Order of surround sound channels.
  250. int channels_; // Number of channels. Value set based on
  251. // |channel_layout|.
  252. int sample_rate_; // Sampling frequency/rate.
  253. int frames_per_buffer_; // Number of frames in a buffer.
  254. int effects_; // Bitmask using PlatformEffectsMask.
  255. // Microphone positions using Cartesian coordinates:
  256. // x: the horizontal dimension, with positive to the right from the camera's
  257. // perspective.
  258. // y: the depth dimension, with positive forward from the camera's
  259. // perspective.
  260. // z: the vertical dimension, with positive upwards.
  261. //
  262. // Usually, the center of the microphone array will be treated as the origin
  263. // (often the position of the camera).
  264. //
  265. // An empty vector indicates unknown positions.
  266. std::vector<Point> mic_positions_;
  267. // Optional tag to pass latency info from renderer to browser. Set to
  268. // AudioLatency::LATENCY_COUNT by default, which means "not specified".
  269. AudioLatency::LatencyType latency_tag_;
  270. // Audio hardware specific parameters, these are treated as read-only and
  271. // changing them has no effect.
  272. absl::optional<HardwareCapabilities> hardware_capabilities_;
  273. };
  274. // Comparison is useful when AudioParameters is used with std structures.
  275. inline bool operator<(const AudioParameters& a, const AudioParameters& b) {
  276. if (a.format() != b.format())
  277. return a.format() < b.format();
  278. if (a.channels() != b.channels())
  279. return a.channels() < b.channels();
  280. if (a.sample_rate() != b.sample_rate())
  281. return a.sample_rate() < b.sample_rate();
  282. return a.frames_per_buffer() < b.frames_per_buffer();
  283. }
  284. } // namespace media
  285. #endif // MEDIA_BASE_AUDIO_PARAMETERS_H_