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_audioencoder.h
18 *
19 * @brief Provides audio encoder capabilities.
20 *
21 * @kit AVCodecKit
22 * @library libnative_media_aenc.so
23 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
24 * @since 9
25 */
26
27#ifndef NATIVE_AVCODEC_AUDIOENCODER_H
28#define NATIVE_AVCODEC_AUDIOENCODER_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 Creates an audio encoder instance from the mime type, this interface is recommended in most cases.
40 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
41 * @param mime mime type description string, refer to {@link AVCODEC_MIME_TYPE}
42 * @return Returns a Pointer to an OH_AVCodec instance
43 * @deprecated since 11
44 * @useinstead OH_AudioCodec_CreateByMime
45 * @since 9
46 * @version 1.0
47 */
48OH_AVCodec *OH_AudioEncoder_CreateByMime(const char *mime);
49
50/**
51 * @brief Create an audio encoder instance through the audio encoder name.
52 * The premise of using this interface is to know the exact name of the encoder.
53 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
54 * @param name Audio encoder name
55 * @return Returns a Pointer to an OH_AVCodec instance
56 * @deprecated since 11
57 * @useinstead OH_AudioCodec_CreateByName
58 * @since 9
59 * @version 1.0
60 */
61OH_AVCodec *OH_AudioEncoder_CreateByName(const char *name);
62
63/**
64 * @brief Clear the internal resources of the encoder and destroy the encoder instance
65 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
66 * @param codec Pointer to an OH_AVCodec instance
67 * @return Returns AV_ERR_OK if the execution is successful,
68 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
69 * @deprecated since 11
70 * @useinstead OH_AudioCodec_Destroy
71 * @since 9
72 * @version 1.0
73 */
74OH_AVErrCode OH_AudioEncoder_Destroy(OH_AVCodec *codec);
75
76/**
77 * @brief Set the asynchronous callback function so that your application can respond to
78 * the events generated by the audio encoder. This interface must be called before Prepare is called.
79 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
80 * @param codec Pointer to an OH_AVCodec instance
81 * @param callback A collection of all callback functions, see {@link OH_AVCodecAsyncCallback}
82 * @param userData User specific data
83 * @return Returns AV_ERR_OK if the execution is successful,
84 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
85 * @deprecated since 11
86 * @useinstead OH_AudioCodec_RegisterCallback
87 * @since 9
88 * @version 1.0
89 */
90OH_AVErrCode OH_AudioEncoder_SetCallback(OH_AVCodec *codec, OH_AVCodecAsyncCallback callback, void *userData);
91
92/**
93 * @brief To configure the audio encoder, typically, you need to configure the description information of
94 * the encoded audio track. This interface must be called before Prepare is called.
95 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
96 * @param codec Pointer to an OH_AVCodec instance
97 * @param format OH_AVFormat handle pointer
98 * @return Returns AV_ERR_OK if the execution is successful,
99 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
100 * @deprecated since 11
101 * @useinstead OH_AudioCodec_Configure
102 * @since 9
103 * @version 1.0
104 */
105OH_AVErrCode OH_AudioEncoder_Configure(OH_AVCodec *codec, OH_AVFormat *format);
106
107/**
108 * @brief To prepare the internal resources of the encoder,
109 * the Configure interface must be called before calling this interface.
110 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
111 * @param codec Pointer to an OH_AVCodec instance
112 * @return Returns AV_ERR_OK if the execution is successful,
113 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
114 * @deprecated since 11
115 * @useinstead OH_AudioCodec_Prepare
116 * @since 9
117 * @version 1.0
118 */
119OH_AVErrCode OH_AudioEncoder_Prepare(OH_AVCodec *codec);
120
121/**
122 * @brief Start the encoder, this interface must be called after the Prepare is successful.
123 * After being successfully started, the encoder will start reporting NeedInputData events.
124 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
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 * @deprecated since 11
129 * @useinstead OH_AudioCodec_Start
130 * @since 9
131 * @version 1.0
132 */
133OH_AVErrCode OH_AudioEncoder_Start(OH_AVCodec *codec);
134
135/**
136 * @brief Stop the encoder. After stopping, you can re-enter the Started state through Start.
137 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
138 * @param codec Pointer to an OH_AVCodec instance
139 * @return Returns AV_ERR_OK if the execution is successful,
140 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
141 * @deprecated since 11
142 * @useinstead OH_AudioCodec_Stop
143 * @since 9
144 * @version 1.0
145 */
146OH_AVErrCode OH_AudioEncoder_Stop(OH_AVCodec *codec);
147
148/**
149 * @brief Clear the input and output data buffered in the encoder. After this interface is called,
150 * all the Buffer indexes previously reported through the asynchronous callback will be invalidated,
151 * make sure not to access the Buffers corresponding to these indexes.
152 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
153 * @param codec Pointer to an OH_AVCodec instance
154 * @return Returns AV_ERR_OK if the execution is successful,
155 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
156 * @deprecated since 11
157 * @useinstead OH_AudioCodec_Flush
158 * @since 9
159 * @version 1.0
160 */
161OH_AVErrCode OH_AudioEncoder_Flush(OH_AVCodec *codec);
162
163/**
164 * @brief Reset the encoder. To continue coding, you need to call the Configure interface
165 * again to configure the encoder instance.
166 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
167 * @param codec Pointer to an OH_AVCodec instance
168 * @return Returns AV_ERR_OK if the execution is successful,
169 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
170 * @deprecated since 11
171 * @useinstead OH_AudioCodec_Reset
172 * @since 9
173 * @version 1.0
174 */
175OH_AVErrCode OH_AudioEncoder_Reset(OH_AVCodec *codec);
176
177/**
178 * @brief Get the description information of the output data of the encoder, refer to {@link OH_AVFormat} for details.
179 * It should be noted that the life cycle of the OH_AVFormat instance pointed to by the return value * needs to
180 * be manually released by the caller.
181 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
182 * @param codec Pointer to an OH_AVCodec instance
183 * @return Returns the OH_AVFormat handle pointer, the life cycle is refreshed with the next GetOutputMediaDescription,
184 * or destroyed with OH_AVCodec;
185 * @deprecated since 11
186 * @useinstead OH_AudioCodec_GetOutputDescription
187 * @since 9
188 * @version 1.0
189 */
190OH_AVFormat *OH_AudioEncoder_GetOutputDescription(OH_AVCodec *codec);
191
192/**
193 * @brief Set dynamic parameters to the encoder. Note: This interface can only be called after the encoder is started.
194 * At the same time, incorrect parameter settings may cause the encoding to fail.
195 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
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 * @deprecated since 11
201 * @useinstead OH_AudioCodec_SetParameter
202 * @since 9
203 * @version 1.0
204 */
205OH_AVErrCode OH_AudioEncoder_SetParameter(OH_AVCodec *codec, OH_AVFormat *format);
206
207/**
208 * @brief Submit the input buffer filled with data to the audio encoder. The {@link OH_AVCodecOnNeedInputData}
209 * callback will report the available input buffer and the corresponding index value. Once the buffer with the
210 * specified index is submitted to the audio encoder, the buffer cannot be accessed again until the
211 * callback is received again reporting that the buffer with the same index is available
212 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
213 * @param codec Pointer to an OH_AVCodec instance
214 * @param index Enter the index value corresponding to the Buffer
215 * @param attr Information describing the data contained in the Buffer
216 * @return Returns AV_ERR_OK if the execution is successful,
217 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
218 * @deprecated since 11
219 * @useinstead OH_AudioCodec_PushInputBuffer
220 * @since 9
221 * @version 1.0
222 */
223OH_AVErrCode OH_AudioEncoder_PushInputData(OH_AVCodec *codec, uint32_t index, OH_AVCodecBufferAttr attr);
224
225/**
226 * @brief Return the processed output Buffer to the encoder.
227 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
228 * @param codec Pointer to an OH_AVCodec instance
229 * @param index The index value corresponding to the output Buffer
230 * @return Returns AV_ERR_OK if the execution is successful,
231 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
232 * @deprecated since 11
233 * @useinstead OH_AudioCodec_FreeOutputBuffer
234 * @since 9
235 * @version 1.0
236 */
237OH_AVErrCode OH_AudioEncoder_FreeOutputData(OH_AVCodec *codec, uint32_t index);
238
239/**
240 * @brief Check whether the current codec instance is valid. It can be used fault recovery or app
241 * switchback from the background
242 * @syscap SystemCapability.Multimedia.Media.AudioEncoder
243 * @param codec Pointer to an OH_AVCodec instance
244 * @param isValid Output Parameter. A pointer to a boolean instance, it is true if the codec instance is valid,
245 * false if the codec instance is invalid
246 * @return Returns AV_ERR_OK if the execution is successful,
247 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
248 * @deprecated since 11
249 * @useinstead OH_AudioCodec_IsValid
250 * @since 10
251 */
252OH_AVErrCode OH_AudioEncoder_IsValid(OH_AVCodec *codec, bool *isValid);
253
254#ifdef __cplusplus
255}
256#endif
257#endif // NATIVE_AVCODEC_AUDIOENCODER_H