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 * @version 1.0 52 */ 53 typedef struct MediaKeySession MediaKeySession; 54 55 /** 56 * @brief Create an audio encoder or decoder instance from the mime type, which is recommended in most cases. 57 * @syscap SystemCapability.Multimedia.Media.AudioCodec 58 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE} 59 * @param isEncoder true indicates the need to create an encoder, while false indicates the need to create a decoder. 60 * @return Returns a Pointer to an OH_AVCodec instance 61 * @since 11 62 */ 63 OH_AVCodec *OH_AudioCodec_CreateByMime(const char *mime, bool isEncoder); 64 65 /** 66 * @brief Create an audio codec instance through the audio codec name. 67 * The premise of using this interface is to know the exact name of the codec. 68 * @syscap SystemCapability.Multimedia.Media.AudioCodec 69 * @param name Audio codec name 70 * @return Returns a Pointer to an OH_AVCodec instance 71 * @since 11 72 */ 73 OH_AVCodec *OH_AudioCodec_CreateByName(const char *name); 74 75 /** 76 * @brief Clear the internal resources of the codec and destroy the codec instance 77 * @syscap SystemCapability.Multimedia.Media.AudioCodec 78 * @param codec Pointer to an OH_AVCodec instance 79 * @return Returns AV_ERR_OK if the execution is successful, 80 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 81 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 82 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 83 * {@link AV_ERR_NO_MEMORY}, inner resource has already released. 84 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 85 * @since 11 86 */ 87 OH_AVErrCode OH_AudioCodec_Destroy(OH_AVCodec *codec); 88 89 /** 90 * @brief Set the asynchronous callback function so that your application 91 * can respond to the events generated by the audio codec. This interface must be called before Prepare is called. 92 * @syscap SystemCapability.Multimedia.Media.AudioCodec 93 * @param codec Pointer to an OH_AVCodec instance 94 * @param callback A collection of all callback functions, see {@link OH_AVCodecCallback} 95 * @param userData User specific data 96 * @return Returns AV_ERR_OK if the execution is successful, 97 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 98 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 99 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 100 * @since 11 101 */ 102 OH_AVErrCode OH_AudioCodec_RegisterCallback(OH_AVCodec *codec, OH_AVCodecCallback callback, void *userData); 103 104 /** 105 * @brief To configure the audio codec, typically, you need to configure the description information of the 106 * audio track. This interface must be called before Prepare is called. 107 * @syscap SystemCapability.Multimedia.Media.AudioCodec 108 * @param codec Pointer to an OH_AVCodec instance 109 * @param format A pointer to an OH_AVFormat giving a description of the audio track to be encoded or decoded 110 * @return Returns AV_ERR_OK if the execution is successful, 111 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 112 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 113 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 114 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 115 * This could be due to an incorrect state or an unsupported operation. 116 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 117 * @since 11 118 */ 119 OH_AVErrCode OH_AudioCodec_Configure(OH_AVCodec *codec, const OH_AVFormat *format); 120 121 /** 122 * @brief To prepare the internal resources of the codec, the Configure interface must be called 123 * before calling this interface. 124 * @syscap SystemCapability.Multimedia.Media.AudioCodec 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 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 129 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 130 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 131 * This could be due to an incorrect state or an unsupported operation. 132 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 133 * @since 11 134 */ 135 OH_AVErrCode OH_AudioCodec_Prepare(OH_AVCodec *codec); 136 137 /** 138 * @brief Start the codec, this interface must be called after the Prepare is successful. 139 * After being successfully started, the codec will start reporting NeedInputData events. 140 * @syscap SystemCapability.Multimedia.Media.AudioCodec 141 * @param codec Pointer to an OH_AVCodec instance 142 * @return Returns AV_ERR_OK if the execution is successful, 143 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 144 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 145 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 146 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 147 * This could be due to an incorrect state or an unsupported operation. 148 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 149 * @since 11 150 */ 151 OH_AVErrCode OH_AudioCodec_Start(OH_AVCodec *codec); 152 153 /** 154 * @brief Stop the codec. After stopping, you can re-enter the Started state through Start, 155 * but it should be noted that need to re-enter if the codec has been input before 156 * Codec-Specific-Data. 157 * @syscap SystemCapability.Multimedia.Media.AudioCodec 158 * @param codec Pointer to an OH_AVCodec instance 159 * @return Returns AV_ERR_OK if the execution is successful, 160 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 161 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 162 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 163 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 164 * This could be due to an incorrect state or an unsupported operation. 165 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 166 * @since 11 167 */ 168 OH_AVErrCode OH_AudioCodec_Stop(OH_AVCodec *codec); 169 170 /** 171 * @brief Clear the input and output data buffered in the codec. After this interface is called, all the Buffer 172 * indexes previously reported through the asynchronous callback will be invalidated, make sure not to access 173 * the Buffers corresponding to these indexes. 174 * @syscap SystemCapability.Multimedia.Media.AudioCodec 175 * @param codec Pointer to an OH_AVCodec instance 176 * @return Returns AV_ERR_OK if the execution is successful, 177 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 178 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 179 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 180 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 181 * This could be due to an incorrect state or an unsupported operation. 182 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 183 * @since 11 184 */ 185 OH_AVErrCode OH_AudioCodec_Flush(OH_AVCodec *codec); 186 187 /** 188 * @brief Reset the codec. To continue encoding or decoding, you need to call the Configure interface again to 189 * configure the codec instance. 190 * @syscap SystemCapability.Multimedia.Media.AudioCodec 191 * @param codec Pointer to an OH_AVCodec instance 192 * @return Returns AV_ERR_OK if the execution is successful, 193 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 194 * {@link AV_ERR_INVALID_VAL}, the codec is nullptr or invalid. 195 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 196 * @since 11 197 */ 198 199 OH_AVErrCode OH_AudioCodec_Reset(OH_AVCodec *codec); 200 201 /** 202 * @brief Get the description information of the output data of the codec, refer to {@link OH_AVFormat} for details. 203 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to 204 * be manually released by calling {@link OH_AVFormat_Destroy}. 205 * @syscap SystemCapability.Multimedia.Media.AudioCodec 206 * @param codec Pointer to an OH_AVCodec instance 207 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription, 208 * or destroyed with OH_AVCodec; 209 * @since 11 210 */ 211 OH_AVFormat *OH_AudioCodec_GetOutputDescription(OH_AVCodec *codec); 212 213 /** 214 * @brief Set dynamic parameters to the codec. Note: This interface can only be called after the codec is started. 215 * At the same time, incorrect parameter settings may cause encoding or decoding failure. 216 * @syscap SystemCapability.Multimedia.Media.AudioCodec 217 * @param codec Pointer to an OH_AVCodec instance 218 * @param format OH_AVFormat handle pointer 219 * @return Returns AV_ERR_OK if the execution is successful, 220 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 221 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 222 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 223 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 224 * This could be due to an incorrect state or an unsupported operation. 225 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 226 * @since 11 227 */ 228 OH_AVErrCode OH_AudioCodec_SetParameter(OH_AVCodec *codec, const OH_AVFormat *format); 229 230 /** 231 * @brief Submit the input buffer filled with data to the audio codec. The {@link OH_AVCodecOnNeedInputBuffer} callback 232 * will report the available input buffer and the corresponding index value. Once the buffer with the specified index 233 * is submitted to the audio codec, the buffer cannot be accessed again until the {@link OH_AVCodecOnNeedInputBuffer} 234 * callback is received again reporting that the buffer with the same index is available. In addition, for some 235 * codecs, it is required to input Codec-Specific-Data to the codec at the beginning to initialize the encoding or 236 * decoding process of the codec. 237 * @syscap SystemCapability.Multimedia.Media.AudioCodec 238 * @param codec Pointer to an OH_AVCodec instance 239 * @param index Enter the index value corresponding to the 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 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. Buffer index 243 * should be given by {@link OH_AVCodecOnNeedInputBuffer}. 244 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 245 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 246 * This could be due to an incorrect state or an unsupported operation. 247 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 248 * @since 11 249 */ 250 OH_AVErrCode OH_AudioCodec_PushInputBuffer(OH_AVCodec *codec, uint32_t index); 251 252 /** 253 * @brief Return the processed output Buffer to the codec. 254 * @syscap SystemCapability.Multimedia.Media.AudioCodec 255 * @param codec Pointer to an OH_AVCodec instance 256 * @param index The index value corresponding to the output Buffer 257 * @return Returns AV_ERR_OK if the execution is successful, 258 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 259 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. Buffer index 260 * should be given by {@link OH_AVCodecOnNewOutputBuffer}. 261 * {@link AV_ERR_INVALID_STATE}, the interface was called in an invalid state. 262 * {@link AV_ERR_OPERATE_NOT_PERMIT}, operation not permitted. 263 * This could be due to an incorrect state or an unsupported operation. 264 * {@link AV_ERR_UNKNOWN}, internal error occurred, it is recommended to check the logs. 265 * @since 11 266 */ 267 OH_AVErrCode OH_AudioCodec_FreeOutputBuffer(OH_AVCodec *codec, uint32_t index); 268 269 /** 270 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app 271 * switchback from the background 272 * @syscap SystemCapability.Multimedia.Media.AudioCodec 273 * @param codec Pointer to an OH_AVCodec instance 274 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid, 275 * false if the codec instance is invalid 276 * @return Returns AV_ERR_OK if the execution is successful, 277 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 278 * {@link AV_ERR_INVALID_VAL}, input parameter is empty or invalid. 279 * @since 11 280 */ 281 OH_AVErrCode OH_AudioCodec_IsValid(OH_AVCodec *codec, bool *isValid); 282 283 /** 284 * @brief Set decryption info. 285 * @syscap SystemCapability.Multimedia.Media.AudioCodec 286 * @param codec Pointer to an OH_AVCodec instance 287 * @param mediaKeySession A media key session instance with decryption function. 288 * @param secureAudio Require secure decoder or not. 289 * @return {@link AV_ERR_OK} 0 - Success 290 * {@link AV_ERR_INVALID_VAL} 3 - If the codec instance is nullptr or invalid, 291 * the mediaKeySession is nullptr or invalid. 292 * {@link AV_ERR_INVALID_STATE} 8 - If the codec service is invalid. 293 * {@link AV_ERR_NO_MEMORY}, failed to request memory. 294 * @since 12 295 * @version 1.0 296 */ 297 OH_AVErrCode OH_AudioCodec_SetDecryptionConfig(OH_AVCodec *codec, MediaKeySession *mediaKeySession, 298 bool secureAudio); 299 #ifdef __cplusplus 300 } 301 #endif 302 #endif // NATIVE_AVCODEC_AUDIOCODEC_H 303 /** @} */