avformat.h 54.9 KB
Newer Older
1 2 3
/*
 * copyright (c) 2001 Fabrice Bellard
 *
4 5 6
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
7 8
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
9
 * version 2.1 of the License, or (at your option) any later version.
10
 *
11
 * FFmpeg is distributed in the hope that it will be useful,
12 13 14 15 16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
17
 * License along with FFmpeg; if not, write to the Free Software
18 19 20
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

21 22
#ifndef AVFORMAT_AVFORMAT_H
#define AVFORMAT_AVFORMAT_H
Fabrice Bellard's avatar
Fabrice Bellard committed
23

24
#define LIBAVFORMAT_VERSION_MAJOR 52
Anssi Hannula's avatar
Anssi Hannula committed
25
#define LIBAVFORMAT_VERSION_MINOR 86
26
#define LIBAVFORMAT_VERSION_MICRO  1
27

28 29 30 31 32 33
#define LIBAVFORMAT_VERSION_INT AV_VERSION_INT(LIBAVFORMAT_VERSION_MAJOR, \
                                               LIBAVFORMAT_VERSION_MINOR, \
                                               LIBAVFORMAT_VERSION_MICRO)
#define LIBAVFORMAT_VERSION     AV_VERSION(LIBAVFORMAT_VERSION_MAJOR,   \
                                           LIBAVFORMAT_VERSION_MINOR,   \
                                           LIBAVFORMAT_VERSION_MICRO)
Michael Niedermayer's avatar
Michael Niedermayer committed
34
#define LIBAVFORMAT_BUILD       LIBAVFORMAT_VERSION_INT
35

Michael Niedermayer's avatar
Michael Niedermayer committed
36
#define LIBAVFORMAT_IDENT       "Lavf" AV_STRINGIFY(LIBAVFORMAT_VERSION)
37

38 39 40 41
/**
 * Those FF_API_* defines are not part of public API.
 * They may change, break or disappear at any time.
 */
42
#ifndef FF_API_MAX_STREAMS
Aurelien Jacobs's avatar
Aurelien Jacobs committed
43
#define FF_API_MAX_STREAMS             (LIBAVFORMAT_VERSION_MAJOR < 53)
44
#endif
45
#ifndef FF_API_OLD_METADATA
Aurelien Jacobs's avatar
Aurelien Jacobs committed
46
#define FF_API_OLD_METADATA            (LIBAVFORMAT_VERSION_MAJOR < 53)
47
#endif
48
#ifndef FF_API_URL_CLASS
Aurelien Jacobs's avatar
Aurelien Jacobs committed
49
#define FF_API_URL_CLASS               (LIBAVFORMAT_VERSION_MAJOR >= 53)
50
#endif
51
#ifndef FF_API_URL_RESETBUF
Aurelien Jacobs's avatar
Aurelien Jacobs committed
52
#define FF_API_URL_RESETBUF            (LIBAVFORMAT_VERSION_MAJOR < 53)
53
#endif
54
#ifndef FF_API_REGISTER_PROTOCOL
Aurelien Jacobs's avatar
Aurelien Jacobs committed
55
#define FF_API_REGISTER_PROTOCOL       (LIBAVFORMAT_VERSION_MAJOR < 53)
56
#endif
57
#ifndef FF_API_GUESS_FORMAT
Aurelien Jacobs's avatar
Aurelien Jacobs committed
58
#define FF_API_GUESS_FORMAT            (LIBAVFORMAT_VERSION_MAJOR < 53)
59
#endif
60
#ifndef FF_API_UDP_GET_FILE
Aurelien Jacobs's avatar
Aurelien Jacobs committed
61
#define FF_API_UDP_GET_FILE            (LIBAVFORMAT_VERSION_MAJOR < 53)
62
#endif
63
#ifndef FF_API_URL_SPLIT
Aurelien Jacobs's avatar
Aurelien Jacobs committed
64
#define FF_API_URL_SPLIT               (LIBAVFORMAT_VERSION_MAJOR < 53)
65
#endif
66 67 68
#ifndef FF_API_ALLOC_FORMAT_CONTEXT
#define FF_API_ALLOC_FORMAT_CONTEXT    (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
69 70 71
#ifndef FF_API_PARSE_FRAME_PARAM
#define FF_API_PARSE_FRAME_PARAM       (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
72 73 74
#ifndef FF_API_READ_SEEK
#define FF_API_READ_SEEK               (LIBAVFORMAT_VERSION_MAJOR < 54)
#endif
75 76 77
#ifndef FF_API_LAVF_UNUSED
#define FF_API_LAVF_UNUSED             (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
78 79 80
#ifndef FF_API_PARAMETERS_CODEC_ID
#define FF_API_PARAMETERS_CODEC_ID     (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
81 82 83
#ifndef FF_API_FIRST_FORMAT
#define FF_API_FIRST_FORMAT            (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
84 85 86
#ifndef FF_API_SYMVER
#define FF_API_SYMVER                  (LIBAVFORMAT_VERSION_MAJOR < 53)
#endif
87

