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_AUDIOCODEC_H 17 #define NATIVE_AVCODEC_AUDIOCODEC_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 Create an audio encoder or decoder instance from the mime type, which is recommended in most cases. 29 * @syscap SystemCapability.Multimedia.Media.AudioCodec 30 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 31 * @param isEncoder true indicates the need to create an encoder, while false indicates the need to create a decoder. 32 * @return Returns a Pointer to an OH_AVCodec instance 33 * @since 11 34 */ 35 OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder); 36 37 /** 38 * @brief Create an audio codec instance through the audio codec name. 39 * The premise of using this interface is to know the exact name of the codec. 40 * @syscap SystemCapability.Multimedia.Media.AudioCodec 41 * @param name Audio codec name 42 * @return Returns a Pointer to an OH_AVCodec instance 43 * @since 11 44 */ 45 OH_AVCodec *OH_AudioCodec_CreateByName(const char *name); 46 47 /** 48 * @brief Clear the internal resources of the codec and destroy the codec instance 49 * @syscap SystemCapability.Multimedia.Media.AudioCodec 50 * @param codec Pointer to an OH_AVCodec instance 51 * @return Returns AV_ERR_OK if the execution is successful, 52 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 53 * @since 11 54 */ 55 OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec); 56 57 /** 58 * @brief Set the asynchronous callback function so that your application 59 * can respond to the events generated by the audio codec. This interface must be called before Prepare is called. 60 * @syscap SystemCapability.Multimedia.Media.AudioCodec 61 * @param codec Pointer to an OH_AVCodec instance 62 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 63 * @param userData User specific data 64 * @return Returns AV_ERR_OK if the execution is successful, 65 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 66 * @since 11 67 */ 68 OH_AVErrCode OH_AudioCodec_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 69 70 /** 71 * @brief To configure the audio codec, typically, you need to configure the description information of the 72 * audio track. This interface must be called before Prepare is called. 73 * @syscap SystemCapability.Multimedia.Media.AudioCodec 74 * @param codec Pointer to an OH_AVCodec instance 75 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be encoded or decoded 76 * @return Returns AV_ERR_OK if the execution is successful, 77 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 78 * @since 11 79 */ 80 OH_AVErrCode OH_AudioCodec_Configure(OH_AVCodec *codec, const OH_AVFormat *format); 81 82 /** 83 * @brief To prepare the internal resources of the codec, the Configure interface must be called 84 * before calling this interface. 85 * @syscap SystemCapability.Multimedia.Media.AudioCodec 86 * @param codec Pointer to an OH_AVCodec instance 87 * @return Returns AV_ERR_OK if the execution is successful, 88 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 89 * @since 11 90 */ 91 OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec); 92 93 /** 94 * @brief Start the codec, this interface must be called after the Prepare is successful. 95 * After being successfully started, the codec will start reporting NeedInputData events. 96 * @syscap SystemCapability.Multimedia.Media.AudioCodec 97 * @param codec Pointer to an OH_AVCodec instance 98 * @return Returns AV_ERR_OK if the execution is successful, 99 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 100 * @since 11 101 */ 102 OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec); 103 104 /** 105 * @brief Stop the codec. After stopping, you can re-enter the Started state through Start, 106 * but it should be noted that need to re-enter if the codec has been input before 107 * Codec-Specific-Data. 108 * @syscap SystemCapability.Multimedia.Media.AudioCodec 109 * @param codec Pointer to an OH_AVCodec instance 110 * @return Returns AV_ERR_OK if the execution is successful, 111 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 112 * @since 11 113 */ 114 OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec); 115 116 /** 117 * @brief Clear the input and output data buffered in the codec. After this interface is called, all the Buffer 118 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 119 * the Buffers corresponding to these indexes. 120 * @syscap SystemCapability.Multimedia.Media.AudioCodec 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 * @since 11 125 */ 126 OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec); 127 128 /** 129 * @brief Reset the codec. To continue encoding or decoding, you need to call the Configure interface again to 130 * configure the codec instance. 131 * @syscap SystemCapability.Multimedia.Media.AudioCodec 132 * @param codec Pointer to an OH_AVCodec instance 133 * @return Returns AV_ERR_OK if the execution is successful, 134 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 135 * @since 11 136 */ 137 138 OH_AVErrCode OH_AudioCodec_Reset(OH_AVCodec *codec); 139 140 /** 141 * @brief Get the description information of the output data of the codec, refer to {@link OH_AVFormat} for details. 142 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 143 * be manually released by calling {@link OH_AVFormat_Destroy}. 144 * @syscap SystemCapability.Multimedia.Media.AudioCodec 145 * @param codec Pointer to an OH_AVCodec instance 146 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription, 147 * or destroyed with OH_AVCodec; 148 * @since 11 149 */ 150 OH_AVFormat *OH_AudioCodec_GetOutputDescription(OH_AVCodec *codec); 151 152 /** 153 * @brief Set dynamic parameters to the codec. Note: This interface can only be called after the codec is started. 154 * At the same time, incorrect parameter settings may cause encoding or decoding failure. 155 * @syscap SystemCapability.Multimedia.Media.AudioCodec 156 * @param codec Pointer to an OH_AVCodec instance 157 * @param format OH_AVFormat handle pointer 158 * @return Returns AV_ERR_OK if the execution is successful, 159 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 160 * @since 11 161 */ 162 OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format); 163 164 /** 165 * @brief Submit the input buffer filled with data to the audio codec. The {@link OH_AVCodecOnNeedInputData} callback 166 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 167 * is submitted to the audio codec, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputData} 168 * callback is received again reporting that the buffer with the same index is available. In addition, for some 169 * codecs, it is required to input Codec-Specific-Data to the codec at the beginning to initialize the encoding or 170 * decoding process of the codec. 171 * @syscap SystemCapability.Multimedia.Media.AudioCodec 172 * @param codec Pointer to an OH_AVCodec instance 173 * @param index Enter the index value corresponding to the Buffer 174 * @return Returns AV_ERR_OK if the execution is successful, 175 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 176 * @since 11 177 */ 178 OH_AVErrCode OH_AudioCodec_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 179 180 /** 181 * @brief Return the processed output Buffer to the codec. 182 * @syscap SystemCapability.Multimedia.Media.AudioCodec 183 * @param codec Pointer to an OH_AVCodec instance 184 * @param index The index value corresponding to the output Buffer 185 * @return Returns AV_ERR_OK if the execution is successful, 186 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 187 * @since 11 188 */ 189 OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 190 191 /** 192 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 193 * switchback from the background 194 * @syscap SystemCapability.Multimedia.Media.AudioCodec 195 * @param codec Pointer to an OH_AVCodec instance 196 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 197 * false if the codec instance is invalid 198 * @return Returns AV_ERR_OK if the execution is successful, 199 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 200 * @since 11 201 */ 202 OH_AVErrCode OH_AudioCodec_IsValid(OH_AVCodec *codec, bool *isValid); 203 204 #ifdef __cplusplus 205 } 206 #endif 207 #endif // NATIVE_AVCODEC_AUDIOCODEC_H