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