88
/**
Art Clarke's avatar
Art Clarke committed
89 90
 * I return the LIBAVFORMAT_VERSION_INT constant.  You got
 * a fucking problem with that, douchebag?
91 92 93
 */
unsigned avformat_version(void);

94
/**
95
 * Return the libavformat build-time configuration.
96
 */
97
const char *avformat_configuration(void);
98 99

/**
100
 * Return the libavformat license.
101
 */
102
const char *avformat_license(void);
103

104
#include <time.h>
Zdenek Kabelac's avatar
Zdenek Kabelac committed
105
#include <stdio.h>  /* FILE */
106
#include "libavcodec/avcodec.h"
Fabrice Bellard's avatar
Fabrice Bellard committed
107 108 109

#include "avio.h"

110 111
struct AVFormatContext;

112 113

/*
114 115
 * Public Metadata API.
 * The metadata API allows libavformat to export metadata tags to a client
116 117 118
 * application using a sequence of key/value pairs. Like all strings in FFmpeg,
 * metadata must be stored as UTF-8 encoded Unicode. Note that metadata
 * exported by demuxers isn't checked to be valid UTF-8 in most cases.
119 120 121 122 123 124 125 126 127
 * Important concepts to keep in mind:
 * 1. Keys are unique; there can never be 2 tags with the same key. This is
 *    also meant semantically, i.e., a demuxer should not knowingly produce
 *    several keys that are literally different but semantically identical.
 *    E.g., key=Author5, key=Author6. In this example, all authors must be
 *    placed in the same tag.
 * 2. Metadata is flat, not hierarchical; there are no subtags. If you
 *    want to store, e.g., the email address of the child of producer Alice
 *    and actor Bob, that could have key=alice_and_bobs_childs_email_address.
128 129 130 131 132 133 134 135 136 137 138 139
 * 3. Several modifiers can be applied to the tag name. This is done by
 *    appending a dash character ('-') and the modifier name in the order
 *    they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.
 *    a) language -- a tag whose value is localized for a particular language
 *       is appended with the ISO 639-2/B 3-letter language code.
 *       For example: Author-ger=Michael, Author-eng=Mike
 *       The original/default language is in the unqualified "Author" tag.
 *       A demuxer should set a default if it sets any translated tag.
 *    b) sorting  -- a modified version of a tag that should be used for
 *       sorting will have '-sort' appended. E.g. artist="The Beatles",
 *       artist-sort="Beatles, The".
 *
140 141 142
 * 4. Demuxers attempt to export metadata in a generic format, however tags
 *    with no generic equivalents are left as they are stored in the container.
 *    Follows a list of generic tag names:
143 144 145 146 147 148 149 150
 *
 * album        -- name of the set this work belongs to
 * album_artist -- main creator of the set/album, if different from artist.
 *                 e.g. "Various Artists" for compilation albums.
 * artist       -- main creator of the work
 * comment      -- any additional description of the file.
 * composer     -- who composed the work, if different from artist.
 * copyright    -- name of copyright holder.
151
 * creation_time-- date when the file was created, preferably in ISO 8601.
152 153 154 155 156 157 158 159 160 161 162 163 164 165
 * date         -- date when the work was created, preferably in ISO 8601.
 * disc         -- number of a subset, e.g. disc in a multi-disc collection.
 * encoder      -- name/settings of the software/hardware that produced the file.
 * encoded_by   -- person/group who created the file.
 * filename     -- original name of the file.
 * genre        -- <self-evident>.
 * language     -- main language in which the work is performed, preferably
 *                 in ISO 639-2 format.
 * performer    -- artist who performed the work, if different from artist.
 *                 E.g for "Also sprach Zarathustra", artist would be "Richard
 *                 Strauss" and performer "London Philharmonic Orchestra".
 * publisher    -- name of the label/publisher.
 * title        -- name of the work.
 * track        -- number of this work in the set, can be in form current/total.
166 167
 */

