/src/ffmpeg/libavformat/mux.h

Source
/*
 * copyright (c) 2001 Fabrice Bellard
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef AVFORMAT_MUX_H
#define AVFORMAT_MUX_H

#include <stdint.h>
#include "libavcodec/packet.h"
#include "avformat.h"

struct AVDeviceInfoList;

/**
 * This flag indicates that the muxer stores data internally
 * and supports flushing it. Flushing is signalled by sending
 * a NULL packet to the muxer's write_packet callback;
 * without this flag, a muxer never receives NULL packets.
 * So the documentation of write_packet below for the semantics
 * of the return value in case of flushing.
 */
#define FF_OFMT_FLAG_ALLOW_FLUSH                    (1 << 1)
/**
 * If this flag is set, it indicates that for each codec type
 * whose corresponding default codec (i.e. AVOutputFormat.audio_codec,
 * AVOutputFormat.video_codec and AVOutputFormat.subtitle_codec)
 * is set (i.e. != AV_CODEC_ID_NONE) only one stream of this type
 * can be muxed. It furthermore indicates that no stream with
 * a codec type that has no default codec or whose default codec
 * is AV_CODEC_ID_NONE can be muxed.
 * Both of these restrictions are checked generically before
 * the actual muxer's init/write_header callbacks.
 */
#define FF_OFMT_FLAG_MAX_ONE_OF_EACH                (1 << 2)
/**
 * If this flag is set, then the only permitted audio/video/subtitle
 * codec ids are AVOutputFormat.audio/video/subtitle_codec;
 * if any of the latter is unset (i.e. equal to AV_CODEC_ID_NONE),
 * then no stream of the corresponding type is supported.
 * In addition, codec types without default codec field
 * are disallowed.
 */
#define FF_OFMT_FLAG_ONLY_DEFAULT_CODECS            (1 << 3)

typedef struct FFOutputFormat {
    /**
     * The public AVOutputFormat. See avformat.h for it.
     */
    AVOutputFormat p;
    /**
     * size of private data so that it can be allocated in the wrapper
     */
    int priv_data_size;

    /**
     * Internal flags. See FF_OFMT_FLAG_* above and FF_FMT_FLAG_* in internal.h.
     */
    int flags_internal;

    int (*write_header)(AVFormatContext *);
    /**
     * Write a packet. If FF_OFMT_FLAG_ALLOW_FLUSH is set in flags_internal,
     * pkt can be NULL in order to flush data buffered in the muxer.
     * When flushing, return 0 if there still is more data to flush,
     * or 1 if everything was flushed and there is no more buffered
     * data.
     */
    int (*write_packet)(AVFormatContext *, AVPacket *pkt);
    int (*write_trailer)(AVFormatContext *);
    /**
     * A format-specific function for interleavement.
     * If unset, packets will be interleaved by dts.
     *
     * @param s           An AVFormatContext for output. pkt will be added to
     *                    resp. taken from its packet buffer.
     * @param[in,out] pkt A packet to be interleaved if has_packet is set;
     *                    also used to return packets. If no packet is returned
     *                    (e.g. on error), pkt is blank on return.
     * @param flush       1 if no further packets are available as input and
     *                    all remaining packets should be output.
     * @param has_packet  If set, pkt contains a packet to be interleaved
     *                    on input; otherwise pkt is blank on input.
     * @return 1 if a packet was output, 0 if no packet could be output,
     *         < 0 if an error occurred
     */
    int (*interleave_packet)(AVFormatContext *s, AVPacket *pkt,
                             int flush, int has_packet);
    /**
     * Test if the given codec can be stored in this container.
     *
     * @return 1 if the codec is supported, 0 if it is not.
     *         A negative number if unknown.
     *         MKTAG('A', 'P', 'I', 'C') if the codec is only supported as AV_DISPOSITION_ATTACHED_PIC
     */
    int (*query_codec)(enum AVCodecID id, int std_compliance);

    void (*get_output_timestamp)(AVFormatContext *s, int stream,
                                 int64_t *dts, int64_t *wall);
    /**
     * Allows sending messages from application to device.
     */
    int (*control_message)(AVFormatContext *s, int type,
                           void *data, size_t data_size);

    /**
     * Write an uncoded AVFrame.
     *
     * See av_write_uncoded_frame() for details.
     *
     * The library will free *frame afterwards, but the muxer can prevent it
     * by setting the pointer to NULL.
     */
    int (*write_uncoded_frame)(AVFormatContext *, int stream_index,
                               struct AVFrame **frame, unsigned flags);
    /**
     * Returns device list with it properties.
     * @see avdevice_list_devices() for more details.
     */
    int (*get_device_list)(AVFormatContext *s, struct AVDeviceInfoList *device_list);
    /**
     * Initialize format. May allocate data here, and set any AVFormatContext or
     * AVStream parameters that need to be set before packets are sent.
     * This method must not write output.
     *
     * Return 0 if streams were fully configured, 1 if not, negative AVERROR on failure
     *
     * Any allocations made here must be freed in deinit().
     */
    int (*init)(AVFormatContext *);
    /**
     * Deinitialize format. If present, this is called whenever the muxer is being
     * destroyed, regardless of whether or not the header has been written.
     *
     * If a trailer is being written, this is called after write_trailer().
     *
     * This is called if init() fails as well.
     */
    void (*deinit)(AVFormatContext *);
    /**
     * Set up any necessary bitstream filtering and extract any extra data needed
     * for the global header.
     *
     * @note pkt might have been directly forwarded by a meta-muxer; therefore
     *       pkt->stream_index as well as the pkt's timebase might be invalid.
     * Return 0 if more packets from this stream must be checked; 1 if not.
     */
    int (*check_bitstream)(AVFormatContext *s, AVStream *st,
                           const AVPacket *pkt);
} FFOutputFormat;

