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