avformat.h 55.4 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

25
/**
Art Clarke's avatar
Art Clarke committed
26 27
 * I return the LIBAVFORMAT_VERSION_INT constant.  You got
 * a fucking problem with that, douchebag?
28 29 30
 */
unsigned avformat_version(void);

31
/**
32
 * Return the libavformat build-time configuration.
33
 */
34
const char *avformat_configuration(void);
35 36

/**
37
 * Return the libavformat license.
38
 */
39
const char *avformat_license(void);
40

41
#include <time.h>
Zdenek Kabelac's avatar
Zdenek Kabelac committed
42
#include <stdio.h>  /* FILE */
43
#include "libavcodec/avcodec.h"
Fabrice Bellard's avatar
Fabrice Bellard committed
44 45

#include "avio.h"
46
#include "libavformat/version.h"
Fabrice Bellard's avatar
Fabrice Bellard committed
47

48 49
struct AVFormatContext;

50 51

/*
52 53
 * Public Metadata API.
 * The metadata API allows libavformat to export metadata tags to a client
54 55 56
 * 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.
57 58 59 60 61 62 63 64 65
 * 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.
66 67 68 69 70 71 72 73 74 75 76 77
 * 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".
 *
78 79 80
 * 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:
81 82 83 84 85 86 87 88
 *
 * 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.
89
 * creation_time-- date when the file was created, preferably in ISO 8601.
90 91 92 93 94 95 96 97 98 99 100 101
 * 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.
102 103
 * service_name     -- name of the service in broadcasting (channel name).
 * service_provider -- name of the service provider in broadcasting.
104 105
 * title        -- name of the work.
 * track        -- number of this work in the set, can be in form current/total.
106 107
 */

108
#define AV_METADATA_MATCH_CASE      1
109
#define AV_METADATA_IGNORE_SUFFIX   2
110 111
#define AV_METADATA_DONT_STRDUP_KEY 4
#define AV_METADATA_DONT_STRDUP_VAL 8
112
#define AV_METADATA_DONT_OVERWRITE 16   ///< Don't overwrite existing tags.
113 114 115 116

typedef struct {
    char *key;
    char *value;
117
}AVMetadataTag;
118

Aurelien Jacobs's avatar
Aurelien Jacobs committed
119
typedef struct AVMetadata AVMetadata;
120
#if FF_API_OLD_METADATA
121
typedef struct AVMetadataConv AVMetadataConv;
122
#endif
123 124

/**
125
 * Get a metadata element with matching key.
126
 *
127
 * @param prev Set to the previous matching element to find the next.
128
 *             If set to NULL the first matching element is returned.
129 130
 * @param flags Allows case as well as suffix-insensitive comparisons.
 * @return Found tag or NULL, changing key or value leads to undefined behavior.
131
 */
132
AVMetadataTag *
Aurelien Jacobs's avatar
Aurelien Jacobs committed
133
av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags);
134

135
#if FF_API_OLD_METADATA
136
/**
137
 * Set the given tag in *pm, overwriting an existing tag.
138
 *
139 140
 * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
 * a metadata struct is allocated and put in *pm.
141 142
 * @param key tag key to add to *pm (will be av_strduped)
 * @param value tag value to add to *pm (will be av_strduped)
143
 * @return >= 0 on success otherwise an error code <0
144
 * @deprecated Use av_metadata_set2() instead.
145
 */
146
attribute_deprecated int av_metadata_set(AVMetadata **pm, const char *key, const char *value);
147 148 149
#endif

/**
150
 * Set the given tag in *pm, overwriting an existing tag.
151
 *
152 153
 * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
 * a metadata struct is allocated and put in *pm.
154 155
 * @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).
156
 *        Passing a NULL value will cause an existing tag to be deleted.
157 158 159
 * @return >= 0 on success otherwise an error code <0
 */
int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
160

161
#if FF_API_OLD_METADATA
162
/**
163
 * This function is provided for compatibility reason and currently does nothing.
164
 */
165 166 167
attribute_deprecated void av_metadata_conv(struct AVFormatContext *ctx, const AVMetadataConv *d_conv,
                                                                        const AVMetadataConv *s_conv);
#endif
168

