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