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