Audio.md

# Audio
## **Overview**
Defines audio-related APIs, including custom data types and functions for loading drivers, accessing a driver adapter, and rendering and capturing audios.
**Since:**
1.0
**Version:**
1.0
## **Summary**
## Files

File Name	Description
audio_adapter.h	Declares APIs for operations related to the audio adapter.
audio_attribute.h	Declares APIs for audio attributes.
audio_capture.h	Declares APIs for audio capturing.
audio_control.h	Declares APIs for audio control.
audio_manager.h	Declares APIs for audio adapter management and loading.
audio_render.h	Declares APIs for audio rendering.
audio_scene.h	Declares APIs for audio scenes.
audio_types.h	Defines custom data types used in API declarations for the audio module, including audio ports, adapter descriptors, device descriptors, scene descriptors, sampling attributes, and timestamp.
audio_volume.h	Declares APIs for audio volume.

## Data Structures

Data Structure Name	Description
AudioAdapter	Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, and obtaining the port capability set.
AudioAttribute	Provides attribute-related APIs for audio rendering or capturing, including functions to obtain frame information and set audio sampling attributes.
AudioCapture	Provides capabilities for audio capturing, including controlling the capturing, setting audio attributes, scenes, and volume, and capturing audio frames.
AudioControl	Provides control-related APIs for audio rendering or capturing, including functions to start, stop, pause, and resume audio rendering or capturing, and flush data in the audio buffer.
AudioManager	Manages audio adapters through a specific adapter driver program loaded based on the given audio adapter descriptor.
AudioRender	Provides capabilities for audio rendering, including controlling the rendering, setting audio attributes, scenes, and volume, obtaining hardware latency, and rendering audio frames.
AudioScene	Provides scene-related APIs for audio rendering or capturing, including functions to select an audio scene and check whether the configuration of an audio scene is supported.
AudioPort	Defines the audio port.
AudioAdapterDescriptor	Defines the audio adapter descriptor.
AudioDeviceDescriptor	Defines the audio device descriptor.
AudioSceneDescriptor	Defines the audio scene descriptor.
AudioSceneDescriptor::SceneDesc	Describes the audio scene.
AudioSampleAttributes	Defines audio sampling attributes.
AudioTimeStamp	Defines the audio timestamp, which is a substitute for POSIX timespec.
AudioSubPortCapability	Defines the sub-port capability.
AudioPortCapability	Defines the audio port capability.
AudioVolume	Provides volume-related APIs for audio rendering or capturing, including functions to set the mute operation, volume, and gain.

## Typedefs

Typedef Name	Description
AudioHandle	typedef void *  Defines the audio handle.

## Enumerations

Enumeration Name	Description
AudioPortDirection { PORT_OUT = 0x1u, PORT_IN = 0x2u, PORT_OUT_IN = 0x3u }	Enumerates the audio port type.
AudioPortPin {   PIN_NONE = 0x0u, PIN_OUT_SPEAKER = 0x1u, PIN_OUT_HEADSET = 0x2u, PIN_OUT_LINEOUT = 0x4u,   PIN_OUT_HDMI = 0x8u, PIN_IN_MIC = 0x8000001u, PIN_IN_HS_MIC = 0x8000002u, PIN_IN_LINEIN = 0x8000004u }	Enumerates the pin of an audio adapter.
AudioCategory { AUDIO_IN_MEDIA = 0, AUDIO_IN_COMMUNICATION }	Enumerates the audio category.
AudioFormat {   AUDIO_FORMAT_PCM_8_BIT = 0x1u, AUDIO_FORMAT_PCM_16_BIT = 0x2u, AUDIO_FORMAT_PCM_24_BIT = 0x3u, AUDIO_FORMAT_PCM_32_BIT = 0x4u,   AUDIO_FORMAT_AAC_MAIN = 0x1000001u, AUDIO_FORMAT_AAC_LC = 0x1000002u, AUDIO_FORMAT_AAC_LD = 0x1000003u, AUDIO_FORMAT_AAC_ELD = 0x1000004u,   AUDIO_FORMAT_AAC_HE_V1 = 0x1000005u, AUDIO_FORMAT_AAC_HE_V2 = 0x1000006u }	Enumerates the audio format.
AudioChannelMask { AUDIO_CHANNEL_FRONT_LEFT = 0x1, AUDIO_CHANNEL_FRONT_RIGHT = 0x2, AUDIO_CHANNEL_MONO = 0x1u, AUDIO_CHANNEL_STEREO = 0x3u }	Enumerates the audio channel mask.
AudioSampleRatesMask {   AUDIO_SAMPLE_RATE_MASK_8000 = 0x1u, AUDIO_SAMPLE_RATE_MASK_12000 = 0x2u, AUDIO_SAMPLE_RATE_MASK_11025 = 0x4u, AUDIO_SAMPLE_RATE_MASK_16000 = 0x8u,   AUDIO_SAMPLE_RATE_MASK_22050 = 0x10u, AUDIO_SAMPLE_RATE_MASK_24000 = 0x20u, AUDIO_SAMPLE_RATE_MASK_32000 = 0x40u, AUDIO_SAMPLE_RATE_MASK_44100 = 0x80u,   AUDIO_SAMPLE_RATE_MASK_48000 = 0x100u, AUDIO_SAMPLE_RATE_MASK_64000 = 0x200u, AUDIO_SAMPLE_RATE_MASK_96000 = 0x400u, AUDIO_SAMPLE_RATE_MASK_INVALID = 0xFFFFFFFFu }	Enumerates masks of audio sampling rates.
AudioPortPassthroughMode { PORT_PASSTHROUGH_LPCM = 0x1, PORT_PASSTHROUGH_RAW = 0x2, PORT_PASSTHROUGH_HBR2LBR = 0x4, PORT_PASSTHROUGH_AUTO = 0x8 }	Enumerates the passthrough data transmission mode of an audio port.
AudioChannelMode {   AUDIO_CHANNEL_NORMAL = 0, AUDIO_CHANNEL_BOTH_LEFT, AUDIO_CHANNEL_BOTH_RIGHT, AUDIO_CHANNEL_EXCHANGE,   AUDIO_CHANNEL_MIX, AUDIO_CHANNEL_LEFT_MUTE, AUDIO_CHANNEL_RIGHT_MUTE, AUDIO_CHANNEL_BOTH_MUTE }	Enumerates channel modes for audio rendering.