169 170 171 172 173 174 175 176 177 178
/**
 * Copy metadata from one AVMetadata struct into another.
 * @param dst pointer to a pointer to a AVMetadata struct. If *dst is NULL,
 *            this function will allocate a struct for you and put it in *dst
 * @param src pointer to source AVMetadata struct
 * @param flags flags to use when setting metadata in *dst
 * @note metadata is read using the AV_METADATA_IGNORE_SUFFIX flag
 */
void av_metadata_copy(AVMetadata **dst, AVMetadata *src, int flags);

179
/**
180
 * Free all the memory allocated for an AVMetadata struct.
181 182 183
 */
void av_metadata_free(AVMetadata **m);

184

Fabrice Bellard's avatar
Fabrice Bellard committed
185 186
/* packet functions */

187 188

/**
189
 * Allocate and read the payload of a packet and initialize its
190
 * fields with default values.
191 192
 *
 * @param pkt packet
Diego Biurrun's avatar
Diego Biurrun committed
193 194
 * @param size desired payload size
 * @return >0 (read size) if OK, AVERROR_xxx otherwise
195
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
196
int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
197

Fabrice Bellard's avatar
Fabrice Bellard committed
198

199
/**
200 201
 * Read data and append it to the current content of the AVPacket.
 * If pkt->size is 0 this is identical to av_get_packet.
202 203 204 205 206 207 208 209 210 211 212 213
 * 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
214 215 216
/*************************************************/
/* fractional numbers for exact pts handling */

217
/**
Diego Biurrun's avatar
Diego Biurrun committed
218 219
 * The exact value of the fractional number is: 'val + num / den'.
 * num is assumed to be 0 <= num < den.
220
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
221
typedef struct AVFrac {
222
    int64_t val, num, den;
223
} AVFrac;
Fabrice Bellard's avatar
Fabrice Bellard committed
224

Fabrice Bellard's avatar
Fabrice Bellard committed
225
/*************************************************/
226
/* input/output formats */
Fabrice Bellard's avatar
Fabrice Bellard committed
227

228 229
struct AVCodecTag;

230 231 232
/**
 * This structure contains the data a format has to probe a file.
 */
233
typedef struct AVProbeData {
234
    const char *filename;
235 236
    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 */
237 238
} AVProbeData;

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

typedef struct AVFormatParameters {
243
    AVRational time_base;
Fabrice Bellard's avatar
Fabrice Bellard committed
244 245 246 247
    int sample_rate;
    int channels;
    int width;
    int height;
248
    enum PixelFormat pix_fmt;
Diego Biurrun's avatar
Diego Biurrun committed
249 250 251 252
    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
253
                                            stream packet (only meaningful if
Diego Biurrun's avatar
Diego Biurrun committed
254 255 256
                                            mpeg2ts_raw is TRUE). */
    unsigned int initial_pause:1;       /**< Do not begin to play the stream
                                            immediately (RTSP only). */
257
    unsigned int prealloced_context:1;
258
#if FF_API_PARAMETERS_CODEC_ID
Anton Khirnov's avatar
Anton Khirnov committed
259 260
    attribute_deprecated enum CodecID video_codec_id;
    attribute_deprecated enum CodecID audio_codec_id;
261
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
262 263
} AVFormatParameters;

Diego Biurrun's avatar
Diego Biurrun committed
264
//! Demuxer will use url_fopen, no opened file should be provided by the caller.
265
#define AVFMT_NOFILE        0x0001
Diego Biurrun's avatar
Diego Biurrun committed
266 267 268 269 270 271 272
#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. */
273
#define AVFMT_TS_DISCONT    0x0200 /**< Format allows timestamp discontinuities. Note, muxers always require valid (monotone) timestamps */
274
#define AVFMT_VARIABLE_FPS  0x0400 /**< Format allows variable fps. */
275
#define AVFMT_NODIMENSIONS  0x0800 /**< Format does not need width/height */
276
#define AVFMT_NOSTREAMS     0x1000 /**< Format does not require any streams */
277 278

