*
* @defgroup lavf_encoding Muxing
* @{
+ * Muxers take encoded data in the form of @ref AVPacket "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 @ref AVFormatContext.oformat "oformat" field must be set to select the
+ * muxer that will be used.
+ * - Unless the format is of the AVFMT_NOFILE type, the @ref AVFormatContext.pb
+ * "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 @ref AVStream.codec "stream codec context" information, such as the
+ * codec @ref AVCodecContext.codec_type "type", @ref AVCodecContext.codec_id
+ * "id" and other parameters (e.g. width / height, the pixel or sample format,
+ * etc.) as known. The @ref AVCodecContext.time_base "codec 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).
+ * - The caller may fill in additional information, such as @ref
+ * AVFormatContext.metadata "global" or @ref AVStream.metadata "per-stream"
+ * metadata, @ref AVFormatContext.chapters "chapters", @ref
+ * AVFormatContext.programs "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 the
+ * caller set on the codec context.
+ *
+ * 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().
* @}
*
* @defgroup lavf_io I/O Read/Write
* Allocate and read the payload of a packet and initialize its
* fields with default values.
*
+ * @param s associated IO context
* @param pkt packet
* @param size desired payload size
* @return >0 (read size) if OK, AVERROR_xxx otherwise
* when there is no reasonable way to know (an upper bound of)
* the final size.
*
+ * @param s associated IO context
* @param pkt packet
* @param size amount of data to read
* @return >0 (read size) if OK, AVERROR_xxx otherwise, previous data
*/
AVPacket attached_pic;
+ /**
+ * An array of side data that applies to the whole stream (i.e. the
+ * container does not allow it to change between packets).
+ *
+ * There may be no overlap between the side data in this array and side data
+ * in the packets. I.e. a given side data is either exported by the muxer
+ * (demuxing) / set by the caller (muxing) in this array, then it never
+ * appears in the packets, or the side data is exported / sent through
+ * the packets (always in the first packet where the value becomes known or
+ * changes), then it does not appear in this array.
+ *
+ * - demuxing: Set by libavformat when the stream is created.
+ * - muxing: May be set by the caller before avformat_write_header().
+ *
+ * Freed by libavformat in avformat_free_context().
+ */
+ AVPacketSideData *side_data;
+ /**
+ * The number of elements in the AVStream.side_data array.
+ */
+ int nb_side_data;
+
/*****************************************************************
* All fields below this line are not part of the public API. They
* may not be used outside of libavformat and can be changed and
AVDictionary *metadata;
} AVChapter;
+typedef struct AVFormatInternal AVFormatInternal;
+
/**
* Format I/O context.
* New fields can be added to the end with minor version bumps.
*/
typedef struct AVFormatContext {
/**
- * A class for logging and AVOptions. Set by avformat_alloc_context().
+ * A class for logging and @ref avoptions. Set by avformat_alloc_context().
* Exports (de)muxer private options if they exist.
*/
const AVClass *av_class;
/**
- * Can only be iformat or oformat, not both at the same time.
+ * The input container format.
*
- * decoding: set by avformat_open_input().
- * encoding: set by the user.
+ * Demuxing only, set by avformat_open_input().
*/
struct AVInputFormat *iformat;
+
+ /**
+ * The output container format.
+ *
+ * Muxing only, must be set by the caller before avformat_write_header().
+ */
struct AVOutputFormat *oformat;
/**
* Format private data. This is an AVOptions-enabled struct
* if and only if iformat/oformat.priv_class is not NULL.
+ *
+ * - muxing: set by avformat_write_header()
+ * - demuxing: set by avformat_open_input()
*/
void *priv_data;
/**
* I/O context.
*
- * decoding: either set by the user before avformat_open_input() (then
- * the user must close it manually) or set by avformat_open_input().
- * encoding: set by the user.
+ * - demuxing: either set by the user before avformat_open_input() (then
+ * the user must close it manually) or set by avformat_open_input().
+ * - muxing: set by the user before avformat_write_header(). The caller must
+ * take care of closing / freeing the IO context.
*
* Do NOT set this field if AVFMT_NOFILE flag is set in
* iformat/oformat.flags. In such a case, the (de)muxer will handle
/* stream info */
int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
+ /**
+ * Number of elements in AVFormatContext.streams.
+ *
+ * Set by avformat_new_stream(), must not be modified by any other code.
+ */
+ unsigned int nb_streams;
/**
* A list of all streams in the file. New streams are created with
* avformat_new_stream().
*
- * decoding: streams are created by libavformat in avformat_open_input().
- * If AVFMTCTX_NOHEADER is set in ctx_flags, then new streams may also
- * appear in av_read_frame().
- * encoding: streams are created by the user before avformat_write_header().
+ * - demuxing: streams are created by libavformat in avformat_open_input().
+ * If AVFMTCTX_NOHEADER is set in ctx_flags, then new streams may also
+ * appear in av_read_frame().
+ * - muxing: streams are created by the user before avformat_write_header().
+ *
+ * Freed by libavformat in avformat_free_context().
*/
- unsigned int nb_streams;
AVStream **streams;
- char filename[1024]; /**< input or output filename */
+ /**
+ * input or output filename
+ *
+ * - demuxing: set by avformat_open_input()
+ * - muxing: may be set by the caller before avformat_write_header()
+ */
+ char filename[1024];
/**
- * Decoding: position of the first frame of the component, in
+ * Position of the first frame of the component, in
* AV_TIME_BASE fractional seconds. NEVER set this value directly:
* It is deduced from the AVStream values.
+ *
+ * Demuxing only, set by libavformat.
*/
int64_t start_time;
/**
- * Decoding: duration of the stream, in AV_TIME_BASE fractional
+ * Duration of the stream, in AV_TIME_BASE fractional
* seconds. Only set this value if you know none of the individual stream
* durations and also do not set any of them. This is deduced from the
* AVStream values if not set.
+ *
+ * Demuxing only, set by libavformat.
*/
int64_t duration;
/**
- * Decoding: total stream bitrate in bit/s, 0 if not
+ * Total stream bitrate in bit/s, 0 if not
* available. Never set it directly if the file_size and the
* duration are known as Libav can compute it automatically.
*/
#define AVFMT_FLAG_FLUSH_PACKETS 0x0200 ///< Flush the AVIOContext every packet.
/**
- * decoding: size of data to probe; encoding: unused.
+ * Maximum size of the data read from input for determining
+ * the input container format.
+ * Demuxing only, set by the caller before avformat_open_input().
*/
unsigned int probesize;
/**
- * decoding: maximum time (in AV_TIME_BASE units) during which the input should
- * be analyzed in avformat_find_stream_info().
+ * Maximum duration (in AV_TIME_BASE units) of the data read
+ * from input in avformat_find_stream_info().
+ * Demuxing only, set by the caller before avformat_find_stream_info().
*/
int max_analyze_duration;
* accurate seeking (depends on demuxer).
* Demuxers for which a full in-memory index is mandatory will ignore
* this.
- * muxing : unused
- * demuxing: set by user
+ * - muxing: unused
+ * - demuxing: set by user
*/
unsigned int max_index_size;
* in the trailer. To write chapters in the trailer, nb_chapters
* must be zero when write_header is called and non-zero when
* write_trailer is called.
- * muxing : set by user
- * demuxing: set by libavformat
+ * - muxing: set by user
+ * - demuxing: set by libavformat
*/
unsigned int nb_chapters;
AVChapter **chapters;
+ /**
+ * Metadata that applies to the whole file.
+ *
+ * - demuxing: set by libavformat in avformat_open_input()
+ * - muxing: may be set by the caller before avformat_write_header()
+ *
+ * Freed by libavformat in avformat_free_context().
+ */
AVDictionary *metadata;
/**
* Start time of the stream in real world time, in microseconds
- * since the unix epoch (00:00 1st January 1970). That is, pts=0
- * in the stream was captured at this real world time.
- * - encoding: Set by user.
- * - decoding: Unused.
+ * since the Unix epoch (00:00 1st January 1970). That is, pts=0 in the
+ * stream was captured at this real world time.
+ * Muxing only, set by the caller before avformat_write_header().
*/
int64_t start_time_realtime;
/**
- * decoding: number of frames used to probe fps
+ * The number of frames used for determining the framerate in
+ * avformat_find_stream_info().
+ * Demuxing only, set by the caller before avformat_find_stream_info().
*/
int fps_probe_size;
/**
* Error recognition; higher values will detect more errors but may
* misdetect some more or less valid parts as errors.
- * - encoding: unused
- * - decoding: Set by user.
+ * Demuxing only, set by the caller before avformat_open_input().
*/
int error_recognition;
/**
* Custom interrupt callbacks for the I/O layer.
*
- * decoding: set by the user before avformat_open_input().
- * encoding: set by the user before avformat_write_header()
+ * demuxing: set by the user before avformat_open_input().
+ * muxing: set by the user before avformat_write_header()
* (mainly useful for AVFMT_NOFILE formats). The callback
* should also be passed to avio_open2() if it's used to
* open the file.
*/
int debug;
#define FF_FDEBUG_TS 0x0001
+
+ /**
+ * Maximum buffering duration for interleaving.
+ *
+ * To ensure all the streams are interleaved correctly,
+ * av_interleaved_write_frame() will wait until it has at least one packet
+ * for each stream before actually writing any packets to the output file.
+ * When some streams are "sparse" (i.e. there are large gaps between
+ * successive packets), this can result in excessive buffering.
+ *
+ * This field specifies the maximum difference between the timestamps of the
+ * first and the last packet in the muxing queue, above which libavformat
+ * will output a packet regardless of whether it has queued a packet for all
+ * the streams.
+ *
+ * Muxing only, set by the caller before avformat_write_header().
+ */
+ int64_t max_interleave_delta;
+
/*****************************************************************
* All fields below this line are not part of the public API. They
* may not be used outside of libavformat and can be changed and
*/
AVRational offset_timebase;
+ /**
+ * An opaque field for libavformat internal usage.
+ * Must not be accessed in any way by callers.
+ */
+ AVFormatInternal *internal;
} AVFormatContext;
typedef struct AVPacketList {
*
* When muxing, should be called by the user before avformat_write_header().
*
+ * @param s media file handle
* @param c If non-NULL, the AVCodecContext corresponding to the new stream
* will be initialized to use this codec. This is needed for e.g. codec-specific
* defaults to be set, so codec should be provided if it is known.
/**
* Guess the file format.
*
+ * @param pd data to be probed
* @param is_opened Whether the file is already opened; determines whether
* demuxers with or without AVFMT_NOFILE are probed.
*/
/**
* Guess the file format.
*
+ * @param pd data to be probed
* @param is_opened Whether the file is already opened; determines whether
* demuxers with or without AVFMT_NOFILE are probed.
* @param score_max A probe score larger that this is required to accept a
/**
* Seek to the keyframe at timestamp.
* 'timestamp' in 'stream_index'.
+ *
+ * @param s media file handle
* @param stream_index If stream_index is (-1), a default
* stream is selected, and timestamp is automatically converted
* from AV_TIME_BASE units to the stream specific time_base.
* If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
* keyframes (this may not be supported by all demuxers).
*
+ * @param s media file handle
* @param stream_index index of the stream which is used as time base reference
* @param min_ts smallest acceptable timestamp
* @param ts target timestamp
/**
* Write a packet to an output media file.
*
- * The packet shall contain one audio or video frame.
- * The packet must be correctly interleaved according to the container
- * specification, if not then av_interleaved_write_frame must be used.
+ * 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.
*
* @param s media file handle
- * @param pkt The packet, which contains the stream_index, buf/buf_size,
- * dts/pts, ...
- * This 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.
+ * @param 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).
+ * <br>
+ * 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.
+ * <br>
+ * Packet's @ref AVPacket.stream_index "stream_index" field must be
+ * set to the index of the corresponding stream in @ref
+ * AVFormatContext.streams "s->streams". It is very strongly
+ * recommended that timing information (@ref AVPacket.pts "pts", @ref
+ * AVPacket.dts "dts", @ref AVPacket.duration "duration") is set to
+ * correct values.
* @return < 0 on error, = 0 if OK, 1 if flushed and there is no more data to flush
+ *
+ * @see av_interleaved_write_frame()
*/
int av_write_frame(AVFormatContext *s, AVPacket *pkt);
/**
* Write a packet to an output media file ensuring correct interleaving.
*
- * The packet must contain one audio or video frame.
- * If the packets are already correctly interleaved, the application should
- * call av_write_frame() instead as it is slightly faster. It is also important
- * to keep in mind that completely non-interleaved input will need huge amounts
- * of memory to interleave with this, so it is preferable to interleave at the
- * demuxer level.
+ * 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.
*
* @param s media file handle
- * @param pkt The packet containing the data to be written. pkt->buf must be set
- * to a valid AVBufferRef describing the packet data. Libavformat takes
- * ownership of this reference and will unref it when it sees fit. The caller
- * must not access the data through this reference after this function returns.
- * This can be NULL (at any time, not just at the end), to flush the
- * interleaving queues.
- * Packet's @ref AVPacket.stream_index "stream_index" field must be set to the
- * index of the corresponding stream in @ref AVFormatContext.streams
- * "s.streams".
- * It is very strongly recommended that timing information (@ref AVPacket.pts
- * "pts", @ref AVPacket.dts "dts" @ref AVPacket.duration "duration") is set to
- * correct values.
- *
- * @return 0 on success, a negative AVERROR on error.
+ * @param pkt The packet containing the data to be written.
+ * <br>
+ * 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.
+ * <br>
+ * This parameter can be NULL (at any time, not just at the end), to
+ * flush the interleaving queues.
+ * <br>
+ * Packet's @ref AVPacket.stream_index "stream_index" field must be
+ * set to the index of the corresponding stream in @ref
+ * AVFormatContext.streams "s->streams". It is very strongly
+ * recommended that timing information (@ref AVPacket.pts "pts", @ref
+ * AVPacket.dts "dts", @ref AVPacket.duration "duration") is set to
+ * correct values.
+ *
+ * @return 0 on success, a negative AVERROR on error. Libavformat will always
+ * take care of freeing the packet, even if this function fails.
+ *
+ * @see av_write_frame(), AVFormatContext.max_interleave_delta
*/
int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
*
* @param tags list of supported codec_id-codec_tag pairs, as stored
* in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
+ * @param tag codec tag to match to a codec ID
*/
enum AVCodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
*
* @param tags list of supported codec_id-codec_tag pairs, as stored
* in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
+ * @param id codec ID to match to a codec tag
*/
unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum AVCodecID id);
/**
* Get the index for a specific timestamp.
+ *
+ * @param st stream that the timestamp belongs to
+ * @param timestamp timestamp to retrieve the index for
* @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
* to the timestamp which is <= the requested one, if backward
* is 0, then it will be >=
* Return a positive value if the given filename has one of the given
* extensions, 0 otherwise.
*
+ * @param filename file name to check against the given extensions
* @param extensions a comma-separated list of filename extensions
*/
int av_match_ext(const char *filename, const char *extensions);
/**
* Test if the given container can store a codec.
*
+ * @param ofmt container to check for compatibility
+ * @param codec_id codec to potentially store in container
* @param std_compliance standards compliance level, one of FF_COMPLIANCE_*
*
* @return 1 if codec with ID codec_id can be stored in ofmt, 0 if it cannot.
projects / ffmpeg / blobdiff