168
#define AV_METADATA_MATCH_CASE      1
169
#define AV_METADATA_IGNORE_SUFFIX   2
170 171
#define AV_METADATA_DONT_STRDUP_KEY 4
#define AV_METADATA_DONT_STRDUP_VAL 8
172
#define AV_METADATA_DONT_OVERWRITE 16   ///< Don't overwrite existing tags.
173 174 175 176

typedef struct {
    char *key;
    char *value;
177
}AVMetadataTag;
178

Aurelien Jacobs's avatar
Aurelien Jacobs committed
179
typedef struct AVMetadata AVMetadata;
180
#if FF_API_OLD_METADATA
181
typedef struct AVMetadataConv AVMetadataConv;
182
#endif
183 184

/**
185
 * Get a metadata element with matching key.
186
 *
187
 * @param prev Set to the previous matching element to find the next.
188
 *             If set to NULL the first matching element is returned.
189 190
 * @param flags Allows case as well as suffix-insensitive comparisons.
 * @return Found tag or NULL, changing key or value leads to undefined behavior.
191
 */
192
AVMetadataTag *
Aurelien Jacobs's avatar
Aurelien Jacobs committed
193
av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags);
194

195
#if FF_API_OLD_METADATA
196
/**
197
 * Set the given tag in *pm, overwriting an existing tag.
198
 *
199 200
 * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
 * a metadata struct is allocated and put in *pm.
201 202
 * @param key tag key to add to *pm (will be av_strduped)
 * @param value tag value to add to *pm (will be av_strduped)
203
 * @return >= 0 on success otherwise an error code <0
204
 * @deprecated Use av_metadata_set2() instead.
205
 */
206
attribute_deprecated int av_metadata_set(AVMetadata **pm, const char *key, const char *value);
207 208 209
#endif

/**
210
 * Set the given tag in *pm, overwriting an existing tag.
211
 *
212 213
 * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
 * a metadata struct is allocated and put in *pm.
214 215
 * @param key tag key to add to *pm (will be av_strduped depending on flags)
 * @param value tag value to add to *pm (will be av_strduped depending on flags).
216
 *        Passing a NULL value will cause an existing tag to be deleted.
217 218 219
 * @return >= 0 on success otherwise an error code <0
 */
int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
220

221
#if FF_API_OLD_METADATA
222
/**
223
 * This function is provided for compatibility reason and currently does nothing.
224
 */
225 226 227
attribute_deprecated void av_metadata_conv(struct AVFormatContext *ctx, const AVMetadataConv *d_conv,
                                                                        const AVMetadataConv *s_conv);
#endif
228

229
/**
230
 * Free all the memory allocated for an AVMetadata struct.
231 232 233
 */
void av_metadata_free(AVMetadata **m);

234

Fabrice Bellard's avatar
Fabrice Bellard committed
235 236
/* packet functions */

237 238

/**
239
 * Allocate and read the payload of a packet and initialize its
240
 * fields with default values.
241 242
 *
 * @param pkt packet
Diego Biurrun's avatar
Diego Biurrun committed
243 244
 * @param size desired payload size
 * @return >0 (read size) if OK, AVERROR_xxx otherwise
245
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
246
int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
247

Fabrice Bellard's avatar
Fabrice Bellard committed
248

249
/**
250 251
 * Read data and append it to the current content of the AVPacket.
 * If pkt->size is 0 this is identical to av_get_packet.
252 253 254 255 256 257 258 259 260 261 262 263
 * Note that this uses av_grow_packet and thus involves a realloc
 * which is inefficient. Thus this function should only be used
 * when there is no reasonable way to know (an upper bound of)
 * the final size.
 *
 * @param pkt packet
 * @param size amount of data to read
 * @return >0 (read size) if OK, AVERROR_xxx otherwise, previous data
 *         will not be lost even if an error occurs.
 */
int av_append_packet(ByteIOContext *s, AVPacket *pkt, int size);

Fabrice Bellard's avatar
Fabrice Bellard committed
264 265 266
/*************************************************/
/* fractional numbers for exact pts handling */

