音频设备模块（ADM）

Audio Device Module (ADM)

音频设备模块（ADM）

Overview

概述

The ADM is responsible for driving input (microphone) and output (speaker) audio in WebRTC and the API is defined in audio_device.h.

​ADM负责驱动WebRTC中的输入（麦克风）和输出（扬声器）音频，API在audio_device.h中定义。

Main functions of the ADM are:

ADM的主要功能是：

• Initialization and termination of native audio libraries.
• 本机音频库的初始化和终止。
• Registration of an AudioTransport object which handles audio callbacks for audio in both directions.
• ​AudioTransport对象的注册，该对象处理双向音频的音频回调。
• Device enumeration and selection (only for Linux, Windows and Mac OSX).
• 设备枚举和选择（仅适用于Linux、Windows和Mac OSX）。
• Start/Stop physical audio streams:
• 启动/停止物理音频流：
  • Recording audio from the selected microphone, and
  • 从所选麦克风录制音频，以及
  • playing out audio on the selected speaker.
  • 在所选扬声器上播放音频。
• Level control of the active audio streams.
• 活动音频流的级别控制。
• Control of built-in audio effects (Audio Echo Cancelation (AEC), Audio Gain Control (AGC) and Noise Suppression (NS)) for Android and iOS.
• Android和iOS的内置音频效果控制（音频回声消除（AEC）、音频增益控制（AGC）和噪声抑制（NS））。

ADM implementations reside at two different locations in the WebRTC repository: /modules/audio_device/ and /sdk/. The latest implementations for iOS and Android can be found under /sdk/. /modules/audio_device/ contains older versions for mobile platforms and also implementations for desktop platforms such as Linux, Windows and Mac OSX. This document is focusing on the parts in /modules/audio_device/ but implementation specific details such as threading models are omitted to keep the descriptions as simple as possible.

​ADM实现位于WebRTC存储库中的两个不同位置：/modules/audio_device/和/sdk/。iOS和Android的最新实现可以在/sdk/./modules/audio_device/下找到，其中包含移动平台的旧版本，也包括Linux、Windows和Mac OSX等桌面平台的实现。本文档主要关注/modules/audio_device/中的部分，但省略了线程模型等特定于实现的细节，以使描述尽可能简单。

By default, the ADM in WebRTC is created in WebRtcVoiceEngine::Init but an external implementation can also be injected using rtc::CreatePeerConnectionFactory. An example of where an external ADM is injected can be found in PeerConnectionInterfaceTest where a so-called fake ADM is utilized to avoid hardware dependency in a gtest. Clients can also inject their own ADMs in situations where functionality is needed that is not provided by the default implementations.

​默认情况下，WebRTC中的ADM是在WebRtcVoiceEngine::Init中创建的，但也可以使用rtc:：CreatePeerConnectionFactory注入外部实现。在PeerConnectionInterfaceTest中可以找到一个注入外部ADM的例子，其中使用所谓的假ADM来避免gtest中的硬件依赖性。在需要默认实现未提供的功能的情况下，客户端还可以注入自己的ADM。

Background

背景

This section contains a historical background of the ADM API.

本节包含ADM API的历史背景。

The ADM interface is old and has undergone many changes over the years. It used to be much more granular but it still contains more than 50 methods and is implemented on several different hardware platforms.

ADM接口很旧，多年来经历了许多变化。它过去更细粒度，但它仍然包含50多个方法，并在几个不同的硬件平台上实现。

Some APIs are not implemented on all platforms, and functionality can be spread out differently between the methods.

有些API并不是在所有平台上都实现的，并且功能可以在方法之间以不同的方式分布。

The most up-to-date implementations of the ADM interface are for iOS and for Android.

​ADM接口的最新实现适用于iOS和Android。

Desktop version are not updated to comply with the latest C++ style guide and more work is also needed to improve the performance and stability of these versions.

​桌面版本没有更新以符合最新的C++风格指南，还需要做更多的工作来提高这些版本的性能和稳定性。

WebRtcVoiceEngine

WebRtcVoiceEngine does not utilize all methods of the ADM but it still serves as the best example of its architecture and how to use it. For a more detailed view of all methods in the ADM interface, see ADM unit tests.

WebRtcVoiceEngine并没有使用ADM的所有方法，但它仍然是其体系结构和如何使用它的最佳示例。有关ADM接口中所有方法的更详细视图，请参阅ADM单元测试。

Assuming that an external ADM implementation is not injected, a default - or internal - ADM is created in WebRtcVoiceEngine::Init using AudioDeviceModule::Create.

​假设没有注入外部ADM实现，则使用AudioDeviceModule::Create在WebRtcVoiceEngine::Init中创建默认的或内部的ADM。