typedef struct AVOutputFormat {
Fabrice Bellard's avatar
Fabrice Bellard committed
279
    const char *name;
280 281
    /**
     * Descriptive name for the format, meant to be more human-readable
282
     * than name. You should use the NULL_IF_CONFIG_SMALL() macro
283 284
     * to define it.
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
285 286
    const char *long_name;
    const char *mime_type;
Diego Biurrun's avatar
Diego Biurrun committed
287
    const char *extensions; /**< comma-separated filename extensions */
288 289 290
    /**
     * size of private data so that it can be allocated in the wrapper
     */
291
    int priv_data_size;
Fabrice Bellard's avatar
Fabrice Bellard committed
292
    /* output support */
293 294
    enum CodecID audio_codec; /**< default audio codec */
    enum CodecID video_codec; /**< default video codec */
Fabrice Bellard's avatar
Fabrice Bellard committed
295
    int (*write_header)(struct AVFormatContext *);
296
    int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
Fabrice Bellard's avatar
Fabrice Bellard committed
297
    int (*write_trailer)(struct AVFormatContext *);
298 299 300
    /**
     * can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER
     */
301
    int flags;
302 303 304
    /**
     * Currently only used to set pixel format if not YUV420P.
     */
305
    int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
306 307
    int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,
                             AVPacket *in, int flush);
308 309

    /**
310
     * List of supported codec_id-codec_tag pairs, ordered by "better
311
     * choice first". The arrays are all terminated by CODEC_ID_NONE.
312
     */
313
    const struct AVCodecTag * const *codec_tag;
314

315 316
    enum CodecID subtitle_codec; /**< default subtitle codec */

317
#if FF_API_OLD_METADATA
318
    const AVMetadataConv *metadata_conv;
319
#endif
320

321 322
    const AVClass *priv_class; ///< AVClass for the private context

323 324 325
    /* private fields */
    struct AVOutputFormat *next;
} AVOutputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
326

327
typedef struct AVInputFormat {
328 329
    /**
     * A comma separated list of short names for the format. New names
330 331
     * may be appended with a minor bump.
     */
332
    const char *name;
333

334 335
    /**
     * Descriptive name for the format, meant to be more human-readable
336
     * than name. You should use the NULL_IF_CONFIG_SMALL() macro
337 338
     * to define it.
     */
339
    const char *long_name;
340 341 342 343

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

346
    /**
347
     * Tell if a given file has a chance of being parsed as this format.
Diego Biurrun's avatar
Diego Biurrun committed
348 349
     * 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.
350
     */
351
    int (*read_probe)(AVProbeData *);
352 353 354 355 356 357 358

    /**
     * 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
359 360
    int (*read_header)(struct AVFormatContext *,
                       AVFormatParameters *ap);
361 362 363 364

    /**
     * Read one packet and put it in 'pkt'. pts and flags are also
     * set. 'av_new_stream' can be called only if the flag
365 366
     * AVFMTCTX_NOHEADER is used and only in the calling thread (not in a
     * background thread).
367 368 369 370
     * @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
371
    int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
372 373 374 375 376

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

379
#if FF_API_READ_SEEK
380
    /**
Diego Biurrun's avatar
Diego Biurrun committed
381 382
     * Seek to a given timestamp relative to the frames in
     * stream component stream_index.
383 384 385
     * @param stream_index Must not be -1.
     * @param flags Selects which direction should be preferred if no exact
     *              match is available.
386
     * @return >= 0 on success (but not necessarily the new offset)
387
     */
Anton Khirnov's avatar
Anton Khirnov committed
388 389
    attribute_deprecated int (*read_seek)(struct AVFormatContext *,
                                          int stream_index, int64_t timestamp, int flags);
390
#endif
391
    /**
Diego Biurrun's avatar
Diego Biurrun committed
392
     * Gets the next timestamp in stream[stream_index].time_base units.
Diego Biurrun's avatar
Diego Biurrun committed
393
     * @return the timestamp or AV_NOPTS_VALUE if an error occurred
394 395 396
     */
    int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
                              int64_t *pos, int64_t pos_limit);
397 398 399 400

    /**
     * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER.
     */
Fabrice Bellard's avatar
Fabrice Bellard committed
401
    int flags;
402 403 404 405 406 407

    /**
     * If extensions are defined, then no probe is done. You should
     * usually not use extension format guessing because it is not
     * reliable enough
     */