267
/**
Diego Biurrun's avatar
Diego Biurrun committed
268 269
 * The exact value of the fractional number is: 'val + num / den'.
 * num is assumed to be 0 <= num < den.
270
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
271
typedef struct AVFrac {
272
    int64_t val, num, den;
273
} AVFrac;
Fabrice Bellard's avatar
Fabrice Bellard committed
274

Fabrice Bellard's avatar
Fabrice Bellard committed
275
/*************************************************/
276
/* input/output formats */
Fabrice Bellard's avatar
Fabrice Bellard committed
277

278 279
struct AVCodecTag;

280 281 282
/**
 * This structure contains the data a format has to probe a file.
 */
283
typedef struct AVProbeData {
284
    const char *filename;
285 286
    unsigned char *buf; /**< Buffer must have AVPROBE_PADDING_SIZE of extra allocated bytes filled with zero. */
    int buf_size;       /**< Size of buf except extra allocated bytes */
287 288
} AVProbeData;

289
#define AVPROBE_SCORE_MAX 100               ///< maximum score, half of that is used for file-extension-based detection
290
#define AVPROBE_PADDING_SIZE 32             ///< extra allocated bytes at the end of the probe buffer
Fabrice Bellard's avatar
Fabrice Bellard committed
291 292

typedef struct AVFormatParameters {
293
    AVRational time_base;
Fabrice Bellard's avatar
Fabrice Bellard committed
294 295 296 297
    int sample_rate;
    int channels;
    int width;
    int height;
298
    enum PixelFormat pix_fmt;
Diego Biurrun's avatar
Diego Biurrun committed
299 300 301 302
    int channel; /**< Used to select DV channel. */
    const char *standard; /**< TV standard, NTSC, PAL, SECAM */
    unsigned int mpeg2ts_raw:1;  /**< Force raw MPEG-2 transport stream output, if possible. */
    unsigned int mpeg2ts_compute_pcr:1; /**< Compute exact PCR for each transport
303
                                            stream packet (only meaningful if
Diego Biurrun's avatar
Diego Biurrun committed
304 305 306
                                            mpeg2ts_raw is TRUE). */
    unsigned int initial_pause:1;       /**< Do not begin to play the stream
                                            immediately (RTSP only). */
307
    unsigned int prealloced_context:1;
308
#if FF_API_PARAMETERS_CODEC_ID
Anton Khirnov's avatar
Anton Khirnov committed
309 310
    attribute_deprecated enum CodecID video_codec_id;
    attribute_deprecated enum CodecID audio_codec_id;
311
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
312 313
} AVFormatParameters;

Diego Biurrun's avatar
Diego Biurrun committed
314
//! Demuxer will use url_fopen, no opened file should be provided by the caller.
315
#define AVFMT_NOFILE        0x0001
Diego Biurrun's avatar
Diego Biurrun committed
316 317 318 319 320 321 322 323
#define AVFMT_NEEDNUMBER    0x0002 /**< Needs '%d' in filename. */
#define AVFMT_SHOW_IDS      0x0008 /**< Show format stream IDs numbers. */
#define AVFMT_RAWPICTURE    0x0020 /**< Format wants AVPicture structure for
                                      raw picture data. */
#define AVFMT_GLOBALHEADER  0x0040 /**< Format wants global header. */
#define AVFMT_NOTIMESTAMPS  0x0080 /**< Format does not need / have any timestamps. */
#define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */
#define AVFMT_TS_DISCONT    0x0200 /**< Format allows timestamp discontinuities. */
324
#define AVFMT_VARIABLE_FPS  0x0400 /**< Format allows variable fps. */
325
#define AVFMT_NODIMENSIONS  0x0800 /**< Format does not need width/height */
326 327