static inline const FFOutputFormat *ffofmt(const AVOutputFormat *fmt)
{
    return (const FFOutputFormat*)fmt;
}

/**
 * Add packet to an AVFormatContext's packet_buffer list, determining its
 * interleaved position using compare() function argument.
 * @return 0 on success, < 0 on error. pkt will always be blank on return.
 */
int ff_interleave_add_packet(AVFormatContext *s, AVPacket *pkt,
                             int (*compare)(AVFormatContext *, const AVPacket *, const AVPacket *));

/**
 * Interleave an AVPacket per dts so it can be muxed.
 * See the documentation of AVOutputFormat.interleave_packet for details.
 */
int ff_interleave_packet_per_dts(AVFormatContext *s, AVPacket *pkt,
                                 int flush, int has_packet);

/**
 * Interleave packets directly in the order in which they arrive
 * without any sort of buffering.
 */
int ff_interleave_packet_passthrough(AVFormatContext *s, AVPacket *pkt,
                                     int flush, int has_packet);

/**
 * Find the next packet in the interleaving queue for the given stream.
 *
 * @return a pointer to a packet if one was found, NULL otherwise.
 */
const AVPacket *ff_interleaved_peek(AVFormatContext *s, int stream);

int ff_get_muxer_ts_offset(AVFormatContext *s, int stream_index, int64_t *offset);

/**
 * Add a bitstream filter to a stream.
 *
 * @param st output stream to add a filter to
 * @param name the name of the filter to add
 * @param args filter-specific argument string
 * @return  >0 on success;
 *          AVERROR code on failure
 */
int ff_stream_add_bitstream_filter(AVStream *st, const char *name, const char *args);

/**
 * Write a packet to another muxer than the one the user originally
 * intended. Useful when chaining muxers, where one muxer internally
 * writes a received packet to another muxer.
 *
 * @param dst the muxer to write the packet to
 * @param dst_stream the stream index within dst to write the packet to
 * @param pkt the packet to be written. It will be returned blank when
 *            av_interleaved_write_frame() is used, unchanged otherwise.
 * @param src the muxer the packet originally was intended for
 * @param interleave 0->use av_write_frame, 1->av_interleaved_write_frame
 * @return the value av_write_frame returned
 */
int ff_write_chained(AVFormatContext *dst, int dst_stream, AVPacket *pkt,
                     AVFormatContext *src, int interleave);

/**
 * Flags for AVFormatContext.write_uncoded_frame()
 */
enum AVWriteUncodedFrameFlags {

    /**
     * Query whether the feature is possible on this stream.
     * The frame argument is ignored.
     */
    AV_WRITE_UNCODED_FRAME_QUERY           = 0x0001,

};