408
    const char *extensions;
409 410 411 412

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

415 416 417 418
    /**
     * Start/resume playing - only meaningful if using a network-based format
     * (RTSP).
     */
419 420
    int (*read_play)(struct AVFormatContext *);

421 422 423 424
    /**
     * Pause playing - only meaningful if using a network-based format
     * (RTSP).
     */
425 426
    int (*read_pause)(struct AVFormatContext *);

427
    const struct AVCodecTag * const *codec_tag;
428

429
    /**
430
     * Seek to timestamp ts.
431 432 433 434
     * 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
435
    int (*read_seek2)(struct AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
436

437
#if FF_API_OLD_METADATA
438
    const AVMetadataConv *metadata_conv;
439
#endif
440

441 442 443
    /* private fields */
    struct AVInputFormat *next;
} AVInputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
444

Aurelien Jacobs's avatar
Aurelien Jacobs committed
445 446 447
enum AVStreamParseType {
    AVSTREAM_PARSE_NONE,
    AVSTREAM_PARSE_FULL,       /**< full parsing and repack */
Diego Biurrun's avatar
Diego Biurrun committed
448
    AVSTREAM_PARSE_HEADERS,    /**< Only parse headers, do not repack. */
449
    AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */
450
    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
451 452
};

453 454 455 456
typedef struct AVIndexEntry {
    int64_t pos;
    int64_t timestamp;
#define AVINDEX_KEYFRAME 0x0001
Michael Niedermayer's avatar
Michael Niedermayer committed
457
    int flags:2;
Diego Biurrun's avatar
Diego Biurrun committed
458 459
    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. */
460 461
} AVIndexEntry;

462 463 464 465 466 467
#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
468 469 470 471 472 473

/**
 * 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.
 */
474
#define AV_DISPOSITION_FORCED    0x0040
475 476
#define AV_DISPOSITION_HEARING_IMPAIRED  0x0080  /**< stream for hearing impaired audiences */
#define AV_DISPOSITION_VISUAL_IMPAIRED   0x0100  /**< stream for visual impaired audiences */
477

478 479 480
/**
 * Stream structure.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
481
 * Removal, reordering and changes to existing fields require a major
482
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
483
 * sizeof(AVStream) must not be used outside libav*.
484
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
485
typedef struct AVStream {
486
    int index;    /**< stream index in AVFormatContext */
Diego Biurrun's avatar
Diego Biurrun committed
487
    int id;       /**< format-specific stream ID */
488
    AVCodecContext *codec; /**< codec context */
489
    /**
490 491
     * 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
492
     * represented accurately (it is the least common multiple of all
493 494
     * 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
495
     * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
496 497
     */
    AVRational r_frame_rate;
Fabrice Bellard's avatar
Fabrice Bellard committed
498
    void *priv_data;
499

500
    /* internal data used in av_find_stream_info() */
501
    int64_t first_dts;
502 503 504 505

    /**
     * encoding: pts generation when outputting stream
     */
506
    struct AVFrac pts;
507 508

    /**
Diego Biurrun's avatar
Diego Biurrun committed
509 510
     * This is the fundamental unit of time (in seconds) in terms
     * of which frame timestamps are represented. For fixed-fps content,
511
     * time base should be 1/framerate and timestamp increments should be 1.
512
     */
513
    AVRational time_base;
514
    int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
Fabrice Bellard's avatar
Fabrice Bellard committed
515
    /* ffmpeg.c private use */
Diego Biurrun's avatar
Diego Biurrun committed
516 517
    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.
518

519
    //FIXME move stuff to a flags field?
520 521 522 523
    /**
     * Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
     * MN: dunno if that is the right place for it
     */
524
    float quality;
525

526
    /**
Diego Biurrun's avatar
Diego Biurrun committed
527 528 529
     * 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.
530
     * This may be undefined (AV_NOPTS_VALUE).
Diego Biurrun's avatar
Diego Biurrun committed
531 532
     * @note The ASF header does NOT contain a correct start_time the ASF
     * demuxer must NOT set this.
533
     */
534
    int64_t start_time;
535

