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