Muxing

Muxers take encoded data in the form of AVPackets and write it into files or other output bytestreams in the specified container format. More...

Data Structures
struct	AVOutputFormat

Macros
#define	AVSTREAM_INIT_IN_WRITE_HEADER   0
	stream parameters initialized in avformat_write_header More...
#define	AVSTREAM_INIT_IN_INIT_OUTPUT   1
	stream parameters initialized in avformat_init_output More...

Functions
av_warn_unused_result int	avformat_write_header (AVFormatContext *s, AVDictionary **options)
	Allocate the stream private data and write the stream header to an output media file. More...
av_warn_unused_result int	avformat_init_output (AVFormatContext *s, AVDictionary **options)
	Allocate the stream private data and initialize the codec, but do not write the header. More...
int	av_write_frame (AVFormatContext *s, AVPacket *pkt)
	Write a packet to an output media file. More...
int	av_interleaved_write_frame (AVFormatContext *s, AVPacket *pkt)
	Write a packet to an output media file ensuring correct interleaving. More...
int	av_write_uncoded_frame (AVFormatContext *s, int stream_index, AVFrame *frame)
	Write an uncoded frame to an output media file. More...
int	av_interleaved_write_uncoded_frame (AVFormatContext *s, int stream_index, AVFrame *frame)
	Write an uncoded frame to an output media file. More...
int	av_write_uncoded_frame_query (AVFormatContext *s, int stream_index)
	Test whether a muxer supports uncoded frame. More...
int	av_write_trailer (AVFormatContext *s)
	Write the stream trailer to an output media file and free the file private data. More...
AVOutputFormat *	av_guess_format (const char *short_name, const char *filename, const char *mime_type)
	Return the output format in the list of registered output formats which best matches the provided parameters, or return NULL if there is no match. More...
enum AVCodecID	av_guess_codec (AVOutputFormat *fmt, const char *short_name, const char *filename, const char *mime_type, enum AVMediaType type)
	Guess the codec ID based upon muxer and filename. More...
int	av_get_output_timestamp (struct AVFormatContext *s, int stream, int64_t *dts, int64_t *wall)
	Get timing information for the data currently output. More...

Detailed Description

Muxers take encoded data in the form of AVPackets and write it into files or other output bytestreams in the specified container format.

The main API functions for muxing are avformat_write_header() for writing the file header, av_write_frame() / av_interleaved_write_frame() for writing the packets and av_write_trailer() for finalizing the file.

At the beginning of the muxing process, the caller must first call avformat_alloc_context() to create a muxing context. The caller then sets up the muxer by filling the various fields in this context:

• The oformat field must be set to select the muxer that will be used.
• Unless the format is of the AVFMT_NOFILE type, the pb field must be set to an opened IO context, either returned from avio_open2() or a custom one.
• Unless the format is of the AVFMT_NOSTREAMS type, at least one stream must be created with the avformat_new_stream() function. The caller should fill the stream codec parameters information, such as the codec type, id and other parameters (e.g. width / height, the pixel or sample format, etc.) as known. The stream timebase should be set to the timebase that the caller desires to use for this stream (note that the timebase actually used by the muxer can be different, as will be described later).
• It is advised to manually initialize only the relevant fields in AVCodecParameters, rather than using avcodec_parameters_copy() during remuxing: there is no guarantee that the codec context values remain valid for both input and output format contexts.
• The caller may fill in additional information, such as global or per-stream metadata, chapters, programs, etc. as described in the AVFormatContext documentation. Whether such information will actually be stored in the output depends on what the container format and the muxer support.

When the muxing context is fully set up, the caller must call avformat_write_header() to initialize the muxer internals and write the file header. Whether anything actually is written to the IO context at this step depends on the muxer, but this function must always be called. Any muxer private options must be passed in the options parameter to this function.