/**
 * Make shift_size amount of space at read_start by shifting data in the output
 * at read_start until the current IO position. The underlying IO context must
 * be seekable.
 */
int ff_format_shift_data(AVFormatContext *s, int64_t read_start, int shift_size);

/**
 * Utility function to open IO stream of output format.
 *
 * @param s AVFormatContext
 * @param url URL or file name to open for writing
 * @options optional options which will be passed to io_open callback
 * @return >=0 on success, negative AVERROR in case of failure
 */
int ff_format_output_open(AVFormatContext *s, const char *url, AVDictionary **options);

/**
 * Parse creation_time in AVFormatContext metadata if exists and warn if the
 * parsing fails.
 *
 * @param s AVFormatContext
 * @param timestamp parsed timestamp in microseconds, only set on successful parsing
 * @param return_seconds set this to get the number of seconds in timestamp instead of microseconds
 * @return 1 if OK, 0 if the metadata was not present, AVERROR(EINVAL) on parse error
 */
int ff_parse_creation_time_metadata(AVFormatContext *s, int64_t *timestamp, int return_seconds);

/**
 * Standardize creation_time metadata in AVFormatContext to an ISO-8601
 * timestamp string.
 *
 * @param s AVFormatContext
 * @return <0 on error
 */
int ff_standardize_creation_time(AVFormatContext *s);

#endif /* AVFORMAT_MUX_H */

Coverage Report

Created: 2026-01-25 07:18

