native_avcodec_audiocodec.h

Overview

The file declares the native APIs used for audio encoding and decoding.

File to include: <multimedia/player_framework/native_avcodec_audiocodec.h>

Library: libnative_media_acodec.so

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Related module: AudioCodec

Sample: AVCodec

Summary

Structs

Name	typedef Keyword	Description
MediaKeySession	MediaKeySession	Describes the fields for MediaKeySession.

Functions

Name	Description
OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder)	Creates an audio codec instance based on a MIME type. This function is recommended in most cases.
OH_AVCodec *OH_AudioCodec_CreateByName(const char *name)	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 OH_AVCapability_GetName.
OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec)	Clears the internal resources of an audio codec and destroys the codec instance. Do not repeatedly destroy the instance. Otherwise, the program may crash.
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. This function must be called prior to Prepare.
OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec)	Prepares internal resources for an audio codec. This function must be called after Configure.
OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec)	Starts an audio codec after it is prepared successfully. After being started, the codec starts to report the OH_AVCodecOnNeedInputBuffer event.
OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec)	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.
OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec)	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.
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 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.
OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format)	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.
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. 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. Note: If the return value is AV_ERR_UNKNOWN, the call does not take effect, and the input buffer is still in the unprocessed state. You need to handle the error according to the specific error code and then call OH_AudioCodec_PushInputBuffer.
OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index)	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.
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.
OH_AVErrCode OH_AudioCodec_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)	Obtains the index of an available input buffer for an audio codec within the specified timeout period. After obtaining the index, call OH_AudioCodec_GetInputBuffer to obtain the buffer corresponding to the index. After the buffer is filled, call OH_AudioCodec_PushInputBuffer with the same index to push the buffer to the codec. Note: This function can be used only in synchronous mode of the audio codec.
OH_AVBuffer *OH_AudioCodec_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index)	Obtains the input buffer identified by index for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.
OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)	Obtains the index of an available output buffer for an audio codec within the specified timeout period. After obtaining the index, call OH_AudioCodec_GetOutputBuffer to obtain the buffer corresponding to the index. After the use, call OH_AudioCodec_FreeOutputBuffer to release the buffer. Once released, the buffer cannot be reused. Prolonged failure to release buffers will block the codec process. Note: This function can be used only in synchronous mode of the audio codec.
OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index)	Obtains the output buffer identified by index for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.

Function Description

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
const char *mime	Pointer to a string that describes the MIME type. For details, see AVCODEC_MIMETYPE.
bool isEncoder	The value true means to create an encoder, and false means to create a decoder.

Returns

Type	Description
OH_AVCodec *	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 OH_AVCapability_GetName.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

Name	Description
const char *name	Pointer to an audio codec name.

Returns

Type	Description
OH_AVCodec *	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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_NO_MEMORY: Internal resources have been released. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
OH_AVCodecCallback callback	Set of all callback functions.
void *userData	User-specific data.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: An input parameter is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
const OH_AVFormat *format	Pointer to an OH_AVFormat instance, which provides the description information about the audio track to be encoded or decoded.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: An input parameter is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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

Name	Description
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.

Returns

Type	Description
OH_AVFormat *	Handle to an OH_AVFormat instance. The lifecycle of this instance is refreshed when OH_AudioCodec_GetOutputDescription is called again and destroyed when the OH_AVCodec instance is destroyed.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
const OH_AVFormat *format	Handle to an OH_AVFormat instance.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: An input parameter is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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.
Note: If the return value is AV_ERR_UNKNOWN, the call does not take effect, and the input buffer is still in the unprocessed state. You need to handle the error according to the specific error code and then call OH_AudioCodec_PushInputBuffer.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 11

Parameters

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

Returns

Type

Description

OH_AVErrCode

AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The input index is used or invalid. Use the index returned by the OH_AVCodecOnNeedInputBuffer callback. AV_ERR_INVALID_STATE: The codec state is incorrect. Before calling OH_AudioCodec_PushInputBuffer, ensure that OH_AudioCodec_Configure, OH_AudioCodec_Prepare, and OH_AudioCodec_Start are successfully called in sequence. AV_ERR_UNKNOWN: The input buffer size is invalid. Ensure that the buffer size and flags are correctly set.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
uint32_t index	Index of the OH_AVCodecOnNewOutputBuffer callback.