The data is then sent to the muxer by repeatedly calling av_write_frame() or av_interleaved_write_frame() (consult those functions' documentation for discussion on the difference between them; only one of them may be used with a single muxing context, they should not be mixed). Do note that the timing information on the packets sent to the muxer must be in the corresponding AVStream's timebase. That timebase is set by the muxer (in the avformat_write_header() step) and may be different from the timebase requested by the caller.

Once all the data has been written, the caller must call av_write_trailer() to flush any buffered packets and finalize the output file, then close the IO context (if any) and finally free the muxing context with avformat_free_context().

Macro Definition Documentation

AVSTREAM_INIT_IN_WRITE_HEADER

#define AVSTREAM_INIT_IN_WRITE_HEADER   0

stream parameters initialized in avformat_write_header

Definition at line 2496 of file avformat.h.

Referenced by avformat_init_output(), and seg_init().

AVSTREAM_INIT_IN_INIT_OUTPUT

#define AVSTREAM_INIT_IN_INIT_OUTPUT   1

stream parameters initialized in avformat_init_output

Definition at line 2497 of file avformat.h.

Referenced by avformat_init_output().

Function Documentation

avformat_write_header()

av_warn_unused_result int avformat_write_header	(	AVFormatContext *	s,
		AVDictionary **	options
	)

Allocate the stream private data and write the stream header to an output media file.

Parameters

s	Media file handle, must be allocated with avformat_alloc_context(). Its oformat field must be set to the desired output format; Its pb field must be set to an already opened AVIOContext.
options	An AVDictionary filled with AVFormatContext and muxer-private options. On return this parameter will be destroyed and replaced with a dict containing options that were not found. May be NULL.

Returns

AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec had not already been fully initialized in avformat_init, AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec had already been fully initialized in avformat_init, negative AVERROR on failure.

See also

av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output.

Examples:

muxing.c, remuxing.c, transcode_aac.c, transcoding.c, and vaapi_transcode.c.

Definition at line 508 of file mux.c.

Referenced by check_init_output_file(), dash_write_header(), dec_enc(), ff_rtp_chain_mux_open(), fifo_basic_test(), fifo_overflow_drop_test(), fifo_thread_write_header(), hds_write_header(), hls_start(), hls_write_header(), init_fps(), ism_write_header(), main(), mpegts_init(), open_output_file(), open_slave(), rtp_mpegts_write_header(), seg_init(), seg_write_header(), segment_start(), write_output_file_header(), and write_packet().

avformat_init_output()

av_warn_unused_result int avformat_init_output	(	AVFormatContext *	s,
		AVDictionary **	options
	)

Allocate the stream private data and initialize the codec, but do not write the header.

May optionally be used before avformat_write_header to initialize stream parameters before actually writing the header. If using this function, do not pass the same options to avformat_write_header.

Parameters

s	Media file handle, must be allocated with avformat_alloc_context(). Its oformat field must be set to the desired output format; Its pb field must be set to an already opened AVIOContext.
options	An AVDictionary filled with AVFormatContext and muxer-private options. On return this parameter will be destroyed and replaced with a dict containing options that were not found. May be NULL.

Returns

AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec requires avformat_write_header to fully initialize, AVSTREAM_INIT_IN_INIT_OUTPUT on success if the codec has been fully initialized, negative AVERROR on failure.

See also

av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header.

Definition at line 488 of file mux.c.

Referenced by avformat_write_header(), dash_init(), hls_mux_init(), and seg_init().

av_write_frame()

int av_write_frame	(	AVFormatContext *	s,
		AVPacket *	pkt
	)

Write a packet to an output media file.

This function passes the packet directly to the muxer, without any buffering or reordering. The caller is responsible for correctly interleaving the packets if the format requires it. Callers that want libavformat to handle the interleaving should call av_interleaved_write_frame() instead of this function.

Parameters

s

media file handle

pkt

The packet containing the data to be written. Note that unlike av_interleaved_write_frame(), this function does not take ownership of the packet passed to it (though some muxers may make an internal reference to the input packet). This parameter can be NULL (at any time, not just at the end), in order to immediately flush data buffered within the muxer, for muxers that buffer up data internally before writing it to the output. Packet's stream_index field must be set to the index of the corresponding stream in s->streams. The timestamps (pts, dts) must be set to correct values in the stream's timebase (unless the output format is flagged with the AVFMT_NOTIMESTAMPS flag, then they can be set to AV_NOPTS_VALUE). The dts for subsequent packets passed to this function must be strictly increasing when compared in their respective timebases (unless the output format is flagged with the AVFMT_TS_NONSTRICT, then they merely have to be nondecreasing). duration) should also be set if known.

Returns

< 0 on error, = 0 if OK, 1 if flushed and there is no more data to flush

See also

av_interleaved_write_frame()

Examples:

transcode_aac.c.

Definition at line 878 of file mux.c.

Referenced by av_write_uncoded_frame_internal(), encode_audio_frame(), ff_write_chained(), fifo_basic_test(), fifo_overflow_drop_test(), fifo_thread_flush_output(), fifo_thread_write_packet(), flush_dynbuf(), hls_write_packet(), ism_flush(), main(), mpegts_write_packet_internal(), mux_frames(), rtp_mpegts_write_packet(), seg_write_header(), segment_end(), and signal_init_ts().

av_interleaved_write_frame()

int av_interleaved_write_frame	(	AVFormatContext *	s,
		AVPacket *	pkt
	)

Write a packet to an output media file ensuring correct interleaving.

This function will buffer the packets internally as needed to make sure the packets in the output file are properly interleaved in the order of increasing dts. Callers doing their own interleaving should call av_write_frame() instead of this function.

Using this function instead of av_write_frame() can give muxers advance knowledge of future packets, improving e.g. the behaviour of the mp4 muxer for VFR content in fragmenting mode.

Parameters

s

media file handle

pkt

The packet containing the data to be written. If the packet is reference-counted, this function will take ownership of this reference and unreference it later when it sees fit. The caller must not access the data through this reference after this function returns. If the packet is not reference-counted, libavformat will make a copy. This parameter can be NULL (at any time, not just at the end), to flush the interleaving queues. Packet's stream_index field must be set to the index of the corresponding stream in s->streams. The timestamps (pts, dts) must be set to correct values in the stream's timebase (unless the output format is flagged with the AVFMT_NOTIMESTAMPS flag, then they can be set to AV_NOPTS_VALUE). The dts for subsequent packets in one stream must be strictly increasing (unless the output format is flagged with the AVFMT_TS_NONSTRICT, then they merely have to be nondecreasing). duration) should also be set if known.

Returns

0 on success, a negative AVERROR on error. Libavformat will always take care of freeing the packet, even if this function fails.

See also

av_write_frame(), AVFormatContext.max_interleave_delta

Examples:

muxing.c, remuxing.c, transcoding.c, and vaapi_transcode.c.

Definition at line 1185 of file mux.c.

Referenced by av_write_uncoded_frame_internal(), encode_write(), encode_write_frame(), ff_write_chained(), main(), mux_frames(), tee_write_packet(), write_frame(), and write_packet().

av_write_uncoded_frame()

int av_write_uncoded_frame	(	AVFormatContext *	s,
		int	stream_index,
		AVFrame *	frame
	)

Write an uncoded frame to an output media file.

The frame must be correctly interleaved according to the container specification; if not, then av_interleaved_write_frame() must be used.

See av_interleaved_write_frame() for details.

Definition at line 1367 of file mux.c.

av_interleaved_write_uncoded_frame()

int av_interleaved_write_uncoded_frame	(	AVFormatContext *	s,
		int	stream_index,
		AVFrame *	frame
	)

Write an uncoded frame to an output media file.

If the muxer supports it, this function makes it possible to write an AVFrame structure directly, without encoding it into a packet. It is mostly useful for devices and similar special muxers that use raw video or PCM data and will not serialize it into a byte stream.

To test whether it is possible to use it with a given muxer and stream, use av_write_uncoded_frame_query().

The caller gives up ownership of the frame and must not access it afterwards.

Returns

>=0 for success, a negative code on error

Definition at line 1373 of file mux.c.

Referenced by main().

av_write_uncoded_frame_query()

int av_write_uncoded_frame_query	(	AVFormatContext *	s,
		int	stream_index
	)

Test whether a muxer supports uncoded frame.

Returns

>=0 if an uncoded frame can be written to that muxer and stream, <0 if not

Definition at line 1379 of file mux.c.

Referenced by main().

av_write_trailer()

int av_write_trailer

(

AVFormatContext *

s

)

Write the stream trailer to an output media file and free the file private data.

May only be called after a successful call to avformat_write_header.

Parameters

s	media file handle

Returns

0 if OK, AVERROR_xxx on error

Examples:

muxing.c, remuxing.c, transcode_aac.c, transcoding.c, and vaapi_transcode.c.

Definition at line 1247 of file mux.c.

Referenced by close_slave(), dash_free(), ff_mov_close_hinting(), ff_rtsp_undo_setup(), fifo_basic_test(), fifo_overflow_drop_test(), fifo_thread_write_trailer(), finish(), hds_free(), hls_write_trailer(), ism_free(), main(), rtp_mpegts_write_close(), sap_write_close(), seg_write_trailer(), segment_end(), transcode(), write_output_file_trailer(), and write_packet().

av_guess_format()

AVOutputFormat* av_guess_format	(	const char *	short_name,
		const char *	filename,
		const char *	mime_type
	)

Return the output format in the list of registered output formats which best matches the provided parameters, or return NULL if there is no match.

Parameters

short_name	if non-NULL checks if short_name matches with the names of the registered formats
filename	if non-NULL checks if filename terminates with the extensions of the registered formats
mime_type	if non-NULL checks if mime_type matches with the MIME type of the registered formats

Examples:

transcode_aac.c.

Definition at line 51 of file format.c.

Referenced by av_guess_codec(), avformat_alloc_output_context2(), dash_init(), ff_rtp_chain_mux_open(), fifo_init(), hds_write_header(), hls_init(), init_fps(), ism_write_header(), mpegts_init(), open_output_file(), rtp_mpegts_write_header(), seg_init(), show_help_muxer(), and webm_chunk_write_header().

av_guess_codec()

enum AVCodecID av_guess_codec	(	AVOutputFormat *	fmt,
		const char *	short_name,
		const char *	filename,
		const char *	mime_type,
		enum AVMediaType	type
	)

Guess the codec ID based upon muxer and filename.

Definition at line 87 of file format.c.

Referenced by choose_encoder(), and open_output_file().

av_get_output_timestamp()

int av_get_output_timestamp	(	struct AVFormatContext *	s,
		int	stream,
		int64_t *	dts,
		int64_t *	wall
	)

Get timing information for the data currently output.

The exact meaning of "currently output" depends on the format. It is mostly relevant for devices that have an internal buffer and/or work in real time.

Parameters

	s	media file handle
	stream	stream in the media file
[out]	dts	DTS of the last packet output for the stream, in stream time_base units
[out]	wall	absolute time when that packet whas output, in microsecond

Returns

0 if OK, AVERROR(ENOSYS) if the format does not support it Note: some formats or devices may not allow to measure dts and wall atomically.

Definition at line 1302 of file mux.c.