Line	Count	Source
1		/*
2		* copyright (c) 2001 Fabrice Bellard
3		*
4		* This file is part of FFmpeg.
5		*
6		* FFmpeg is free software; you can redistribute it and/or
7		* modify it under the terms of the GNU Lesser General Public
8		* License as published by the Free Software Foundation; either
9		* version 2.1 of the License, or (at your option) any later version.
10		*
11		* FFmpeg is distributed in the hope that it will be useful,
12		* but WITHOUT ANY WARRANTY; without even the implied warranty of
13		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14		* Lesser General Public License for more details.
15		*
16		* You should have received a copy of the GNU Lesser General Public
17		* License along with FFmpeg; if not, write to the Free Software
18		* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19		*/
20
21		#ifndef AVFORMAT_MUX_H
22		#define AVFORMAT_MUX_H
23
24		#include <stdint.h>
25		#include "libavcodec/packet.h"
26		#include "avformat.h"
27
28		struct AVDeviceInfoList;
29
30		/**
31		* This flag indicates that the muxer stores data internally
32		* and supports flushing it. Flushing is signalled by sending
33		* a NULL packet to the muxer's write_packet callback;
34		* without this flag, a muxer never receives NULL packets.
35		* So the documentation of write_packet below for the semantics
36		* of the return value in case of flushing.
37		*/
38		#define FF_OFMT_FLAG_ALLOW_FLUSH (1 << 1)
39		/**
40		* If this flag is set, it indicates that for each codec type
41		* whose corresponding default codec (i.e. AVOutputFormat.audio_codec,
42		* AVOutputFormat.video_codec and AVOutputFormat.subtitle_codec)
43		* is set (i.e. != AV_CODEC_ID_NONE) only one stream of this type
44		* can be muxed. It furthermore indicates that no stream with
45		* a codec type that has no default codec or whose default codec
46		* is AV_CODEC_ID_NONE can be muxed.
47		* Both of these restrictions are checked generically before
48		* the actual muxer's init/write_header callbacks.
49		*/
50		#define FF_OFMT_FLAG_MAX_ONE_OF_EACH (1 << 2)
51		/**
52		* If this flag is set, then the only permitted audio/video/subtitle
53		* codec ids are AVOutputFormat.audio/video/subtitle_codec;
54		* if any of the latter is unset (i.e. equal to AV_CODEC_ID_NONE),
55		* then no stream of the corresponding type is supported.
56		* In addition, codec types without default codec field
57		* are disallowed.
58		*/
59		#define FF_OFMT_FLAG_ONLY_DEFAULT_CODECS (1 << 3)
60
61		typedef struct FFOutputFormat {
62		/**
63		* The public AVOutputFormat. See avformat.h for it.
64		*/
65		AVOutputFormat p;
66		/**
67		* size of private data so that it can be allocated in the wrapper
68		*/
69		int priv_data_size;
70
71		/**
72		* Internal flags. See FF_OFMT_FLAG_* above and FF_FMT_FLAG_* in internal.h.
73		*/
74		int flags_internal;
75
76		int (write_header)(AVFormatContext );
77		/**
78		* Write a packet. If FF_OFMT_FLAG_ALLOW_FLUSH is set in flags_internal,
79		* pkt can be NULL in order to flush data buffered in the muxer.
80		* When flushing, return 0 if there still is more data to flush,
81		* or 1 if everything was flushed and there is no more buffered
82		* data.
83		*/
84		int (write_packet)(AVFormatContext , AVPacket *pkt);
85		int (write_trailer)(AVFormatContext );
86		/**
87		* A format-specific function for interleavement.
88		* If unset, packets will be interleaved by dts.
89		*
90		* @param s An AVFormatContext for output. pkt will be added to
91		* resp. taken from its packet buffer.
92		* @param[in,out] pkt A packet to be interleaved if has_packet is set;
93		* also used to return packets. If no packet is returned
94		* (e.g. on error), pkt is blank on return.
95		* @param flush 1 if no further packets are available as input and
96		* all remaining packets should be output.
97		* @param has_packet If set, pkt contains a packet to be interleaved
98		* on input; otherwise pkt is blank on input.
99		* @return 1 if a packet was output, 0 if no packet could be output,
100		* < 0 if an error occurred
101		*/
102		int (interleave_packet)(AVFormatContext s, AVPacket *pkt,
103		int flush, int has_packet);
104		/**
105		* Test if the given codec can be stored in this container.
106		*
107		* @return 1 if the codec is supported, 0 if it is not.
108		* A negative number if unknown.
109		* MKTAG('A', 'P', 'I', 'C') if the codec is only supported as AV_DISPOSITION_ATTACHED_PIC
110		*/
111		int (*query_codec)(enum AVCodecID id, int std_compliance);
112
113		void (get_output_timestamp)(AVFormatContext s, int stream,
114		int64_t dts, int64_t wall);
115		/**
116		* Allows sending messages from application to device.
117		*/
118		int (control_message)(AVFormatContext s, int type,
119		void *data, size_t data_size);
120
121		/**
122		* Write an uncoded AVFrame.
123		*
124		* See av_write_uncoded_frame() for details.
125		*
126		* The library will free *frame afterwards, but the muxer can prevent it
127		* by setting the pointer to NULL.
128		*/
129		int (write_uncoded_frame)(AVFormatContext , int stream_index,
130		struct AVFrame **frame, unsigned flags);
131		/**
132		* Returns device list with it properties.
133		* @see avdevice_list_devices() for more details.
134		*/
135		int (get_device_list)(AVFormatContext s, struct AVDeviceInfoList *device_list);
136		/**
137		* Initialize format. May allocate data here, and set any AVFormatContext or
138		* AVStream parameters that need to be set before packets are sent.
139		* This method must not write output.
140		*
141		* Return 0 if streams were fully configured, 1 if not, negative AVERROR on failure
142		*
143		* Any allocations made here must be freed in deinit().
144		*/
145		int (init)(AVFormatContext );
146		/**
147		* Deinitialize format. If present, this is called whenever the muxer is being
148		* destroyed, regardless of whether or not the header has been written.
149		*
150		* If a trailer is being written, this is called after write_trailer().
151		*
152		* This is called if init() fails as well.
153		*/
154		void (deinit)(AVFormatContext );
155		/**
156		* Set up any necessary bitstream filtering and extract any extra data needed
157		* for the global header.
158		*
159		* @note pkt might have been directly forwarded by a meta-muxer; therefore
160		* pkt->stream_index as well as the pkt's timebase might be invalid.
161		* Return 0 if more packets from this stream must be checked; 1 if not.
162		*/
163		int (check_bitstream)(AVFormatContext s, AVStream *st,
164		const AVPacket *pkt);
165		} FFOutputFormat;
166
167		static inline const FFOutputFormat ffofmt(const AVOutputFormat fmt)
168	0	{
169	0	return (const FFOutputFormat*)fmt;
170	0	} Unexecuted instantiation: avformat.c:ffofmt Unexecuted instantiation: allformats.c:ffofmt
171
172		/**
173		* Add packet to an AVFormatContext's packet_buffer list, determining its
174		* interleaved position using compare() function argument.
175		* @return 0 on success, < 0 on error. pkt will always be blank on return.
176		*/
177		int ff_interleave_add_packet(AVFormatContext s, AVPacket pkt,
178		int (compare)(AVFormatContext , const AVPacket , const AVPacket ));
179
180		/**
181		* Interleave an AVPacket per dts so it can be muxed.
182		* See the documentation of AVOutputFormat.interleave_packet for details.
183		*/
184		int ff_interleave_packet_per_dts(AVFormatContext s, AVPacket pkt,
185		int flush, int has_packet);
186
187		/**
188		* Interleave packets directly in the order in which they arrive
189		* without any sort of buffering.
190		*/
191		int ff_interleave_packet_passthrough(AVFormatContext s, AVPacket pkt,
192		int flush, int has_packet);
193
194		/**
195		* Find the next packet in the interleaving queue for the given stream.
196		*
197		* @return a pointer to a packet if one was found, NULL otherwise.
198		*/
199		const AVPacket ff_interleaved_peek(AVFormatContext s, int stream);
200
201		int ff_get_muxer_ts_offset(AVFormatContext s, int stream_index, int64_t offset);
202
203		/**
204		* Add a bitstream filter to a stream.
205		*
206		* @param st output stream to add a filter to
207		* @param name the name of the filter to add
208		* @param args filter-specific argument string
209		* @return >0 on success;
210		* AVERROR code on failure
211		*/
212		int ff_stream_add_bitstream_filter(AVStream st, const char name, const char *args);
213
214		/**
215		* Write a packet to another muxer than the one the user originally
216		* intended. Useful when chaining muxers, where one muxer internally
217		* writes a received packet to another muxer.
218		*
219		* @param dst the muxer to write the packet to
220		* @param dst_stream the stream index within dst to write the packet to
221		* @param pkt the packet to be written. It will be returned blank when
222		* av_interleaved_write_frame() is used, unchanged otherwise.
223		* @param src the muxer the packet originally was intended for
224		* @param interleave 0->use av_write_frame, 1->av_interleaved_write_frame
225		* @return the value av_write_frame returned
226		*/
227		int ff_write_chained(AVFormatContext dst, int dst_stream, AVPacket pkt,
228		AVFormatContext *src, int interleave);
229
230		/**
231		* Flags for AVFormatContext.write_uncoded_frame()
232		*/
233		enum AVWriteUncodedFrameFlags {
234
235		/**
236		* Query whether the feature is possible on this stream.
237		* The frame argument is ignored.
238		*/
239		AV_WRITE_UNCODED_FRAME_QUERY = 0x0001,
240
241		};
242
243		/**
244		* Make shift_size amount of space at read_start by shifting data in the output
245		* at read_start until the current IO position. The underlying IO context must
246		* be seekable.
247		*/
248		int ff_format_shift_data(AVFormatContext *s, int64_t read_start, int shift_size);
249
250		/**
251		* Utility function to open IO stream of output format.
252		*
253		* @param s AVFormatContext
254		* @param url URL or file name to open for writing
255		* @options optional options which will be passed to io_open callback
256		* @return >=0 on success, negative AVERROR in case of failure
257		*/
258		int ff_format_output_open(AVFormatContext s, const char url, AVDictionary **options);
259
260		/**
261		* Parse creation_time in AVFormatContext metadata if exists and warn if the
262		* parsing fails.
263		*
264		* @param s AVFormatContext
265		* @param timestamp parsed timestamp in microseconds, only set on successful parsing
266		* @param return_seconds set this to get the number of seconds in timestamp instead of microseconds
267		* @return 1 if OK, 0 if the metadata was not present, AVERROR(EINVAL) on parse error
268		*/
269		int ff_parse_creation_time_metadata(AVFormatContext s, int64_t timestamp, int return_seconds);
270
271		/**
272		* Standardize creation_time metadata in AVFormatContext to an ISO-8601
273		* timestamp string.
274		*
275		* @param s AVFormatContext
276		* @return <0 on error
277		*/
278		int ff_standardize_creation_time(AVFormatContext *s);
279
280		#endif /* AVFORMAT_MUX_H */