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