536
    /**
Diego Biurrun's avatar
Diego Biurrun committed
537
     * Decoding: duration of the stream, in stream time base.
538
     * If a source file does not specify a duration, but does specify
Diego Biurrun's avatar
Diego Biurrun committed
539
     * a bitrate, this value will be estimated from bitrate and file size.
540
     */
541
    int64_t duration;
542

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

547
    /* av_read_frame() support */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
548
    enum AVStreamParseType need_parsing;
549
    struct AVCodecParserContext *parser;
550

551
    int64_t cur_dts;
Michael Niedermayer's avatar
Michael Niedermayer committed
552 553
    int last_IP_duration;
    int64_t last_IP_pts;
554
    /* av_seek_frame() support */
Diego Biurrun's avatar
Diego Biurrun committed
555 556
    AVIndexEntry *index_entries; /**< Only used if the format does not
                                    support seeking natively. */
557
    int nb_index_entries;
Måns Rullgård's avatar
Måns Rullgård committed
558
    unsigned int index_entries_allocated_size;
559

560
    int64_t nb_frames;                 ///< number of frames in this stream if known or 0
561

562
#if FF_API_LAVF_UNUSED
Anton Khirnov's avatar
Anton Khirnov committed
563
    attribute_deprecated int64_t unused[4+1];
564
#endif
565

566
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
567
    attribute_deprecated char *filename; /**< source filename of the stream */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
568
#endif
569

Diego Biurrun's avatar
Diego Biurrun committed
570
    int disposition; /**< AV_DISPOSITION_* bit field */
571 572

    AVProbeData probe_data;
573 574
#define MAX_REORDER_DELAY 16
    int64_t pts_buffer[MAX_REORDER_DELAY+1];
575 576 577 578 579 580 581

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

Aurelien Jacobs's avatar
Aurelien Jacobs committed
583
    AVMetadata *metadata;
584

585 586
    /* Intended mostly for av_read_frame() support. Not supposed to be used by */
    /* external applications; try to use something else if at all possible.    */
587 588 589
    const uint8_t *cur_ptr;
    int cur_len;
    AVPacket cur_pkt;
590 591 592 593 594 595 596 597 598 599

    // 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;
600 601 602 603 604

    /**
     * Number of packets to buffer for codec probing
     * NOT PART OF PUBLIC API
     */
605
#define MAX_PROBE_PACKETS 2500
606
    int probe_packets;
607 608

    /**
609
     * last packet in packet_buffer for this stream when muxing.
610 611
     * used internally, NOT PART OF PUBLIC API, dont read or write from outside of libav*
     */
612
    struct AVPacketList *last_in_packet_buffer;
Michael Niedermayer's avatar
Michael Niedermayer committed
613 614 615 616 617

    /**
     * Average framerate
     */
    AVRational avg_frame_rate;
618 619 620 621 622

    /**
     * Number of frames that have been demuxed during av_find_stream_info()
     */
    int codec_info_nb_frames;
623 624 625 626 627 628 629 630 631 632 633 634

    /**
     * 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
635 636
} AVStream;

637 638
#define AV_PROGRAM_RUNNING 1

639 640
/**
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
641
 * Removal, reordering and changes to existing fields require a major
642
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
643
 * sizeof(AVProgram) must not be used outside libav*.
644
 */
645 646
typedef struct AVProgram {
    int            id;
647
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
648 649
    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
650
#endif
651 652
    int            flags;
    enum AVDiscard discard;        ///< selects which program to discard and which to feed to the caller
653 654
    unsigned int   *stream_index;
    unsigned int   nb_stream_indexes;
Aurelien Jacobs's avatar
Aurelien Jacobs committed
655
    AVMetadata *metadata;
656 657
} AVProgram;

658
#define AVFMTCTX_NOHEADER      0x0001 /**< signal that no header is present
659 660
                                         (streams are added dynamically) */

661
typedef struct AVChapter {
Diego Biurrun's avatar
Diego Biurrun committed
662 663
    int id;                 ///< unique ID to identify the chapter
    AVRational time_base;   ///< time base in which the start/end timestamps are specified
664
    int64_t start, end;     ///< chapter start/end time in time_base units
665
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
666
    attribute_deprecated char *title;            ///< chapter title
Aurelien Jacobs's avatar
Aurelien Jacobs committed
667
#endif
Aurelien Jacobs's avatar
Aurelien Jacobs committed
668
    AVMetadata *metadata;
669 670
} AVChapter;