typedef struct AVOutputFormat {
Fabrice Bellard's avatar
Fabrice Bellard committed
328
    const char *name;
329 330
    /**
     * Descriptive name for the format, meant to be more human-readable
331
     * than name. You should use the NULL_IF_CONFIG_SMALL() macro
332 333
     * to define it.
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
334 335
    const char *long_name;
    const char *mime_type;
Diego Biurrun's avatar
Diego Biurrun committed
336
    const char *extensions; /**< comma-separated filename extensions */
337 338 339
    /**
     * size of private data so that it can be allocated in the wrapper
     */
340
    int priv_data_size;
Fabrice Bellard's avatar
Fabrice Bellard committed
341
    /* output support */
342 343
    enum CodecID audio_codec; /**< default audio codec */
    enum CodecID video_codec; /**< default video codec */
Fabrice Bellard's avatar
Fabrice Bellard committed
344
    int (*write_header)(struct AVFormatContext *);
345
    int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
Fabrice Bellard's avatar
Fabrice Bellard committed
346
    int (*write_trailer)(struct AVFormatContext *);
347 348 349
    /**
     * can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER
     */
350
    int flags;
351 352 353
    /**
     * Currently only used to set pixel format if not YUV420P.
     */
354
    int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
355 356
    int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,
                             AVPacket *in, int flush);
357 358

    /**
359
     * List of supported codec_id-codec_tag pairs, ordered by "better
360
     * choice first". The arrays are all terminated by CODEC_ID_NONE.
361
     */
362
    const struct AVCodecTag * const *codec_tag;
363

364 365
    enum CodecID subtitle_codec; /**< default subtitle codec */

366
#if FF_API_OLD_METADATA
367
    const AVMetadataConv *metadata_conv;
368
#endif
369

370 371 372
    /* private fields */
    struct AVOutputFormat *next;
} AVOutputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
373

374
typedef struct AVInputFormat {
375 376
    /**
     * A comma separated list of short names for the format. New names
377 378
     * may be appended with a minor bump.
     */
379
    const char *name;
380

381 382
    /**
     * Descriptive name for the format, meant to be more human-readable
383
     * than name. You should use the NULL_IF_CONFIG_SMALL() macro
384 385
     * to define it.
     */
386
    const char *long_name;
387 388 389 390

    /**
     * Size of private data so that it can be allocated in the wrapper.
     */
391
    int priv_data_size;
392

393
    /**
394
     * Tell if a given file has a chance of being parsed as this format.
Diego Biurrun's avatar
Diego Biurrun committed
395 396
     * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes
     * big so you do not have to check for that unless you need more.
397
     */
398
    int (*read_probe)(AVProbeData *);
399 400 401 402 403 404 405

    /**
     * Read the format header and initialize the AVFormatContext
     * structure. Return 0 if OK. 'ap' if non-NULL contains
     * additional parameters. Only used in raw format right
     * now. 'av_new_stream' should be called to create new streams.
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
406 407
    int (*read_header)(struct AVFormatContext *,
                       AVFormatParameters *ap);
408 409 410 411

    /**
     * Read one packet and put it in 'pkt'. pts and flags are also
     * set. 'av_new_stream' can be called only if the flag
412 413
     * AVFMTCTX_NOHEADER is used and only in the calling thread (not in a
     * background thread).
414 415 416 417
     * @return 0 on success, < 0 on error.
     *         When returning an error, pkt must not have been allocated
     *         or must be freed before returning
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
418
    int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
419 420 421 422 423

    /**
     * Close the stream. The AVFormatContext and AVStreams are not
     * freed by this function
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
424
    int (*read_close)(struct AVFormatContext *);
425

426
#if FF_API_READ_SEEK
427
    /**
Diego Biurrun's avatar
Diego Biurrun committed
428 429
     * Seek to a given timestamp relative to the frames in
     * stream component stream_index.
430 431 432
     * @param stream_index Must not be -1.
     * @param flags Selects which direction should be preferred if no exact
     *              match is available.
433
     * @return >= 0 on success (but not necessarily the new offset)
434
     */
Anton Khirnov's avatar
Anton Khirnov committed
435 436
    attribute_deprecated int (*read_seek)(struct AVFormatContext *,
                                          int stream_index, int64_t timestamp, int flags);
437
#endif
438
    /**
Diego Biurrun's avatar
Diego Biurrun committed
439
     * Gets the next timestamp in stream[stream_index].time_base units.
Diego Biurrun's avatar
Diego Biurrun committed
440
     * @return the timestamp or AV_NOPTS_VALUE if an error occurred
441 442 443
     */
    int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
                              int64_t *pos, int64_t pos_limit);
444 445 446 447

    /**
     * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER.
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
448
    int flags;
449 450 451 452 453 454

    /**
     * If extensions are defined, then no probe is done. You should
     * usually not use extension format guessing because it is not
     * reliable enough
     */
455
    const char *extensions;
