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