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 AudioEncoder 18 * @{ 19 * 20 * @brief The AudioEncoder module provides functions for audio encoding. 21 * 22 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 23 * @since 9 24 */ 25 26 /** 27 * @file native_avcodec_audioencoder.h 28 * 29 * @brief Declare the Native API used for audio encoding. 30 * 31 * @kit AVCodecKit 32 * @library libnative_media_aenc.so 33 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 34 * @since 9 35 */ 36 37 #ifndef NATIVE_AVCODEC_AUDIOENCODER_H 38 #define NATIVE_AVCODEC_AUDIOENCODER_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 encoder instance from the mime type, this interface is recommended in most cases. 50 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 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_AudioEncoder_CreateByMime(const char *mime); 59 60 /** 61 * @brief Create an audio encoder instance through the audio encoder name. 62 * The premise of using this interface is to know the exact name of the encoder. 63 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 64 * @param name Audio encoder 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_AudioEncoder_CreateByName(const char *name); 72 73 /** 74 * @brief Clear the internal resources of the encoder and destroy the encoder instance 75 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 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_AudioEncoder_Destroy(OH_AVCodec *codec); 85 86 /** 87 * @brief Set the asynchronous callback function so that your application can respond to 88 * the events generated by the audio encoder. This interface must be called before Prepare is called. 89 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 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_AudioEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData); 101 102 /** 103 * @brief To configure the audio encoder, typically, you need to configure the description information of 104 * the encoded audio track. This interface must be called before Prepare is called. 105 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 106 * @param codec Pointer to an OH_AVCodec instance 107 * @param format OH_AVFormat handle pointer 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_AudioEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format); 116 117 /** 118 * @brief To prepare the internal resources of the encoder, 119 * the Configure interface must be called before calling this interface. 120 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 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_AudioEncoder_Prepare(OH_AVCodec *codec); 130 131 /** 132 * @brief Start the encoder, this interface must be called after the Prepare is successful. 133 * After being successfully started, the encoder will start reporting NeedInputData events. 134 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 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_AudioEncoder_Start(OH_AVCodec *codec); 144 145 /** 146 * @brief Stop the encoder. After stopping, you can re-enter the Started state through Start. 147 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 148 * @param codec Pointer to an OH_AVCodec instance 149 * @return Returns AV_ERR_OK if the execution is successful, 150 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 151 * @deprecated since 11 152 * @useinstead OH_AudioCodec_Stop 153 * @since 9 154 * @version 1.0 155 */ 156 OH_AVErrCode OH_AudioEncoder_Stop(OH_AVCodec *codec); 157 158 /** 159 * @brief Clear the input and output data buffered in the encoder. After this interface is called, 160 * all the Buffer indexes previously reported through the asynchronous callback will be invalidated, 161 * make sure not to access the Buffers corresponding to these indexes. 162 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 163 * @param codec Pointer to an OH_AVCodec instance 164 * @return Returns AV_ERR_OK if the execution is successful, 165 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 166 * @deprecated since 11 167 * @useinstead OH_AudioCodec_Flush 168 * @since 9 169 * @version 1.0 170 */ 171 OH_AVErrCode OH_AudioEncoder_Flush(OH_AVCodec *codec); 172 173 /** 174 * @brief Reset the encoder. To continue coding, you need to call the Configure interface 175 * again to configure the encoder instance. 176 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 177 * @param codec Pointer to an OH_AVCodec instance 178 * @return Returns AV_ERR_OK if the execution is successful, 179 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 180 * @deprecated since 11 181 * @useinstead OH_AudioCodec_Reset 182 * @since 9 183 * @version 1.0 184 */ 185 OH_AVErrCode OH_AudioEncoder_Reset(OH_AVCodec *codec); 186 187 /** 188 * @brief Get the description information of the output data of the encoder, refer to {@link OH_AVFormat} for details. 189 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 190 * be manually released by the caller. 191 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 192 * @param codec Pointer to an OH_AVCodec instance 193 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription, 194 * or destroyed with OH_AVCodec; 195 * @deprecated since 11 196 * @useinstead OH_AudioCodec_GetOutputDescription 197 * @since 9 198 * @version 1.0 199 */ 200 OH_AVFormat *OH_AudioEncoder_GetOutputDescription(OH_AVCodec *codec); 201 202 /** 203 * @brief Set dynamic parameters to the encoder. Note: This interface can only be called after the encoder is started. 204 * At the same time, incorrect parameter settings may cause the encoding to fail. 205 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 206 * @param codec Pointer to an OH_AVCodec instance 207 * @param format OH_AVFormat handle pointer 208 * @return Returns AV_ERR_OK if the execution is successful, 209 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 210 * @deprecated since 11 211 * @useinstead OH_AudioCodec_SetParameter 212 * @since 9 213 * @version 1.0 214 */ 215 OH_AVErrCode OH_AudioEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format); 216 217 /** 218 * @brief Submit the input buffer filled with data to the audio encoder. The {@link OH_AVCodecOnNeedInputData} 219 * callback will report the available input buffer and the corresponding index value. Once the buffer with the 220 * specified index is submitted to the audio encoder, the buffer cannot be accessed again until the 221 * callback is received again reporting that the buffer with the same index is available 222 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 223 * @param codec Pointer to an OH_AVCodec instance 224 * @param index Enter the index value corresponding to the Buffer 225 * @param attr Information describing the data contained in the Buffer 226 * @return Returns AV_ERR_OK if the execution is successful, 227 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 228 * @deprecated since 11 229 * @useinstead OH_AudioCodec_PushInputBuffer 230 * @since 9 231 * @version 1.0 232 */ 233 OH_AVErrCode OH_AudioEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr); 234 235 /** 236 * @brief Return the processed output Buffer to the encoder. 237 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 238 * @param codec Pointer to an OH_AVCodec instance 239 * @param index The index value corresponding to the output Buffer 240 * @return Returns AV_ERR_OK if the execution is successful, 241 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 242 * @deprecated since 11 243 * @useinstead OH_AudioCodec_FreeOutputBuffer 244 * @since 9 245 * @version 1.0 246 */ 247 OH_AVErrCode OH_AudioEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index); 248 249 /** 250 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 251 * switchback from the background 252 * @syscap SystemCapability.Multimedia.Media.AudioEncoder 253 * @param codec Pointer to an OH_AVCodec instance 254 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 255 * false if the codec instance is invalid 256 * @return Returns AV_ERR_OK if the execution is successful, 257 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 258 * @deprecated since 11 259 * @useinstead OH_AudioCodec_IsValid 260 * @since 10 261 */ 262 OH_AVErrCode OH_AudioEncoder_IsValid(OH_AVCodec *codec, bool *isValid); 263 264 #ifdef __cplusplus 265 } 266 #endif 267 #endif // NATIVE_AVCODEC_AUDIOENCODER_H 268 /** @} */