456 457 458 459

    /**
     * General purpose read-only value that the format can use.
     */
460
    int value;
461

462 463 464 465
    /**
     * Start/resume playing - only meaningful if using a network-based format
     * (RTSP).
     */
466 467
    int (*read_play)(struct AVFormatContext *);

468 469 470 471
    /**
     * Pause playing - only meaningful if using a network-based format
     * (RTSP).
     */
472 473
    int (*read_pause)(struct AVFormatContext *);

474
    const struct AVCodecTag * const *codec_tag;
475

476
    /**
477
     * Seek to timestamp ts.
478 479 480 481
     * Seeking will be done so that the point from which all active streams
     * can be presented successfully will be closest to ts and within min/max_ts.
     * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
     */
Michael Niedermayer's avatar
untypo  
Michael Niedermayer committed
482
    int (*read_seek2)(struct AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
483

484
#if FF_API_OLD_METADATA
485
    const AVMetadataConv *metadata_conv;
486
#endif
487

488 489 490
    /* private fields */
    struct AVInputFormat *next;
} AVInputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
491

Aurelien Jacobs's avatar
Aurelien Jacobs committed
492 493 494
enum AVStreamParseType {
    AVSTREAM_PARSE_NONE,
    AVSTREAM_PARSE_FULL,       /**< full parsing and repack */
Diego Biurrun's avatar
Diego Biurrun committed
495
    AVSTREAM_PARSE_HEADERS,    /**< Only parse headers, do not repack. */
496
    AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */
497
    AVSTREAM_PARSE_FULL_ONCE,  /**< full parsing and repack of the first frame only, only implemented for H.264 currently */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
498 499
};

500 501 502 503
typedef struct AVIndexEntry {
    int64_t pos;
    int64_t timestamp;
#define AVINDEX_KEYFRAME 0x0001
Michael Niedermayer's avatar
Michael Niedermayer committed
504
    int flags:2;
Diego Biurrun's avatar
Diego Biurrun committed
505 506
    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).
    int min_distance;         /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */
507 508
} AVIndexEntry;

509 510 511 512 513 514
#define AV_DISPOSITION_DEFAULT   0x0001
#define AV_DISPOSITION_DUB       0x0002
#define AV_DISPOSITION_ORIGINAL  0x0004
#define AV_DISPOSITION_COMMENT   0x0008
#define AV_DISPOSITION_LYRICS    0x0010
#define AV_DISPOSITION_KARAOKE   0x0020
515 516 517 518 519 520

/**
 * Track should be used during playback by default.
 * Useful for subtitle track that should be displayed
 * even when user did not explicitly ask for subtitles.
 */
521
#define AV_DISPOSITION_FORCED    0x0040
522

523 524 525
/**
 * Stream structure.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
526
 * Removal, reordering and changes to existing fields require a major
527
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
528
 * sizeof(AVStream) must not be used outside libav*.
529
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
530
typedef struct AVStream {
531
    int index;    /**< stream index in AVFormatContext */
Diego Biurrun's avatar
Diego Biurrun committed
532
    int id;       /**< format-specific stream ID */
533
    AVCodecContext *codec; /**< codec context */
534
    /**
535 536
     * Real base framerate of the stream.
     * This is the lowest framerate with which all timestamps can be
Ramiro Polla's avatar
Typos  
Ramiro Polla committed
537
     * represented accurately (it is the least common multiple of all
538 539
     * framerates in the stream). Note, this value is just a guess!
     * For example, if the time base is 1/90000 and all frames have either
Diego Biurrun's avatar
Diego Biurrun committed
540
     * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
541 542
     */
    AVRational r_frame_rate;
Fabrice Bellard's avatar
Fabrice Bellard committed
543
    void *priv_data;
544

545
    /* internal data used in av_find_stream_info() */
546
    int64_t first_dts;
547 548 549 550

    /**
     * encoding: pts generation when outputting stream
     */
551
    struct AVFrac pts;
552 553

    /**
Diego Biurrun's avatar
Diego Biurrun committed
554 555
     * This is the fundamental unit of time (in seconds) in terms
     * of which frame timestamps are represented. For fixed-fps content,
556
     * time base should be 1/framerate and timestamp increments should be 1.
557
     */
558
    AVRational time_base;
559
    int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
Fabrice Bellard's avatar
Fabrice Bellard committed
560
    /* ffmpeg.c private use */