Basic initialization is done using a utility method called adm_helpers::Init which calls fundamental ADM APIs like:

​基本初始化是使用名为adm_helpers::Init的实用程序方法完成的，该方法调用基本的adm API，如：

• AudiDeviceModule::Init - initializes the native audio parts required for each platform.
• AudiDeviceModule::Init-初始化每个平台所需的本地音频部分。
• AudiDeviceModule::SetPlayoutDevice - specifies which speaker to use for playing out audio using an index retrieved by the corresponding enumeration method AudiDeviceModule::PlayoutDeviceName.
• AudiDeviceModule::SetPlayoutDevice-指定使用相应枚举方法AudiDeviceModuler::PlayoutDeviceName检索的索引播放音频时使用的扬声器。
• AudiDeviceModule::SetRecordingDevice - specifies which microphone to use for recording audio using an index retrieved by the corresponding enumeration method which is AudiDeviceModule::RecordingDeviceName.
• AudiDeviceModule::SetRecordingDevice-指定使用相应枚举方法检索的索引录制音频的麦克风，该枚举方法为AudiDeviceModuler::RecordingDeviceName。
• AudiDeviceModule::InitSpeaker - sets up the parts of the ADM needed to use the selected output device.
• AudiDeviceModule::InitSpeaker-设置使用所选输出设备所需的ADM部分。
• AudiDeviceModule::InitMicrophone - sets up the parts of the ADM needed to use the selected input device.
• AudiDeviceModule::InitMicrophone-设置使用所选输入设备所需的ADM部分。
• AudiDeviceModule::SetStereoPlayout - enables playout in stereo if the selected audio device supports it.
• AudiDeviceModule::SetStereoLayout-如果所选音频设备支持立体声播放，则启用立体声播放。
• AudiDeviceModule::SetStereoRecording - enables recording in stereo if the selected audio device supports it.
• AudiDeviceModule::SetStereoRecording-如果所选音频设备支持立体声录制，则启用立体声录制。

WebRtcVoiceEngine::Init also calls AudiDeviceModule::RegisterAudioTransport to register an existing AudioTransport implementation which handles audio callbacks in both directions and therefore serves as the bridge between the native ADM and the upper WebRTC layers.

WebRtcVoiceEngine::Init还调用AudiDeviceModule::RegisterAudioTransport来注册一个现有的AudioBransport实现，该实现处理两个方向的音频回调，因此充当本地ADM和上层WebRTC之间的桥梁。

Recorded audio samples are delivered from the ADM to the WebRtcVoiceEngine (who owns the AudioTransport object) via AudioTransport::RecordedDataIsAvailable:

​录制的音频样本通过AudioTransport::RecordedDataIsAvailable从ADM传递到WebRtcVoiceEngine（拥有AudioTransport对象）：

int32_t RecordedDataIsAvailable(const void* audioSamples, size_t nSamples, size_t nBytesPerSample,
                                size_t nChannels, uint32_t samplesPerSec, uint32_t totalDelayMS,
                                int32_t clockDrift, uint32_t currentMicLevel, bool keyPressed,
                                uint32_t& newMicLevel)

Decoded audio samples ready to be played out are are delivered by the WebRtcVoiceEngine to the ADM, via AudioTransport::NeedMorePlayoutData:

​准备播放的解码音频样本由WebRtcVoiceEngine通过AudioTransport::NeedMorePlayoutData发送到ADM：

int32_t NeedMorePlayData(size_t nSamples, size_t nBytesPerSample, size_t nChannels, int32_t samplesPerSec,
                         void* audioSamples, size_t& nSamplesOut,
                         int64_t* elapsed_time_ms, int64_t* ntp_time_ms)

Audio samples are 16-bit linear PCM using regular interleaving of channels within each sample.

​音频样本是16位线性PCM，在每个样本内使用信道的规则交错。

WebRtcVoiceEngine also owns an AudioState member and this class is used has helper to start and stop audio to and from the ADM. To initialize and start recording, it calls:

​WebRtcVoiceEngine还拥有一个AudioState成员，该类用于启动和停止与ADM之间的音频。要初始化和开始录制，它调用：

• AudiDeviceModule::InitRecording
• AudiDeviceModule::StartRecording

and to initialize and start playout:

以及初始化并开始播放：

• AudiDeviceModule::InitPlayout
• AudiDeviceModule::StartPlayout

Finally, the corresponding stop methods AudiDeviceModule::StopRecording and AudiDeviceModule::StopPlayout are called followed by AudiDeviceModule::Terminate.

​最后，调用相应的停止方法AudiDeviceModule::StopRecording和AudiDeviceModule::StopPlayout，然后调用AudiDeviceModuler::Terminate。