1 /* 2 * Copyright (C) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef NATIVE_AVCODEC_AUDIODECODER_H 17 #define NATIVE_AVCODEC_AUDIODECODER_H 18 19 #include <stdint.h> 20 #include <stdio.h> 21 #include "native_averrors.h" 22 #include "native_avformat.h" 23 #include "native_avmemory.h" 24 #include "native_avcodec_base.h" 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @brief Creates an audio decoder instance from the mime type, which is recommended in most cases. 32 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 33 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 34 * @return Returns a Pointer to an OH_AVCodec instance 35 * @since 9 36 * @version 1.0 37 */ 38 OH_AVCodec *OH_AudioDecoder_CreateByMime(const char *mime); 39 40 /** 41 * @brief Create an audio decoder instance through the audio decoder name. 42 * The premise of using this interface is to know the exact name of the decoder. 43 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 44 * @param name Audio codec name 45 * @return Returns a Pointer to an OH_AVCodec instance 46 * @since 9 47 * @version 1.0 48 */ 49 OH_AVCodec *OH_AudioDecoder_CreateByName(const char *name); 50 51 /** 52 * @brief Clear the internal resources of the decoder and destroy the decoder instance 53 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 54 * @param codec Pointer to an OH_AVCodec instance 55 * @return Returns AV_ERR_OK if the execution is successful, 56 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 57 * @since 9 58 * @version 1.0 59 */ 60 OH_AVErrCode OH_AudioDecoder_Destroy(OH_AVCodec *codec); 61 62 /** 63 * @brief Set the asynchronous callback function so that your application 64 * can respond to the events generated by the audio decoder. This interface must be called before Prepare is called. 65 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 66 * @param codec Pointer to an OH_AVCodec instance 67 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} 68 * @param userData User specific data 69 * @return Returns AV_ERR_OK if the execution is successful, 70 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 71 * @since 9 72 * @version 1.0 73 */ 74 OH_AVErrCode OH_AudioDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 75 76 /** 77 * @brief To configure the audio decoder, typically, you need to configure the description information of the decoded 78 * audio track, which can be extracted from the container. This interface must be called before Prepare is called. 79 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 80 * @param codec Pointer to an OH_AVCodec instance 81 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be decoded 82 * @return Returns AV_ERR_OK if the execution is successful, 83 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 84 * @since 9 85 * @version 1.0 86 */ 87 OH_AVErrCode OH_AudioDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 88 89 /** 90 * @brief To prepare the internal resources of the decoder, the Configure interface must be called 91 * before calling this interface. 92 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 93 * @param codec Pointer to an OH_AVCodec instance 94 * @return Returns AV_ERR_OK if the execution is successful, 95 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 96 * @since 9 97 * @version 1.0 98 */ 99 OH_AVErrCode OH_AudioDecoder_Prepare(OH_AVCodec *codec); 100 101 /** 102 * @brief Start the decoder, this interface must be called after the Prepare is successful. 103 * After being successfully started, the decoder will start reporting NeedInputData events. 104 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 105 * @param codec Pointer to an OH_AVCodec instance 106 * @return Returns AV_ERR_OK if the execution is successful, 107 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 108 * @since 9 109 * @version 1.0 110 */ 111 OH_AVErrCode OH_AudioDecoder_Start(OH_AVCodec *codec); 112 113 /** 114 * @brief Stop the decoder. After stopping, you can re-enter the Started state through Start, 115 * but it should be noted that need to re-enter if the decoder has been input before 116 * Codec-Specific-Data. 117 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 118 * @param codec Pointer to an OH_AVCodec instance 119 * @return Returns AV_ERR_OK if the execution is successful, 120 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 121 * @since 9 122 * @version 1.0 123 */ 124 OH_AVErrCode OH_AudioDecoder_Stop(OH_AVCodec *codec); 125 126 /** 127 * @brief Clear the input and output data buffered in the decoder. After this interface is called, all the Buffer 128 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 129 * the Buffers corresponding to these indexes. 130 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 131 * @param codec Pointer to an OH_AVCodec instance 132 * @return Returns AV_ERR_OK if the execution is successful, 133 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 134 * @since 9 135 * @version 1.0 136 */ 137 OH_AVErrCode OH_AudioDecoder_Flush(OH_AVCodec *codec); 138 139 /** 140 * @brief Reset the decoder. To continue decoding, you need to call the Configure interface again to 141 * configure the decoder instance. 142 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 143 * @param codec Pointer to an OH_AVCodec instance 144 * @return Returns AV_ERR_OK if the execution is successful, 145 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 146 * @since 9 147 * @version 1.0 148 */ 149 150 OH_AVErrCode OH_AudioDecoder_Reset(OH_AVCodec *codec); 151 152 /** 153 * @brief Get the description information of the output data of the decoder, refer to {@link OH_AVFormat} for details. 154 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 155 * be manually released by the caller 156 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 157 * @param codec Pointer to an OH_AVCodec instance 158 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription, 159 * or destroyed with OH_AVCodec; 160 * @since 9 161 * @version 1.0 162 */ 163 OH_AVFormat *OH_AudioDecoder_GetOutputDescription(OH_AVCodec *codec); 164 165 /** 166 * @brief Set dynamic parameters to the decoder. Note: This interface can only be called after the decoder is started. 167 * At the same time, incorrect parameter settings may cause decoding failure. 168 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 169 * @param codec Pointer to an OH_AVCodec instance 170 * @param format OH_AVFormat handle pointer 171 * @return Returns AV_ERR_OK if the execution is successful, 172 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 173 * @since 9 174 * @version 1.0 175 */ 176 OH_AVErrCode OH_AudioDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 177 178 /** 179 * @brief Submit the input buffer filled with data to the audio decoder. The {@link OH_AVCodecOnNeedInputData} callback 180 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 181 * is submitted to the audio decoder, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData} 182 * callback is received again reporting that the buffer with the same index is available. In addition, for some 183 * decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding 184 * process of the decoder. 185 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 186 * @param codec Pointer to an OH_AVCodec instance 187 * @param index Enter the index value corresponding to the Buffer 188 * @param attr Information describing the data contained in the Buffer 189 * @return Returns AV_ERR_OK if the execution is successful, 190 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 191 * @since 9 192 * @version 1.0 193 */ 194 OH_AVErrCode OH_AudioDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 195 196 /** 197 * @brief Return the processed output Buffer to the decoder. 198 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 199 * @param codec Pointer to an OH_AVCodec instance 200 * @param index The index value corresponding to the output Buffer 201 * @return Returns AV_ERR_OK if the execution is successful, 202 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 203 * @since 9 204 * @version 1.0 205 */ 206 OH_AVErrCode OH_AudioDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 207 208 #ifdef __cplusplus 209 } 210 #endif 211 212 #endif // NATIVE_AVCODEC_AUDIODECODER_H