2 * copyright (c) 2001 Fabrice Bellard
4 * This file is part of FFmpeg.
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.
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.
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
21 #ifndef AVFORMAT_AVFORMAT_H
22 #define AVFORMAT_AVFORMAT_H
24 #define LIBAVFORMAT_VERSION_MAJOR 52
25 #define LIBAVFORMAT_VERSION_MINOR 72
26 #define LIBAVFORMAT_VERSION_MICRO 0
28 #define LIBAVFORMAT_VERSION_INT AV_VERSION_INT(LIBAVFORMAT_VERSION_MAJOR, \
29 LIBAVFORMAT_VERSION_MINOR, \
30 LIBAVFORMAT_VERSION_MICRO)
31 #define LIBAVFORMAT_VERSION AV_VERSION(LIBAVFORMAT_VERSION_MAJOR, \
32 LIBAVFORMAT_VERSION_MINOR, \
33 LIBAVFORMAT_VERSION_MICRO)
34 #define LIBAVFORMAT_BUILD LIBAVFORMAT_VERSION_INT
36 #define LIBAVFORMAT_IDENT "Lavf" AV_STRINGIFY(LIBAVFORMAT_VERSION)
39 * I return the LIBAVFORMAT_VERSION_INT constant. You got
40 * a fucking problem with that, douchebag?
42 unsigned avformat_version(void);
45 * Return the libavformat build-time configuration.
47 const char *avformat_configuration(void);
50 * Return the libavformat license.
52 const char *avformat_license(void);
55 #include <stdio.h> /* FILE */
56 #include "libavcodec/avcodec.h"
60 struct AVFormatContext;
64 * Public Metadata API.
65 * The metadata API allows libavformat to export metadata tags to a client
66 * application using a sequence of key/value pairs. Like all strings in FFmpeg,
67 * metadata must be stored as UTF-8 encoded Unicode. Note that metadata
68 * exported by demuxers isn't checked to be valid UTF-8 in most cases.
69 * Important concepts to keep in mind:
70 * 1. Keys are unique; there can never be 2 tags with the same key. This is
71 * also meant semantically, i.e., a demuxer should not knowingly produce
72 * several keys that are literally different but semantically identical.
73 * E.g., key=Author5, key=Author6. In this example, all authors must be
74 * placed in the same tag.
75 * 2. Metadata is flat, not hierarchical; there are no subtags. If you
76 * want to store, e.g., the email address of the child of producer Alice
77 * and actor Bob, that could have key=alice_and_bobs_childs_email_address.
78 * 3. Several modifiers can be applied to the tag name. This is done by
79 * appending a dash character ('-') and the modifier name in the order
80 * they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.
81 * a) language -- a tag whose value is localized for a particular language
82 * is appended with the ISO 639-2/B 3-letter language code.
83 * For example: Author-ger=Michael, Author-eng=Mike
84 * The original/default language is in the unqualified "Author" tag.
85 * A demuxer should set a default if it sets any translated tag.
86 * b) sorting -- a modified version of a tag that should be used for
87 * sorting will have '-sort' appended. E.g. artist="The Beatles",
88 * artist-sort="Beatles, The".
90 * 4. Tag names are normally exported exactly as stored in the container to
91 * allow lossless remuxing to the same format. For container-independent
92 * handling of metadata, av_metadata_conv() can convert it to ffmpeg generic
93 * format. Follows a list of generic tag names:
95 * album -- name of the set this work belongs to
96 * album_artist -- main creator of the set/album, if different from artist.
97 * e.g. "Various Artists" for compilation albums.
98 * artist -- main creator of the work
99 * comment -- any additional description of the file.
100 * composer -- who composed the work, if different from artist.
101 * copyright -- name of copyright holder.
102 * date -- date when the work was created, preferably in ISO 8601.
103 * disc -- number of a subset, e.g. disc in a multi-disc collection.
104 * encoder -- name/settings of the software/hardware that produced the file.
105 * encoded_by -- person/group who created the file.
106 * filename -- original name of the file.
107 * genre -- <self-evident>.
108 * language -- main language in which the work is performed, preferably
109 * in ISO 639-2 format.
110 * performer -- artist who performed the work, if different from artist.
111 * E.g for "Also sprach Zarathustra", artist would be "Richard
112 * Strauss" and performer "London Philharmonic Orchestra".
113 * publisher -- name of the label/publisher.
114 * title -- name of the work.
115 * track -- number of this work in the set, can be in form current/total.
118 #define AV_METADATA_MATCH_CASE 1
119 #define AV_METADATA_IGNORE_SUFFIX 2
120 #define AV_METADATA_DONT_STRDUP_KEY 4
121 #define AV_METADATA_DONT_STRDUP_VAL 8
122 #define AV_METADATA_DONT_OVERWRITE 16 ///< Don't overwrite existing tags.
129 typedef struct AVMetadata AVMetadata;
130 typedef struct AVMetadataConv AVMetadataConv;
133 * Get a metadata element with matching key.
134 * @param prev Set to the previous matching element to find the next.
135 * If set to NULL the first matching element is returned.
136 * @param flags Allows case as well as suffix-insensitive comparisons.
137 * @return Found tag or NULL, changing key or value leads to undefined behavior.
140 av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags);
142 #if LIBAVFORMAT_VERSION_MAJOR == 52
144 * Set the given tag in m, overwriting an existing tag.
145 * @param key tag key to add to m (will be av_strduped)
146 * @param value tag value to add to m (will be av_strduped)
147 * @return >= 0 on success otherwise an error code <0
148 * @deprecated Use av_metadata_set2() instead.
150 attribute_deprecated int av_metadata_set(AVMetadata **pm, const char *key, const char *value);
154 * Set the given tag in m, overwriting an existing tag.
155 * @param key tag key to add to m (will be av_strduped depending on flags)
156 * @param value tag value to add to m (will be av_strduped depending on flags).
157 * Passing a NULL value will cause an existing tag to be deleted.
158 * @return >= 0 on success otherwise an error code <0
160 int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
163 * Convert all the metadata sets from ctx according to the source and
164 * destination conversion tables. If one of the tables is NULL, then
165 * tags are converted to/from ffmpeg generic tag names.
166 * @param d_conv destination tags format conversion table
167 * @param s_conv source tags format conversion table
169 void av_metadata_conv(struct AVFormatContext *ctx,const AVMetadataConv *d_conv,
170 const AVMetadataConv *s_conv);
173 * Free all the memory allocated for an AVMetadata struct.
175 void av_metadata_free(AVMetadata **m);
178 /* packet functions */
182 * Allocate and read the payload of a packet and initialize its
183 * fields with default values.
186 * @param size desired payload size
187 * @return >0 (read size) if OK, AVERROR_xxx otherwise
189 int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
192 /*************************************************/
193 /* fractional numbers for exact pts handling */
196 * The exact value of the fractional number is: 'val + num / den'.
197 * num is assumed to be 0 <= num < den.
199 typedef struct AVFrac {
200 int64_t val, num, den;
203 /*************************************************/
204 /* input/output formats */
208 /** This structure contains the data a format has to probe a file. */
209 typedef struct AVProbeData {
210 const char *filename;
211 unsigned char *buf; /**< Buffer must have AVPROBE_PADDING_SIZE of extra allocated bytes filled with zero. */
212 int buf_size; /**< Size of buf except extra allocated bytes */
215 #define AVPROBE_SCORE_MAX 100 ///< maximum score, half of that is used for file-extension-based detection
216 #define AVPROBE_PADDING_SIZE 32 ///< extra allocated bytes at the end of the probe buffer
218 typedef struct AVFormatParameters {
219 AVRational time_base;
224 enum PixelFormat pix_fmt;
225 int channel; /**< Used to select DV channel. */
226 const char *standard; /**< TV standard, NTSC, PAL, SECAM */
227 unsigned int mpeg2ts_raw:1; /**< Force raw MPEG-2 transport stream output, if possible. */
228 unsigned int mpeg2ts_compute_pcr:1; /**< Compute exact PCR for each transport
229 stream packet (only meaningful if
230 mpeg2ts_raw is TRUE). */
231 unsigned int initial_pause:1; /**< Do not begin to play the stream
232 immediately (RTSP only). */
233 unsigned int prealloced_context:1;
234 #if LIBAVFORMAT_VERSION_INT < (53<<16)
235 enum CodecID video_codec_id;
236 enum CodecID audio_codec_id;
238 } AVFormatParameters;
240 //! Demuxer will use url_fopen, no opened file should be provided by the caller.
241 #define AVFMT_NOFILE 0x0001
242 #define AVFMT_NEEDNUMBER 0x0002 /**< Needs '%d' in filename. */
243 #define AVFMT_SHOW_IDS 0x0008 /**< Show format stream IDs numbers. */
244 #define AVFMT_RAWPICTURE 0x0020 /**< Format wants AVPicture structure for
246 #define AVFMT_GLOBALHEADER 0x0040 /**< Format wants global header. */
247 #define AVFMT_NOTIMESTAMPS 0x0080 /**< Format does not need / have any timestamps. */
248 #define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */
249 #define AVFMT_TS_DISCONT 0x0200 /**< Format allows timestamp discontinuities. */
250 #define AVFMT_VARIABLE_FPS 0x0400 /**< Format allows variable fps. */
251 #define AVFMT_NODIMENSIONS 0x0800 /**< Format does not need width/height */
253 typedef struct AVOutputFormat {
256 * Descriptive name for the format, meant to be more human-readable
257 * than name. You should use the NULL_IF_CONFIG_SMALL() macro
260 const char *long_name;
261 const char *mime_type;
262 const char *extensions; /**< comma-separated filename extensions */
263 /** size of private data so that it can be allocated in the wrapper */
266 enum CodecID audio_codec; /**< default audio codec */
267 enum CodecID video_codec; /**< default video codec */
268 int (*write_header)(struct AVFormatContext *);
269 int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
270 int (*write_trailer)(struct AVFormatContext *);
271 /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */
273 /** Currently only used to set pixel format if not YUV420P. */
274 int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
275 int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,
276 AVPacket *in, int flush);
279 * List of supported codec_id-codec_tag pairs, ordered by "better
280 * choice first". The arrays are all terminated by CODEC_ID_NONE.
282 const struct AVCodecTag * const *codec_tag;
284 enum CodecID subtitle_codec; /**< default subtitle codec */
286 const AVMetadataConv *metadata_conv;
289 struct AVOutputFormat *next;
292 typedef struct AVInputFormat {
295 * Descriptive name for the format, meant to be more human-readable
296 * than name. You should use the NULL_IF_CONFIG_SMALL() macro
299 const char *long_name;
300 /** Size of private data so that it can be allocated in the wrapper. */
303 * Tell if a given file has a chance of being parsed as this format.
304 * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes
305 * big so you do not have to check for that unless you need more.
307 int (*read_probe)(AVProbeData *);
308 /** Read the format header and initialize the AVFormatContext
309 structure. Return 0 if OK. 'ap' if non-NULL contains
310 additional parameters. Only used in raw format right
311 now. 'av_new_stream' should be called to create new streams. */
312 int (*read_header)(struct AVFormatContext *,
313 AVFormatParameters *ap);
314 /** Read one packet and put it in 'pkt'. pts and flags are also
315 set. 'av_new_stream' can be called only if the flag
316 AVFMTCTX_NOHEADER is used.
317 @return 0 on success, < 0 on error.
318 When returning an error, pkt must not have been allocated
319 or must be freed before returning */
320 int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
321 /** Close the stream. The AVFormatContext and AVStreams are not
322 freed by this function */
323 int (*read_close)(struct AVFormatContext *);
325 #if LIBAVFORMAT_VERSION_MAJOR < 53
327 * Seek to a given timestamp relative to the frames in
328 * stream component stream_index.
329 * @param stream_index Must not be -1.
330 * @param flags Selects which direction should be preferred if no exact
331 * match is available.
332 * @return >= 0 on success (but not necessarily the new offset)
334 int (*read_seek)(struct AVFormatContext *,
335 int stream_index, int64_t timestamp, int flags);
338 * Gets the next timestamp in stream[stream_index].time_base units.
339 * @return the timestamp or AV_NOPTS_VALUE if an error occurred
341 int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
342 int64_t *pos, int64_t pos_limit);
343 /** Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER. */
345 /** If extensions are defined, then no probe is done. You should
346 usually not use extension format guessing because it is not
348 const char *extensions;
349 /** General purpose read-only value that the format can use. */
352 /** Start/resume playing - only meaningful if using a network-based format
354 int (*read_play)(struct AVFormatContext *);
356 /** Pause playing - only meaningful if using a network-based format
358 int (*read_pause)(struct AVFormatContext *);
360 const struct AVCodecTag * const *codec_tag;
363 * Seek to timestamp ts.
364 * Seeking will be done so that the point from which all active streams
365 * can be presented successfully will be closest to ts and within min/max_ts.
366 * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
368 int (*read_seek2)(struct AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
370 const AVMetadataConv *metadata_conv;
373 struct AVInputFormat *next;
376 enum AVStreamParseType {
378 AVSTREAM_PARSE_FULL, /**< full parsing and repack */
379 AVSTREAM_PARSE_HEADERS, /**< Only parse headers, do not repack. */
380 AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */
381 AVSTREAM_PARSE_FULL_ONCE, /**< full parsing and repack of the first frame only, only implemented for H.264 currently */
384 typedef struct AVIndexEntry {
387 #define AVINDEX_KEYFRAME 0x0001
389 int size:30; //Yeah, trying to keep the size of this small to reduce memory requirements (it is 24 vs. 32 bytes due to possible 8-byte alignment).
390 int min_distance; /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */
393 #define AV_DISPOSITION_DEFAULT 0x0001
394 #define AV_DISPOSITION_DUB 0x0002
395 #define AV_DISPOSITION_ORIGINAL 0x0004
396 #define AV_DISPOSITION_COMMENT 0x0008
397 #define AV_DISPOSITION_LYRICS 0x0010
398 #define AV_DISPOSITION_KARAOKE 0x0020
402 * New fields can be added to the end with minor version bumps.
403 * Removal, reordering and changes to existing fields require a major
405 * sizeof(AVStream) must not be used outside libav*.
407 typedef struct AVStream {
408 int index; /**< stream index in AVFormatContext */
409 int id; /**< format-specific stream ID */
410 AVCodecContext *codec; /**< codec context */
412 * Real base framerate of the stream.
413 * This is the lowest framerate with which all timestamps can be
414 * represented accurately (it is the least common multiple of all
415 * framerates in the stream). Note, this value is just a guess!
416 * For example, if the time base is 1/90000 and all frames have either
417 * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
419 AVRational r_frame_rate;
422 /* internal data used in av_find_stream_info() */
424 /** encoding: pts generation when outputting stream */
428 * This is the fundamental unit of time (in seconds) in terms
429 * of which frame timestamps are represented. For fixed-fps content,
430 * time base should be 1/framerate and timestamp increments should be 1.
432 AVRational time_base;
433 int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
434 /* ffmpeg.c private use */
435 int stream_copy; /**< If set, just copy stream. */
436 enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
437 //FIXME move stuff to a flags field?
438 /** Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
439 * MN: dunno if that is the right place for it */
442 * Decoding: pts of the first frame of the stream, in stream time base.
443 * Only set this if you are absolutely 100% sure that the value you set
444 * it to really is the pts of the first frame.
445 * This may be undefined (AV_NOPTS_VALUE).
446 * @note The ASF header does NOT contain a correct start_time the ASF
447 * demuxer must NOT set this.
451 * Decoding: duration of the stream, in stream time base.
452 * If a source file does not specify a duration, but does specify
453 * a bitrate, this value will be estimated from bitrate and file size.
457 #if LIBAVFORMAT_VERSION_INT < (53<<16)
458 char language[4]; /** ISO 639-2/B 3-letter language code (empty string if undefined) */
461 /* av_read_frame() support */
462 enum AVStreamParseType need_parsing;
463 struct AVCodecParserContext *parser;
466 int last_IP_duration;
468 /* av_seek_frame() support */
469 AVIndexEntry *index_entries; /**< Only used if the format does not
470 support seeking natively. */
471 int nb_index_entries;
472 unsigned int index_entries_allocated_size;
474 int64_t nb_frames; ///< number of frames in this stream if known or 0
476 #if LIBAVFORMAT_VERSION_INT < (53<<16)
479 char *filename; /**< source filename of the stream */
482 int disposition; /**< AV_DISPOSITION_* bit field */
484 AVProbeData probe_data;
485 #define MAX_REORDER_DELAY 16
486 int64_t pts_buffer[MAX_REORDER_DELAY+1];
489 * sample aspect ratio (0 if unknown)
490 * - encoding: Set by user.
491 * - decoding: Set by libavformat.
493 AVRational sample_aspect_ratio;
495 AVMetadata *metadata;
497 /* av_read_frame() support */
498 const uint8_t *cur_ptr;
502 // Timestamp generation support:
504 * Timestamp corresponding to the last dts sync point.
506 * Initialized when AVCodecParserContext.dts_sync_point >= 0 and
507 * a DTS is received from the underlying container. Otherwise set to
508 * AV_NOPTS_VALUE by default.
510 int64_t reference_dts;
513 * Number of packets to buffer for codec probing
514 * NOT PART OF PUBLIC API
516 #define MAX_PROBE_PACKETS 2500
520 * last packet in packet_buffer for this stream when muxing.
521 * used internally, NOT PART OF PUBLIC API, dont read or write from outside of libav*
523 struct AVPacketList *last_in_packet_buffer;
528 AVRational avg_frame_rate;
531 * Number of frames that have been demuxed during av_find_stream_info()
533 int codec_info_nb_frames;
536 #define AV_PROGRAM_RUNNING 1
539 * New fields can be added to the end with minor version bumps.
540 * Removal, reordering and changes to existing fields require a major
542 * sizeof(AVProgram) must not be used outside libav*.
544 typedef struct AVProgram {
546 #if LIBAVFORMAT_VERSION_INT < (53<<16)
547 char *provider_name; ///< network name for DVB streams
548 char *name; ///< service name for DVB streams
551 enum AVDiscard discard; ///< selects which program to discard and which to feed to the caller
552 unsigned int *stream_index;
553 unsigned int nb_stream_indexes;
554 AVMetadata *metadata;
557 #define AVFMTCTX_NOHEADER 0x0001 /**< signal that no header is present
558 (streams are added dynamically) */
560 typedef struct AVChapter {
561 int id; ///< unique ID to identify the chapter
562 AVRational time_base; ///< time base in which the start/end timestamps are specified
563 int64_t start, end; ///< chapter start/end time in time_base units
564 #if LIBAVFORMAT_VERSION_INT < (53<<16)
565 char *title; ///< chapter title
567 AVMetadata *metadata;
570 #if LIBAVFORMAT_VERSION_MAJOR < 53
571 #define MAX_STREAMS 20
575 * Format I/O context.
576 * New fields can be added to the end with minor version bumps.
577 * Removal, reordering and changes to existing fields require a major
579 * sizeof(AVFormatContext) must not be used outside libav*.
581 typedef struct AVFormatContext {
582 const AVClass *av_class; /**< Set by avformat_alloc_context. */
583 /* Can only be iformat or oformat, not both at the same time. */
584 struct AVInputFormat *iformat;
585 struct AVOutputFormat *oformat;
588 unsigned int nb_streams;
589 AVStream *streams[MAX_STREAMS];
590 char filename[1024]; /**< input or output filename */
593 #if LIBAVFORMAT_VERSION_INT < (53<<16)
599 int year; /**< ID3 year, 0 if none */
600 int track; /**< track number, 0 if none */
601 char genre[32]; /**< ID3 genre */
604 int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
605 /* private data for pts handling (do not modify directly). */
606 /** This buffer is only needed when packets were already buffered but
607 not decoded, for example to get the codec parameters in MPEG
609 struct AVPacketList *packet_buffer;
611 /** Decoding: position of the first frame of the component, in
612 AV_TIME_BASE fractional seconds. NEVER set this value directly:
613 It is deduced from the AVStream values. */
615 /** Decoding: duration of the stream, in AV_TIME_BASE fractional
616 seconds. Only set this value if you know none of the individual stream
617 durations and also dont set any of them. This is deduced from the
618 AVStream values if not set. */
620 /** decoding: total file size, 0 if unknown */
622 /** Decoding: total stream bitrate in bit/s, 0 if not
623 available. Never set it directly if the file_size and the
624 duration are known as FFmpeg can compute it automatically. */
627 /* av_read_frame() support */
629 #if LIBAVFORMAT_VERSION_INT < (53<<16)
630 const uint8_t *cur_ptr_deprecated;
631 int cur_len_deprecated;
632 AVPacket cur_pkt_deprecated;
635 /* av_seek_frame() support */
636 int64_t data_offset; /** offset of the first packet */
640 unsigned int packet_size;
644 #define AVFMT_NOOUTPUTLOOP -1
645 #define AVFMT_INFINITEOUTPUTLOOP 0
646 /** number of times to loop output in formats that support it */
650 #define AVFMT_FLAG_GENPTS 0x0001 ///< Generate missing pts even if it requires parsing future frames.
651 #define AVFMT_FLAG_IGNIDX 0x0002 ///< Ignore index.
652 #define AVFMT_FLAG_NONBLOCK 0x0004 ///< Do not block when reading packets from input.
653 #define AVFMT_FLAG_IGNDTS 0x0008 ///< Ignore DTS on frames that contain both DTS & PTS
654 #define AVFMT_FLAG_NOFILLIN 0x0010 ///< Do not infer any values from other values, just return what is stored in the container
655 #define AVFMT_FLAG_NOPARSE 0x0020 ///< Do not use AVParsers, you also must set AVFMT_FLAG_NOFILLIN as the fillin code works on frames and no parsing -> no frames. Also seeking to frames can not work if parsing to find frame boundaries has been disabled
656 #define AVFMT_FLAG_RTP_HINT 0x0040 ///< Add RTP hinting to the output file
659 /** decoding: size of data to probe; encoding: unused. */
660 unsigned int probesize;
663 * Maximum time (in AV_TIME_BASE units) during which the input should
664 * be analyzed in av_find_stream_info().
666 int max_analyze_duration;
671 unsigned int nb_programs;
672 AVProgram **programs;
675 * Forced video codec_id.
676 * Demuxing: Set by user.
678 enum CodecID video_codec_id;
680 * Forced audio codec_id.
681 * Demuxing: Set by user.
683 enum CodecID audio_codec_id;
685 * Forced subtitle codec_id.
686 * Demuxing: Set by user.
688 enum CodecID subtitle_codec_id;
691 * Maximum amount of memory in bytes to use for the index of each stream.
692 * If the index exceeds this size, entries will be discarded as
693 * needed to maintain a smaller size. This can lead to slower or less
694 * accurate seeking (depends on demuxer).
695 * Demuxers for which a full in-memory index is mandatory will ignore
698 * demuxing: set by user
700 unsigned int max_index_size;
703 * Maximum amount of memory in bytes to use for buffering frames
704 * obtained from realtime capture devices.
706 unsigned int max_picture_buffer;
708 unsigned int nb_chapters;
709 AVChapter **chapters;
712 * Flags to enable debugging.
715 #define FF_FDEBUG_TS 0x0001
718 * Raw packets from the demuxer, prior to parsing and decoding.
719 * This buffer is used for buffering packets until the codec can
720 * be identified, as parsing cannot be done without knowing the
723 struct AVPacketList *raw_packet_buffer;
724 struct AVPacketList *raw_packet_buffer_end;
726 struct AVPacketList *packet_buffer_end;
728 AVMetadata *metadata;
731 * Remaining size available for raw_packet_buffer, in bytes.
732 * NOT PART OF PUBLIC API
734 #define RAW_PACKET_BUFFER_SIZE 2500000
735 int raw_packet_buffer_remaining_size;
738 * Start time of the stream in real world time, in microseconds
739 * since the unix epoch (00:00 1st January 1970). That is, pts=0
740 * in the stream was captured at this real world time.
741 * - encoding: Set by user.
742 * - decoding: Unused.
744 int64_t start_time_realtime;
747 typedef struct AVPacketList {
749 struct AVPacketList *next;
752 #if LIBAVFORMAT_VERSION_INT < (53<<16)
753 extern AVInputFormat *first_iformat;
754 extern AVOutputFormat *first_oformat;
758 * If f is NULL, returns the first registered input format,
759 * if f is non-NULL, returns the next registered input format after f
760 * or NULL if f is the last one.
762 AVInputFormat *av_iformat_next(AVInputFormat *f);
765 * If f is NULL, returns the first registered output format,
766 * if f is non-NULL, returns the next registered output format after f
767 * or NULL if f is the last one.
769 AVOutputFormat *av_oformat_next(AVOutputFormat *f);
771 enum CodecID av_guess_image2_codec(const char *filename);
773 /* XXX: Use automatic init with either ELF sections or C file parser */
777 void av_register_input_format(AVInputFormat *format);
778 void av_register_output_format(AVOutputFormat *format);
779 #if LIBAVFORMAT_VERSION_MAJOR < 53
780 attribute_deprecated AVOutputFormat *guess_stream_format(const char *short_name,
781 const char *filename,
782 const char *mime_type);
785 * @deprecated Use av_guess_format() instead.
787 attribute_deprecated AVOutputFormat *guess_format(const char *short_name,
788 const char *filename,
789 const char *mime_type);
793 * Return the output format in the list of registered output formats
794 * which best matches the provided parameters, or return NULL if
797 * @param short_name if non-NULL checks if short_name matches with the
798 * names of the registered formats
799 * @param filename if non-NULL checks if filename terminates with the
800 * extensions of the registered formats
801 * @param mime_type if non-NULL checks if mime_type matches with the
802 * MIME type of the registered formats
804 AVOutputFormat *av_guess_format(const char *short_name,
805 const char *filename,
806 const char *mime_type);
809 * Guess the codec ID based upon muxer and filename.
811 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
812 const char *filename, const char *mime_type,
813 enum AVMediaType type);
816 * Send a nice hexadecimal dump of a buffer to the specified file stream.
818 * @param f The file stream pointer where the dump should be sent to.
820 * @param size buffer size
822 * @see av_hex_dump_log, av_pkt_dump, av_pkt_dump_log
824 void av_hex_dump(FILE *f, uint8_t *buf, int size);
827 * Send a nice hexadecimal dump of a buffer to the log.
829 * @param avcl A pointer to an arbitrary struct of which the first field is a
830 * pointer to an AVClass struct.
831 * @param level The importance level of the message, lower values signifying
834 * @param size buffer size
836 * @see av_hex_dump, av_pkt_dump, av_pkt_dump_log
838 void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
841 * Send a nice dump of a packet to the specified file stream.
843 * @param f The file stream pointer where the dump should be sent to.
844 * @param pkt packet to dump
845 * @param dump_payload True if the payload must be displayed, too.
847 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
850 * Send a nice dump of a packet to the log.
852 * @param avcl A pointer to an arbitrary struct of which the first field is a
853 * pointer to an AVClass struct.
854 * @param level The importance level of the message, lower values signifying
856 * @param pkt packet to dump
857 * @param dump_payload True if the payload must be displayed, too.
859 void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
862 * Initialize libavformat and register all the muxers, demuxers and
863 * protocols. If you do not call this function, then you can select
864 * exactly which formats you want to support.
866 * @see av_register_input_format()
867 * @see av_register_output_format()
868 * @see av_register_protocol()
870 void av_register_all(void);
873 * Get the CodecID for the given codec tag tag.
874 * If no codec id is found returns CODEC_ID_NONE.
876 * @param tags list of supported codec_id-codec_tag pairs, as stored
877 * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
879 enum CodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
882 * Get the codec tag for the given codec id id.
883 * If no codec tag is found returns 0.
885 * @param tags list of supported codec_id-codec_tag pairs, as stored
886 * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
888 unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum CodecID id);
890 /* media file input */
893 * Find AVInputFormat based on the short name of the input format.
895 AVInputFormat *av_find_input_format(const char *short_name);
898 * Guess the file format.
900 * @param is_opened Whether the file is already opened; determines whether
901 * demuxers with or without AVFMT_NOFILE are probed.
903 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
906 * Guess the file format.
908 * @param is_opened Whether the file is already opened; determines whether
909 * demuxers with or without AVFMT_NOFILE are probed.
910 * @param score_max A probe score larger that this is required to accept a
911 * detection, the variable is set to the actual detection
913 * If the score is <= AVPROBE_SCORE_MAX / 4 it is recommended
914 * to retry with a larger probe buffer.
916 AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max);
919 * Allocate all the structures needed to read an input stream.
920 * This does not open the needed codecs for decoding the stream[s].
922 int av_open_input_stream(AVFormatContext **ic_ptr,
923 ByteIOContext *pb, const char *filename,
924 AVInputFormat *fmt, AVFormatParameters *ap);
927 * Open a media file as input. The codecs are not opened. Only the file
928 * header (if present) is read.
930 * @param ic_ptr The opened media file handle is put here.
931 * @param filename filename to open
932 * @param fmt If non-NULL, force the file format to use.
933 * @param buf_size optional buffer size (zero if default is OK)
934 * @param ap Additional parameters needed when opening the file
936 * @return 0 if OK, AVERROR_xxx otherwise
938 int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
941 AVFormatParameters *ap);
943 #if LIBAVFORMAT_VERSION_MAJOR < 53
945 * @deprecated Use avformat_alloc_context() instead.
947 attribute_deprecated AVFormatContext *av_alloc_format_context(void);
951 * Allocate an AVFormatContext.
952 * Can be freed with av_free() but do not forget to free everything you
953 * explicitly allocated as well!
955 AVFormatContext *avformat_alloc_context(void);
958 * Read packets of a media file to get stream information. This
959 * is useful for file formats with no headers such as MPEG. This
960 * function also computes the real framerate in case of MPEG-2 repeat
962 * The logical file position is not changed by this function;
963 * examined packets may be buffered for later processing.
965 * @param ic media file handle
966 * @return >=0 if OK, AVERROR_xxx on error
967 * @todo Let the user decide somehow what information is needed so that
968 * we do not waste time getting stuff the user does not need.
970 int av_find_stream_info(AVFormatContext *ic);
973 * Read a transport packet from a media file.
975 * This function is obsolete and should never be used.
976 * Use av_read_frame() instead.
978 * @param s media file handle
979 * @param pkt is filled
980 * @return 0 if OK, AVERROR_xxx on error
982 int av_read_packet(AVFormatContext *s, AVPacket *pkt);
985 * Return the next frame of a stream.
987 * The returned packet is valid
988 * until the next av_read_frame() or until av_close_input_file() and
989 * must be freed with av_free_packet. For video, the packet contains
990 * exactly one frame. For audio, it contains an integer number of
991 * frames if each frame has a known fixed size (e.g. PCM or ADPCM
992 * data). If the audio frames have a variable size (e.g. MPEG audio),
993 * then it contains one frame.
995 * pkt->pts, pkt->dts and pkt->duration are always set to correct
996 * values in AVStream.time_base units (and guessed if the format cannot
997 * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
998 * has B-frames, so it is better to rely on pkt->dts if you do not
999 * decompress the payload.
1001 * @return 0 if OK, < 0 on error or end of file
1003 int av_read_frame(AVFormatContext *s, AVPacket *pkt);
1006 * Seek to the keyframe at timestamp.
1007 * 'timestamp' in 'stream_index'.
1008 * @param stream_index If stream_index is (-1), a default
1009 * stream is selected, and timestamp is automatically converted
1010 * from AV_TIME_BASE units to the stream specific time_base.
1011 * @param timestamp Timestamp in AVStream.time_base units
1012 * or, if no stream is specified, in AV_TIME_BASE units.
1013 * @param flags flags which select direction and seeking mode
1014 * @return >= 0 on success
1016 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
1020 * Seek to timestamp ts.
1021 * Seeking will be done so that the point from which all active streams
1022 * can be presented successfully will be closest to ts and within min/max_ts.
1023 * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
1025 * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and
1026 * are the file position (this may not be supported by all demuxers).
1027 * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames
1028 * in the stream with stream_index (this may not be supported by all demuxers).
1029 * Otherwise all timestamps are in units of the stream selected by stream_index
1030 * or if stream_index is -1, in AV_TIME_BASE units.
1031 * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
1032 * keyframes (this may not be supported by all demuxers).
1034 * @param stream_index index of the stream which is used as time base reference
1035 * @param min_ts smallest acceptable timestamp
1036 * @param ts target timestamp
1037 * @param max_ts largest acceptable timestamp
1038 * @param flags flags
1039 * @return >=0 on success, error code otherwise
1041 * @NOTE This is part of the new seek API which is still under construction.
1042 * Thus do not use this yet. It may change at any time, do not expect
1043 * ABI compatibility yet!
1045 int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
1048 * Start playing a network-based stream (e.g. RTSP stream) at the
1051 int av_read_play(AVFormatContext *s);
1054 * Pause a network-based stream (e.g. RTSP stream).
1056 * Use av_read_play() to resume it.
1058 int av_read_pause(AVFormatContext *s);
1061 * Free a AVFormatContext allocated by av_open_input_stream.
1062 * @param s context to free
1064 void av_close_input_stream(AVFormatContext *s);
1067 * Close a media file (but not its codecs).
1069 * @param s media file handle
1071 void av_close_input_file(AVFormatContext *s);
1074 * Add a new stream to a media file.
1076 * Can only be called in the read_header() function. If the flag
1077 * AVFMTCTX_NOHEADER is in the format context, then new streams
1078 * can be added in read_packet too.
1080 * @param s media file handle
1081 * @param id file-format-dependent stream ID
1083 AVStream *av_new_stream(AVFormatContext *s, int id);
1084 AVProgram *av_new_program(AVFormatContext *s, int id);
1087 * Add a new chapter.
1088 * This function is NOT part of the public API
1089 * and should ONLY be used by demuxers.
1091 * @param s media file handle
1092 * @param id unique ID for this chapter
1093 * @param start chapter start time in time_base units
1094 * @param end chapter end time in time_base units
1095 * @param title chapter title
1097 * @return AVChapter or NULL on error
1099 AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base,
1100 int64_t start, int64_t end, const char *title);
1103 * Set the pts for a given stream.
1106 * @param pts_wrap_bits number of bits effectively used by the pts
1107 * (used for wrap control, 33 is the value for MPEG)
1108 * @param pts_num numerator to convert to seconds (MPEG: 1)
1109 * @param pts_den denominator to convert to seconds (MPEG: 90000)
1111 void av_set_pts_info(AVStream *s, int pts_wrap_bits,
1112 unsigned int pts_num, unsigned int pts_den);
1114 #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
1115 #define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes
1116 #define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non-keyframes
1117 #define AVSEEK_FLAG_FRAME 8 ///< seeking based on frame number
1119 int av_find_default_stream_index(AVFormatContext *s);
1122 * Get the index for a specific timestamp.
1123 * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
1124 * to the timestamp which is <= the requested one, if backward
1125 * is 0, then it will be >=
1126 * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
1127 * @return < 0 if no such timestamp could be found
1129 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
1132 * Ensure the index uses less memory than the maximum specified in
1133 * AVFormatContext.max_index_size by discarding entries if it grows
1135 * This function is not part of the public API and should only be called
1138 void ff_reduce_index(AVFormatContext *s, int stream_index);
1141 * Add an index entry into a sorted list. Update the entry if the list
1142 * already contains it.
1144 * @param timestamp timestamp in the time base of the given stream
1146 int av_add_index_entry(AVStream *st, int64_t pos, int64_t timestamp,
1147 int size, int distance, int flags);
1150 * Perform a binary search using av_index_search_timestamp() and
1151 * AVCodec.read_timestamp().
1152 * This is not supposed to be called directly by a user application,
1154 * @param target_ts target timestamp in the time base of the given stream
1155 * @param stream_index stream number
1157 int av_seek_frame_binary(AVFormatContext *s, int stream_index,
1158 int64_t target_ts, int flags);
1161 * Update cur_dts of all streams based on the given timestamp and AVStream.
1163 * Stream ref_st unchanged, others set cur_dts in their native time base.
1164 * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
1165 * @param timestamp new dts expressed in time_base of param ref_st
1166 * @param ref_st reference stream giving time_base of param timestamp
1168 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
1171 * Perform a binary search using read_timestamp().
1172 * This is not supposed to be called directly by a user application,
1174 * @param target_ts target timestamp in the time base of the given stream
1175 * @param stream_index stream number
1177 int64_t av_gen_search(AVFormatContext *s, int stream_index,
1178 int64_t target_ts, int64_t pos_min,
1179 int64_t pos_max, int64_t pos_limit,
1180 int64_t ts_min, int64_t ts_max,
1181 int flags, int64_t *ts_ret,
1182 int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t ));
1184 /** media file output */
1185 int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
1188 * Split a URL string into components.
1190 * The pointers to buffers for storing individual components may be null,
1191 * in order to ignore that component. Buffers for components not found are
1192 * set to empty strings. If the port is not found, it is set to a negative
1195 * @param proto the buffer for the protocol
1196 * @param proto_size the size of the proto buffer
1197 * @param authorization the buffer for the authorization
1198 * @param authorization_size the size of the authorization buffer
1199 * @param hostname the buffer for the host name
1200 * @param hostname_size the size of the hostname buffer
1201 * @param port_ptr a pointer to store the port number in
1202 * @param path the buffer for the path
1203 * @param path_size the size of the path buffer
1204 * @param url the URL to split
1206 void av_url_split(char *proto, int proto_size,
1207 char *authorization, int authorization_size,
1208 char *hostname, int hostname_size,
1210 char *path, int path_size,
1214 * Allocate the stream private data and write the stream header to an
1215 * output media file.
1217 * @param s media file handle
1218 * @return 0 if OK, AVERROR_xxx on error
1220 int av_write_header(AVFormatContext *s);
1223 * Write a packet to an output media file.
1225 * The packet shall contain one audio or video frame.
1226 * The packet must be correctly interleaved according to the container
1227 * specification, if not then av_interleaved_write_frame must be used.
1229 * @param s media file handle
1230 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1232 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
1234 int av_write_frame(AVFormatContext *s, AVPacket *pkt);
1237 * Write a packet to an output media file ensuring correct interleaving.
1239 * The packet must contain one audio or video frame.
1240 * If the packets are already correctly interleaved, the application should
1241 * call av_write_frame() instead as it is slightly faster. It is also important
1242 * to keep in mind that completely non-interleaved input will need huge amounts
1243 * of memory to interleave with this, so it is preferable to interleave at the
1246 * @param s media file handle
1247 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1249 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
1251 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
1254 * Interleave a packet per dts in an output media file.
1256 * Packets with pkt->destruct == av_destruct_packet will be freed inside this
1257 * function, so they cannot be used after it. Note that calling av_free_packet()
1258 * on them is still safe.
1260 * @param s media file handle
1261 * @param out the interleaved packet will be output here
1262 * @param pkt the input packet
1263 * @param flush 1 if no further packets are available as input and all
1264 * remaining packets should be output
1265 * @return 1 if a packet was output, 0 if no packet could be output,
1266 * < 0 if an error occurred
1268 int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out,
1269 AVPacket *pkt, int flush);
1272 * Write the stream trailer to an output media file and free the
1273 * file private data.
1275 * May only be called after a successful call to av_write_header.
1277 * @param s media file handle
1278 * @return 0 if OK, AVERROR_xxx on error
1280 int av_write_trailer(AVFormatContext *s);
1282 void dump_format(AVFormatContext *ic,
1287 #if LIBAVFORMAT_VERSION_MAJOR < 53
1289 * Parse width and height out of string str.
1290 * @deprecated Use av_parse_video_frame_size instead.
1292 attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr,
1296 * Convert framerate from a string to a fraction.
1297 * @deprecated Use av_parse_video_frame_rate instead.
1299 attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
1304 * Parse datestr and return a corresponding number of microseconds.
1305 * @param datestr String representing a date or a duration.
1306 * - If a date the syntax is:
1308 * now|{[{YYYY-MM-DD|YYYYMMDD}[T|t| ]]{{HH[:MM[:SS[.m...]]]}|{HH[MM[SS[.m...]]]}}[Z|z]}
1310 * If the value is "now" it takes the current time.
1311 * Time is local time unless Z is appended, in which case it is
1312 * interpreted as UTC.
1313 * If the year-month-day part is not specified it takes the current
1315 * @return the number of microseconds since 1st of January, 1970 up to
1316 * the time of the parsed date or INT64_MIN if datestr cannot be
1317 * successfully parsed.
1318 * - If a duration the syntax is:
1320 * [-]HH[:MM[:SS[.m...]]]
1323 * @return the number of microseconds contained in a time interval
1324 * with the specified duration or INT64_MIN if datestr cannot be
1325 * successfully parsed.
1326 * @param duration Flag which tells how to interpret datestr, if
1327 * not zero datestr is interpreted as a duration, otherwise as a
1330 int64_t parse_date(const char *datestr, int duration);
1332 /** Get the current time in microseconds. */
1333 int64_t av_gettime(void);
1335 /* ffm-specific for ffserver */
1336 #define FFM_PACKET_SIZE 4096
1337 int64_t ffm_read_write_index(int fd);
1338 int ffm_write_write_index(int fd, int64_t pos);
1339 void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size);
1342 * Attempt to find a specific tag in a URL.
1344 * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
1345 * Return 1 if found.
1347 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
1350 * Return in 'buf' the path with '%d' replaced by a number.
1352 * Also handles the '%0nd' format where 'n' is the total number
1353 * of digits and '%%'.
1355 * @param buf destination buffer
1356 * @param buf_size destination buffer size
1357 * @param path numbered sequence string
1358 * @param number frame number
1359 * @return 0 if OK, -1 on format error
1361 int av_get_frame_filename(char *buf, int buf_size,
1362 const char *path, int number);
1365 * Check whether filename actually is a numbered sequence generator.
1367 * @param filename possible numbered sequence string
1368 * @return 1 if a valid numbered sequence string, 0 otherwise
1370 int av_filename_number_test(const char *filename);
1373 * Generate an SDP for an RTP session.
1375 * @param ac array of AVFormatContexts describing the RTP streams. If the
1376 * array is composed by only one context, such context can contain
1377 * multiple AVStreams (one AVStream per RTP stream). Otherwise,
1378 * all the contexts in the array (an AVCodecContext per RTP stream)
1379 * must contain only one AVStream.
1380 * @param n_files number of AVCodecContexts contained in ac
1381 * @param buff buffer where the SDP will be stored (must be allocated by
1383 * @param size the size of the buffer
1384 * @return 0 if OK, AVERROR_xxx on error
1386 int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
1389 * Return a positive value if the given filename has one of the given
1390 * extensions, 0 otherwise.
1392 * @param extensions a comma-separated list of filename extensions
1394 int av_match_ext(const char *filename, const char *extensions);
1396 #endif /* AVFORMAT_AVFORMAT_H */