harmony 鸿蒙AudioCodec

2025-06-12
浏览 (3)

AudioCodec

Overview

The AudioCodec module provides the functions for audio encoding and decoding.

You can refer to the corresponding development guide and samples based on your development requirements.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Summary

Files

Name	Description
native_avcodec_audiocodec.h	Declares the native APIs used for audio encoding and decoding.

Functions

Name	Description
OH_AVCodec * OH_AudioCodec_CreateByMime (const char *mime, bool isEncoder)	Creates an audio codec instance based on a MIME type.
OH_AVCodec * OH_AudioCodec_CreateByName (const char *name)	Creates an audio codec instance based on a codec name.
OH_AVErrCode OH_AudioCodec_Destroy (OH_AVCodec *codec)	Clears the internal resources of an audio codec and destroys the codec instance.
OH_AVErrCode OH_AudioCodec_RegisterCallback (OH_AVCodec codec, OH_AVCodecCallback callback, void userData)	Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to Prepare.
OH_AVErrCode OH_AudioCodec_Configure (OH_AVCodec codec, const OH_AVFormat format)	Configures the audio description. The audio codec is usually configured based on the audio description.
OH_AVErrCode OH_AudioCodec_Prepare (OH_AVCodec *codec)	Prepares internal resources for an audio codec.
OH_AVErrCode OH_AudioCodec_Start (OH_AVCodec *codec)	Starts an audio codec after it is prepared successfully.
OH_AVErrCode OH_AudioCodec_Stop (OH_AVCodec *codec)	Stops an audio codec.
OH_AVErrCode OH_AudioCodec_Flush (OH_AVCodec *codec)	Clears the input and output data in the internal buffer of an audio codec.
OH_AVErrCode OH_AudioCodec_Reset (OH_AVCodec *codec)	Resets an audio codec. The configured parameters and input and output data are cleared. To continue encoding or decoding, you must call Configure to configure the codec again.
OH_AVFormat * OH_AudioCodec_GetOutputDescription (OH_AVCodec *codec)	Obtains the description information about the output data of an audio codec.
OH_AVErrCode OH_AudioCodec_SetParameter (OH_AVCodec codec, const OH_AVFormat format)	Sets dynamic parameters for an audio codec.
OH_AVErrCode OH_AudioCodec_PushInputBuffer (OH_AVCodec *codec, uint32_t index)	Notifies the audio codec that the input data has been written to the buffer identified by index.
OH_AVErrCode OH_AudioCodec_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index)	Frees an output buffer of an audio codec.
OH_AVErrCode OH_AudioCodec_IsValid (OH_AVCodec codec, bool isValid)	Checks whether an audio codec instance is valid. This function is used to detect the codec status when a background fault is rectified or an application is switched from the background.
OH_AVErrCode OH_AudioCodec_SetDecryptionConfig (OH_AVCodec codec, MediaKeySession mediaKeySession, bool secureAudio)	Sets the decryption information.

Function Description

OH_AudioCodec_Configure()

OH_AVErrCode OH_AudioCodec_Configure (OH_AVCodec *codec, const OH_AVFormat *format)

Description

Configures the audio description. The audio codec is usually configured based on the audio description. This function must be called prior to Prepare.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
format	Pointer to an OH_AVFormat instance, which provides the description information about the audio track to be encoded or decoded.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_CreateByMime()

OH_AVCodec* OH_AudioCodec_CreateByMime (const char *mime, bool isEncoder)

Description

Creates an audio codec instance based on a MIME type. This function is recommended in most cases.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
mime	Pointer to a string that describes the MIME type. For details, see AVCODEC_MIMETYPE.
isEncoder	The value true means to create an encoder, and false means to create a decoder.

Returns

Returns the pointer to an OH_AVCodec instance.

OH_AudioCodec_CreateByName()

OH_AVCodec* OH_AudioCodec_CreateByName (const char *name)

Description

Creates an audio codec instance based on a codec name.

To use this function, you must know the exact name of the codec, which can be obtained by calling the corresponding API.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
name	Pointer to an audio codec name.

Returns

Returns the pointer to an OH_AVCodec instance.

OH_AudioCodec_Destroy()

OH_AVErrCode OH_AudioCodec_Destroy (OH_AVCodec *codec)

Description

Clears the internal resources of an audio codec and destroys the codec instance.

Do not repeatedly destroy the instance. Otherwise, the program may crash.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_Flush()

OH_AVErrCode OH_AudioCodec_Flush (OH_AVCodec *codec)

Description

Clears the input and output data in the internal buffer of an audio codec.