## Functions

Function Name	Description
GetAudioManagerFuncs (void)	struct AudioManager *  Obtains the operation function list of the AudioManager class.

## **Details**
## **Enumeration Type Documentation**
## AudioCategory
```
enum [AudioCategory](Audio.md#gaf210d41d152890f3aaf2aaac99bd28d5)
```
**Description:**
Enumerates the audio category.

Enumerator	Description
AUDIO_IN_MEDIA	Media
AUDIO_IN_COMMUNICATION	Communications

## AudioChannelMask
```
enum [AudioChannelMask](Audio.md#ga137eb03027d5947ea294b32f5095b83c)
```
**Description:**
Enumerates the audio channel mask.
A mask describes an audio channel position.

Enumerator	Description
AUDIO_CHANNEL_FRONT_LEFT	Front left channel
AUDIO_CHANNEL_FRONT_RIGHT	Front right channel
AUDIO_CHANNEL_MONO	Mono channel
AUDIO_CHANNEL_STEREO	Stereo channel, consisting of front left and front right channels

## AudioChannelMode
```
enum [AudioChannelMode](Audio.md#ga78aab1fafb9657451804e42b42897123)
```
**Description:**
Enumerates channel modes for audio rendering.
**Attention:**
The following modes are set for rendering dual-channel audios. Others are not supported.

Enumerator	Description
AUDIO_CHANNEL_NORMAL	Normal mode. No processing is required.
AUDIO_CHANNEL_BOTH_LEFT	Two left channels
AUDIO_CHANNEL_BOTH_RIGHT	Two right channels
AUDIO_CHANNEL_EXCHANGE	Data exchange between the left and right channels. The left channel takes the audio stream of the right channel, and the right channel takes that of the left channel.
AUDIO_CHANNEL_MIX	Mix of streams of the left and right channels
AUDIO_CHANNEL_LEFT_MUTE	Left channel muted. The stream of the right channel is output.
AUDIO_CHANNEL_RIGHT_MUTE	Right channel muted. The stream of the left channel is output.
AUDIO_CHANNEL_BOTH_MUTE	Both left and right channels muted

## AudioFormat
```
enum [AudioFormat](Audio.md#ga98d5d077cca088ddf77314871474fe59)
```
**Description:**
Enumerates the audio format.

Enumerator	Description
AUDIO_FORMAT_PCM_8_BIT	8-bit PCM
AUDIO_FORMAT_PCM_16_BIT	16-bit PCM
AUDIO_FORMAT_PCM_24_BIT	24-bit PCM
AUDIO_FORMAT_PCM_32_BIT	32-bit PCM
AUDIO_FORMAT_AAC_MAIN	AAC main
AUDIO_FORMAT_AAC_LC	AAC LC
AUDIO_FORMAT_AAC_LD	AAC LD
AUDIO_FORMAT_AAC_ELD	AAC ELD
AUDIO_FORMAT_AAC_HE_V1	AAC HE_V1
AUDIO_FORMAT_AAC_HE_V2	AAC HE_V2

## AudioPortDirection
```
enum [AudioPortDirection](Audio.md#ga68ff7140b15790debbac4bbc62f8e9f8)
```
**Description:**
Enumerates the audio port type.

Enumerator	Description
PORT_OUT	Output port
PORT_IN	Input port
PORT_OUT_IN	Input/output port, supporting both audio input and output

## AudioPortPassthroughMode
```
enum [AudioPortPassthroughMode](Audio.md#ga186d2d4f9a2ecacb80cd2cce2bd26f0e)
```
**Description:**
Enumerates the passthrough data transmission mode of an audio port.

Enumerator	Description
PORT_PASSTHROUGH_LPCM	Stereo PCM
PORT_PASSTHROUGH_RAW	HDMI passthrough
PORT_PASSTHROUGH_HBR2LBR	Blu-ray next-generation audio output with reduced specifications
PORT_PASSTHROUGH_AUTO	Mode automatically matched based on the HDMI EDID

## AudioPortPin
```
enum [AudioPortPin](Audio.md#gaa7114aeeccf3ac4f5f7e1d880bcfa835)
```
**Description:**
Enumerates the pin of an audio adapter.

Enumerator	Description
PIN_NONE	Invalid pin
PIN_OUT_SPEAKER	Speaker output pin
PIN_OUT_HEADSET	Wired headset pin for output
PIN_OUT_LINEOUT	Line-out pin
PIN_OUT_HDMI	HDMI output pin
PIN_IN_MIC	Microphone input pin
PIN_IN_HS_MIC	Wired headset microphone pin for input
PIN_IN_LINEIN	Line-in pin

## AudioSampleRatesMask
```
enum [AudioSampleRatesMask](Audio.md#ga7053fcaa56d1dc47d2fcd83ee131fe4c)
```
**Description:**
Enumerates masks of audio sampling rates.

Enumerator	Description
AUDIO_SAMPLE_RATE_MASK_8000	8 kHz
AUDIO_SAMPLE_RATE_MASK_12000	12 kHz
AUDIO_SAMPLE_RATE_MASK_11025	11.025 kHz
AUDIO_SAMPLE_RATE_MASK_16000	16 kHz
AUDIO_SAMPLE_RATE_MASK_22050	22.050 kHz
AUDIO_SAMPLE_RATE_MASK_24000	24 kHz
AUDIO_SAMPLE_RATE_MASK_32000	32 kHz
AUDIO_SAMPLE_RATE_MASK_44100	44.1 kHz
AUDIO_SAMPLE_RATE_MASK_48000	48 kHz
AUDIO_SAMPLE_RATE_MASK_64000	64 kHz
AUDIO_SAMPLE_RATE_MASK_96000	96 kHz
AUDIO_SAMPLE_RATE_MASK_INVALID	Invalid sampling rate

## **Function Documentation**
## GetAudioManagerFuncs\(\)
```
struct [AudioManager](AudioManager.md)* GetAudioManagerFuncs (void )
```
**Description:**
Obtains the operation function list of the [AudioManager](AudioManager.md) class.
**Returns:**
Returns the pointer to the **[AudioManager](AudioManager.md)** object if the list is obtained; returns **NULL** otherwise.
## **Variable Documentation**
## adapterName
```
const char* AudioAdapterDescriptor::adapterName
```
**Description:**
Name of the audio adapter
## channelCount \[1/2\]
```
uint32_t AudioSampleAttributes::channelCount
```
**Description:**
Number of audio channels. For example, for the mono channel, the value is 1, and for the stereo channel, the value is 2.
## channelCount \[2/2\]
```
uint32_t AudioPortCapability::channelCount
```
**Description:**
Supported maximum number of audio channels
## channelMasks
```
enum [AudioChannelMask](Audio.md#ga137eb03027d5947ea294b32f5095b83c) AudioPortCapability::channelMasks
```
**Description:**
Audio channel layout mask of the device. For details, see [AudioChannelMask](Audio.md#ga137eb03027d5947ea294b32f5095b83c).
## desc \[1/4\]
```
const char* AudioDeviceDescriptor::desc
```
**Description:**
Audio device name
## desc \[2/4\]
```
struct [AudioDeviceDescriptor](AudioDeviceDescriptor.md) AudioSceneDescriptor::desc
```
**Description:**
Audio device descriptor
## desc \[3/4\]
```
const char* AudioSceneDescriptor::SceneDesc::desc
```
**Description:**
Name of the audio scene
## desc \[4/4\]
```
const char* AudioSubPortCapability::desc
```
**Description:**
Sub-port name
## deviceId
```
uint32_t AudioPortCapability::deviceId
```
**Description:**
Device ID used for device binding
## deviceType
```
uint32_t AudioPortCapability::deviceType
```
**Description:**
Device type \(output or input\)
## dir
```
enum [AudioPortDirection](Audio.md#ga68ff7140b15790debbac4bbc62f8e9f8) AudioPort::dir
```
**Description:**
Audio port type. For details, see [AudioPortDirection](Audio.md#ga68ff7140b15790debbac4bbc62f8e9f8)
## format
```
enum [AudioFormat](Audio.md#ga98d5d077cca088ddf77314871474fe59) AudioSampleAttributes::format
```
**Description:**
Audio data format. For details, see [AudioFormat](Audio.md#ga98d5d077cca088ddf77314871474fe59).
## formatNum
```
uint32_t AudioPortCapability::formatNum
```
**Description:**
Number of the supported audio formats
## formats
```
enum [AudioFormat](Audio.md#ga98d5d077cca088ddf77314871474fe59)* AudioPortCapability::formats
```
**Description:**
Supported audio formats. For details, see [AudioFormat](Audio.md#ga98d5d077cca088ddf77314871474fe59).
## hardwareMode
```
bool AudioPortCapability::hardwareMode
```
**Description:**
Whether to support device binding
## id
```
uint32_t AudioSceneDescriptor::SceneDesc::id
```
**Description:**
Audio scene ID
## interleaved
```
bool AudioSampleAttributes::interleaved
```
**Description:**
Interleaving flag of audio data
## mask
```
enum [AudioPortPassthroughMode](Audio.md#ga186d2d4f9a2ecacb80cd2cce2bd26f0e) AudioSubPortCapability::mask
```
**Description:**
Passthrough mode of data transmission. For details, see [AudioPortPassthroughMode](Audio.md#ga186d2d4f9a2ecacb80cd2cce2bd26f0e).
## pins
```
enum [AudioPortPin](Audio.md#gaa7114aeeccf3ac4f5f7e1d880bcfa835) AudioDeviceDescriptor::pins
```
**Description:**
Pins of audio ports \(input and output\). For details, see [AudioPortPin](Audio.md#gaa7114aeeccf3ac4f5f7e1d880bcfa835).
## portId \[1/3\]
```
uint32_t AudioPort::portId
```
**Description:**
Audio port ID
## portId \[2/3\]
```
uint32_t AudioDeviceDescriptor::portId
```
**Description:**
Audio port ID
## portId \[3/3\]
```
uint32_t AudioSubPortCapability::portId
```
**Description:**
Sub-port ID
## portName
```
const char* AudioPort::portName
```
**Description:**
Audio port name
## portNum
```
uint32_t AudioAdapterDescriptor::portNum
```
**Description:**
Number of ports supported by an audio adapter
## ports
```
struct [AudioPort](AudioPort.md)* AudioAdapterDescriptor::ports
```
**Description:**
List of ports supported by an audio adapter
## sampleRate
```
uint32_t AudioSampleAttributes::sampleRate
```
**Description:**
Audio sampling rate
## sampleRateMasks
```
uint32_t AudioPortCapability::sampleRateMasks
```
**Description:**
Supported audio sampling rates \(8 kHz, 16 kHz, 32 kHz, and 48 kHz\)
## scene
```
union [AudioSceneDescriptor::SceneDesc](AudioSceneDescriptor-SceneDesc.md) AudioSceneDescriptor::scene
```
**Description:**
The **scene** object
## subPorts
```
struct [AudioSubPortCapability](AudioSubPortCapability.md)* AudioPortCapability::subPorts
```
**Description:**
List of supported sub-ports
## subPortsNum
```
uint32_t AudioPortCapability::subPortsNum
```
**Description:**
Number of supported sub-ports \(for output devices only\)
## tvNSec
```
int64_t AudioTimeStamp::tvNSec
```
**Description:**
Nanoseconds
## tvSec
```
int64_t AudioTimeStamp::tvSec
```
**Description:**
Seconds
## type
```
enum [AudioCategory](Audio.md#gaf210d41d152890f3aaf2aaac99bd28d5) AudioSampleAttributes::type
```
**Description:**
Audio type. For details, see [AudioCategory](Audio.md#gaf210d41d152890f3aaf2aaac99bd28d5)