Place the concat protocol entry at the begin of the registered
[libav.git] / libavformat / avformat.h
CommitLineData
04d7f601
DB
1/*
2 * copyright (c) 2001 Fabrice Bellard
3 *
b78e7197
DB
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
04d7f601
DB
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
b78e7197 9 * version 2.1 of the License, or (at your option) any later version.
04d7f601 10 *
b78e7197 11 * FFmpeg is distributed in the hope that it will be useful,
04d7f601
DB
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
b78e7197 17 * License along with FFmpeg; if not, write to the Free Software
04d7f601
DB
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
98790382
SS
21#ifndef AVFORMAT_AVFORMAT_H
22#define AVFORMAT_AVFORMAT_H
de6d9b64 23
800c289a 24#define LIBAVFORMAT_VERSION_MAJOR 52
ba2c508d 25#define LIBAVFORMAT_VERSION_MINOR 77
a2403986 26#define LIBAVFORMAT_VERSION_MICRO 0
e97ac1e6 27
800c289a
MR
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)
5aa083ee 34#define LIBAVFORMAT_BUILD LIBAVFORMAT_VERSION_INT
8026c3b5 35
5aa083ee 36#define LIBAVFORMAT_IDENT "Lavf" AV_STRINGIFY(LIBAVFORMAT_VERSION)
4b1f4f23 37
c97429e2 38/**
f2e77e4b
AC
39 * I return the LIBAVFORMAT_VERSION_INT constant. You got
40 * a fucking problem with that, douchebag?
c97429e2
SS
41 */
42unsigned avformat_version(void);
43
c1736936 44/**
49bd8e4b 45 * Return the libavformat build-time configuration.
c1736936 46 */
41600690 47const char *avformat_configuration(void);
c1736936
DB
48
49/**
49bd8e4b 50 * Return the libavformat license.
c1736936 51 */
41600690 52const char *avformat_license(void);
c1736936 53
f71869a4 54#include <time.h>
67070e4f 55#include <stdio.h> /* FILE */
76a448ed 56#include "libavcodec/avcodec.h"
de6d9b64 57
de6d9b64
FB
58#include "avio.h"
59
f610a9f2
AJ
60struct AVFormatContext;
61
a6d18a0e
MN
62
63/*
ea29242c
MM
64 * Public Metadata API.
65 * The metadata API allows libavformat to export metadata tags to a client
61648423
AK
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.
ea29242c
MM
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.
ca76a119
AK
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".
89 *
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:
94 *
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.
a6d18a0e
MN
116 */
117
48a81c0f 118#define AV_METADATA_MATCH_CASE 1
a6d18a0e 119#define AV_METADATA_IGNORE_SUFFIX 2
a181981e
MN
120#define AV_METADATA_DONT_STRDUP_KEY 4
121#define AV_METADATA_DONT_STRDUP_VAL 8
56a8242f 122#define AV_METADATA_DONT_OVERWRITE 16 ///< Don't overwrite existing tags.
a6d18a0e
MN
123
124typedef struct {
125 char *key;
126 char *value;
bc1d2afb 127}AVMetadataTag;
a6d18a0e 128
e232c252 129typedef struct AVMetadata AVMetadata;
f610a9f2 130typedef struct AVMetadataConv AVMetadataConv;
a6d18a0e
MN
131
132/**
49bd8e4b 133 * Get a metadata element with matching key.
22e77e44 134 * @param prev Set to the previous matching element to find the next.
66b6c745 135 * If set to NULL the first matching element is returned.
22e77e44
DB
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.
a6d18a0e 138 */
bc1d2afb 139AVMetadataTag *
e232c252 140av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags);
a6d18a0e 141
a181981e 142#if LIBAVFORMAT_VERSION_MAJOR == 52
a6d18a0e 143/**
49bd8e4b 144 * Set the given tag in m, overwriting an existing tag.
22e77e44
DB
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
2ef6c124 148 * @deprecated Use av_metadata_set2() instead.
a6d18a0e 149 */
2ef6c124 150attribute_deprecated int av_metadata_set(AVMetadata **pm, const char *key, const char *value);
a181981e
MN
151#endif
152
153/**
49bd8e4b 154 * Set the given tag in m, overwriting an existing tag.
a181981e 155 * @param key tag key to add to m (will be av_strduped depending on flags)
160c896c
AK
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.
a181981e
MN
158 * @return >= 0 on success otherwise an error code <0
159 */
160int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
a6d18a0e 161
094d9df7 162/**
49bd8e4b 163 * Convert all the metadata sets from ctx according to the source and
ca76a119
AK
164 * destination conversion tables. If one of the tables is NULL, then
165 * tags are converted to/from ffmpeg generic tag names.
f610a9f2
AJ
166 * @param d_conv destination tags format conversion table
167 * @param s_conv source tags format conversion table
168 */
169void av_metadata_conv(struct AVFormatContext *ctx,const AVMetadataConv *d_conv,
170 const AVMetadataConv *s_conv);
171
172/**
49bd8e4b 173 * Free all the memory allocated for an AVMetadata struct.
094d9df7
AJ
174 */
175void av_metadata_free(AVMetadata **m);
176
a6d18a0e 177
de6d9b64
FB
178/* packet functions */
179
3217cb42
PI
180
181/**
49bd8e4b 182 * Allocate and read the payload of a packet and initialize its
d1b9adf2 183 * fields with default values.
3217cb42
PI
184 *
185 * @param pkt packet
4f57fa8c
DB
186 * @param size desired payload size
187 * @return >0 (read size) if OK, AVERROR_xxx otherwise
3217cb42 188 */
2692067a 189int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
3217cb42 190
de6d9b64
FB
191
192/*************************************************/
916c80e9
FB
193/* fractional numbers for exact pts handling */
194
671adb17 195/**
4f57fa8c
DB
196 * The exact value of the fractional number is: 'val + num / den'.
197 * num is assumed to be 0 <= num < den.
4c08b2bd 198 */
916c80e9 199typedef struct AVFrac {
115329f1 200 int64_t val, num, den;
52e57500 201} AVFrac;
916c80e9 202
916c80e9 203/*************************************************/
b9a281db 204/* input/output formats */
de6d9b64 205
7caf0cc6
MN
206struct AVCodecTag;
207
4f57fa8c 208/** This structure contains the data a format has to probe a file. */
b9a281db 209typedef struct AVProbeData {
5c91a675 210 const char *filename;
e5f58f81 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 */
b9a281db
FB
213} AVProbeData;
214
22e77e44 215#define AVPROBE_SCORE_MAX 100 ///< maximum score, half of that is used for file-extension-based detection
87e87886 216#define AVPROBE_PADDING_SIZE 32 ///< extra allocated bytes at the end of the probe buffer
de6d9b64
FB
217
218typedef struct AVFormatParameters {
c0df9d75 219 AVRational time_base;
de6d9b64
FB
220 int sample_rate;
221 int channels;
222 int width;
223 int height;
4606ac8d 224 enum PixelFormat pix_fmt;
4f57fa8c
DB
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
72e043dd 229 stream packet (only meaningful if
4f57fa8c
DB
230 mpeg2ts_raw is TRUE). */
231 unsigned int initial_pause:1; /**< Do not begin to play the stream
232 immediately (RTSP only). */
72e043dd 233 unsigned int prealloced_context:1;
71957315 234#if LIBAVFORMAT_VERSION_INT < (53<<16)
5b6d5596
MN
235 enum CodecID video_codec_id;
236 enum CodecID audio_codec_id;
71957315 237#endif
de6d9b64
FB
238} AVFormatParameters;
239
4f57fa8c 240//! Demuxer will use url_fopen, no opened file should be provided by the caller.
40d9c544 241#define AVFMT_NOFILE 0x0001
4f57fa8c
DB
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
245 raw picture data. */
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. */
25918212 250#define AVFMT_VARIABLE_FPS 0x0400 /**< Format allows variable fps. */
ab5a0175 251#define AVFMT_NODIMENSIONS 0x0800 /**< Format does not need width/height */
b9a281db
FB
252
253typedef struct AVOutputFormat {
de6d9b64 254 const char *name;
bde15e74
SS
255 /**
256 * Descriptive name for the format, meant to be more human-readable
819174fa 257 * than name. You should use the NULL_IF_CONFIG_SMALL() macro
bde15e74
SS
258 * to define it.
259 */
de6d9b64
FB
260 const char *long_name;
261 const char *mime_type;
4f57fa8c 262 const char *extensions; /**< comma-separated filename extensions */
22e77e44 263 /** size of private data so that it can be allocated in the wrapper */
b9a281db 264 int priv_data_size;
de6d9b64 265 /* output support */
43d414ba
PI
266 enum CodecID audio_codec; /**< default audio codec */
267 enum CodecID video_codec; /**< default video codec */
de6d9b64 268 int (*write_header)(struct AVFormatContext *);
e928649b 269 int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
de6d9b64 270 int (*write_trailer)(struct AVFormatContext *);
43d414ba 271 /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */
b9a281db 272 int flags;
4f57fa8c 273 /** Currently only used to set pixel format if not YUV420P. */
290c5fa6 274 int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
78cb7273
DB
275 int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,
276 AVPacket *in, int flush);
7caf0cc6
MN
277
278 /**
78cb7273 279 * List of supported codec_id-codec_tag pairs, ordered by "better
22e77e44 280 * choice first". The arrays are all terminated by CODEC_ID_NONE.
7caf0cc6 281 */
c1854592 282 const struct AVCodecTag * const *codec_tag;
7caf0cc6 283
11bf3847
AJ
284 enum CodecID subtitle_codec; /**< default subtitle codec */
285
719e721a 286 const AVMetadataConv *metadata_conv;
f610a9f2 287
b9a281db
FB
288 /* private fields */
289 struct AVOutputFormat *next;
290} AVOutputFormat;
de6d9b64 291
b9a281db 292typedef struct AVInputFormat {
ac3ccbc0
AC
293 /** A comma separated list of short names for the format. New names
294 * may be appended with a minor bump.
295 */
b9a281db 296 const char *name;
bde15e74
SS
297 /**
298 * Descriptive name for the format, meant to be more human-readable
819174fa 299 * than name. You should use the NULL_IF_CONFIG_SMALL() macro
bde15e74
SS
300 * to define it.
301 */
b9a281db 302 const char *long_name;
4f57fa8c 303 /** Size of private data so that it can be allocated in the wrapper. */
b9a281db 304 int priv_data_size;
65d7d68b 305 /**
22e77e44 306 * Tell if a given file has a chance of being parsed as this format.
5d81d641
DB
307 * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes
308 * big so you do not have to check for that unless you need more.
65d7d68b 309 */
b9a281db 310 int (*read_probe)(AVProbeData *);
4f57fa8c
DB
311 /** Read the format header and initialize the AVFormatContext
312 structure. Return 0 if OK. 'ap' if non-NULL contains
313 additional parameters. Only used in raw format right
b9a281db 314 now. 'av_new_stream' should be called to create new streams. */
de6d9b64
FB
315 int (*read_header)(struct AVFormatContext *,
316 AVFormatParameters *ap);
4f57fa8c 317 /** Read one packet and put it in 'pkt'. pts and flags are also
b9a281db 318 set. 'av_new_stream' can be called only if the flag
6883ebe4
RD
319 AVFMTCTX_NOHEADER is used.
320 @return 0 on success, < 0 on error.
321 When returning an error, pkt must not have been allocated
322 or must be freed before returning */
de6d9b64 323 int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
4f57fa8c 324 /** Close the stream. The AVFormatContext and AVStreams are not
de6d9b64
FB
325 freed by this function */
326 int (*read_close)(struct AVFormatContext *);
1de2db8f
MN
327
328#if LIBAVFORMAT_VERSION_MAJOR < 53
115329f1 329 /**
4f57fa8c
DB
330 * Seek to a given timestamp relative to the frames in
331 * stream component stream_index.
22e77e44
DB
332 * @param stream_index Must not be -1.
333 * @param flags Selects which direction should be preferred if no exact
334 * match is available.
05ce0f11 335 * @return >= 0 on success (but not necessarily the new offset)
3ba1438d 336 */
115329f1 337 int (*read_seek)(struct AVFormatContext *,
3ba1438d 338 int stream_index, int64_t timestamp, int flags);
1de2db8f 339#endif
8d14a25c 340 /**
4f57fa8c 341 * Gets the next timestamp in stream[stream_index].time_base units.
d9526386 342 * @return the timestamp or AV_NOPTS_VALUE if an error occurred
8d14a25c
MN
343 */
344 int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
345 int64_t *pos, int64_t pos_limit);
4f57fa8c 346 /** Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER. */
de6d9b64 347 int flags;
4f57fa8c 348 /** If extensions are defined, then no probe is done. You should
b9a281db
FB
349 usually not use extension format guessing because it is not
350 reliable enough */
351 const char *extensions;
4f57fa8c 352 /** General purpose read-only value that the format can use. */
b9a281db 353 int value;
fb2758c8 354
49bd8e4b 355 /** Start/resume playing - only meaningful if using a network-based format
4f57fa8c 356 (RTSP). */
fb2758c8
FB
357 int (*read_play)(struct AVFormatContext *);
358
49bd8e4b 359 /** Pause playing - only meaningful if using a network-based format
4f57fa8c 360 (RTSP). */
fb2758c8
FB
361 int (*read_pause)(struct AVFormatContext *);
362
c1854592 363 const struct AVCodecTag * const *codec_tag;
7caf0cc6 364
1de2db8f 365 /**
49bd8e4b 366 * Seek to timestamp ts.
1de2db8f
MN
367 * Seeking will be done so that the point from which all active streams
368 * can be presented successfully will be closest to ts and within min/max_ts.
369 * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
370 */
882fb0a3 371 int (*read_seek2)(struct AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
1de2db8f 372
719e721a 373 const AVMetadataConv *metadata_conv;
f610a9f2 374
b9a281db
FB
375 /* private fields */
376 struct AVInputFormat *next;
377} AVInputFormat;
de6d9b64 378
57004ff1
AJ
379enum AVStreamParseType {
380 AVSTREAM_PARSE_NONE,
381 AVSTREAM_PARSE_FULL, /**< full parsing and repack */
4f57fa8c 382 AVSTREAM_PARSE_HEADERS, /**< Only parse headers, do not repack. */
78cb7273 383 AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */
74a6df59 384 AVSTREAM_PARSE_FULL_ONCE, /**< full parsing and repack of the first frame only, only implemented for H.264 currently */
57004ff1
AJ
385};
386
fb2758c8
FB
387typedef struct AVIndexEntry {
388 int64_t pos;
389 int64_t timestamp;
390#define AVINDEX_KEYFRAME 0x0001
30a43f2d 391 int flags:2;
4f57fa8c
DB
392 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).
393 int min_distance; /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */
fb2758c8
FB
394} AVIndexEntry;
395
90c2295b
ES
396#define AV_DISPOSITION_DEFAULT 0x0001
397#define AV_DISPOSITION_DUB 0x0002
398#define AV_DISPOSITION_ORIGINAL 0x0004
399#define AV_DISPOSITION_COMMENT 0x0008
400#define AV_DISPOSITION_LYRICS 0x0010
401#define AV_DISPOSITION_KARAOKE 0x0020
7a617a86
AJ
402/** Track should be used during playback by default.
403 Useful for subtitle track that should be displayed
404 even when user did not explicitly ask for subtitles. */
405#define AV_DISPOSITION_FORCED 0x0040
90c2295b 406
ba66ae94
MN
407/**
408 * Stream structure.
409 * New fields can be added to the end with minor version bumps.
8bfb108b 410 * Removal, reordering and changes to existing fields require a major
ba66ae94 411 * version bump.
8bfb108b 412 * sizeof(AVStream) must not be used outside libav*.
ba66ae94 413 */
de6d9b64 414typedef struct AVStream {
43d414ba 415 int index; /**< stream index in AVFormatContext */
4f57fa8c 416 int id; /**< format-specific stream ID */
43d414ba 417 AVCodecContext *codec; /**< codec context */
b4b87d48 418 /**
22e77e44
DB
419 * Real base framerate of the stream.
420 * This is the lowest framerate with which all timestamps can be
864ff8c1 421 * represented accurately (it is the least common multiple of all
22e77e44
DB
422 * framerates in the stream). Note, this value is just a guess!
423 * For example, if the time base is 1/90000 and all frames have either
4f57fa8c 424 * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
b4b87d48
MN
425 */
426 AVRational r_frame_rate;
de6d9b64 427 void *priv_data;
82583548 428
b9a281db 429 /* internal data used in av_find_stream_info() */
82583548 430 int64_t first_dts;
4f57fa8c 431 /** encoding: pts generation when outputting stream */
a9fd2b19 432 struct AVFrac pts;
5b28c8c3
MN
433
434 /**
8bfb108b
DB
435 * This is the fundamental unit of time (in seconds) in terms
436 * of which frame timestamps are represented. For fixed-fps content,
22e77e44 437 * time base should be 1/framerate and timestamp increments should be 1.
5b28c8c3 438 */
9ee91c2f 439 AVRational time_base;
43d414ba 440 int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
a48b7a6b 441 /* ffmpeg.c private use */
4f57fa8c
DB
442 int stream_copy; /**< If set, just copy stream. */
443 enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
b4aea108 444 //FIXME move stuff to a flags field?
4f57fa8c 445 /** Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
755bfeab 446 * MN: dunno if that is the right place for it */
115329f1 447 float quality;
6d96a9b9 448 /**
8bfb108b
DB
449 * Decoding: pts of the first frame of the stream, in stream time base.
450 * Only set this if you are absolutely 100% sure that the value you set
451 * it to really is the pts of the first frame.
4854c253 452 * This may be undefined (AV_NOPTS_VALUE).
8bfb108b
DB
453 * @note The ASF header does NOT contain a correct start_time the ASF
454 * demuxer must NOT set this.
6d96a9b9 455 */
115329f1 456 int64_t start_time;
e26381b6 457 /**
8bfb108b 458 * Decoding: duration of the stream, in stream time base.
e26381b6 459 * If a source file does not specify a duration, but does specify
4f57fa8c 460 * a bitrate, this value will be estimated from bitrate and file size.
e26381b6 461 */
ee404803 462 int64_t duration;
fb2758c8 463
827f7e28 464#if LIBAVFORMAT_VERSION_INT < (53<<16)
7e030c47 465 char language[4]; /** ISO 639-2/B 3-letter language code (empty string if undefined) */
827f7e28 466#endif
09730260 467
fb2758c8 468 /* av_read_frame() support */
57004ff1 469 enum AVStreamParseType need_parsing;
fb2758c8 470 struct AVCodecParserContext *parser;
6ec87caa 471
fb2758c8 472 int64_t cur_dts;
635fbcb1
MN
473 int last_IP_duration;
474 int64_t last_IP_pts;
fb2758c8 475 /* av_seek_frame() support */
4f57fa8c
DB
476 AVIndexEntry *index_entries; /**< Only used if the format does not
477 support seeking natively. */
fb2758c8 478 int nb_index_entries;
191e8ca7 479 unsigned int index_entries_allocated_size;
115329f1 480
b4b87d48 481 int64_t nb_frames; ///< number of frames in this stream if known or 0
504ee036 482
0d84a8f6
BC
483#if LIBAVFORMAT_VERSION_INT < (53<<16)
484 int64_t unused[4+1];
f8d7c9d3
ES
485
486 char *filename; /**< source filename of the stream */
827f7e28 487#endif
90c2295b 488
4f57fa8c 489 int disposition; /**< AV_DISPOSITION_* bit field */
0bef08e5
MN
490
491 AVProbeData probe_data;
0d84a8f6
BC
492#define MAX_REORDER_DELAY 16
493 int64_t pts_buffer[MAX_REORDER_DELAY+1];
c30a4489
AJ
494
495 /**
496 * sample aspect ratio (0 if unknown)
497 * - encoding: Set by user.
498 * - decoding: Set by libavformat.
499 */
500 AVRational sample_aspect_ratio;
f526adaf 501
e232c252 502 AVMetadata *metadata;
3a41c2f7 503
31769dad
VP
504 /* Intended mostly for av_read_frame() support. Not supposed to be used by */
505 /* external applications; try to use something else if at all possible. */
3a41c2f7
MN
506 const uint8_t *cur_ptr;
507 int cur_len;
508 AVPacket cur_pkt;
27ca0a79
IS
509
510 // Timestamp generation support:
511 /**
512 * Timestamp corresponding to the last dts sync point.
513 *
514 * Initialized when AVCodecParserContext.dts_sync_point >= 0 and
515 * a DTS is received from the underlying container. Otherwise set to
516 * AV_NOPTS_VALUE by default.
517 */
518 int64_t reference_dts;
86cb7e33
BC
519
520 /**
521 * Number of packets to buffer for codec probing
522 * NOT PART OF PUBLIC API
523 */
48616887 524#define MAX_PROBE_PACKETS 2500
86cb7e33 525 int probe_packets;
ddce56ef
MN
526
527 /**
e07b882b 528 * last packet in packet_buffer for this stream when muxing.
ddce56ef
MN
529 * used internally, NOT PART OF PUBLIC API, dont read or write from outside of libav*
530 */
e07b882b 531 struct AVPacketList *last_in_packet_buffer;
02b398ef
MN
532
533 /**
534 * Average framerate
535 */
536 AVRational avg_frame_rate;
6c6e6ef5
MN
537
538 /**
539 * Number of frames that have been demuxed during av_find_stream_info()
540 */
541 int codec_info_nb_frames;
de6d9b64
FB
542} AVStream;
543
15afa396
NS
544#define AV_PROGRAM_RUNNING 1
545
ba66ae94 546/**
ba66ae94 547 * New fields can be added to the end with minor version bumps.
8bfb108b 548 * Removal, reordering and changes to existing fields require a major
ba66ae94 549 * version bump.
8bfb108b 550 * sizeof(AVProgram) must not be used outside libav*.
ba66ae94 551 */
15afa396
NS
552typedef struct AVProgram {
553 int id;
827f7e28 554#if LIBAVFORMAT_VERSION_INT < (53<<16)
4f57fa8c
DB
555 char *provider_name; ///< network name for DVB streams
556 char *name; ///< service name for DVB streams
827f7e28 557#endif
15afa396
NS
558 int flags;
559 enum AVDiscard discard; ///< selects which program to discard and which to feed to the caller
526efa10
NS
560 unsigned int *stream_index;
561 unsigned int nb_stream_indexes;
e232c252 562 AVMetadata *metadata;
15afa396
NS
563} AVProgram;
564
43d414ba 565#define AVFMTCTX_NOHEADER 0x0001 /**< signal that no header is present
da24c5e3
FB
566 (streams are added dynamically) */
567
79d7836a 568typedef struct AVChapter {
4f57fa8c
DB
569 int id; ///< unique ID to identify the chapter
570 AVRational time_base; ///< time base in which the start/end timestamps are specified
8931e7b4 571 int64_t start, end; ///< chapter start/end time in time_base units
827f7e28 572#if LIBAVFORMAT_VERSION_INT < (53<<16)
c2fb6be4 573 char *title; ///< chapter title
827f7e28 574#endif
e232c252 575 AVMetadata *metadata;
79d7836a
AK
576} AVChapter;
577
ad5cc780 578#if LIBAVFORMAT_VERSION_MAJOR < 53
de6d9b64 579#define MAX_STREAMS 20
ad5cc780 580#endif
de6d9b64 581
252f17e2 582/**
4f57fa8c 583 * Format I/O context.
252f17e2 584 * New fields can be added to the end with minor version bumps.
8bfb108b 585 * Removal, reordering and changes to existing fields require a major
252f17e2 586 * version bump.
8bfb108b 587 * sizeof(AVFormatContext) must not be used outside libav*.
252f17e2 588 */
de6d9b64 589typedef struct AVFormatContext {
1447aac4 590 const AVClass *av_class; /**< Set by avformat_alloc_context. */
4f57fa8c 591 /* Can only be iformat or oformat, not both at the same time. */
b9a281db
FB
592 struct AVInputFormat *iformat;
593 struct AVOutputFormat *oformat;
de6d9b64 594 void *priv_data;
899681cd 595 ByteIOContext *pb;
db69c2e5 596 unsigned int nb_streams;
de6d9b64 597 AVStream *streams[MAX_STREAMS];
43d414ba 598 char filename[1024]; /**< input or output filename */
de6d9b64 599 /* stream info */
4568325a 600 int64_t timestamp;
827f7e28 601#if LIBAVFORMAT_VERSION_INT < (53<<16)
de6d9b64
FB
602 char title[512];
603 char author[512];
604 char copyright[512];
605 char comment[512];
6a58e151 606 char album[512];
43d414ba
PI
607 int year; /**< ID3 year, 0 if none */
608 int track; /**< track number, 0 if none */
609 char genre[32]; /**< ID3 genre */
827f7e28 610#endif
6a58e151 611
4f57fa8c
DB
612 int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
613 /* private data for pts handling (do not modify directly). */
43d414ba 614 /** This buffer is only needed when packets were already buffered but
4f57fa8c
DB
615 not decoded, for example to get the codec parameters in MPEG
616 streams. */
ee404803
FB
617 struct AVPacketList *packet_buffer;
618
4f57fa8c 619 /** Decoding: position of the first frame of the component, in
ee404803 620 AV_TIME_BASE fractional seconds. NEVER set this value directly:
4f57fa8c 621 It is deduced from the AVStream values. */
115329f1 622 int64_t start_time;
4f57fa8c 623 /** Decoding: duration of the stream, in AV_TIME_BASE fractional
37f57ab4
MN
624 seconds. Only set this value if you know none of the individual stream
625 durations and also dont set any of them. This is deduced from the
626 AVStream values if not set. */
ee404803 627 int64_t duration;
4f57fa8c 628 /** decoding: total file size, 0 if unknown */
ee404803 629 int64_t file_size;
4f57fa8c 630 /** Decoding: total stream bitrate in bit/s, 0 if not
ee404803 631 available. Never set it directly if the file_size and the
22e77e44 632 duration are known as FFmpeg can compute it automatically. */
ee404803 633 int bit_rate;
fb2758c8
FB
634
635 /* av_read_frame() support */
636 AVStream *cur_st;
3a41c2f7
MN
637#if LIBAVFORMAT_VERSION_INT < (53<<16)
638 const uint8_t *cur_ptr_deprecated;
639 int cur_len_deprecated;
640 AVPacket cur_pkt_deprecated;
641#endif
fb2758c8 642
fb2758c8 643 /* av_seek_frame() support */
43d414ba 644 int64_t data_offset; /** offset of the first packet */
fb2758c8 645 int index_built;
115329f1 646
2db3c638 647 int mux_rate;
92400be2 648 unsigned int packet_size;
17c88cb0
MN
649 int preload;
650 int max_delay;
8108551a 651
115329f1
DB
652#define AVFMT_NOOUTPUTLOOP -1
653#define AVFMT_INFINITEOUTPUTLOOP 0
43d414ba 654 /** number of times to loop output in formats that support it */
8108551a 655 int loop_output;
115329f1 656
30bc6613 657 int flags;
22e77e44 658#define AVFMT_FLAG_GENPTS 0x0001 ///< Generate missing pts even if it requires parsing future frames.
4f57fa8c
DB
659#define AVFMT_FLAG_IGNIDX 0x0002 ///< Ignore index.
660#define AVFMT_FLAG_NONBLOCK 0x0004 ///< Do not block when reading packets from input.
c55806e3 661#define AVFMT_FLAG_IGNDTS 0x0008 ///< Ignore DTS on frames that contain both DTS & PTS
fe8344a2
MN
662#define AVFMT_FLAG_NOFILLIN 0x0010 ///< Do not infer any values from other values, just return what is stored in the container
663#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
796ac233 664#define AVFMT_FLAG_RTP_HINT 0x0040 ///< Add RTP hinting to the output file
5894e1bb
VP
665
666 int loop_input;
22e77e44 667 /** decoding: size of data to probe; encoding: unused. */
9e6c9470 668 unsigned int probesize;
a44b3c4d
MN
669
670 /**
4f57fa8c
DB
671 * Maximum time (in AV_TIME_BASE units) during which the input should
672 * be analyzed in av_find_stream_info().
a44b3c4d
MN
673 */
674 int max_analyze_duration;
c964c2c7
RD
675
676 const uint8_t *key;
677 int keylen;
15afa396
NS
678
679 unsigned int nb_programs;
680 AVProgram **programs;
62600469
MN
681
682 /**
683 * Forced video codec_id.
4f57fa8c 684 * Demuxing: Set by user.
62600469
MN
685 */
686 enum CodecID video_codec_id;
687 /**
688 * Forced audio codec_id.
4f57fa8c 689 * Demuxing: Set by user.
62600469
MN
690 */
691 enum CodecID audio_codec_id;
692 /**
693 * Forced subtitle codec_id.
4f57fa8c 694 * Demuxing: Set by user.
62600469
MN
695 */
696 enum CodecID subtitle_codec_id;
3dea63bd
PK
697
698 /**
22e77e44
DB
699 * Maximum amount of memory in bytes to use for the index of each stream.
700 * If the index exceeds this size, entries will be discarded as
3dea63bd
PK
701 * needed to maintain a smaller size. This can lead to slower or less
702 * accurate seeking (depends on demuxer).
4f57fa8c 703 * Demuxers for which a full in-memory index is mandatory will ignore
3dea63bd
PK
704 * this.
705 * muxing : unused
706 * demuxing: set by user
707 */
708 unsigned int max_index_size;
ab8ab30c
RP
709
710 /**
ffa71b2b 711 * Maximum amount of memory in bytes to use for buffering frames
4f57fa8c 712 * obtained from realtime capture devices.
ab8ab30c
RP
713 */
714 unsigned int max_picture_buffer;
79d7836a 715
fbabf1e9 716 unsigned int nb_chapters;
79d7836a 717 AVChapter **chapters;
45b2b05f
MN
718
719 /**
4f57fa8c 720 * Flags to enable debugging.
45b2b05f
MN
721 */
722 int debug;
723#define FF_FDEBUG_TS 0x0001
0bef08e5
MN
724
725 /**
4f57fa8c 726 * Raw packets from the demuxer, prior to parsing and decoding.
0bef08e5
MN
727 * This buffer is used for buffering packets until the codec can
728 * be identified, as parsing cannot be done without knowing the
729 * codec.
730 */
731 struct AVPacketList *raw_packet_buffer;
5c5b1731
MR
732 struct AVPacketList *raw_packet_buffer_end;
733
734 struct AVPacketList *packet_buffer_end;
47146dfb 735
e232c252 736 AVMetadata *metadata;
af122d6a
BC
737
738 /**
739 * Remaining size available for raw_packet_buffer, in bytes.
740 * NOT PART OF PUBLIC API
741 */
48616887 742#define RAW_PACKET_BUFFER_SIZE 2500000
af122d6a 743 int raw_packet_buffer_remaining_size;
b8819c85
MS
744
745 /**
746 * Start time of the stream in real world time, in microseconds
747 * since the unix epoch (00:00 1st January 1970). That is, pts=0
748 * in the stream was captured at this real world time.
749 * - encoding: Set by user.
750 * - decoding: Unused.
751 */
752 int64_t start_time_realtime;
de6d9b64
FB
753} AVFormatContext;
754
755typedef struct AVPacketList {
756 AVPacket pkt;
757 struct AVPacketList *next;
758} AVPacketList;
759
84be6e72 760#if LIBAVFORMAT_VERSION_INT < (53<<16)
b9a281db
FB
761extern AVInputFormat *first_iformat;
762extern AVOutputFormat *first_oformat;
84be6e72
MN
763#endif
764
aeedac95
SS
765/**
766 * If f is NULL, returns the first registered input format,
22e77e44 767 * if f is non-NULL, returns the next registered input format after f
aeedac95
SS
768 * or NULL if f is the last one.
769 */
84be6e72 770AVInputFormat *av_iformat_next(AVInputFormat *f);
aeedac95
SS
771
772/**
773 * If f is NULL, returns the first registered output format,
22e77e44 774 * if f is non-NULL, returns the next registered output format after f
aeedac95
SS
775 * or NULL if f is the last one.
776 */
84be6e72 777AVOutputFormat *av_oformat_next(AVOutputFormat *f);
de6d9b64 778
5b6d5596 779enum CodecID av_guess_image2_codec(const char *filename);
290c5fa6 780
22e77e44
DB
781/* XXX: Use automatic init with either ELF sections or C file parser */
782/* modules. */
de6d9b64 783
b9a281db 784/* utils.c */
b9a281db
FB
785void av_register_input_format(AVInputFormat *format);
786void av_register_output_format(AVOutputFormat *format);
1642ee43
SS
787#if LIBAVFORMAT_VERSION_MAJOR < 53
788attribute_deprecated AVOutputFormat *guess_stream_format(const char *short_name,
78cb7273
DB
789 const char *filename,
790 const char *mime_type);
a1f547b9
SS
791
792/**
793 * @deprecated Use av_guess_format() instead.
794 */
795attribute_deprecated AVOutputFormat *guess_format(const char *short_name,
796 const char *filename,
797 const char *mime_type);
1642ee43 798#endif
f48b0fa2
SS
799
800/**
49bd8e4b
MR
801 * Return the output format in the list of registered output formats
802 * which best matches the provided parameters, or return NULL if
f48b0fa2
SS
803 * there is no match.
804 *
805 * @param short_name if non-NULL checks if short_name matches with the
806 * names of the registered formats
807 * @param filename if non-NULL checks if filename terminates with the
808 * extensions of the registered formats
809 * @param mime_type if non-NULL checks if mime_type matches with the
810 * MIME type of the registered formats
811 */
a1f547b9 812AVOutputFormat *av_guess_format(const char *short_name,
94b1f338
SS
813 const char *filename,
814 const char *mime_type);
3217cb42
PI
815
816/**
49bd8e4b 817 * Guess the codec ID based upon muxer and filename.
3217cb42 818 */
115329f1 819enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
78cb7273 820 const char *filename, const char *mime_type,
72415b2a 821 enum AVMediaType type);
de6d9b64 822
3217cb42 823/**
49bd8e4b 824 * Send a nice hexadecimal dump of a buffer to the specified file stream.
750f0e1f
PI
825 *
826 * @param f The file stream pointer where the dump should be sent to.
3217cb42
PI
827 * @param buf buffer
828 * @param size buffer size
750f0e1f
PI
829 *
830 * @see av_hex_dump_log, av_pkt_dump, av_pkt_dump_log
3217cb42 831 */
fb2758c8 832void av_hex_dump(FILE *f, uint8_t *buf, int size);
3217cb42
PI
833
834/**
49bd8e4b 835 * Send a nice hexadecimal dump of a buffer to the log.
750f0e1f
PI
836 *
837 * @param avcl A pointer to an arbitrary struct of which the first field is a
838 * pointer to an AVClass struct.
839 * @param level The importance level of the message, lower values signifying
840 * higher importance.
841 * @param buf buffer
842 * @param size buffer size
843 *
844 * @see av_hex_dump, av_pkt_dump, av_pkt_dump_log
845 */
846void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
847
848/**
49bd8e4b 849 * Send a nice dump of a packet to the specified file stream.
750f0e1f
PI
850 *
851 * @param f The file stream pointer where the dump should be sent to.
3217cb42 852 * @param pkt packet to dump
4f57fa8c 853 * @param dump_payload True if the payload must be displayed, too.
3217cb42 854 */
fb2758c8 855void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
de6d9b64 856
750f0e1f 857/**
49bd8e4b 858 * Send a nice dump of a packet to the log.
750f0e1f
PI
859 *
860 * @param avcl A pointer to an arbitrary struct of which the first field is a
861 * pointer to an AVClass struct.
862 * @param level The importance level of the message, lower values signifying
863 * higher importance.
864 * @param pkt packet to dump
4f57fa8c 865 * @param dump_payload True if the payload must be displayed, too.
750f0e1f
PI
866 */
867void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
868
4815e246 869/**
49bd8e4b 870 * Initialize libavformat and register all the muxers, demuxers and
4815e246
SS
871 * protocols. If you do not call this function, then you can select
872 * exactly which formats you want to support.
873 *
874 * @see av_register_input_format()
875 * @see av_register_output_format()
5d377501 876 * @see av_register_protocol()
4815e246 877 */
94988531 878void av_register_all(void);
de6d9b64 879
7693b93e 880/**
49bd8e4b 881 * Get the CodecID for the given codec tag tag.
7693b93e
SS
882 * If no codec id is found returns CODEC_ID_NONE.
883 *
884 * @param tags list of supported codec_id-codec_tag pairs, as stored
885 * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
886 */
15545a09 887enum CodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
7693b93e
SS
888
889/**
49bd8e4b 890 * Get the codec tag for the given codec id id.
7693b93e
SS
891 * If no codec tag is found returns 0.
892 *
893 * @param tags list of supported codec_id-codec_tag pairs, as stored
894 * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
895 */
15545a09 896unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum CodecID id);
7caf0cc6 897
b9a281db 898/* media file input */
3217cb42
PI
899
900/**
49bd8e4b 901 * Find AVInputFormat based on the short name of the input format.
3217cb42 902 */
b9a281db 903AVInputFormat *av_find_input_format(const char *short_name);
3217cb42
PI
904
905/**
49bd8e4b 906 * Guess the file format.
3217cb42 907 *
4f57fa8c
DB
908 * @param is_opened Whether the file is already opened; determines whether
909 * demuxers with or without AVFMT_NOFILE are probed.
3217cb42 910 */
94988531 911AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
3217cb42
PI
912
913/**
49bd8e4b 914 * Guess the file format.
8e2ee182
RD
915 *
916 * @param is_opened Whether the file is already opened; determines whether
917 * demuxers with or without AVFMT_NOFILE are probed.
c99d506b
RD
918 * @param score_max A probe score larger that this is required to accept a
919 * detection, the variable is set to the actual detection
920 * score afterwards.
921 * If the score is <= AVPROBE_SCORE_MAX / 4 it is recommended
8e2ee182
RD
922 * to retry with a larger probe buffer.
923 */
924AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max);
925
926/**
49bd8e4b 927 * Allocate all the structures needed to read an input stream.
3217cb42
PI
928 * This does not open the needed codecs for decoding the stream[s].
929 */
115329f1
DB
930int av_open_input_stream(AVFormatContext **ic_ptr,
931 ByteIOContext *pb, const char *filename,
da24c5e3 932 AVInputFormat *fmt, AVFormatParameters *ap);
3217cb42
PI
933
934/**
49bd8e4b 935 * Open a media file as input. The codecs are not opened. Only the file
3217cb42
PI
936 * header (if present) is read.
937 *
4f57fa8c
DB
938 * @param ic_ptr The opened media file handle is put here.
939 * @param filename filename to open
940 * @param fmt If non-NULL, force the file format to use.
3217cb42 941 * @param buf_size optional buffer size (zero if default is OK)
78cb7273
DB
942 * @param ap Additional parameters needed when opening the file
943 * (NULL if default).
4f57fa8c 944 * @return 0 if OK, AVERROR_xxx otherwise
3217cb42 945 */
115329f1 946int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
b9a281db
FB
947 AVInputFormat *fmt,
948 int buf_size,
949 AVFormatParameters *ap);
88a28965
SS
950
951#if LIBAVFORMAT_VERSION_MAJOR < 53
952/**
953 * @deprecated Use avformat_alloc_context() instead.
954 */
955attribute_deprecated AVFormatContext *av_alloc_format_context(void);
956#endif
957
88808c60 958/**
49bd8e4b 959 * Allocate an AVFormatContext.
5d81d641 960 * Can be freed with av_free() but do not forget to free everything you
88808c60
MN
961 * explicitly allocated as well!
962 */
88a28965 963AVFormatContext *avformat_alloc_context(void);
b9a281db 964
3217cb42 965/**
49bd8e4b 966 * Read packets of a media file to get stream information. This
3217cb42 967 * is useful for file formats with no headers such as MPEG. This
22e77e44 968 * function also computes the real framerate in case of MPEG-2 repeat
3217cb42
PI
969 * frame mode.
970 * The logical file position is not changed by this function;
971 * examined packets may be buffered for later processing.
972 *
973 * @param ic media file handle
4f57fa8c
DB
974 * @return >=0 if OK, AVERROR_xxx on error
975 * @todo Let the user decide somehow what information is needed so that
976 * we do not waste time getting stuff the user does not need.
3217cb42 977 */
b9a281db 978int av_find_stream_info(AVFormatContext *ic);
3217cb42
PI
979
980/**
49bd8e4b 981 * Read a transport packet from a media file.
3217cb42 982 *
864ff8c1 983 * This function is obsolete and should never be used.
3217cb42
PI
984 * Use av_read_frame() instead.
985 *
986 * @param s media file handle
987 * @param pkt is filled
4f57fa8c 988 * @return 0 if OK, AVERROR_xxx on error
3217cb42 989 */
de6d9b64 990int av_read_packet(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
991
992/**
49bd8e4b 993 * Return the next frame of a stream.
3217cb42
PI
994 *
995 * The returned packet is valid
996 * until the next av_read_frame() or until av_close_input_file() and
997 * must be freed with av_free_packet. For video, the packet contains
998 * exactly one frame. For audio, it contains an integer number of
999 * frames if each frame has a known fixed size (e.g. PCM or ADPCM
1000 * data). If the audio frames have a variable size (e.g. MPEG audio),
1001 * then it contains one frame.
1002 *
1003 * pkt->pts, pkt->dts and pkt->duration are always set to correct
22e77e44 1004 * values in AVStream.time_base units (and guessed if the format cannot
4f57fa8c
DB
1005 * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
1006 * has B-frames, so it is better to rely on pkt->dts if you do not
3217cb42
PI
1007 * decompress the payload.
1008 *
4f57fa8c 1009 * @return 0 if OK, < 0 on error or end of file
3217cb42 1010 */
fb2758c8 1011int av_read_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
1012
1013/**
49bd8e4b 1014 * Seek to the keyframe at timestamp.
3217cb42
PI
1015 * 'timestamp' in 'stream_index'.
1016 * @param stream_index If stream_index is (-1), a default
1017 * stream is selected, and timestamp is automatically converted
1018 * from AV_TIME_BASE units to the stream specific time_base.
4f57fa8c
DB
1019 * @param timestamp Timestamp in AVStream.time_base units
1020 * or, if no stream is specified, in AV_TIME_BASE units.
3217cb42
PI
1021 * @param flags flags which select direction and seeking mode
1022 * @return >= 0 on success
1023 */
78cb7273
DB
1024int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
1025 int flags);
3217cb42
PI
1026
1027/**
49bd8e4b 1028 * Seek to timestamp ts.
d04768fa
MN
1029 * Seeking will be done so that the point from which all active streams
1030 * can be presented successfully will be closest to ts and within min/max_ts.
1031 * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
1032 *
22e77e44 1033 * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and
d04768fa 1034 * are the file position (this may not be supported by all demuxers).
22e77e44 1035 * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames
d04768fa 1036 * in the stream with stream_index (this may not be supported by all demuxers).
22e77e44
DB
1037 * Otherwise all timestamps are in units of the stream selected by stream_index
1038 * or if stream_index is -1, in AV_TIME_BASE units.
1039 * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
d04768fa
MN
1040 * keyframes (this may not be supported by all demuxers).
1041 *
22e77e44 1042 * @param stream_index index of the stream which is used as time base reference
d04768fa
MN
1043 * @param min_ts smallest acceptable timestamp
1044 * @param ts target timestamp
1045 * @param max_ts largest acceptable timestamp
1046 * @param flags flags
32e543f8 1047 * @return >=0 on success, error code otherwise
998b6f7c 1048 *
8a4d7a30 1049 * @note This is part of the new seek API which is still under construction.
22e77e44
DB
1050 * Thus do not use this yet. It may change at any time, do not expect
1051 * ABI compatibility yet!
d04768fa
MN
1052 */
1053int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
1054
1055/**
49bd8e4b 1056 * Start playing a network-based stream (e.g. RTSP stream) at the
4f57fa8c 1057 * current position.
3217cb42 1058 */
fb2758c8 1059int av_read_play(AVFormatContext *s);
3217cb42
PI
1060
1061/**
49bd8e4b 1062 * Pause a network-based stream (e.g. RTSP stream).
3217cb42
PI
1063 *
1064 * Use av_read_play() to resume it.
1065 */
fb2758c8 1066int av_read_pause(AVFormatContext *s);
3217cb42
PI
1067
1068/**
49bd8e4b 1069 * Free a AVFormatContext allocated by av_open_input_stream.
2506fd54
RD
1070 * @param s context to free
1071 */
1072void av_close_input_stream(AVFormatContext *s);
1073
1074/**
49bd8e4b 1075 * Close a media file (but not its codecs).
3217cb42
PI
1076 *
1077 * @param s media file handle
1078 */
de6d9b64 1079void av_close_input_file(AVFormatContext *s);
3217cb42
PI
1080
1081/**
49bd8e4b 1082 * Add a new stream to a media file.
3217cb42
PI
1083 *
1084 * Can only be called in the read_header() function. If the flag
1085 * AVFMTCTX_NOHEADER is in the format context, then new streams
1086 * can be added in read_packet too.
1087 *
1088 * @param s media file handle
4f57fa8c 1089 * @param id file-format-dependent stream ID
3217cb42 1090 */
b9a281db 1091AVStream *av_new_stream(AVFormatContext *s, int id);
15afa396 1092AVProgram *av_new_program(AVFormatContext *s, int id);
3217cb42
PI
1093
1094/**
49bd8e4b 1095 * Add a new chapter.
79d7836a 1096 * This function is NOT part of the public API
4f57fa8c 1097 * and should ONLY be used by demuxers.
79d7836a
AK
1098 *
1099 * @param s media file handle
4f57fa8c 1100 * @param id unique ID for this chapter
abd2256d
MN
1101 * @param start chapter start time in time_base units
1102 * @param end chapter end time in time_base units
79d7836a 1103 * @param title chapter title
5c37f43a 1104 *
4f57fa8c 1105 * @return AVChapter or NULL on error
79d7836a 1106 */
78cb7273
DB
1107AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base,
1108 int64_t start, int64_t end, const char *title);
79d7836a
AK
1109
1110/**
49bd8e4b 1111 * Set the pts for a given stream.
3217cb42
PI
1112 *
1113 * @param s stream
1114 * @param pts_wrap_bits number of bits effectively used by the pts
1115 * (used for wrap control, 33 is the value for MPEG)
1116 * @param pts_num numerator to convert to seconds (MPEG: 1)
1117 * @param pts_den denominator to convert to seconds (MPEG: 90000)
1118 */
9ee91c2f 1119void av_set_pts_info(AVStream *s, int pts_wrap_bits,
dec14949 1120 unsigned int pts_num, unsigned int pts_den);
de6d9b64 1121
3ba1438d
MN
1122#define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
1123#define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes
4f57fa8c 1124#define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non-keyframes
2bf74f49 1125#define AVSEEK_FLAG_FRAME 8 ///< seeking based on frame number
3ba1438d 1126
b754978a 1127int av_find_default_stream_index(AVFormatContext *s);
3217cb42
PI
1128
1129/**
49bd8e4b 1130 * Get the index for a specific timestamp.
4f57fa8c
DB
1131 * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
1132 * to the timestamp which is <= the requested one, if backward
1133 * is 0, then it will be >=
3217cb42
PI
1134 * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
1135 * @return < 0 if no such timestamp could be found
1136 */
dc56fc38 1137int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
3217cb42
PI
1138
1139/**
49bd8e4b 1140 * Ensure the index uses less memory than the maximum specified in
22e77e44 1141 * AVFormatContext.max_index_size by discarding entries if it grows
3dea63bd
PK
1142 * too large.
1143 * This function is not part of the public API and should only be called
1144 * by demuxers.
1145 */
1146void ff_reduce_index(AVFormatContext *s, int stream_index);
1147
1148/**
49bd8e4b 1149 * Add an index entry into a sorted list. Update the entry if the list
4f57fa8c 1150 * already contains it.
3217cb42 1151 *
4f57fa8c 1152 * @param timestamp timestamp in the time base of the given stream
3217cb42 1153 */
78cb7273
DB
1154int av_add_index_entry(AVStream *st, int64_t pos, int64_t timestamp,
1155 int size, int distance, int flags);
3217cb42
PI
1156
1157/**
49bd8e4b 1158 * Perform a binary search using av_index_search_timestamp() and
3673f4ab 1159 * AVInputFormat.read_timestamp().
78cb7273
DB
1160 * This is not supposed to be called directly by a user application,
1161 * but by demuxers.
3217cb42
PI
1162 * @param target_ts target timestamp in the time base of the given stream
1163 * @param stream_index stream number
1164 */
78cb7273
DB
1165int av_seek_frame_binary(AVFormatContext *s, int stream_index,
1166 int64_t target_ts, int flags);
3217cb42
PI
1167
1168/**
49bd8e4b 1169 * Update cur_dts of all streams based on the given timestamp and AVStream.
3217cb42 1170 *
4f57fa8c
DB
1171 * Stream ref_st unchanged, others set cur_dts in their native time base.
1172 * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
3217cb42
PI
1173 * @param timestamp new dts expressed in time_base of param ref_st
1174 * @param ref_st reference stream giving time_base of param timestamp
1175 */
22ffac70 1176void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
3217cb42
PI
1177
1178/**
49bd8e4b 1179 * Perform a binary search using read_timestamp().
78cb7273
DB
1180 * This is not supposed to be called directly by a user application,
1181 * but by demuxers.
3217cb42
PI
1182 * @param target_ts target timestamp in the time base of the given stream
1183 * @param stream_index stream number
1184 */
78cb7273
DB
1185int64_t av_gen_search(AVFormatContext *s, int stream_index,
1186 int64_t target_ts, int64_t pos_min,
1187 int64_t pos_max, int64_t pos_limit,
1188 int64_t ts_min, int64_t ts_max,
1189 int flags, int64_t *ts_ret,
1190 int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t ));
b754978a 1191
43d414ba 1192/** media file output */
290c5fa6 1193int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
3217cb42
PI
1194
1195/**
f3bfe388
MR
1196 * Split a URL string into components.
1197 *
1198 * The pointers to buffers for storing individual components may be null,
1199 * in order to ignore that component. Buffers for components not found are
1200 * set to empty strings. If the port is not found, it is set to a negative
1201 * value.
1202 *
1203 * @param proto the buffer for the protocol
1204 * @param proto_size the size of the proto buffer
1205 * @param authorization the buffer for the authorization
1206 * @param authorization_size the size of the authorization buffer
1207 * @param hostname the buffer for the host name
1208 * @param hostname_size the size of the hostname buffer
1209 * @param port_ptr a pointer to store the port number in
1210 * @param path the buffer for the path
1211 * @param path_size the size of the path buffer
1212 * @param url the URL to split
1213 */
1214void av_url_split(char *proto, int proto_size,
1215 char *authorization, int authorization_size,
1216 char *hostname, int hostname_size,
1217 int *port_ptr,
1218 char *path, int path_size,
1219 const char *url);
1220
1221/**
49bd8e4b 1222 * Allocate the stream private data and write the stream header to an
755bfeab 1223 * output media file.
3217cb42
PI
1224 *
1225 * @param s media file handle
4f57fa8c 1226 * @return 0 if OK, AVERROR_xxx on error
3217cb42 1227 */
b9a281db 1228int av_write_header(AVFormatContext *s);
3217cb42
PI
1229
1230/**
49bd8e4b 1231 * Write a packet to an output media file.
3217cb42
PI
1232 *
1233 * The packet shall contain one audio or video frame.
78cb7273
DB
1234 * The packet must be correctly interleaved according to the container
1235 * specification, if not then av_interleaved_write_frame must be used.
3217cb42
PI
1236 *
1237 * @param s media file handle
78cb7273
DB
1238 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1239 dts/pts, ...
4f57fa8c 1240 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
3217cb42 1241 */
e928649b 1242int av_write_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
1243
1244/**
49bd8e4b 1245 * Write a packet to an output media file ensuring correct interleaving.
3217cb42
PI
1246 *
1247 * The packet must contain one audio or video frame.
22e77e44 1248 * If the packets are already correctly interleaved, the application should
90b5b51e
DB
1249 * call av_write_frame() instead as it is slightly faster. It is also important
1250 * to keep in mind that completely non-interleaved input will need huge amounts
1251 * of memory to interleave with this, so it is preferable to interleave at the
1252 * demuxer level.
3217cb42
PI
1253 *
1254 * @param s media file handle
78cb7273
DB
1255 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1256 dts/pts, ...
4f57fa8c 1257 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
3217cb42 1258 */
3c895fc0 1259int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
1260
1261/**
49bd8e4b 1262 * Interleave a packet per dts in an output media file.
3217cb42 1263 *
78cb7273 1264 * Packets with pkt->destruct == av_destruct_packet will be freed inside this
22e77e44 1265 * function, so they cannot be used after it. Note that calling av_free_packet()
78cb7273 1266 * on them is still safe.
3217cb42
PI
1267 *
1268 * @param s media file handle
1269 * @param out the interleaved packet will be output here
9a58234f 1270 * @param pkt the input packet
3217cb42
PI
1271 * @param flush 1 if no further packets are available as input and all
1272 * remaining packets should be output
1273 * @return 1 if a packet was output, 0 if no packet could be output,
d9526386 1274 * < 0 if an error occurred
3217cb42 1275 */
78cb7273
DB
1276int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out,
1277 AVPacket *pkt, int flush);
e928649b 1278
3217cb42 1279/**
49bd8e4b 1280 * Write the stream trailer to an output media file and free the
2b75bde6 1281 * file private data.
3217cb42 1282 *
dc76fe13
RD
1283 * May only be called after a successful call to av_write_header.
1284 *
3217cb42 1285 * @param s media file handle
4f57fa8c 1286 * @return 0 if OK, AVERROR_xxx on error
3217cb42 1287 */
b9a281db 1288int av_write_trailer(AVFormatContext *s);
de6d9b64
FB
1289
1290void dump_format(AVFormatContext *ic,
115329f1 1291 int index,
de6d9b64
FB
1292 const char *url,
1293 int is_output);
3217cb42 1294
1ca9133f 1295#if LIBAVFORMAT_VERSION_MAJOR < 53
3217cb42 1296/**
49bd8e4b 1297 * Parse width and height out of string str.
26ef3220 1298 * @deprecated Use av_parse_video_frame_size instead.
3217cb42 1299 */
78cb7273
DB
1300attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr,
1301 const char *str);
3217cb42
PI
1302
1303/**
49bd8e4b 1304 * Convert framerate from a string to a fraction.
26ef3220 1305 * @deprecated Use av_parse_video_frame_rate instead.
3217cb42 1306 */
78cb7273
DB
1307attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
1308 const char *arg);
1ca9133f 1309#endif
3217cb42
PI
1310
1311/**
49bd8e4b 1312 * Parse datestr and return a corresponding number of microseconds.
f9436161
SS
1313 * @param datestr String representing a date or a duration.
1314 * - If a date the syntax is:
3217cb42 1315 * @code
fcd10c4f 1316 * now|{[{YYYY-MM-DD|YYYYMMDD}[T|t| ]]{{HH[:MM[:SS[.m...]]]}|{HH[MM[SS[.m...]]]}}[Z|z]}
3217cb42 1317 * @endcode
fcd10c4f 1318 * If the value is "now" it takes the current time.
4f57fa8c 1319 * Time is local time unless Z is appended, in which case it is
f9436161 1320 * interpreted as UTC.
4f57fa8c 1321 * If the year-month-day part is not specified it takes the current
f9436161 1322 * year-month-day.
49bd8e4b 1323 * @return the number of microseconds since 1st of January, 1970 up to
819174fa 1324 * the time of the parsed date or INT64_MIN if datestr cannot be
f9436161
SS
1325 * successfully parsed.
1326 * - If a duration the syntax is:
1327 * @code
1328 * [-]HH[:MM[:SS[.m...]]]
1329 * [-]S+[.m...]
1330 * @endcode
49bd8e4b 1331 * @return the number of microseconds contained in a time interval
819174fa 1332 * with the specified duration or INT64_MIN if datestr cannot be
7338d368 1333 * successfully parsed.
819174fa
SS
1334 * @param duration Flag which tells how to interpret datestr, if
1335 * not zero datestr is interpreted as a duration, otherwise as a
f9436161 1336 * date.
3217cb42 1337 */
0c1a9eda 1338int64_t parse_date(const char *datestr, int duration);
de6d9b64 1339
49bd8e4b 1340/** Get the current time in microseconds. */
0c1a9eda 1341int64_t av_gettime(void);
94988531 1342
4f57fa8c 1343/* ffm-specific for ffserver */
de6d9b64 1344#define FFM_PACKET_SIZE 4096
bc5c918e 1345int64_t ffm_read_write_index(int fd);
6fcce4f9 1346int ffm_write_write_index(int fd, int64_t pos);
bc5c918e 1347void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size);
de6d9b64 1348
3217cb42 1349/**
49bd8e4b 1350 * Attempt to find a specific tag in a URL.
3217cb42
PI
1351 *
1352 * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
1353 * Return 1 if found.
1354 */
de6d9b64
FB
1355int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
1356
3217cb42 1357/**
49bd8e4b 1358 * Return in 'buf' the path with '%d' replaced by a number.
4f57fa8c 1359 *
3217cb42
PI
1360 * Also handles the '%0nd' format where 'n' is the total number
1361 * of digits and '%%'.
1362 *
1363 * @param buf destination buffer
1364 * @param buf_size destination buffer size
1365 * @param path numbered sequence string
8ea0e802 1366 * @param number frame number
4f57fa8c 1367 * @return 0 if OK, -1 on format error
3217cb42 1368 */
5c07cf53
MB
1369int av_get_frame_filename(char *buf, int buf_size,
1370 const char *path, int number);
3217cb42
PI
1371
1372/**
49bd8e4b 1373 * Check whether filename actually is a numbered sequence generator.
3217cb42
PI
1374 *
1375 * @param filename possible numbered sequence string
4f57fa8c 1376 * @return 1 if a valid numbered sequence string, 0 otherwise
3217cb42 1377 */
5c07cf53 1378int av_filename_number_test(const char *filename);
96baaa6a 1379
c5388c07 1380/**
49bd8e4b 1381 * Generate an SDP for an RTP session.
c5388c07
LA
1382 *
1383 * @param ac array of AVFormatContexts describing the RTP streams. If the
1384 * array is composed by only one context, such context can contain
1385 * multiple AVStreams (one AVStream per RTP stream). Otherwise,
1386 * all the contexts in the array (an AVCodecContext per RTP stream)
4f57fa8c 1387 * must contain only one AVStream.
8767b80f
LA
1388 * @param n_files number of AVCodecContexts contained in ac
1389 * @param buff buffer where the SDP will be stored (must be allocated by
4f57fa8c 1390 * the caller)
8767b80f 1391 * @param size the size of the buffer
4f57fa8c 1392 * @return 0 if OK, AVERROR_xxx on error
c5388c07 1393 */
8767b80f 1394int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
c5388c07 1395
1a70d127 1396/**
49bd8e4b 1397 * Return a positive value if the given filename has one of the given
1a70d127
SS
1398 * extensions, 0 otherwise.
1399 *
1400 * @param extensions a comma-separated list of filename extensions
1401 */
1402int av_match_ext(const char *filename, const char *extensions);
1403
98790382 1404#endif /* AVFORMAT_AVFORMAT_H */