native_avcodec_videodecoder.h
Overview
The file declares the native APIs used for video decoding.
File to include: <multimedia/player_framework/native_avcodec_videodecoder.h>
Library: libnative_media_vdec.so
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Related module: VideoDecoder
Sample: AVCodec
The following figures show the APIs supported by each version and the APIs that can be called in different states.
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| MediaKeySession | MediaKeySession | Describes a native object for MediaKeySession. |
Functions
| Name | Description |
|---|---|
| OH_AVCodec *OH_VideoDecoder_CreateByMime(const char *mime) | Creates a video decoder instance based on a MIME type. This function is recommended in most cases. |
| OH_AVCodec *OH_VideoDecoder_CreateByName(const char *name) | Creates a video decoder instance based on a decoder name. To use this function, you must know the exact name of the decoder. The decoder name can be obtained through capability query. |
| OH_AVErrCode OH_VideoDecoder_Destroy(OH_AVCodec *codec) | Clears the internal resources of a video decoder and destroys the decoder instance. You only need to call the function once. |
| OH_AVErrCode OH_VideoDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData) | Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to OH_VideoDecoder_Prepare. (This function is deprecated since API version 11.) |
| OH_AVErrCode OH_VideoDecoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData) | Registers an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to OH_VideoDecoder_Prepare. |
| OH_AVErrCode OH_VideoDecoder_SetSurface(OH_AVCodec *codec, OHNativeWindow *window) | Sets an output surface for a video decoder. In the initialization phase, this function must be called prior to OH_VideoDecoder_Prepare. In the executing state, it can be called directly. |
| OH_AVErrCode OH_VideoDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format) | Configures a video decoder. It is typically necessary to provide the information about the video to decode, which can be extracted from OH_AVSource. This function must be called prior to OH_VideoDecoder_Prepare. |
| OH_AVErrCode OH_VideoDecoder_Prepare(OH_AVCodec *codec) | Prepares internal resources for a video decoder. This function must be called after OH_VideoDecoder_Configure. |
| OH_AVErrCode OH_VideoDecoder_Start(OH_AVCodec *codec) | Starts a video decoder. This function should be called after a successful call of OH_VideoDecoder_Prepare. After being started, the decoder starts to report the registered event. |
| OH_AVErrCode OH_VideoDecoder_Stop(OH_AVCodec *codec) | Stops a video decoder and releases the input and output buffers. After the video decoder is stopped, you can call OH_VideoDecoder_Start to enter the running state again. If you have passed codec-specific data in the previous Start for the decoder, you must pass it again. |
| OH_AVErrCode OH_VideoDecoder_Flush(OH_AVCodec *codec) | Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video decoder. 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_VideoDecoder_Reset(OH_AVCodec *codec) | Resets a video decoder. The decoder returns to the initial state. To continue decoding, you must call OH_VideoDecoder_Configure to configure the decoder again. |
| OH_AVFormat *OH_VideoDecoder_GetOutputDescription(OH_AVCodec *codec) | Obtains the OH_AVFormat information about the decoder's output data. For details, see OH_AVFormat. You must call OH_AVFormat_Destroy to release the OH_AVFormat instance when its lifecycle ends. |
| OH_AVErrCode OH_VideoDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format) | Sets dynamic parameters for a video decoder. This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure. |
| OH_AVErrCode OH_VideoDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr) | Pushes the input buffer filled with data to a video decoder. The input callback reports the available input buffer and the index. For details, see OH_AVCodecOnNeedInputData. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. (This function is deprecated since API version 11.) |
| OH_AVErrCode OH_VideoDecoder_RenderOutputData(OH_AVCodec *codec, uint32_t index) | Returns the processed output buffer to a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface. If no output surface is configured, calling this function only frees the output buffer. (This function is deprecated since API version 11.) |
| OH_AVErrCode OH_VideoDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index) | Frees an output buffer of a video decoder. (This function is deprecated since API version 11.) |
| OH_AVErrCode OH_VideoDecoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index) | Notifies a video decoder that the buffer corresponding to the index has been filled with input data. The input callback reports the available input buffer and the index. For details, see OH_AVCodecOnNeedInputBuffer. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process. This function is used to transfer the parameters (such as H.264 PPS/SPS) required for decoding to the decoder. The parameters can be transferred to the decoder separately or together with the data to be decoded. |
| OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer(OH_AVCodec *codec, uint32_t index) | Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering on the output surface. If no output surface is configured, calling this function only frees the output buffer. |
| OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs) | Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering within the specified duration on the output surface. |
| OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index) | Frees an output buffer of a video decoder. You need to call this function to release the output buffer in a timely manner. Otherwise, the decoding process is blocked. |
| OH_AVErrCode OH_VideoDecoder_IsValid(OH_AVCodec *codec, bool *isValid) | Checks whether the decoder service is valid when a decoder instance exists. |
| OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath) | Sets the decryption configuration. This function can be called prior to OH_VideoDecoder_Prepare. |
| OH_AVErrCode OH_VideoDecoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available input buffer. After calling this function, you must call OH_VideoDecoder_GetInputBuffer to obtain the buffer instance and call OH_VideoDecoder_PushInputBuffer to pass the buffer instance to the decoder. Note that the preceding operations are supported only in synchronous mode. |
| OH_AVBuffer *OH_VideoDecoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index) | Obtains the instance of the available input buffer. Note that this function works only in synchronous mode. |
| OH_AVErrCode OH_VideoDecoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs) | Obtains the index of the next available output buffer. You can perform the following operations to display or release the decoded frame of the buffer instance obtained through OH_VideoDecoder_GetOutputBuffer: 1. Return the processed output buffer to the decoder by calling OH_VideoDecoder_FreeOutputBuffer. 2. Render the output surface by calling OH_VideoDecoder_RenderOutputBuffer. 3. Render the output surface within the specified time by calling OH_VideoDecoder_RenderOutputBufferAtTime. Note that the preceding operations are supported only in synchronous mode. |
| OH_AVBuffer *OH_VideoDecoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index) | Obtains the instance of the available output buffer. Note that this function works only in synchronous mode. |
Function Description
OH_VideoDecoder_CreateByMime()
OH_AVCodec *OH_VideoDecoder_CreateByMime(const char *mime)
Description
Creates a video decoder instance based on a MIME type. This function is recommended in most cases.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| const char *mime | Pointer to a string that describes the MIME type. For details, see AVCODEC_MIME_TYPE. |
Returns
| Type | Description |
|---|---|
| OH_AVCodec * | Pointer to the video decoder instance. If the decoder type is not supported or the memory is insufficient, NULL is returned. |
OH_VideoDecoder_CreateByName()
OH_AVCodec *OH_VideoDecoder_CreateByName(const char *name)
Description
Creates a video decoder instance based on a decoder name. To use this function, you must know the exact name of the decoder. The decoder name can be obtained through capability query.
For details, see Obtaining Supported Codecs.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| const char *name | Pointer to a video decoder name. |
Returns
| Type | Description |
|---|---|
| OH_AVCodec * | Pointer to the video decoder instance. If the decoder name is not supported or the memory is insufficient, NULL is returned. |
OH_VideoDecoder_Destroy()
OH_AVErrCode OH_VideoDecoder_Destroy(OH_AVCodec *codec)
Description
Clears the internal resources of a video decoder and destroys the decoder instance. You only need to call the function once.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_SetCallback()
OH_AVErrCode OH_VideoDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData)
Description
Sets an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to OH_VideoDecoder_Prepare.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Deprecated from: 11
Substitute: OH_VideoDecoder_RegisterCallback
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| OH_AVCodecAsyncCallback callback | All callback functions. |
| void *userData | Pointer to the data on which the caller depends when executing the callback. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_RegisterCallback()
OH_AVErrCode OH_VideoDecoder_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData)
Description
Registers an asynchronous callback so that your application can respond to events generated by a video decoder. This function must be called prior to OH_VideoDecoder_Prepare.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| OH_AVCodecCallback callback | All callback functions. |
| void *userData | Pointer to the data on which the caller depends when executing the callback. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_SetSurface()
OH_AVErrCode OH_VideoDecoder_SetSurface(OH_AVCodec *codec, OHNativeWindow *window)
Description
Sets an output surface for a video decoder.
In the initialization phase, this function must be called prior to OH_VideoDecoder_Prepare. In the executing state, it can be called directly.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_OPERATE_NOT_PERMIT: The function is called in the buffer mode. It can be called only in the surface mode. AV_ERR_INVALID_VAL: 1. The value of codec is nullptr or does not point to a decoder instance. 2. The value of window is nullptr. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. |
OH_VideoDecoder_Configure()
OH_AVErrCode OH_VideoDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format)
Description
Configures a video decoder. It is typically necessary to provide the information about the video to decode, which can be extracted from OH_AVSource. This function must be called prior to OH_VideoDecoder_Prepare.
The value ranges of the following parameters can be obtained from Capability Query. All the values of OH_MD_KEY_ROTATION are supported.
If the current platform does not support OH_MD_KEY_VIDEO_ENABLE_LOW_LATENCY, no error is reported and the normal decoding process is used.
Parameter verification rules are as follows:
| Key | Value Within the Range | Value Out of Range | No Value Configured |
|---|---|---|---|
| OH_MD_KEY_WIDTH | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL |
| OH_MD_KEY_HEIGHT | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_INVALID_VAL |
| OH_MD_KEY_PIXEL_FORMAT OH_AVPixelFormat | AV_ERR_OK | AV_ERR_UNSUPPORT | AV_ERR_OK |
| OH_MD_KEY_FRAME_RATE | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK |
| OH_MD_KEY_ROTATION | AV_ERR_OK | AV_ERR_INVALID_VAL | AV_ERR_OK |
NOTE You are advised to set the parameters based on the maximum resolution supported by the instance. Otherwise, an exception may occur when streams with the resolution higher than the maximum resolution are to be decoded. This setting directly affects the memory usage of the application.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| OH_AVFormat *format | Pointer to an OH_AVFormat instance, which provides the description information about the video track to be decoded. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: 1. The value of codec is nullptr or does not point to a decoder instance. 2. The format is not supported. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. AV_ERR_INVALID_STATE: The function is not called prior to OH_VideoDecoder_Prepare. AV_ERR_VIDEO_UNSUPPORTED_COLOR_SPACE_CONVERSION: CSC is not supported. AV_ERR_UNSUPPORT: The pixel format is not supported. |
OH_VideoDecoder_Prepare()
OH_AVErrCode OH_VideoDecoder_Prepare(OH_AVCodec *codec)
Description
Prepares internal resources for a video decoder. This function must be called after OH_VideoDecoder_Configure.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: 1. The operation is not allowed. 2. CSC is configured, but the decoder is in buffer mode. |
OH_VideoDecoder_Start()
OH_AVErrCode OH_VideoDecoder_Start(OH_AVCodec *codec)
Description
Starts a video decoder. This function should be called after a successful call of OH_VideoDecoder_Prepare. After being started, the decoder starts to report the registered event.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: 1. The operation is not allowed. 2. CSC is configured, but OH_VideoDecoder_Prepare is not called. |
OH_VideoDecoder_Stop()
OH_AVErrCode OH_VideoDecoder_Stop(OH_AVCodec *codec)
Description
Stops a video decoder and releases the input and output buffers. After the video decoder is stopped, you can call OH_VideoDecoder_Start to enter the running state again.
If you have passed codec-specific data in the previous Start for the decoder, you must pass it again.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_Flush()
OH_AVErrCode OH_VideoDecoder_Flush(OH_AVCodec *codec)
Description
Clears the input and output data and parameters, for example, H.264 PPS/SPS, cached in a video decoder.
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.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_Reset()
OH_AVErrCode OH_VideoDecoder_Reset(OH_AVCodec *codec)
Description
Resets a video decoder. The decoder returns to the initial state. To continue decoding, you must call OH_VideoDecoder_Configure to configure the decoder again.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_GetOutputDescription()
OH_AVFormat *OH_VideoDecoder_GetOutputDescription(OH_AVCodec *codec)
Description
Obtains the OH_AVFormat information about the decoder's output data. For details, see OH_AVFormat.
You must call OH_AVFormat_Destroy to release the OH_AVFormat instance when its lifecycle ends.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
Returns
| Type | Description |
|---|---|
| OH_AVFormat * | Pointer to an OH_AVFormat instance. If the value of codec is nullptr or does not point to a decoder instance, NULL is returned. |
OH_VideoDecoder_SetParameter()
OH_AVErrCode OH_VideoDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format)
Description
Sets dynamic parameters for a video decoder.
This function can be called only after the decoder is started. Incorrect parameter settings may cause decoding failure.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| OH_AVFormat *format | Pointer to an OH_AVFormat instance. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: 1. The value of codec is nullptr or does not point to a decoder instance. 2. The format is not supported. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_PushInputData()
OH_AVErrCode OH_VideoDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr)
Description
Pushes the input buffer filled with data to a video decoder.
The input callback reports the available input buffer and the index. For details, see OH_AVCodecOnNeedInputData. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Deprecated from: 11
Substitute: OH_VideoDecoder_PushInputBuffer
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an input buffer. The value is provided by OH_AVCodecOnNeedInputData. |
| OH_AVCodecBufferAttr attr | Description information about the data in the buffer. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_RenderOutputData()
OH_AVErrCode OH_VideoDecoder_RenderOutputData(OH_AVCodec *codec, uint32_t index)
Description
Returns the processed output buffer to a video decoder and instructs the decoder to render the decoded data in the buffer on the output surface.
If no output surface is configured, calling this API only returns the output buffer corresponding to the specified index to the decoder.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Deprecated from: 11
Substitute: OH_VideoDecoder_RenderOutputBuffer
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an output buffer. The value is provided by OH_AVCodecOnNewOutputData. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_FreeOutputData()
OH_AVErrCode OH_VideoDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index)
Description
Frees an output buffer of a video decoder.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 9
Deprecated from: 11
Substitute: OH_VideoDecoder_FreeOutputBuffer
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an output buffer. The value is provided by OH_AVCodecOnNewOutputData. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_PushInputBuffer()
OH_AVErrCode OH_VideoDecoder_PushInputBuffer(OH_AVCodec *codec, uint32_t index)
Description
Notifies a video decoder that the buffer corresponding to the index has been filled with input data.
The input callback reports the available input buffer and the index. For details, see OH_AVCodecOnNeedInputBuffer. After being pushed to the decoder, a buffer is not accessible until the buffer with the same index is reported again through the input callback. In addition, some decoders require the input of codec-specific data, such as PPS/SPS data in H.264 format, to initialize the decoding process.
This function is used to transfer the parameters (such as H.264 PPS/SPS) required for decoding to the decoder. The parameters can be transferred to the decoder separately or together with the data to be decoded.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an input buffer. The value is provided by OH_AVCodecOnNeedInputBuffer. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. AV_ERR_DRM_DECRYPT_FAILED: The DRM-protected video buffer fails to be decrypted. You are advised to view logs. |
OH_VideoDecoder_RenderOutputBuffer()
OH_AVErrCode OH_VideoDecoder_RenderOutputBuffer(OH_AVCodec *codec, uint32_t index)
Description
Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering on the output surface.
If no output surface is configured, calling this API only returns the output buffer corresponding to the specified index to the decoder.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an output buffer. The value is provided by OH_AVCodecOnNewOutputBuffer. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_RenderOutputBufferAtTime()
OH_AVErrCode OH_VideoDecoder_RenderOutputBufferAtTime(OH_AVCodec *codec, uint32_t index, int64_t renderTimestampNs)
Description
Returns the output buffer corresponding to the index to a video decoder. The buffer carries the decoded data and is used to instruct the decoder to finish rendering within the specified duration on the output surface.
If no output surface is configured, calling this API only returns the output buffer corresponding to the specified index to the decoder.
You can request the system to render the buffer at a specific time (after the VSYNC or buffer timestamp) based on the timestamp. To render the buffer at the specified timestamp, that timestamp should approximate the current system time within an acceptable margin of error. Pay attention to the following:
1. Buffers are processed sequentially, which may result in the display of subsequent buffers on the surface being blocked. This is particularly important for interactive scenarios, such as responding to user actions like stopping, fast-forwarding, or rewinding a video.
2. If multiple buffers are sent to the surface for rendering on a single VSYNC event, the last buffer is rendered and other buffers are discarded.
3. If the difference between the timestamp and the current system time exceeds the acceptable margin of error, the surface ignores the timestamp and renders the buffer at the earliest feasible time. In this case, no frames are discarded.
4. If you want the system to handle frame-dropping based on the display's refresh rate, you have to use this function. Otherwise, your application manages frame-dropping on its own.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 12
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an output buffer. The value is provided by OH_AVCodecOnNewOutputBuffer. |
| int64_t renderTimestampNs | Timestamp (in nanoseconds) when the output buffer is sent to the surface. The value must be greater than 0 and should be generated by the clock of the std::chrono::steady_clock standard library. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_FreeOutputBuffer()
OH_AVErrCode OH_VideoDecoder_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index)
Description
Frees an output buffer of a video decoder. You need to call this function to release the output buffer in a timely manner. Otherwise, the decoding process is blocked.
For details, see step 12 in surface mode or step 10 in buffer mode in Video Decoding.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of an output buffer. The value is provided by OH_AVCodecOnNewOutputBuffer. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: 1. The value of codec is nullptr or does not point to a decoder instance. 2. The index is invalid or the same index is used consecutively. This error does not affect the subsequent decoding process. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: The operation is not allowed. |
OH_VideoDecoder_IsValid()
OH_AVErrCode OH_VideoDecoder_IsValid(OH_AVCodec *codec, bool *isValid)
Description
Checks whether the decoder service is valid when a decoder instance exists.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 10
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| bool *isValid | Pointer of the Boolean type. The value indicates the validity of the decoder service only when the function returns AV_ERR_OK. The value true means that the decoder service is valid, and false means the opposite. It is recommended that you initialize isValid to false. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. |
OH_VideoDecoder_SetDecryptionConfig()
OH_AVErrCode OH_VideoDecoder_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, bool secureVideoPath)
Description
Sets the decryption configuration. This function can be called prior to OH_VideoDecoder_Prepare.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_AVCodec *codec | Pointer to a video decoder instance. |
| MediaKeySession *mediaKeySession | Pointer to a media key session instance with decryption capabilities. |
| bool secureVideoPath | Whether a secure video channel is used. The value true means a secure video channel, and false means a non-secure video channel. In surface mode, both secure and non-secure video channels are supported. In buffer mode, only non-secure video channels are supported. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_OPERATE_NOT_PERMIT: 1. The operation is not allowed. 2. The decoding service process is abnormal. 3. The media key session service is in an error state. AV_ERR_INVALID_VAL: 1. The value of codec is nullptr or does not point to a decoder instance. 2. The value of mediaKeySession is nullptr or invalid. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. |
OH_VideoDecoder_QueryInputBuffer()
OH_AVErrCode OH_VideoDecoder_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)
Description
Obtains the index of the next available input buffer.
After calling this function, you must call OH_VideoDecoder_GetInputBuffer to obtain the buffer instance and call OH_VideoDecoder_PushInputBuffer to pass the buffer instance to the decoder.
Note that the preceding operations are supported only in synchronous mode.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 20
Parameters
| Name | Description |
|---|---|
| struct OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t *index | Index of an input buffer. |
| int64_t timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value 0 means to return immediately. A positive value means to wait for the specified time before exiting. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: This function is called in asynchronous mode. AV_ERR_TRY_AGAIN_LATER: The query fails. Try again after a short interval. |
OH_VideoDecoder_GetInputBuffer()
OH_AVBuffer *OH_VideoDecoder_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index)
Description
Obtains the instance of the available input buffer.
Note that this function works only in synchronous mode.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 20
Parameters
| Name | Description |
|---|---|
| struct OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of the input buffer. It can be obtained by calling OH_VideoDecoder_QueryInputBuffer. |
Returns
| Type | Description |
|---|---|
| OH_AVBuffer * | Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. |
OH_VideoDecoder_QueryOutputBuffer()
OH_AVErrCode OH_VideoDecoder_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs)
Description
Obtains the index of the next available output buffer.
You can perform the following operations to display or release the decoded frame of the buffer instance obtained through OH_VideoDecoder_GetOutputBuffer:
1. Return the processed output buffer to the decoder by calling OH_VideoDecoder_FreeOutputBuffer.
2. Render the output surface by calling OH_VideoDecoder_RenderOutputBuffer.
3. Render the output surface within the specified time by calling OH_VideoDecoder_RenderOutputBufferAtTime.
Note that the preceding operations are supported only in synchronous mode.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 20
Parameters
| Name | Description |
|---|---|
| struct OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t *index | Index of an output buffer. |
| int64_t timeoutUs | Timeout duration, in microseconds. A negative value means to wait infinitely. The value 0 means to return immediately. A positive value means to wait for the specified time before exiting. |
Returns
| Type | Description |
|---|---|
| OH_AVErrCode | AV_ERR_OK: The operation is successful. AV_ERR_NO_MEMORY: The decoder instance has been destroyed. AV_ERR_INVALID_VAL: The value of codec is nullptr or does not point to a decoder instance. AV_ERR_UNKNOWN: An unknown error occurs. AV_ERR_INVALID_STATE: This API cannot be called in the current decoder state. AV_ERR_OPERATE_NOT_PERMIT: This function is called in asynchronous mode. AV_ERR_STREAM_CHANGED: The stream format has changed. You can call OH_VideoDecoder_GetOutputDescription to obtain the new stream information. AV_ERR_TRY_AGAIN_LATER: The query fails. Try again after a short interval. |
OH_VideoDecoder_GetOutputBuffer()
OH_AVBuffer *OH_VideoDecoder_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index)
Description
Obtains the instance of the available output buffer. Note that this function works only in synchronous mode.
System capability: SystemCapability.Multimedia.Media.VideoDecoder
Since: 20
Parameters
| Name | Description |
|---|---|
| struct OH_AVCodec *codec | Pointer to a video decoder instance. |
| uint32_t index | Index of the output buffer. It can be obtained by calling OH_VideoDecoder_QueryOutputBuffer. |
Returns
| Type | Description |
|---|---|
| OH_AVBuffer * | Pointer to the OH_AVBuffer instance created. If the operation fails, NULL is returned. |