This function invalidates the indexes of all buffers previously reported through the asynchronous callback. Therefore, before calling this function, ensure that the buffers with the specified indexes are no longer required.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_FreeOutputBuffer()

OH_AVErrCode OH_AudioCodec_FreeOutputBuffer (OH_AVCodec *codec, uint32_t index)

Description

Frees an output buffer of an audio codec.

You need to call this function to release the output buffer in a timely manner. Otherwise, the encoding or decoding process is blocked.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
index	Index of the OH_AVCodecOnNewOutputBuffer.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_GetOutputDescription()

OH_AVFormat* OH_AudioCodec_GetOutputDescription (OH_AVCodec *codec)

Description

Obtains the OH_AVFormat information about the output data of an audio codec.

You must call OH_AVFormat_Destroy to manually release the OH_AVFormat instance in the return value.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns the handle to an OH_AVFormat instance. The lifecycle of this instance is refreshed when GetOutputDescription is called again and destroyed when the OH_AVCodec instance is destroyed.

OH_AudioCodec_IsValid()

OH_AVErrCode OH_AudioCodec_IsValid (OH_AVCodec *codec, bool *isValid)

Description

Checks whether an audio codec instance is valid.
This function is used to detect the codec status when a background fault is rectified or an application is switched from the background.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
isValid	Output parameter. Pointer to an instance of the Boolean type. The value true means that the codec instance is valid, and false means the opposite.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_Prepare()

OH_AVErrCode OH_AudioCodec_Prepare (OH_AVCodec *codec)

Description

Prepares internal resources for an audio codec. This function must be called after Configure.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_PushInputBuffer()

OH_AVErrCode OH_AudioCodec_PushInputBuffer (OH_AVCodec *codec, uint32_t index)

Description

Notifies the audio codec that the input data has been written to the buffer identified by index.

The OH_AVCodecOnNeedInputBuffer callback reports the available input buffer and the index. After being pushed to the codec, a buffer is not accessible until the buffer with the same index is reported again through the OH_AVCodecOnNeedInputBuffer callback.

In addition, some codecs require the input of codec-specific data to initialize the encoding or decoding process.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
index	Index of the OH_AVCodecOnNeedInputBuffer.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_RegisterCallback()

OH_AVErrCode OH_AudioCodec_RegisterCallback (OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData)

Description

Sets an asynchronous callback so that your application can respond to events generated by an audio codec. This function must be called prior to Prepare.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
callback	Callback function to set. For details, see OH_AVCodecCallback.
userData	User-specific data.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_Reset()

OH_AVErrCode OH_AudioCodec_Reset (OH_AVCodec *codec)

Description

Resets an audio codec. The configured parameters and input and output data are cleared.

To continue encoding or decoding, you must call Configure to configure the codec again.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_SetDecryptionConfig()

OH_AVErrCode OH_AudioCodec_SetDecryptionConfig (OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureAudio)

Description

Sets the decryption information.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 12

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
mediaKeySession	Pointer to the media key session with the decryption feature.
secureAudio	Whether a secure decoder is used. The value true means that a secure decoder is used, and false means the opposite. Currently, the secure decoder is not supported for audio decryption.

Returns

Returns a result code defined in OH_AVErrCode.

AV_ERR_OK is returned if the operation is successful.

AV_ERR_INVALID_VAL is returned if the OH_AVCodec instance is a null pointer or invalid, or the mediaKeySystemInfo instance is a null pointer or invalid.

AV_ERR_INVALID_STATE if the decoder service is unavailable.

OH_AudioCodec_SetParameter()

OH_AVErrCode OH_AudioCodec_SetParameter (OH_AVCodec *codec, const OH_AVFormat *format)

Description

Sets dynamic parameters for an audio codec.

This function can be called only after the codec is started. Incorrect parameter settings may cause encoding or decoding failure.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.
format	Handle to an OH_AVFormat instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_Start()

OH_AVErrCode OH_AudioCodec_Start (OH_AVCodec *codec)

Description

Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the OH_AVCodecOnNeedInputBuffer event.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
codec	Pointer to an OH_AVCodec instance.

Returns

Returns AV_ERR_OK if the operation is successful; returns an error code defined in OH_AVErrCode otherwise.

OH_AudioCodec_Stop()

OH_AVErrCode OH_AudioCodec_Stop (OH_AVCodec *codec)

Description

Stops an audio codec.

After the codec is stopped, you can call Start to start it again. If you have passed specific data in the previous Start for the codec, you must pass it again.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters