Document av_probe_input_format2 API addition.
[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
43d414ba 871/** codec tag <-> codec id */
15545a09
SS
872enum CodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
873unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum CodecID id);
7caf0cc6 874
b9a281db 875/* media file input */
3217cb42
PI
876
877/**
4f57fa8c 878 * Finds AVInputFormat based on the short name of the input format.
3217cb42 879 */
b9a281db 880AVInputFormat *av_find_input_format(const char *short_name);
3217cb42
PI
881
882/**
d1b9adf2 883 * Guesses the file format.
3217cb42 884 *
4f57fa8c
DB
885 * @param is_opened Whether the file is already opened; determines whether
886 * demuxers with or without AVFMT_NOFILE are probed.
3217cb42 887 */
94988531 888AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
3217cb42
PI
889
890/**
8e2ee182
RD
891 * Guesses the file format.
892 *
893 * @param is_opened Whether the file is already opened; determines whether
894 * demuxers with or without AVFMT_NOFILE are probed.
895 * @param score_max minimum score required to accept a detection, set to actual
896 * detection score afterwards.
897 * If the score is < AVPROBE_SCORE_MAX / 4 it is recommended
898 * to retry with a larger probe buffer.
899 */
900AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max);
901
902/**
3217cb42
PI
903 * Allocates all the structures needed to read an input stream.
904 * This does not open the needed codecs for decoding the stream[s].
905 */
115329f1
DB
906int av_open_input_stream(AVFormatContext **ic_ptr,
907 ByteIOContext *pb, const char *filename,
da24c5e3 908 AVInputFormat *fmt, AVFormatParameters *ap);
3217cb42
PI
909
910/**
d1b9adf2 911 * Opens a media file as input. The codecs are not opened. Only the file
3217cb42
PI
912 * header (if present) is read.
913 *
4f57fa8c
DB
914 * @param ic_ptr The opened media file handle is put here.
915 * @param filename filename to open
916 * @param fmt If non-NULL, force the file format to use.
3217cb42 917 * @param buf_size optional buffer size (zero if default is OK)
78cb7273
DB
918 * @param ap Additional parameters needed when opening the file
919 * (NULL if default).
4f57fa8c 920 * @return 0 if OK, AVERROR_xxx otherwise
3217cb42 921 */
115329f1 922int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
b9a281db
FB
923 AVInputFormat *fmt,
924 int buf_size,
925 AVFormatParameters *ap);
88a28965
SS
926
927#if LIBAVFORMAT_VERSION_MAJOR < 53
928/**
929 * @deprecated Use avformat_alloc_context() instead.
930 */
931attribute_deprecated AVFormatContext *av_alloc_format_context(void);
932#endif
933
88808c60 934/**
d1b9adf2 935 * Allocates an AVFormatContext.
5d81d641 936 * Can be freed with av_free() but do not forget to free everything you
88808c60
MN
937 * explicitly allocated as well!
938 */
88a28965 939AVFormatContext *avformat_alloc_context(void);
b9a281db 940
3217cb42 941/**
d1b9adf2 942 * Reads packets of a media file to get stream information. This
3217cb42 943 * is useful for file formats with no headers such as MPEG. This
22e77e44 944 * function also computes the real framerate in case of MPEG-2 repeat
3217cb42
PI
945 * frame mode.
946 * The logical file position is not changed by this function;
947 * examined packets may be buffered for later processing.
948 *
949 * @param ic media file handle
4f57fa8c
DB
950 * @return >=0 if OK, AVERROR_xxx on error
951 * @todo Let the user decide somehow what information is needed so that
952 * we do not waste time getting stuff the user does not need.
3217cb42 953 */
b9a281db 954int av_find_stream_info(AVFormatContext *ic);
3217cb42
PI
955
956/**
d1b9adf2 957 * Reads a transport packet from a media file.
3217cb42 958 *
864ff8c1 959 * This function is obsolete and should never be used.
3217cb42
PI
960 * Use av_read_frame() instead.
961 *
962 * @param s media file handle
963 * @param pkt is filled
4f57fa8c 964 * @return 0 if OK, AVERROR_xxx on error
3217cb42 965 */
de6d9b64 966int av_read_packet(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
967
968/**
d1b9adf2 969 * Returns the next frame of a stream.
3217cb42
PI
970 *
971 * The returned packet is valid
972 * until the next av_read_frame() or until av_close_input_file() and
973 * must be freed with av_free_packet. For video, the packet contains
974 * exactly one frame. For audio, it contains an integer number of
975 * frames if each frame has a known fixed size (e.g. PCM or ADPCM
976 * data). If the audio frames have a variable size (e.g. MPEG audio),
977 * then it contains one frame.
978 *
979 * pkt->pts, pkt->dts and pkt->duration are always set to correct
22e77e44 980 * values in AVStream.time_base units (and guessed if the format cannot
4f57fa8c
DB
981 * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
982 * has B-frames, so it is better to rely on pkt->dts if you do not
3217cb42
PI
983 * decompress the payload.
984 *
4f57fa8c 985 * @return 0 if OK, < 0 on error or end of file
3217cb42 986 */
fb2758c8 987int av_read_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
988
989/**
d1b9adf2 990 * Seeks to the keyframe at timestamp.
3217cb42
PI
991 * 'timestamp' in 'stream_index'.
992 * @param stream_index If stream_index is (-1), a default
993 * stream is selected, and timestamp is automatically converted
994 * from AV_TIME_BASE units to the stream specific time_base.
4f57fa8c
DB
995 * @param timestamp Timestamp in AVStream.time_base units
996 * or, if no stream is specified, in AV_TIME_BASE units.
3217cb42
PI
997 * @param flags flags which select direction and seeking mode
998 * @return >= 0 on success
999 */
78cb7273
DB
1000int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
1001 int flags);
3217cb42
PI
1002
1003/**
d1b9adf2 1004 * Seeks to timestamp ts.
d04768fa
MN
1005 * Seeking will be done so that the point from which all active streams
1006 * can be presented successfully will be closest to ts and within min/max_ts.
1007 * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
1008 *
22e77e44 1009 * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and
d04768fa 1010 * are the file position (this may not be supported by all demuxers).
22e77e44 1011 * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames
d04768fa 1012 * in the stream with stream_index (this may not be supported by all demuxers).
22e77e44
DB
1013 * Otherwise all timestamps are in units of the stream selected by stream_index
1014 * or if stream_index is -1, in AV_TIME_BASE units.
1015 * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
d04768fa
MN
1016 * keyframes (this may not be supported by all demuxers).
1017 *
22e77e44 1018 * @param stream_index index of the stream which is used as time base reference
d04768fa
MN
1019 * @param min_ts smallest acceptable timestamp
1020 * @param ts target timestamp
1021 * @param max_ts largest acceptable timestamp
1022 * @param flags flags
32e543f8 1023 * @return >=0 on success, error code otherwise
998b6f7c 1024 *
22e77e44
DB
1025 * @NOTE This is part of the new seek API which is still under construction.
1026 * Thus do not use this yet. It may change at any time, do not expect
1027 * ABI compatibility yet!
d04768fa
MN
1028 */
1029int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
1030
1031/**
d1b9adf2 1032 * Starts playing a network-based stream (e.g. RTSP stream) at the
4f57fa8c 1033 * current position.
3217cb42 1034 */
fb2758c8 1035int av_read_play(AVFormatContext *s);
3217cb42
PI
1036
1037/**
d1b9adf2 1038 * Pauses a network-based stream (e.g. RTSP stream).
3217cb42
PI
1039 *
1040 * Use av_read_play() to resume it.
1041 */
fb2758c8 1042int av_read_pause(AVFormatContext *s);
3217cb42
PI
1043
1044/**
d1b9adf2 1045 * Frees a AVFormatContext allocated by av_open_input_stream.
2506fd54
RD
1046 * @param s context to free
1047 */
1048void av_close_input_stream(AVFormatContext *s);
1049
1050/**
d1b9adf2 1051 * Closes a media file (but not its codecs).
3217cb42
PI
1052 *
1053 * @param s media file handle
1054 */
de6d9b64 1055void av_close_input_file(AVFormatContext *s);
3217cb42
PI
1056
1057/**
d1b9adf2 1058 * Adds a new stream to a media file.
3217cb42
PI
1059 *
1060 * Can only be called in the read_header() function. If the flag
1061 * AVFMTCTX_NOHEADER is in the format context, then new streams
1062 * can be added in read_packet too.
1063 *
1064 * @param s media file handle
4f57fa8c 1065 * @param id file-format-dependent stream ID
3217cb42 1066 */
b9a281db 1067AVStream *av_new_stream(AVFormatContext *s, int id);
15afa396 1068AVProgram *av_new_program(AVFormatContext *s, int id);
3217cb42
PI
1069
1070/**
d1b9adf2 1071 * Adds a new chapter.
79d7836a 1072 * This function is NOT part of the public API
4f57fa8c 1073 * and should ONLY be used by demuxers.
79d7836a
AK
1074 *
1075 * @param s media file handle
4f57fa8c 1076 * @param id unique ID for this chapter
abd2256d
MN
1077 * @param start chapter start time in time_base units
1078 * @param end chapter end time in time_base units
79d7836a 1079 * @param title chapter title
5c37f43a 1080 *
4f57fa8c 1081 * @return AVChapter or NULL on error
79d7836a 1082 */
78cb7273
DB
1083AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base,
1084 int64_t start, int64_t end, const char *title);
79d7836a
AK
1085
1086/**
d1b9adf2 1087 * Sets the pts for a given stream.
3217cb42
PI
1088 *
1089 * @param s stream
1090 * @param pts_wrap_bits number of bits effectively used by the pts
1091 * (used for wrap control, 33 is the value for MPEG)
1092 * @param pts_num numerator to convert to seconds (MPEG: 1)
1093 * @param pts_den denominator to convert to seconds (MPEG: 90000)
1094 */
9ee91c2f 1095void av_set_pts_info(AVStream *s, int pts_wrap_bits,
dec14949 1096 unsigned int pts_num, unsigned int pts_den);
de6d9b64 1097
3ba1438d
MN
1098#define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
1099#define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes
4f57fa8c 1100#define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non-keyframes
2bf74f49 1101#define AVSEEK_FLAG_FRAME 8 ///< seeking based on frame number
3ba1438d 1102
b754978a 1103int av_find_default_stream_index(AVFormatContext *s);
3217cb42
PI
1104
1105/**
1106 * Gets the index for a specific timestamp.
4f57fa8c
DB
1107 * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
1108 * to the timestamp which is <= the requested one, if backward
1109 * is 0, then it will be >=
3217cb42
PI
1110 * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
1111 * @return < 0 if no such timestamp could be found
1112 */
dc56fc38 1113int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
3217cb42
PI
1114
1115/**
3dea63bd 1116 * Ensures the index uses less memory than the maximum specified in
22e77e44 1117 * AVFormatContext.max_index_size by discarding entries if it grows
3dea63bd
PK
1118 * too large.
1119 * This function is not part of the public API and should only be called
1120 * by demuxers.
1121 */
1122void ff_reduce_index(AVFormatContext *s, int stream_index);
1123
1124/**
d1b9adf2 1125 * Adds an index entry into a sorted list. Updates the entry if the list
4f57fa8c 1126 * already contains it.
3217cb42 1127 *
4f57fa8c 1128 * @param timestamp timestamp in the time base of the given stream
3217cb42 1129 */
78cb7273
DB
1130int av_add_index_entry(AVStream *st, int64_t pos, int64_t timestamp,
1131 int size, int distance, int flags);
3217cb42
PI
1132
1133/**
78cb7273
DB
1134 * Does a binary search using av_index_search_timestamp() and
1135 * AVCodec.read_timestamp().
1136 * This is not supposed to be called directly by a user application,
1137 * but by demuxers.
3217cb42
PI
1138 * @param target_ts target timestamp in the time base of the given stream
1139 * @param stream_index stream number
1140 */
78cb7273
DB
1141int av_seek_frame_binary(AVFormatContext *s, int stream_index,
1142 int64_t target_ts, int flags);
3217cb42
PI
1143
1144/**
4f57fa8c 1145 * Updates cur_dts of all streams based on the given timestamp and AVStream.
3217cb42 1146 *
4f57fa8c
DB
1147 * Stream ref_st unchanged, others set cur_dts in their native time base.
1148 * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
3217cb42
PI
1149 * @param timestamp new dts expressed in time_base of param ref_st
1150 * @param ref_st reference stream giving time_base of param timestamp
1151 */
22ffac70 1152void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
3217cb42
PI
1153
1154/**
1155 * Does a binary search using read_timestamp().
78cb7273
DB
1156 * This is not supposed to be called directly by a user application,
1157 * but by demuxers.
3217cb42
PI
1158 * @param target_ts target timestamp in the time base of the given stream
1159 * @param stream_index stream number
1160 */
78cb7273
DB
1161int64_t av_gen_search(AVFormatContext *s, int stream_index,
1162 int64_t target_ts, int64_t pos_min,
1163 int64_t pos_max, int64_t pos_limit,
1164 int64_t ts_min, int64_t ts_max,
1165 int flags, int64_t *ts_ret,
1166 int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t ));
b754978a 1167
43d414ba 1168/** media file output */
290c5fa6 1169int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
3217cb42
PI
1170
1171/**
d1b9adf2 1172 * Allocates the stream private data and writes the stream header to an
755bfeab 1173 * output media file.
3217cb42
PI
1174 *
1175 * @param s media file handle
4f57fa8c 1176 * @return 0 if OK, AVERROR_xxx on error
3217cb42 1177 */
b9a281db 1178int av_write_header(AVFormatContext *s);
3217cb42
PI
1179
1180/**
d1b9adf2 1181 * Writes a packet to an output media file.
3217cb42
PI
1182 *
1183 * The packet shall contain one audio or video frame.
78cb7273
DB
1184 * The packet must be correctly interleaved according to the container
1185 * specification, if not then av_interleaved_write_frame must be used.
3217cb42
PI
1186 *
1187 * @param s media file handle
78cb7273
DB
1188 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1189 dts/pts, ...
4f57fa8c 1190 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
3217cb42 1191 */
e928649b 1192int av_write_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
1193
1194/**
1195 * Writes a packet to an output media file ensuring correct interleaving.
1196 *
1197 * The packet must contain one audio or video frame.
22e77e44 1198 * If the packets are already correctly interleaved, the application should
90b5b51e
DB
1199 * call av_write_frame() instead as it is slightly faster. It is also important
1200 * to keep in mind that completely non-interleaved input will need huge amounts
1201 * of memory to interleave with this, so it is preferable to interleave at the
1202 * demuxer level.
3217cb42
PI
1203 *
1204 * @param s media file handle
78cb7273
DB
1205 * @param pkt The packet, which contains the stream_index, buf/buf_size,
1206 dts/pts, ...
4f57fa8c 1207 * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
3217cb42 1208 */
3c895fc0 1209int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
3217cb42
PI
1210
1211/**
d1b9adf2 1212 * Interleaves a packet per dts in an output media file.
3217cb42 1213 *
78cb7273 1214 * Packets with pkt->destruct == av_destruct_packet will be freed inside this
22e77e44 1215 * function, so they cannot be used after it. Note that calling av_free_packet()
78cb7273 1216 * on them is still safe.
3217cb42
PI
1217 *
1218 * @param s media file handle
1219 * @param out the interleaved packet will be output here
1220 * @param in the input packet
1221 * @param flush 1 if no further packets are available as input and all
1222 * remaining packets should be output
1223 * @return 1 if a packet was output, 0 if no packet could be output,
d9526386 1224 * < 0 if an error occurred
3217cb42 1225 */
78cb7273
DB
1226int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out,
1227 AVPacket *pkt, int flush);
e928649b 1228
3217cb42 1229/**
2b75bde6
SS
1230 * Writes the stream trailer to an output media file and frees the
1231 * file private data.
3217cb42 1232 *
dc76fe13
RD
1233 * May only be called after a successful call to av_write_header.
1234 *
3217cb42 1235 * @param s media file handle
4f57fa8c 1236 * @return 0 if OK, AVERROR_xxx on error
3217cb42 1237 */
b9a281db 1238int av_write_trailer(AVFormatContext *s);
de6d9b64
FB
1239
1240void dump_format(AVFormatContext *ic,
115329f1 1241 int index,
de6d9b64
FB
1242 const char *url,
1243 int is_output);
3217cb42 1244
1ca9133f 1245#if LIBAVFORMAT_VERSION_MAJOR < 53
3217cb42 1246/**
4f57fa8c 1247 * Parses width and height out of string str.
26ef3220 1248 * @deprecated Use av_parse_video_frame_size instead.
3217cb42 1249 */
78cb7273
DB
1250attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr,
1251 const char *str);
3217cb42
PI
1252
1253/**
22e77e44 1254 * Converts framerate from a string to a fraction.
26ef3220 1255 * @deprecated Use av_parse_video_frame_rate instead.
3217cb42 1256 */
78cb7273
DB
1257attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
1258 const char *arg);
1ca9133f 1259#endif
3217cb42
PI
1260
1261/**
819174fa 1262 * Parses datestr and returns a corresponding number of microseconds.
f9436161
SS
1263 * @param datestr String representing a date or a duration.
1264 * - If a date the syntax is:
3217cb42 1265 * @code
3217cb42 1266 * [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}
3217cb42 1267 * @endcode
4f57fa8c 1268 * Time is local time unless Z is appended, in which case it is
f9436161 1269 * interpreted as UTC.
4f57fa8c 1270 * If the year-month-day part is not specified it takes the current
f9436161
SS
1271 * year-month-day.
1272 * Returns the number of microseconds since 1st of January, 1970 up to
819174fa 1273 * the time of the parsed date or INT64_MIN if datestr cannot be
f9436161
SS
1274 * successfully parsed.
1275 * - If a duration the syntax is:
1276 * @code
1277 * [-]HH[:MM[:SS[.m...]]]
1278 * [-]S+[.m...]
1279 * @endcode
1280 * Returns the number of microseconds contained in a time interval
819174fa 1281 * with the specified duration or INT64_MIN if datestr cannot be
7338d368 1282 * successfully parsed.
819174fa
SS
1283 * @param duration Flag which tells how to interpret datestr, if
1284 * not zero datestr is interpreted as a duration, otherwise as a
f9436161 1285 * date.
3217cb42 1286 */
0c1a9eda 1287int64_t parse_date(const char *datestr, int duration);
de6d9b64 1288
fff5e687 1289/** Gets the current time in microseconds. */
0c1a9eda 1290int64_t av_gettime(void);
94988531 1291
4f57fa8c 1292/* ffm-specific for ffserver */
de6d9b64 1293#define FFM_PACKET_SIZE 4096
bc5c918e 1294int64_t ffm_read_write_index(int fd);
6fcce4f9 1295int ffm_write_write_index(int fd, int64_t pos);
bc5c918e 1296void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size);
de6d9b64 1297
3217cb42
PI
1298/**
1299 * Attempts to find a specific tag in a URL.
1300 *
1301 * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
1302 * Return 1 if found.
1303 */
de6d9b64
FB
1304int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
1305
3217cb42 1306/**
22e77e44 1307 * Returns in 'buf' the path with '%d' replaced by a number.
4f57fa8c 1308 *
3217cb42
PI
1309 * Also handles the '%0nd' format where 'n' is the total number
1310 * of digits and '%%'.
1311 *
1312 * @param buf destination buffer
1313 * @param buf_size destination buffer size
1314 * @param path numbered sequence string
8ea0e802 1315 * @param number frame number
4f57fa8c 1316 * @return 0 if OK, -1 on format error
3217cb42 1317 */
5c07cf53
MB
1318int av_get_frame_filename(char *buf, int buf_size,
1319 const char *path, int number);
3217cb42
PI
1320
1321/**
d1b9adf2 1322 * Checks whether filename actually is a numbered sequence generator.
3217cb42
PI
1323 *
1324 * @param filename possible numbered sequence string
4f57fa8c 1325 * @return 1 if a valid numbered sequence string, 0 otherwise
3217cb42 1326 */
5c07cf53 1327int av_filename_number_test(const char *filename);
96baaa6a 1328
c5388c07 1329/**
d1b9adf2 1330 * Generates an SDP for an RTP session.
c5388c07
LA
1331 *
1332 * @param ac array of AVFormatContexts describing the RTP streams. If the
1333 * array is composed by only one context, such context can contain
1334 * multiple AVStreams (one AVStream per RTP stream). Otherwise,
1335 * all the contexts in the array (an AVCodecContext per RTP stream)
4f57fa8c 1336 * must contain only one AVStream.
8767b80f
LA
1337 * @param n_files number of AVCodecContexts contained in ac
1338 * @param buff buffer where the SDP will be stored (must be allocated by
4f57fa8c 1339 * the caller)
8767b80f 1340 * @param size the size of the buffer
4f57fa8c 1341 * @return 0 if OK, AVERROR_xxx on error
c5388c07 1342 */
8767b80f 1343int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
c5388c07 1344
1a70d127
SS
1345/**
1346 * Returns a positive value if the given filename has one of the given
1347 * extensions, 0 otherwise.
1348 *
1349 * @param extensions a comma-separated list of filename extensions
1350 */
1351int av_match_ext(const char *filename, const char *extensions);
1352
98790382 1353#endif /* AVFORMAT_AVFORMAT_H */