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_avmuxer.h
18 *
19 * @brief Provides audio and video muxer capabilities.
20 *
21 * @kit AVCodecKit
22 * @library libnative_media_avmuxer.so
23 * @syscap SystemCapability.Multimedia.Media.Muxer
24 * @since 10
25 */
26
27#ifndef NATIVE_AVMUXER_H
28#define NATIVE_AVMUXER_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 Forward declaration of OH_AVMuxer.
40 *
41 * @since 10
42 */
43typedef struct OH_AVMuxer OH_AVMuxer;
44
45/**
46 * @brief Create an OH_AVMuxer instance by output file description and format.
47 * @syscap SystemCapability.Multimedia.Media.Muxer
48 * @param fd Must be opened with read and write permission. Caller is responsible for closing fd.
49 * @param format The output format is {@link OH_AVOutputFormat} .
50 * @return Returns a pointer to an OH_AVMuxer instance, needs to be freed by OH_AVMuxer_Destroy.
51 * @since 10
52 */
53OH_AVMuxer *OH_AVMuxer_Create(int32_t fd, OH_AVOutputFormat format);
54
55/**
56 * @brief Set the rotation for output video playback.
57 * Note: This interface can only be called before OH_AVMuxer_Start.
58 * @syscap SystemCapability.Multimedia.Media.Muxer
59 * @param muxer Pointer to an OH_AVMuxer instance.
60 * @param rotation The supported angles are 0, 90, 180, and 270 degrees.
61 * @return Returns AV_ERR_OK if the execution is successful,
62 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
63 * {@link AV_ERR_INVALID_VAL}, the muxer or rotation invalid.
64 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
65 * @since 10
66 */
67OH_AVErrCode OH_AVMuxer_SetRotation(OH_AVMuxer *muxer, int32_t rotation);
68
69/**
70 * @brief Add track format to the muxer.
71 * Note: This interface can only be called before OH_AVMuxer_Start.
72 * @syscap SystemCapability.Multimedia.Media.Muxer
73 * @param muxer Pointer to an OH_AVMuxer instance
74 * @param trackIndex The int32_t handle pointer used to get the track index for this newly added track,
75 * and it should be used in the OH_AVMuxer_WriteSample. The track index is greater than or equal to 0,
76 * others is error index.
77 * @param trackFormat OH_AVFormat handle pointer contain track format
78 * @return Returns AV_ERR_OK if the execution is successful,
79 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
80 * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or trackFormat invalid.
81 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
82 * {@link AV_ERR_UNSUPPORT}, the mime type is not supported.
83 * {@link AV_ERR_NO_MEMORY}, failed to malloc memory.
84 * {@link AV_ERR_UNKNOWN}, unknown error.
85 * @since 10
86 */
87OH_AVErrCode OH_AVMuxer_AddTrack(OH_AVMuxer *muxer, int32_t *trackIndex, OH_AVFormat *trackFormat);
88
89/**
90 * @brief Start the muxer.
91 * Note: This interface is called after OH_AVMuxer_AddTrack and before OH_AVMuxer_WriteSample.
92 * @syscap SystemCapability.Multimedia.Media.Muxer
93 * @param muxer Pointer to an OH_AVMuxer instance
94 * @return Returns AV_ERR_OK if the execution is successful,
95 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
96 * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
97 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
98 * {@link AV_ERR_UNKNOWN}, unknown error.
99 * @since 10
100 */
101OH_AVErrCode OH_AVMuxer_Start(OH_AVMuxer *muxer);
102
103/**
104 * @brief Write an encoded sample to the muxer.
105 * Note: This interface can only be called after OH_AVMuxer_Start and before OH_AVMuxer_Stop. The application needs to
106 * make sure that the samples are written to the right tacks. Also, it needs to make sure the samples for each track are
107 * written in chronological order.
108 * @syscap SystemCapability.Multimedia.Media.Muxer
109 * @param muxer Pointer to an OH_AVMuxer instance
110 * @param trackIndex The track index for this sample
111 * @param sample The encoded or demuxer sample
112 * @param info The buffer information related to this sample {@link OH_AVCodecBufferAttr}
113 * @return Returns AV_ERR_OK if the execution is successful,
114 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
115 * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or sample or info invalid.
116 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
117 * {@link AV_ERR_NO_MEMORY}, failed to request memory.
118 * {@link AV_ERR_UNKNOWN}, unknown error.
119 * @deprecated since 11
120 * @useinstead OH_AVMuxer_WriteSampleBuffer
121 * @since 10
122 */
123OH_AVErrCode OH_AVMuxer_WriteSample(OH_AVMuxer *muxer, uint32_t trackIndex,
124    OH_AVMemory *sample, OH_AVCodecBufferAttr info);
125
126/**
127 * @brief Write an encoded sample to the muxer.
128 * Note: This interface can only be called after OH_AVMuxer_Start and before OH_AVMuxer_Stop. The application needs to
129 * make sure that the samples are written to the right tracks. Also, it needs to make sure the samples for each track
130 * are written in chronological order.
131 * @syscap SystemCapability.Multimedia.Media.Muxer
132 * @param muxer Pointer to an OH_AVMuxer instance
133 * @param trackIndex The track index for this sample
134 * @param sample The encoded or demuxer sample, which including data and buffer information
135 * @return Returns AV_ERR_OK if the execution is successful,
136 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
137 * {@link AV_ERR_INVALID_VAL}, the muxer or trackIndex or sample invalid.
138 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
139 * {@link AV_ERR_NO_MEMORY}, failed to request memory.
140 * {@link AV_ERR_UNKNOWN}, unknown error.
141 * @since 11
142 */
143OH_AVErrCode OH_AVMuxer_WriteSampleBuffer(OH_AVMuxer *muxer, uint32_t trackIndex,
144    const OH_AVBuffer *sample);
145
146/**
147 * @brief Stop the muxer.
148 * Note: Once the muxer stops, it can not be restarted.
149 * @syscap SystemCapability.Multimedia.Media.Muxer
150 * @param muxer Pointer to an OH_AVMuxer instance
151 * @return Returns AV_ERR_OK if the execution is successful,
152 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
153 * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
154 * {@link AV_ERR_OPERATE_NOT_PERMIT}, not permit to call the interface, it was called in invalid state.
155 * @since 10
156 */
157OH_AVErrCode OH_AVMuxer_Stop(OH_AVMuxer *muxer);
158
159/**
160 * @brief Clear the internal resources of the muxer and destroy the muxer instance
161 * @syscap SystemCapability.Multimedia.Media.Muxer
162 * @param muxer Pointer to an OH_AVMuxer instance
163 * @return Returns AV_ERR_OK if the execution is successful,
164 * otherwise returns a specific error code, refer to {@link OH_AVErrCode}
165 * {@link AV_ERR_INVALID_VAL}, the muxer invalid.
166 * @since 10
167 */
168OH_AVErrCode OH_AVMuxer_Destroy(OH_AVMuxer *muxer);
169
170#ifdef __cplusplus
171}
172#endif
173
174#endif // NATIVE_AVMUXER_H