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