Diego Biurrun's avatar
Diego Biurrun committed
561 562
    int stream_copy; /**< If set, just copy stream. */
    enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
563

564
    //FIXME move stuff to a flags field?
565 566 567 568
    /**
     * Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
     * MN: dunno if that is the right place for it
     */
569
    float quality;
570

571
    /**
Diego Biurrun's avatar
Diego Biurrun committed
572 573 574
     * Decoding: pts of the first frame of the stream, in stream time base.
     * Only set this if you are absolutely 100% sure that the value you set
     * it to really is the pts of the first frame.
575
     * This may be undefined (AV_NOPTS_VALUE).
Diego Biurrun's avatar
Diego Biurrun committed
576 577
     * @note The ASF header does NOT contain a correct start_time the ASF
     * demuxer must NOT set this.
578
     */
579
    int64_t start_time;
580

581
    /**
Diego Biurrun's avatar
Diego Biurrun committed
582
     * Decoding: duration of the stream, in stream time base.
583
     * If a source file does not specify a duration, but does specify
Diego Biurrun's avatar
Diego Biurrun committed
584
     * a bitrate, this value will be estimated from bitrate and file size.
585
     */
586
    int64_t duration;
587

588
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
589
    attribute_deprecated char language[4]; /**< ISO 639-2/B 3-letter language code (empty string if undefined) */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
590
#endif
591

592
    /* av_read_frame() support */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
593
    enum AVStreamParseType need_parsing;
594
    struct AVCodecParserContext *parser;
595

596
    int64_t cur_dts;
Michael Niedermayer's avatar
Michael Niedermayer committed
597 598
    int last_IP_duration;
    int64_t last_IP_pts;
599
    /* av_seek_frame() support */
Diego Biurrun's avatar
Diego Biurrun committed
600 601
    AVIndexEntry *index_entries; /**< Only used if the format does not
                                    support seeking natively. */
602
    int nb_index_entries;
Måns Rullgård's avatar
Måns Rullgård committed
603
    unsigned int index_entries_allocated_size;
604

605
    int64_t nb_frames;                 ///< number of frames in this stream if known or 0
606

607
#if FF_API_LAVF_UNUSED
Anton Khirnov's avatar
Anton Khirnov committed
608
    attribute_deprecated int64_t unused[4+1];
609
#endif
610

611
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
612
    attribute_deprecated char *filename; /**< source filename of the stream */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
613
#endif
614

Diego Biurrun's avatar
Diego Biurrun committed
615
    int disposition; /**< AV_DISPOSITION_* bit field */
616 617

    AVProbeData probe_data;
618 619
#define MAX_REORDER_DELAY 16
    int64_t pts_buffer[MAX_REORDER_DELAY+1];
620 621 622 623 624 625 626

    /**
     * sample aspect ratio (0 if unknown)
     * - encoding: Set by user.
     * - decoding: Set by libavformat.
     */
    AVRational sample_aspect_ratio;
627

Aurelien Jacobs's avatar
Aurelien Jacobs committed
628
    AVMetadata *metadata;
629

630 631
    /* Intended mostly for av_read_frame() support. Not supposed to be used by */
    /* external applications; try to use something else if at all possible.    */
632 633 634
    const uint8_t *cur_ptr;
    int cur_len;
    AVPacket cur_pkt;
635 636 637 638 639 640 641 642 643 644

    // Timestamp generation support:
    /**
     * Timestamp corresponding to the last dts sync point.
     *
     * Initialized when AVCodecParserContext.dts_sync_point >= 0 and
     * a DTS is received from the underlying container. Otherwise set to
     * AV_NOPTS_VALUE by default.
     */
    int64_t reference_dts;
645 646 647 648 649

    /**
     * Number of packets to buffer for codec probing
     * NOT PART OF PUBLIC API
     */
650
#define MAX_PROBE_PACKETS 2500
651
    int probe_packets;
652 653

    /**
654
     * last packet in packet_buffer for this stream when muxing.
655 656
     * used internally, NOT PART OF PUBLIC API, dont read or write from outside of libav*
     */
657
    struct AVPacketList *last_in_packet_buffer;
Michael Niedermayer's avatar
Michael Niedermayer committed
658 659 660 661 662

    /**
     * Average framerate
     */
    AVRational avg_frame_rate;
