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