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 AudioCodec 18 * @{ 19 * 20 * @brief The AudioCodec module provides functions for audio encoding and decoding. 21 * 22 * @syscap SystemCapability.Multimedia.Media.AudioCodec 23 * @since 11 24 */ 25 26 /** 27 * @file native_avcodec_audiocodec.h 28 * 29 * @brief Declare the Native API used for audio encoding and decoding. 30 * 31 * @kit AVCodecKit 32 * @library libnative_media_acodec.so 33 * @syscap SystemCapability.Multimedia.Media.AudioCodec 34 * @since 11 35 */ 36 37 #ifndef NATIVE_AVCODEC_AUDIOCODEC_H 38 #define NATIVE_AVCODEC_AUDIOCODEC_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 MediaKeySession field. 50 * @since 12 51 */ 52 typedef struct MediaKeySession MediaKeySession; 53 54 /** 55 * @brief Create an audio encoder or decoder instance from the mime type, which is recommended in most cases. 56 * @syscap SystemCapability.Multimedia.Media.AudioCodec 57 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 58 * @param isEncoder true indicates the need to create an encoder, while false indicates the need to create a decoder. 59 * @return Returns a Pointer to an OH_AVCodec instance 60 * @since 11 61 */ 62 OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder); 63 64 /** 65 * @brief Create an audio codec instance through the audio codec name. 66 * The premise of using this interface is to know the exact name of the codec. 67 * @syscap SystemCapability.Multimedia.Media.AudioCodec 68 * @param name Audio codec name 69 * @return Returns a Pointer to an OH_AVCodec instance 70 * @since 11 71 */ 72 OH_AVCodec *OH_AudioCodec_CreateByName(const char *name); 73 74 /** 75 * @brief Clear the internal resources of the codec and destroy the codec instance 76 * @syscap SystemCapability.Multimedia.Media.AudioCodec 77 * @param codec Pointer to an OH_AVCodec instance 78 * @return Returns AV_ERR_OK if the execution is successful, 79 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 80 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 81 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 82 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 83 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 84 * @since 11 85 */ 86 OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec); 87 88 /** 89 * @brief Set the asynchronous callback function so that your application 90 * can respond to the events generated by the audio codec. This interface must be called before Prepare is called. 91 * @syscap SystemCapability.Multimedia.Media.AudioCodec 92 * @param codec Pointer to an OH_AVCodec instance 93 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 94 * @param userData User specific data 95 * @return Returns AV_ERR_OK if the execution is successful, 96 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 97 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 98 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 99 * @since 11 100 */ 101 OH_AVErrCode OH_AudioCodec_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 102 103 /** 104 * @brief To configure the audio codec, typically, you need to configure the description information of the 105 * audio track. This interface must be called before Prepare is called. 106 * @syscap SystemCapability.Multimedia.Media.AudioCodec 107 * @param codec Pointer to an OH_AVCodec instance 108 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be encoded or decoded 109 * @return Returns AV_ERR_OK if the execution is successful, 110 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 111 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 112 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 113 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 114 * This could be due to an incorrect state or an unsupported operation. 115 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 116 * @since 11 117 */ 118 OH_AVErrCode OH_AudioCodec_Configure(OH_AVCodec *codec, const OH_AVFormat *format); 119 120 /** 121 * @brief To prepare the internal resources of the codec, the Configure interface must be called 122 * before calling this interface. 123 * @syscap SystemCapability.Multimedia.Media.AudioCodec 124 * @param codec Pointer to an OH_AVCodec instance 125 * @return Returns AV_ERR_OK if the execution is successful, 126 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 127 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 128 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 129 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 130 * This could be due to an incorrect state or an unsupported operation. 131 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 132 * @since 11 133 */ 134 OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec); 135 136 /** 137 * @brief Start the codec, this interface must be called after the Prepare is successful. 138 * After being successfully started, the codec will start reporting NeedInputData events. 139 * @syscap SystemCapability.Multimedia.Media.AudioCodec 140 * @param codec Pointer to an OH_AVCodec instance 141 * @return Returns AV_ERR_OK if the execution is successful, 142 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 143 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 144 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 145 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 146 * This could be due to an incorrect state or an unsupported operation. 147 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 148 * @since 11 149 */ 150 OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec); 151 152 /** 153 * @brief Stop the codec. After stopping, you can re-enter the Started state through Start, 154 * but it should be noted that need to re-enter if the codec has been input before 155 * Codec-Specific-Data. 156 * @syscap SystemCapability.Multimedia.Media.AudioCodec 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 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 161 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 162 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 163 * This could be due to an incorrect state or an unsupported operation. 164 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 165 * @since 11 166 */ 167 OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec); 168 169 /** 170 * @brief Clear the input and output data buffered in the codec. After this interface is called, all the Buffer 171 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 172 * the Buffers corresponding to these indexes. 173 * @syscap SystemCapability.Multimedia.Media.AudioCodec 174 * @param codec Pointer to an OH_AVCodec instance 175 * @return Returns AV_ERR_OK if the execution is successful, 176 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 177 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 178 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 179 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 180 * This could be due to an incorrect state or an unsupported operation. 181 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 182 * @since 11 183 */ 184 OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec); 185 186 /** 187 * @brief Reset the codec. To continue encoding or decoding, you need to call the Configure interface again to 188 * configure the codec instance. 189 * @syscap SystemCapability.Multimedia.Media.AudioCodec 190 * @param codec Pointer to an OH_AVCodec instance 191 * @return Returns AV_ERR_OK if the execution is successful, 192 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 193 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 194 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 195 * @since 11 196 */ 197 198 OH_AVErrCode OH_AudioCodec_Reset(OH_AVCodec *codec); 199 200 /** 201 * @brief Get the description information of the output data of the codec, refer to {@link OH_AVFormat} for details. 202 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 203 * be manually released by calling {@link OH_AVFormat_Destroy}. 204 * @syscap SystemCapability.Multimedia.Media.AudioCodec 205 * @param codec Pointer to an OH_AVCodec instance 206 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with 207 * the next {@link OH_AudioCodec_GetOutputDescription}, or destroyed with OH_AVCodec; 208 * @since 11 209 */ 210 OH_AVFormat *OH_AudioCodec_GetOutputDescription(OH_AVCodec *codec); 211 212 /** 213 * @brief Set dynamic parameters to the codec. Note: This interface can only be called after the codec is started. 214 * At the same time, incorrect parameter settings may cause encoding or decoding failure. 215 * @syscap SystemCapability.Multimedia.Media.AudioCodec 216 * @param codec Pointer to an OH_AVCodec instance 217 * @param format OH_AVFormat handle pointer 218 * @return Returns AV_ERR_OK if the execution is successful, 219 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 220 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 221 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 222 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 223 * This could be due to an incorrect state or an unsupported operation. 224 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 225 * @since 11 226 */ 227 OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format); 228 229 /** 230 * @brief Submit the input buffer filled with data to the audio codec. The {@link OH_AVCodecOnNeedInputBuffer} callback 231 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 232 * is submitted to the audio codec, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputBuffer} 233 * callback is received again reporting that the buffer with the same index is available. In addition, for some 234 * codecs, it is required to input Codec-Specific-Data to the codec at the beginning to initialize the encoding or 235 * decoding process of the codec. 236 * @syscap SystemCapability.Multimedia.Media.AudioCodec 237 * @param codec Pointer to an OH_AVCodec instance 238 * @param index Enter the index value corresponding to the Buffer 239 * @return Returns AV_ERR_OK if the execution is successful, 240 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 241 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. Buffer index 242 * should be given by {@link OH_AVCodecOnNeedInputBuffer}. 243 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 244 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 245 * This could be due to an incorrect state or an unsupported operation. 246 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 247 * @since 11 248 */ 249 OH_AVErrCode OH_AudioCodec_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 250 251 /** 252 * @brief Return the processed output Buffer to the codec. 253 * @syscap SystemCapability.Multimedia.Media.AudioCodec 254 * @param codec Pointer to an OH_AVCodec instance 255 * @param index The index value corresponding to the output Buffer 256 * @return Returns AV_ERR_OK if the execution is successful, 257 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 258 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. Buffer index 259 * should be given by {@link OH_AVCodecOnNewOutputBuffer}. 260 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 261 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 262 * This could be due to an incorrect state or an unsupported operation. 263 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 264 * @since 11 265 */ 266 OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 267 268 /** 269 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 270 * switchback from the background 271 * @syscap SystemCapability.Multimedia.Media.AudioCodec 272 * @param codec Pointer to an OH_AVCodec instance 273 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 274 * false if the codec instance is invalid 275 * @return Returns AV_ERR_OK if the execution is successful, 276 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 277 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 278 * @since 11 279 */ 280 OH_AVErrCode OH_AudioCodec_IsValid(OH_AVCodec *codec, bool *isValid); 281 282 /** 283 * @brief Set decryption info. 284 * @syscap SystemCapability.Multimedia.Media.AudioCodec 285 * @param codec Pointer to an OH_AVCodec instance 286 * @param mediaKeySession A media key session instance with decryption function. 287 * @param secureAudio Require secure decoder or not. 288 * @return {@link AV_ERR_OK} 0 - Success 289 * {@link AV_ERR_INVALID_VAL} 3 - If the codec instance is nullptr or invalid, 290 * the mediaKeySession is nullptr or invalid. 291 * {@link AV_ERR_INVALID_STATE} 8 - If the codec service is invalid. 292 * {@link AV_ERR_NO_MEMORY}, failed to request memory. 293 * @since 12 294 * @version 1.0 295 */ 296 OH_AVErrCode OH_AudioCodec_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, 297 bool secureAudio); 298 299 /** 300 * @brief Queries the index of the next available input buffer. 301 * 302 * This API must be followed by calling {@link OH_AudioCodec_GetInputBuffer} to obtain the buffer handle, 303 * which should then be passed to the codec via {@link OH_AudioCodec_PushInputBuffer}.\n 304 * Note: This operation is only supported in synchronous mode.\n 305 * 306 * @syscap SystemCapability.Multimedia.Media.AudioCodec 307 * @param codec Pointer to an OH_AVCodec instance. 308 * @param index The index of the input buffer. 309 * @param timeoutUs Timeout duration in microseconds, negative value indicates infinite wait. 310 * @return Returns AV_ERR_OK if the execution is successful, 311 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 312 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 313 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 314 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permitted in asynchronous mode. 315 * {@link AV_ERR_TRY_AGAIN_LATER}, query failed, recommended retry after delay. 316 * @since 20 317 */ 318 OH_AVErrCode OH_AudioCodec_QueryInputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 319 320 /** 321 * @brief Acquires the handle of an available input buffer. 322 * 323 * Note: It's only applicable in synchronous mode.\n 324 * 325 * @syscap SystemCapability.Multimedia.Media.AudioCodec 326 * @param codec Pointer to an OH_AVCodec instance 327 * @param index Buffer index obtained via {@link OH_AudioCodec_QueryInputBuffer}. 328 * @return Returns a Pointer to an OH_AVBuffer instance. 329 * Return nullptr if no buffer available. 330 * @since 20 331 */ 332 OH_AVBuffer *OH_AudioCodec_GetInputBuffer(struct OH_AVCodec *codec, uint32_t index); 333 334 /** 335 * @brief Queries the index of the next available output buffer. 336 * 337 * The obtained buffer handle through {@link OH_AudioCodec_GetOutputBuffer} must be 338 * return to the audio codec via {@link OH_AudioCodec_FreeOutputBuffer}.\n 339 * Note: This operation is only supported in synchronous mode.\n 340 * 341 * @syscap SystemCapability.Multimedia.Media.AudioCodec 342 * @param codec Pointer to an OH_AVCodec instance 343 * @param index The index of the output buffer 344 * @param timeoutUs Timeout duration in microseconds, negative value indicates infinite wait. 345 * @return Returns AV_ERR_OK if the execution is successful, 346 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}. 347 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 348 * {@link AV_ERR_INVALID_STATE}, this interface was called in invalid state. 349 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permitted in asynchronous mode. 350 * {@link AV_ERR_STREAM_CHANGED}, stream format changed, call {@link OH_AudioCodec_GetOutputDescription} to 351 * retrieve new steam information. 352 * {@link AV_ERR_TRY_AGAIN_LATER}, query failed, recommended retry after delay. 353 * @since 20 354 */ 355 OH_AVErrCode OH_AudioCodec_QueryOutputBuffer(struct OH_AVCodec *codec, uint32_t *index, int64_t timeoutUs); 356 357 /** 358 * @brief Get the available output buffer handle. 359 * 360 * Note: This operation is only supported in synchronous mode.\n 361 * 362 * @syscap SystemCapability.Multimedia.Media.AudioCodec 363 * @param codec Pointer to an OH_AVCodec instance 364 * @param index The index value corresponding to the output buffer, 365 * should be given by {@link OH_AudioCodec_QueryOutputBuffer}. 366 * @return Returns a Pointer to an OH_AVBuffer instance. 367 * Return nullptr if no buffer available. 368 * @since 20 369 */ 370 OH_AVBuffer *OH_AudioCodec_GetOutputBuffer(struct OH_AVCodec *codec, uint32_t index); 371 372 #ifdef __cplusplus 373 } 374 #endif 375 #endif // NATIVE_AVCODEC_AUDIOCODEC_H 376 /** @} */