Returns

Type

Description

OH_AVErrCode

AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: An input parameter is nullptr or invalid. The buffer index is obtained from OH_AVCodecOnNewOutputBuffer. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. This may be because of incorrect state or unsupported operation. AV_ERR_UNKNOWN: An internal error occurs. You are advised to check logs.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
bool *isValid	Pointer to an instance of the Boolean type. The value true means that the codec instance is valid, and false means the opposite.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: An input parameter is nullptr or invalid.

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
OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
MediaKeySession *mediaKeySession	Pointer to the media key session with the decryption feature.
bool secureAudio	Whether a secure decoder is used. true if used, false otherwise. Currently, the secure decoder is not supported for audio decryption.

Returns

Type	Description
OH_AVErrCode	AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The OH_AVCodec instance is nullptr or invalid, or the mediaKeySystemInfo instance is nullptr or invalid. AV_ERR_INVALID_STATE: The codec service is unavailable. AV_ERR_NO_MEMORY: Memory allocation fails.

OH_AudioCodec_QueryInputBuffer()

OH_AVErrCode OH_AudioCodec_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)

Description

Obtains the index of an available input buffer for an audio codec within the specified timeout period.
After obtaining the index, call OH_AudioCodec_GetInputBuffer to obtain the buffer corresponding to the index.
After the buffer is filled, call OH_AudioCodec_PushInputBuffer with the same index to push the buffer to the codec.
Note: This function can be used only in synchronous mode of the audio codec.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 20

Parameters

Name	Description
struct OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
uint32_t *index	Pointer to the index of the input buffer obtained.
int64_t timeoutUs	Timeout period, in microseconds. A negative value means to wait infinitely.

Returns

Type

Description

OH_AVErrCode

AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The operation fails due to incorrect input parameters. AV_ERR_INVALID_STATE: The operation fails due to an invalid state, for example, the codec not being started. AV_ERR_OPERATE_NOT_PERMIT: The operation fails because the call is not allowed in asynchronous mode. AV_ERR_TRY_AGAIN_LATER: The operation fails because no available buffer is obtained within the timeout period.

OH_AudioCodec_GetInputBuffer()

OH_AVBuffer *OH_AudioCodec_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index)

Description

Obtains the input buffer identified by index for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 20

Parameters

Name	Description
struct OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
uint32_t index	Index of the input buffer. It is obtained by calling OH_AudioCodec_QueryInputBuffer.

Returns

Type	Description
OH_AVBuffer *	Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.

OH_AudioCodec_QueryOutputBuffer()

OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)

Description

Obtains the index of an available output buffer for an audio codec within the specified timeout period. After obtaining the index, call OH_AudioCodec_GetOutputBuffer to obtain the buffer corresponding to the index.
After the use, call OH_AudioCodec_FreeOutputBuffer to release the buffer. Once released, the buffer cannot be reused. Prolonged failure to release buffers will block the codec process. Note: This function can be used only in synchronous mode of the audio codec.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 20

Parameters

Name	Description
struct OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
uint32_t *index	Pointer to the index of the output buffer obtained.
int64_t timeoutUs	Timeout period, in microseconds. A negative value means to wait infinitely.

Returns

Type

Description

OH_AVErrCode

AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The operation fails due to incorrect input parameters. AV_ERR_INVALID_STATE: The operation fails due to an invalid state, for example, the codec not being started. AV_ERR_OPERATE_NOT_PERMIT: The operation fails because the call is not allowed in asynchronous mode. AV_ERR_STREAM_CHANGED: The format of the decoded output stream changes. You can call OH_AudioCodec_GetOutputDescription to obtain the new stream information. AV_ERR_TRY_AGAIN_LATER: The operation fails because no available buffer is obtained within the timeout period.

OH_AudioCodec_GetOutputBuffer()

OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index)

Description

Obtains the output buffer identified by index for an audio codec. Note: This function can be used only in synchronous mode of the audio codec.

System capability: SystemCapability.Multimedia.Media.AudioCodec

Since: 20

Parameters

Name	Description
struct OH_AVCodec *codec	Pointer to an OH_AVCodec instance.
uint32_t index	Index of the output buffer. It is obtained by calling OH_AudioCodec_QueryOutputBuffer.

Returns

Type	Description
OH_AVBuffer *	Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned.