* 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)(struct AVFormatContext *);
#define AV_DISPOSITION_CLEAN_EFFECTS 0x0200 /**< stream without voice */
/**
* The stream is stored in the file as an attached picture/"cover art" (e.g.
- * APIC frame in ID3v2). The single packet associated with it will be returned
- * among the first few packets read from the file unless seeking takes place.
- * It can also be accessed at any time in AVStream.attached_pic.
+ * APIC frame in ID3v2). The first (usually only) packet associated with it
+ * will be returned among the first few packets read from the file unless
+ * seeking takes place. It can also be accessed at any time in
+ * AVStream.attached_pic.
*/
#define AV_DISPOSITION_ATTACHED_PIC 0x0400
+/**
+ * The stream is sparse, and contains thumbnail images, often corresponding
+ * to chapter markers. Only ever used with AV_DISPOSITION_ATTACHED_PIC.
+ */
+#define AV_DISPOSITION_TIMED_THUMBNAILS 0x0800
typedef struct AVStreamInternal AVStreamInternal;
* Decoding: duration of the stream, in stream time base.
* If a source file does not specify a duration, but does specify
* a bitrate, this value will be estimated from bitrate and file size.
+ *
+ * Encoding: May be set by the caller before avformat_write_header() to
+ * provide a hint to the muxer about the estimated duration.
*/
int64_t duration;
* 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
* removed at will.
- * New public fields should be added right above.
+ * Internal note: be aware that physically removing these fields
+ * will break ABI. Replace removed fields with dummy fields, and
+ * add new fields to AVStreamInternal.
*****************************************************************
*/
/**
- * Stream information used internally by av_find_stream_info()
+ * Stream information used internally by avformat_find_stream_info()
*/
#define MAX_STD_TIMEBASES (30*12+30+3+6)
struct {
int probe_packets;
/**
- * Number of frames that have been demuxed during av_find_stream_info()
+ * Number of frames that have been demuxed during avformat_find_stream_info()
*/
int codec_info_nb_frames;
*/
int inject_global_side_data;
+ /*****************************************************************
+ * All fields above this line are not part of the public API.
+ * Fields below are part of the public API and ABI again.
+ *****************************************************************
+ */
+
/**
* String containing paris of key and values describing recommended encoder configuration.
* Paris are separated by ','.
/**
* Audio preload in microseconds.
* Note, not all formats support this and unpredictable things may happen if it is used when not supported.
- * - encoding: Set by user via AVOptions (NO direct access)
+ * - encoding: Set by user
* - decoding: unused
*/
int audio_preload;
/**
* Max chunk time in microseconds.
* Note, not all formats support this and unpredictable things may happen if it is used when not supported.
- * - encoding: Set by user via AVOptions (NO direct access)
+ * - encoding: Set by user
* - decoding: unused
*/
int max_chunk_duration;
/**
* Max chunk size in bytes
* Note, not all formats support this and unpredictable things may happen if it is used when not supported.
- * - encoding: Set by user via AVOptions (NO direct access)
+ * - encoding: Set by user
* - decoding: unused
*/
int max_chunk_size;
* forces the use of wallclock timestamps as pts/dts of packets
* This has undefined results in the presence of B frames.
* - encoding: unused
- * - decoding: Set by user via AVOptions (NO direct access)
+ * - decoding: Set by user
*/
int use_wallclock_as_timestamps;
/**
* avio flags, used to force AVIO_FLAG_DIRECT.
* - encoding: unused
- * - decoding: Set by user via AVOptions (NO direct access)
+ * - decoding: Set by user
*/
int avio_flags;
* The duration field can be estimated through various ways, and this field can be used
* to know how the duration was estimated.
* - encoding: unused
- * - decoding: Read by user via AVOptions (NO direct access)
+ * - decoding: Read by user
*/
enum AVDurationEstimationMethod duration_estimation_method;
/**
* Skip initial bytes when opening stream
* - encoding: unused
- * - decoding: Set by user via AVOptions (NO direct access)
+ * - decoding: Set by user
*/
int64_t skip_initial_bytes;
/**
* Correct single timestamp overflows
* - encoding: unused
- * - decoding: Set by user via AVOptions (NO direct access)
+ * - decoding: Set by user
*/
unsigned int correct_ts_overflow;
/**
* Force seeking to any (also non key) frames.
* - encoding: unused
- * - decoding: Set by user via AVOptions (NO direct access)
+ * - decoding: Set by user
*/
int seek2any;
/**
* Flush the I/O context after each packet.
- * - encoding: Set by user via AVOptions (NO direct access)
+ * - encoding: Set by user
* - decoding: unused
*/
int flush_packets;
* The maximal score is AVPROBE_SCORE_MAX, its set when the demuxer probes
* the format.
* - encoding: unused
- * - decoding: set by avformat, read by user via av_format_get_probe_score() (NO direct access)
+ * - decoding: set by avformat, read by user
*/
int probe_score;
/**
* number of bytes to read maximally to identify format.
* - encoding: unused
- * - decoding: set by user through AVOPtions (NO direct access)
+ * - decoding: set by user
*/
int format_probesize;
* ',' separated list of allowed decoders.
* If NULL then all are allowed
* - encoding: unused
- * - decoding: set by user through AVOptions (NO direct access)
+ * - decoding: set by user
*/
char *codec_whitelist;
* ',' separated list of allowed demuxers.
* If NULL then all are allowed
* - encoding: unused
- * - decoding: set by user through AVOptions (NO direct access)
+ * - decoding: set by user
*/
char *format_whitelist;
* Forced video codec.
* This allows forcing a specific decoder, even when there are multiple with
* the same codec_id.
- * Demuxing: Set by user via av_format_set_video_codec (NO direct access).
+ * Demuxing: Set by user
*/
AVCodec *video_codec;
* Forced audio codec.
* This allows forcing a specific decoder, even when there are multiple with
* the same codec_id.
- * Demuxing: Set by user via av_format_set_audio_codec (NO direct access).
+ * Demuxing: Set by user
*/
AVCodec *audio_codec;
* Forced subtitle codec.
* This allows forcing a specific decoder, even when there are multiple with
* the same codec_id.
- * Demuxing: Set by user via av_format_set_subtitle_codec (NO direct access).
+ * Demuxing: Set by user
*/
AVCodec *subtitle_codec;
* Forced data codec.
* This allows forcing a specific decoder, even when there are multiple with
* the same codec_id.
- * Demuxing: Set by user via av_format_set_data_codec (NO direct access).
+ * Demuxing: Set by user
*/
AVCodec *data_codec;
/**
* Output timestamp offset, in microseconds.
- * Muxing: set by user via AVOptions (NO direct access)
+ * Muxing: set by user
*/
int64_t output_ts_offset;
/**
* dump format separator.
* can be ", " or "\n " or anything else
- * Code outside libavformat should access this field using AVOptions
- * (NO direct access).
* - muxing: Set by user.
* - demuxing: Set by user.
*/
/**
* ',' separated list of allowed protocols.
* - encoding: unused
- * - decoding: set by user through AVOptions (NO direct access)
+ * - decoding: set by user
*/
char *protocol_whitelist;
/**
* ',' separated list of disallowed protocols.
* - encoding: unused
- * - decoding: set by user through AVOptions (NO direct access)
+ * - decoding: set by user
*/
char *protocol_blacklist;
+
+ /**
+ * The maximum number of streams.
+ * - encoding: unused
+ * - decoding: set by user
+ */
+ int max_streams;
} AVFormatContext;
+/**
+ * Accessors for some AVFormatContext fields. These used to be provided for ABI
+ * compatibility, and do not need to be used anymore.
+ */
int av_format_get_probe_score(const AVFormatContext *s);
AVCodec * av_format_get_video_codec(const AVFormatContext *s);
void av_format_set_video_codec(AVFormatContext *s, AVCodec *c);
*/
AVStream *avformat_new_stream(AVFormatContext *s, const AVCodec *c);
+/**
+ * Wrap an existing array as stream side data.
+ *
+ * @param st stream
+ * @param type side information type
+ * @param data the side data array. It must be allocated with the av_malloc()
+ * family of functions. The ownership of the data is transferred to
+ * st.
+ * @param size side information size
+ * @return zero on success, a negative AVERROR code on failure. On failure,
+ * the stream is unchanged and the data remains owned by the caller.
+ */
+int av_stream_add_side_data(AVStream *st, enum AVPacketSideDataType type,
+ uint8_t *data, size_t size);
+
/**
* Allocate new information from stream.
*
* @addtogroup lavf_encoding
* @{
*/
+
+#define AVSTREAM_INIT_IN_WRITE_HEADER 0 ///< stream parameters initialized in avformat_write_header
+#define AVSTREAM_INIT_IN_INIT_OUTPUT 1 ///< stream parameters initialized in avformat_init_output
+
/**
* Allocate the stream private data and write the stream header to
* an output media file.
* On return this parameter will be destroyed and replaced with a dict containing
* options that were not found. May be NULL.
*
- * @return 0 on success, negative AVERROR on failure.
+ * @return 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 av_opt_find, av_dict_set, avio_open, av_oformat_next.
+ * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output.
*/
av_warn_unused_result
int avformat_write_header(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.
+ *
+ * @param 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.
+ * @param 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.
+ *
+ * @return 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 av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header.
+ */
+av_warn_unused_result
+int avformat_init_output(AVFormatContext *s, AVDictionary **options);
+
/**
* Write a packet to an output media file.
*