671
#if FF_API_MAX_STREAMS
Fabrice Bellard's avatar
Fabrice Bellard committed
672
#define MAX_STREAMS 20
673
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
674

675
/**
Diego Biurrun's avatar
Diego Biurrun committed
676
 * Format I/O context.
677
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
678
 * Removal, reordering and changes to existing fields require a major
679
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
680
 * sizeof(AVFormatContext) must not be used outside libav*.
681
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
682
typedef struct AVFormatContext {
683
    const AVClass *av_class; /**< Set by avformat_alloc_context. */
Diego Biurrun's avatar
Diego Biurrun committed
684
    /* Can only be iformat or oformat, not both at the same time. */
685 686
    struct AVInputFormat *iformat;
    struct AVOutputFormat *oformat;
Fabrice Bellard's avatar
Fabrice Bellard committed
687
    void *priv_data;
688
    ByteIOContext *pb;
689
    unsigned int nb_streams;
690
#if FF_API_MAX_STREAMS
Fabrice Bellard's avatar
Fabrice Bellard committed
691
    AVStream *streams[MAX_STREAMS];
692 693 694
#else
    AVStream **streams;
#endif
695
    char filename[1024]; /**< input or output filename */
Fabrice Bellard's avatar
Fabrice Bellard committed
696
    /* stream info */
697
    int64_t timestamp;
698
#if FF_API_OLD_METADATA
Anton Khirnov's avatar
Anton Khirnov committed
699 700 701 702 703 704 705 706
    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
707
#endif
708

Diego Biurrun's avatar
Diego Biurrun committed
709 710
    int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
    /* private data for pts handling (do not modify directly). */
711 712 713 714 715
    /**
     * This buffer is only needed when packets were already buffered but
     * not decoded, for example to get the codec parameters in MPEG
     * streams.
     */
716 717
    struct AVPacketList *packet_buffer;

718 719 720 721 722
    /**
     * Decoding: position of the first frame of the component, in
     * AV_TIME_BASE fractional seconds. NEVER set this value directly:
     * It is deduced from the AVStream values.
     */
723
    int64_t start_time;
724 725 726 727 728 729 730

    /**
     * Decoding: duration of the stream, in AV_TIME_BASE fractional
     * seconds. Only set this value if you know none of the individual stream
     * durations and also dont set any of them. This is deduced from the
     * AVStream values if not set.
     */
731
    int64_t duration;
732 733 734 735

    /**
     * decoding: total file size, 0 if unknown
     */
736
    int64_t file_size;
737 738 739 740 741 742

    /**
     * Decoding: total stream bitrate in bit/s, 0 if not
     * available. Never set it directly if the file_size and the
     * duration are known as FFmpeg can compute it automatically.
     */
743
    int bit_rate;
744 745 746

    /* av_read_frame() support */
    AVStream *cur_st;
747
#if FF_API_LAVF_UNUSED
748 749 750 751
    const uint8_t *cur_ptr_deprecated;
    int cur_len_deprecated;
    AVPacket cur_pkt_deprecated;
#endif
752 753

    /* av_seek_frame() support */
754
    int64_t data_offset; /**< offset of the first packet */
755 756 757
#if FF_API_INDEX_BUILT
    attribute_deprecated int index_built;
#endif
758

759
    int mux_rate;
760
    unsigned int packet_size;
761 762
    int preload;
    int max_delay;
763

764 765
#define AVFMT_NOOUTPUTLOOP -1
#define AVFMT_INFINITEOUTPUTLOOP 0
766 767 768
    /**
     * number of times to loop output in formats that support it
     */
769
    int loop_output;
770

771
    int flags;
772
#define AVFMT_FLAG_GENPTS       0x0001 ///< Generate missing pts even if it requires parsing future frames.
Diego Biurrun's avatar
Diego Biurrun committed
773 774
#define AVFMT_FLAG_IGNIDX       0x0002 ///< Ignore index.
#define AVFMT_FLAG_NONBLOCK     0x0004 ///< Do not block when reading packets from input.
775
#define AVFMT_FLAG_IGNDTS