1 /* 2 * Copyright (C) 2023 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_avcodec_base.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * @brief Creates an audio decoder instance from the mime type, which is recommended in most cases. 29 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 30 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 31 * @return Returns a Pointer to an OH_AVCodec instance 32 * @deprecated since 11 33 * @useinstead OH_AudioCodec_CreateByMime 34 * @since 9 35 * @version 1.0 36 */ 37 OH_AVCodec *OH_AudioDecoder_CreateByMime(const char *mime); 38 39 /** 40 * @brief Create an audio decoder instance through the audio decoder name. 41 * The premise of using this interface is to know the exact name of the decoder. 42 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 43 * @param name Audio codec name 44 * @return Returns a Pointer to an OH_AVCodec instance 45 * @deprecated since 11 46 * @useinstead OH_AudioCodec_CreateByName 47 * @since 9 48 * @version 1.0 49 */ 50 OH_AVCodec *OH_AudioDecoder_CreateByName(const char *name); 51 52 /** 53 * @brief Clear the internal resources of the decoder and destroy the decoder instance 54 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 55 * @param codec Pointer to an OH_AVCodec instance 56 * @return Returns AV_ERR_OK if the execution is successful, 57 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 58 * @deprecated since 11 59 * @useinstead OH_AudioCodec_Destroy 60 * @since 9 61 * @version 1.0 62 */ 63 OH_AVErrCode OH_AudioDecoder_Destroy(OH_AVCodec *codec); 64 65 /** 66 * @brief Set the asynchronous callback function so that your application 67 * can respond to the events generated by the audio decoder. This interface must be called before Prepare is called. 68 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 69 * @param codec Pointer to an OH_AVCodec instance 70 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback} 71 * @param userData User specific data 72 * @return Returns AV_ERR_OK if the execution is successful, 73 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 74 * @deprecated since 11 75 * @useinstead OH_AudioCodec_RegisterCallback 76 * @since 9 77 * @version 1.0 78 */ 79 OH_AVErrCode OH_AudioDecoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 80 81 /** 82 * @brief To configure the audio decoder, typically, you need to configure the description information of the decoded 83 * audio track, which can be extracted from the OH_AVSource. This interface must be called before Prepare is called. 84 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 85 * @param codec Pointer to an OH_AVCodec instance 86 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be decoded 87 * @return Returns AV_ERR_OK if the execution is successful, 88 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 89 * @deprecated since 11 90 * @useinstead OH_AudioCodec_Configure 91 * @since 9 92 * @version 1.0 93 */ 94 OH_AVErrCode OH_AudioDecoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 95 96 /** 97 * @brief To prepare the internal resources of the decoder, the Configure interface must be called 98 * before calling this interface. 99 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 100 * @param codec Pointer to an OH_AVCodec instance 101 * @return Returns AV_ERR_OK if the execution is successful, 102 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 103 * @deprecated since 11 104 * @useinstead OH_AudioCodec_Prepare 105 * @since 9 106 * @version 1.0 107 */ 108 OH_AVErrCode OH_AudioDecoder_Prepare(OH_AVCodec *codec); 109 110 /** 111 * @brief Start the decoder, this interface must be called after the Prepare is successful. 112 * After being successfully started, the decoder will start reporting NeedInputData events. 113 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 114 * @param codec Pointer to an OH_AVCodec instance 115 * @return Returns AV_ERR_OK if the execution is successful, 116 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 117 * @deprecated since 11 118 * @useinstead OH_AudioCodec_Start 119 * @since 9 120 * @version 1.0 121 */ 122 OH_AVErrCode OH_AudioDecoder_Start(OH_AVCodec *codec); 123 124 /** 125 * @brief Stop the decoder. After stopping, you can re-enter the Started state through Start, 126 * but it should be noted that need to re-enter if the decoder has been input before 127 * Codec-Specific-Data. 128 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 129 * @param codec Pointer to an OH_AVCodec instance 130 * @return Returns AV_ERR_OK if the execution is successful, 131 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 132 * @deprecated since 11 133 * @useinstead OH_AudioCodec_Stop 134 * @since 9 135 * @version 1.0 136 */ 137 OH_AVErrCode OH_AudioDecoder_Stop(OH_AVCodec *codec); 138 139 /** 140 * @brief Clear the input and output data buffered in the decoder. After this interface is called, all the Buffer 141 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 142 * the Buffers corresponding to these indexes. 143 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 144 * @param codec Pointer to an OH_AVCodec instance 145 * @return Returns AV_ERR_OK if the execution is successful, 146 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 147 * @deprecated since 11 148 * @useinstead OH_AudioCodec_Flush 149 * @since 9 150 * @version 1.0 151 */ 152 OH_AVErrCode OH_AudioDecoder_Flush(OH_AVCodec *codec); 153 154 /** 155 * @brief Reset the decoder. To continue decoding, you need to call the Configure interface again to 156 * configure the decoder instance. 157 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 158 * @param codec Pointer to an OH_AVCodec instance 159 * @return Returns AV_ERR_OK if the execution is successful, 160 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 161 * @deprecated since 11 162 * @useinstead OH_AudioCodec_Reset 163 * @since 9 164 * @version 1.0 165 */ 166 167 OH_AVErrCode OH_AudioDecoder_Reset(OH_AVCodec *codec); 168 169 /** 170 * @brief Get the description information of the output data of the decoder, refer to {@link OH_AVFormat} for details. 171 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 172 * be manually released by the caller 173 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 174 * @param codec Pointer to an OH_AVCodec instance 175 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription, 176 * or destroyed with OH_AVCodec; 177 * @deprecated since 11 178 * @useinstead OH_AudioCodec_GetOutputDescription 179 * @since 9 180 * @version 1.0 181 */ 182 OH_AVFormat *OH_AudioDecoder_GetOutputDescription(OH_AVCodec *codec); 183 184 /** 185 * @brief Set dynamic parameters to the decoder. Note: This interface can only be called after the decoder is started. 186 * At the same time, incorrect parameter settings may cause decoding failure. 187 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 188 * @param codec Pointer to an OH_AVCodec instance 189 * @param format OH_AVFormat handle pointer 190 * @return Returns AV_ERR_OK if the execution is successful, 191 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 192 * @deprecated since 11 193 * @useinstead OH_AudioCodec_SetParameter 194 * @since 9 195 * @version 1.0 196 */ 197 OH_AVErrCode OH_AudioDecoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 198 199 /** 200 * @brief Submit the input buffer filled with data to the audio decoder. The {@link OH_AVCodecOnNeedInputData} callback 201 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 202 * is submitted to the audio decoder, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData} 203 * callback is received again reporting that the buffer with the same index is available. In addition, for some 204 * decoders, it is required to input Codec-Specific-Data to the decoder at the beginning to initialize the decoding 205 * process of the decoder. 206 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 207 * @param codec Pointer to an OH_AVCodec instance 208 * @param index Enter the index value corresponding to the Buffer 209 * @param attr Information describing the data contained in the Buffer 210 * @return Returns AV_ERR_OK if the execution is successful, 211 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 212 * @deprecated since 11 213 * @useinstead OH_AudioCodec_PushInputBuffer 214 * @since 9 215 * @version 1.0 216 */ 217 OH_AVErrCode OH_AudioDecoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 218 219 /** 220 * @brief Return the processed output Buffer to the decoder. 221 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 222 * @param codec Pointer to an OH_AVCodec instance 223 * @param index The index value corresponding to the output Buffer 224 * @return Returns AV_ERR_OK if the execution is successful, 225 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 226 * @deprecated since 11 227 * @useinstead OH_AudioCodec_FreeOutputBuffer 228 * @since 9 229 * @version 1.0 230 */ 231 OH_AVErrCode OH_AudioDecoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 232 233 /** 234 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 235 * switchback from the background 236 * @syscap SystemCapability.Multimedia.Media.AudioDecoder 237 * @param codec Pointer to an OH_AVCodec instance 238 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 239 * false if the codec instance is invalid 240 * @return Returns AV_ERR_OK if the execution is successful, 241 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 242 * @deprecated since 11 243 * @useinstead OH_AudioCodec_IsValid 244 * @since 10 245 */ 246 OH_AVErrCode OH_AudioDecoder_IsValid(OH_AVCodec *codec, bool *isValid); 247 248 #ifdef __cplusplus 249 } 250 #endif 251 #endif // NATIVE_AVCODEC_AUDIODECODER_H