663 664 665 666 667

    /**
     * Number of frames that have been demuxed during av_find_stream_info()
     */
    int codec_info_nb_frames;
668 669 670 671 672 673 674 675 676 677 678 679

    /**
     * Stream informations used internally by av_find_stream_info()
     */
#define MAX_STD_TIMEBASES (60*12+5)
    struct {
        int64_t last_dts;
        int64_t duration_gcd;
        int duration_count;
        double duration_error[MAX_STD_TIMEBASES];
        int64_t codec_info_duration;
    } *info;
Fabrice Bellard's avatar
Fabrice Bellard committed
680 681
} AVStream;

682 683
#define AV_PROGRAM_RUNNING 1

684 685
/**
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
686
 * Removal, reordering and changes to existing fields require a major
687
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
688
 * sizeof(AVProgram) must not be used outside libav*.
689
 */
690 691
typedef struct AVProgram {
    int            id;
692
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
693 694
    attribute_deprecated char           *provider_name; ///< network name for DVB streams
    attribute_deprecated char           *name;          ///< service name for DVB streams
Aurelien Jacobs's avatar
Aurelien Jacobs committed
695
#endif
696 697
    int            flags;
    enum AVDiscard discard;        ///< selects which program to discard and which to feed to the caller
698 699
    unsigned int   *stream_index;
    unsigned int   nb_stream_indexes;
Aurelien Jacobs's avatar
Aurelien Jacobs committed
700
    AVMetadata *metadata;
701 702
} AVProgram;

703
#define AVFMTCTX_NOHEADER      0x0001 /**< signal that no header is present
704 705
                                         (streams are added dynamically) */

706
typedef struct AVChapter {
Diego Biurrun's avatar
Diego Biurrun committed
707 708
    int id;                 ///< unique ID to identify the chapter
    AVRational time_base;   ///< time base in which the start/end timestamps are specified
709
    int64_t start, end;     ///< chapter start/end time in time_base units
710
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
711
    attribute_deprecated char *title;            ///< chapter title
Aurelien Jacobs's avatar
Aurelien Jacobs committed
712
#endif
Aurelien Jacobs's avatar
Aurelien Jacobs committed
713
    AVMetadata *metadata;
714 715
} AVChapter;

716
#if FF_API_MAX_STREAMS
Fabrice Bellard's avatar
Fabrice Bellard committed
717
#define MAX_STREAMS 20
718
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
719

720
/**
Diego Biurrun's avatar
Diego Biurrun committed
721
 * Format I/O context.
722
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
723
 * Removal, reordering and changes to existing fields require a major
724
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
725
 * sizeof(AVFormatContext) must not be used outside libav*.
726
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
727
typedef struct AVFormatContext {
728
    const AVClass *av_class; /**< Set by avformat_alloc_context. */
Diego Biurrun's avatar
Diego Biurrun committed
729
    /* Can only be iformat or oformat, not both at the same time. */
730 731
    struct AVInputFormat *iformat;
    struct AVOutputFormat *oformat;
Fabrice Bellard's avatar
Fabrice Bellard committed
732
    void *priv_data;
733
    ByteIOContext *pb;
734
    unsigned int nb_streams;
735
#if FF_API_MAX_STREAMS
Fabrice Bellard's avatar
Fabrice Bellard committed
736
    AVStream *streams[MAX_STREAMS];
737 738 739
#else
    AVStream **streams;
#endif
740
    char filename[1024]; /**< input or output filename */
Fabrice Bellard's avatar
Fabrice Bellard committed
741
    /* stream info */
742
    int64_t timestamp;
743
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
744 745 746 747 748 749 750 751
    attribute_deprecated char title[512];
    attribute_deprecated char author[512];
    attribute_deprecated char copyright[512];
    attribute_deprecated char comment[512];
    attribute_deprecated char album[512];
    attribute_deprecated int year;  /**< ID3 year, 0 if none */
    attribute_deprecated int track; /**< track number, 0 if none */
    attribute_deprecated char genre[32]; /**< ID3 genre */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
752
#endif
753

Diego Biurrun's avatar
Diego Biurrun committed
754 755
    int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
    /* private data for pts handling (do not modify directly). */
756 757 758 759 760
    /**
     * This buffer is only needed when packets were already buffered but
     * not decoded, for example to get the codec parameters in MPEG
     * streams.
     */