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