avformat.h 35.8 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 FFMPEG_AVFORMAT_H
#define FFMPEG_AVFORMAT_H
Fabrice Bellard's avatar
Fabrice Bellard committed
23

24
#define LIBAVFORMAT_VERSION_MAJOR 52
25
#define LIBAVFORMAT_VERSION_MINOR  9
26
#define LIBAVFORMAT_VERSION_MICRO  0
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
#include <time.h>
Zdenek Kabelac's avatar
Zdenek Kabelac committed
39
#include <stdio.h>  /* FILE */
40
#include "libavcodec/avcodec.h"
Fabrice Bellard's avatar
Fabrice Bellard committed
41 42 43 44 45 46

#include "avio.h"

/* packet functions */

typedef struct AVPacket {
Michael Niedermayer's avatar
Michael Niedermayer committed
47 48
    int64_t pts;                            ///< presentation time stamp in time_base units
    int64_t dts;                            ///< decompression time stamp in time_base units
49
    uint8_t *data;
50 51 52
    int   size;
    int   stream_index;
    int   flags;
Michael Niedermayer's avatar
Michael Niedermayer committed
53
    int   duration;                         ///< presentation duration in time_base units (0 if not available)
54 55
    void  (*destruct)(struct AVPacket *);
    void  *priv;
Michael Niedermayer's avatar
Michael Niedermayer committed
56
    int64_t pos;                            ///< byte position in stream, -1 if unknown
57
} AVPacket;
58 59
#define PKT_FLAG_KEY   0x0001

Michael Niedermayer's avatar
Michael Niedermayer committed
60
void av_destruct_packet_nofree(AVPacket *pkt);
61 62 63 64

/**
 * Default packet destructor.
 */
65
void av_destruct_packet(AVPacket *pkt);
Michael Niedermayer's avatar
Michael Niedermayer committed
66

Ramiro Polla's avatar
Ramiro Polla committed
67 68 69 70 71
/**
 * Initialize optional fields of a packet to default values.
 *
 * @param pkt packet
 */
Ramiro Polla's avatar
Ramiro Polla committed
72
void av_init_packet(AVPacket *pkt);
Fabrice Bellard's avatar
Fabrice Bellard committed
73

74
/**
Diego Biurrun's avatar
Diego Biurrun committed
75
 * Allocate the payload of a packet and initialize its fields to default values.
76 77 78 79 80
 *
 * @param pkt packet
 * @param size wanted payload size
 * @return 0 if OK. AVERROR_xxx otherwise.
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
81
int av_new_packet(AVPacket *pkt, int size);
82 83

/**
Diego Biurrun's avatar
Diego Biurrun committed
84
 * Allocate and read the payload of a packet and initialize its fields to default values.
85 86 87 88 89
 *
 * @param pkt packet
 * @param size wanted payload size
 * @return >0 (read size) if OK. AVERROR_xxx otherwise.
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
90
int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
91

92 93 94 95
/**
 * @warning This is a hack - the packet memory allocation stuff is broken. The
 * packet is allocated if it was not really allocated
 */
96
int av_dup_packet(AVPacket *pkt);
97 98 99 100 101 102 103 104

/**
 * Free a packet
 *
 * @param pkt packet to free
 */
static inline void av_free_packet(AVPacket *pkt)
{
105
    if (pkt && pkt->destruct) {
106
        pkt->destruct(pkt);
107
    }
108
}
Fabrice Bellard's avatar
Fabrice Bellard committed
109

Fabrice Bellard's avatar
Fabrice Bellard committed
110 111 112
/*************************************************/
/* fractional numbers for exact pts handling */

113 114 115 116 117
/**
 * the exact value of the fractional number is: 'val + num / den'.
 * num is assumed to be such as 0 <= num < den
 * @deprecated Use AVRational instead
*/
Fabrice Bellard's avatar
Fabrice Bellard committed
118
typedef struct AVFrac {
119
    int64_t val, num, den;
Michael Niedermayer's avatar
Michael Niedermayer committed
120
} AVFrac attribute_deprecated;
Fabrice Bellard's avatar
Fabrice Bellard committed
121

Fabrice Bellard's avatar
Fabrice Bellard committed
122
/*************************************************/
123
/* input/output formats */
Fabrice Bellard's avatar
Fabrice Bellard committed
124

125 126
struct AVCodecTag;

Fabrice Bellard's avatar
Fabrice Bellard committed
127
struct AVFormatContext;
128

129
/** this structure contains the data a format has to probe a file */
130
typedef struct AVProbeData {
131
    const char *filename;
132 133 134 135
    unsigned char *buf;
    int buf_size;
} AVProbeData;

Michael Niedermayer's avatar
Michael Niedermayer committed
136
#define AVPROBE_SCORE_MAX 100               ///< max score, half of that is used for file extension based detection
137
#define AVPROBE_PADDING_SIZE 32             ///< extra allocated bytes at the end of the probe buffer
Fabrice Bellard's avatar
Fabrice Bellard committed
138 139

typedef struct AVFormatParameters {
140
    AVRational time_base;
Fabrice Bellard's avatar
Fabrice Bellard committed
141 142 143 144
    int sample_rate;
    int channels;
    int width;
    int height;
145
    enum PixelFormat pix_fmt;
146 147 148 149
    int channel; /**< used to select dv channel */
    const char *standard; /**< tv standard, NTSC, PAL, SECAM */
    int mpeg2ts_raw:1;  /**< force raw MPEG2 transport stream output, if possible */
    int mpeg2ts_compute_pcr:1; /**< compute exact PCR for each transport
150
                                  stream packet (only meaningful if
Ramiro Polla's avatar
Typos  
Ramiro Polla committed
151
                                  mpeg2ts_raw is TRUE) */
152
    int initial_pause:1;       /**< do not begin to play the stream
153
                                  immediately (RTSP only) */
154
    int prealloced_context:1;
155
#if LIBAVFORMAT_VERSION_INT < (53<<16)
156 157
    enum CodecID video_codec_id;
    enum CodecID audio_codec_id;
158
#endif
Fabrice Bellard's avatar
Fabrice Bellard committed
159 160
} AVFormatParameters;

161 162
//! demuxer will use url_fopen, no opened file should be provided by the caller
#define AVFMT_NOFILE        0x0001
163 164 165
#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
Fabrice Bellard's avatar
Fabrice Bellard committed
166
                                      raw picture data */
167
#define AVFMT_GLOBALHEADER  0x0040 /**< format wants global header */
Diego Biurrun's avatar
Diego Biurrun committed
168
#define AVFMT_NOTIMESTAMPS  0x0080 /**< format does not need / have any timestamps */
169
#define AVFMT_GENERIC_INDEX 0x0100 /**< use generic index building code */
170 171

typedef struct AVOutputFormat {
Fabrice Bellard's avatar
Fabrice Bellard committed
172 173 174
    const char *name;
    const char *long_name;
    const char *mime_type;
175
    const char *extensions; /**< comma separated filename extensions */
176
    /** size of private data so that it can be allocated in the wrapper */
177
    int priv_data_size;
Fabrice Bellard's avatar
Fabrice Bellard committed
178
    /* output support */
179 180
    enum CodecID audio_codec; /**< default audio codec */
    enum CodecID video_codec; /**< default video codec */
Fabrice Bellard's avatar
Fabrice Bellard committed
181
    int (*write_header)(struct AVFormatContext *);
182
    int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
Fabrice Bellard's avatar
Fabrice Bellard committed
183
    int (*write_trailer)(struct AVFormatContext *);
184
    /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */
185
    int flags;
186
    /** currently only used to set pixel format if not YUV420P */
187
    int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
188
    int (*interleave_packet)(struct AVFormatContext *, AVPacket *out, AVPacket *in, int flush);
189 190 191 192 193

    /**
     * list of supported codec_id-codec_tag pairs, ordered by "better choice first"
     * the arrays are all CODEC_ID_NONE terminated
     */
194
    const struct AVCodecTag **codec_tag;
195

196 197
    enum CodecID subtitle_codec; /**< default subtitle codec */

198 199 200
    /* private fields */
    struct AVOutputFormat *next;
} AVOutputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
201

202 203 204
typedef struct AVInputFormat {
    const char *name;
    const char *long_name;
205
    /** size of private data so that it can be allocated in the wrapper */
206
    int priv_data_size;
207
    /**
Diego Biurrun's avatar
Diego Biurrun committed
208 209 210
     * Tell if a given file has a chance of being parsed by this format.
     * 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.
211
     */
212
    int (*read_probe)(AVProbeData *);
213
    /** read the format header and initialize the AVFormatContext
Fabrice Bellard's avatar
Fabrice Bellard committed
214
       structure. Return 0 if OK. 'ap' if non NULL contains
Diego Biurrun's avatar
Diego Biurrun committed
215
       additional paramters. Only used in raw format right
216
       now. 'av_new_stream' should be called to create new streams.  */
Fabrice Bellard's avatar
Fabrice Bellard committed
217 218
    int (*read_header)(struct AVFormatContext *,
                       AVFormatParameters *ap);
219
    /** read one packet and put it in 'pkt'. pts and flags are also
220
       set. 'av_new_stream' can be called only if the flag
221
       AVFMTCTX_NOHEADER is used. */
Fabrice Bellard's avatar
Fabrice Bellard committed
222
    int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
223
    /** close the stream. The AVFormatContext and AVStreams are not
Fabrice Bellard's avatar
Fabrice Bellard committed
224 225
       freed by this function */
    int (*read_close)(struct AVFormatContext *);
226 227
    /**
     * seek to a given timestamp relative to the frames in
228 229
     * stream component stream_index
     * @param stream_index must not be -1
230
     * @param flags selects which direction should be preferred if no exact
231
     *              match is available
232
     * @return >= 0 on success (but not necessarily the new offset)
233
     */
234
    int (*read_seek)(struct AVFormatContext *,
235
                     int stream_index, int64_t timestamp, int flags);
236
    /**
237
     * gets the next timestamp in stream[stream_index].time_base units.
238
     * @return the timestamp or AV_NOPTS_VALUE if an error occured
239 240 241
     */
    int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
                              int64_t *pos, int64_t pos_limit);
242
    /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER */
Fabrice Bellard's avatar
Fabrice Bellard committed
243
    int flags;
244
    /** if extensions are defined, then no probe is done. You should
245 246 247
       usually not use extension format guessing because it is not
       reliable enough */
    const char *extensions;
248
    /** general purpose read only value that the format can use */
249
    int value;
250

251
    /** start/resume playing - only meaningful if using a network based format
252 253 254
       (RTSP) */
    int (*read_play)(struct AVFormatContext *);

255
    /** pause playing - only meaningful if using a network based format
256 257 258
       (RTSP) */
    int (*read_pause)(struct AVFormatContext *);

259
    const struct AVCodecTag **codec_tag;
260

261 262 263
    /* private fields */
    struct AVInputFormat *next;
} AVInputFormat;
Fabrice Bellard's avatar
Fabrice Bellard committed
264

Aurelien Jacobs's avatar
Aurelien Jacobs committed
265 266 267 268 269 270 271
enum AVStreamParseType {
    AVSTREAM_PARSE_NONE,
    AVSTREAM_PARSE_FULL,       /**< full parsing and repack */
    AVSTREAM_PARSE_HEADERS,    /**< only parse headers, don't repack */
    AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on packet boundary */
};

272 273 274 275
typedef struct AVIndexEntry {
    int64_t pos;
    int64_t timestamp;
#define AVINDEX_KEYFRAME 0x0001
Michael Niedermayer's avatar
Michael Niedermayer committed
276
    int flags:2;
Diego Biurrun's avatar
Diego Biurrun committed
277
    int size:30; //Yeah, trying to keep the size of this small to reduce memory requirements (it is 24 vs 32 byte due to possible 8byte align).
278
    int min_distance;         /**< min distance between this and the previous keyframe, used to avoid unneeded searching */
279 280
} AVIndexEntry;

281 282 283 284 285 286 287
#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

288 289 290
/**
 * Stream structure.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
291
 * Removal, reordering and changes to existing fields require a major
292
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
293
 * sizeof(AVStream) must not be used outside libav*.
294
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
295
typedef struct AVStream {
296 297 298
    int index;    /**< stream index in AVFormatContext */
    int id;       /**< format specific stream id */
    AVCodecContext *codec; /**< codec context */
299
    /**
Diego Biurrun's avatar
Diego Biurrun committed
300 301
     * Real base frame rate of the stream.
     * This is the lowest frame rate with which all timestamps can be
Ramiro Polla's avatar
Typos  
Ramiro Polla committed
302
     * represented accurately (it is the least common multiple of all
Diego Biurrun's avatar
Diego Biurrun committed
303 304 305
     * frame rates in the stream), Note, this value is just a guess!
     * For example if the timebase is 1/90000 and all frames have either
     * approximately 3600 or 1800 timer ticks then r_frame_rate will be 50/1.
306 307
     */
    AVRational r_frame_rate;
Fabrice Bellard's avatar
Fabrice Bellard committed
308
    void *priv_data;
309

310
    /* internal data used in av_find_stream_info() */
311
    int64_t first_dts;
312
    /** encoding: PTS generation when outputing stream */
313
    struct AVFrac pts;
314 315

    /**
Diego Biurrun's avatar
Diego Biurrun committed
316 317 318
     * This is the fundamental unit of time (in seconds) in terms
     * of which frame timestamps are represented. For fixed-fps content,
     * timebase should be 1/frame rate and timestamp increments should be
319 320
     * identically 1.
     */
321
    AVRational time_base;
322
    int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
Fabrice Bellard's avatar
Fabrice Bellard committed
323
    /* ffmpeg.c private use */
Panagiotis Issaris's avatar
Panagiotis Issaris committed
324
    int stream_copy; /**< if set, just copy stream */
Diego Biurrun's avatar
Diego Biurrun committed
325
    enum AVDiscard discard; ///< selects which packets can be discarded at will and do not need to be demuxed
326
    //FIXME move stuff to a flags field?
327
    /** quality, as it has been removed from AVCodecContext and put in AVVideoFrame
Diego Biurrun's avatar
Diego Biurrun committed
328
     * MN: dunno if that is the right place for it */
329
    float quality;
330
    /**
Diego Biurrun's avatar
Diego Biurrun committed
331 332 333
     * 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.
334
     * This may be undefined (AV_NOPTS_VALUE).
Diego Biurrun's avatar
Diego Biurrun committed
335 336
     * @note The ASF header does NOT contain a correct start_time the ASF
     * demuxer must NOT set this.
337
     */
338
    int64_t start_time;
339
    /**
Diego Biurrun's avatar
Diego Biurrun committed
340
     * Decoding: duration of the stream, in stream time base.
341 342 343
     * If a source file does not specify a duration, but does specify
     * a bitrate, this value will be estimates from bit rate and file size.
     */
344
    int64_t duration;
345

346
    char language[4]; /** ISO 639 3-letter language code (empty string if undefined) */
347

348
    /* av_read_frame() support */
Aurelien Jacobs's avatar
Aurelien Jacobs committed
349
    enum AVStreamParseType need_parsing;
350
    struct AVCodecParserContext *parser;
351

352
    int64_t cur_dts;
Michael Niedermayer's avatar
Michael Niedermayer committed
353 354
    int last_IP_duration;
    int64_t last_IP_pts;
355
    /* av_seek_frame() support */
356
    AVIndexEntry *index_entries; /**< only used if the format does not
357 358
                                    support seeking natively */
    int nb_index_entries;
Måns Rullgård's avatar
Måns Rullgård committed
359
    unsigned int index_entries_allocated_size;
360

361
    int64_t nb_frames;                 ///< number of frames in this stream if known or 0
362 363 364

#define MAX_REORDER_DELAY 4
    int64_t pts_buffer[MAX_REORDER_DELAY+1];
365 366

    char *filename; /**< source filename of the stream */
367 368

    int disposition; /**< AV_DISPOSITION_* bitfield */
Fabrice Bellard's avatar
Fabrice Bellard committed
369 370
} AVStream;

371 372
#define AV_PROGRAM_RUNNING 1

373 374
/**
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
375
 * Removal, reordering and changes to existing fields require a major
376
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
377
 * sizeof(AVProgram) must not be used outside libav*.
378
 */
379 380 381 382 383 384
typedef struct AVProgram {
    int            id;
    char           *provider_name; ///< Network name for DVB streams
    char           *name;          ///< Service name for DVB streams
    int            flags;
    enum AVDiscard discard;        ///< selects which program to discard and which to feed to the caller
385 386
    unsigned int   *stream_index;
    unsigned int   nb_stream_indexes;
387 388
} AVProgram;

389
#define AVFMTCTX_NOHEADER      0x0001 /**< signal that no header is present
390 391
                                         (streams are added dynamically) */

Fabrice Bellard's avatar
Fabrice Bellard committed
392 393
#define MAX_STREAMS 20

394 395 396
/**
 * format I/O context.
 * New fields can be added to the end with minor version bumps.
Diego Biurrun's avatar
Diego Biurrun committed
397
 * Removal, reordering and changes to existing fields require a major
398
 * version bump.
Diego Biurrun's avatar
Diego Biurrun committed
399
 * sizeof(AVFormatContext) must not be used outside libav*.
400
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
401
typedef struct AVFormatContext {
402
    const AVClass *av_class; /**< set by av_alloc_format_context */
403 404 405
    /* can only be iformat or oformat, not both at the same time */
    struct AVInputFormat *iformat;
    struct AVOutputFormat *oformat;
Fabrice Bellard's avatar
Fabrice Bellard committed
406
    void *priv_data;
407
    ByteIOContext *pb;
408
    unsigned int nb_streams;
Fabrice Bellard's avatar
Fabrice Bellard committed
409
    AVStream *streams[MAX_STREAMS];
410
    char filename[1024]; /**< input or output filename */
Fabrice Bellard's avatar
Fabrice Bellard committed
411
    /* stream info */
412
    int64_t timestamp;
Fabrice Bellard's avatar
Fabrice Bellard committed
413 414 415 416
    char title[512];
    char author[512];
    char copyright[512];
    char comment[512];
417
    char album[512];
418 419 420
    int year;  /**< ID3 year, 0 if none */
    int track; /**< track number, 0 if none */
    char genre[32]; /**< ID3 genre */
421

422
    int ctx_flags; /**< format specific flags, see AVFMTCTX_xx */
Fabrice Bellard's avatar
Fabrice Bellard committed
423
    /* private data for pts handling (do not modify directly) */
424
    /** This buffer is only needed when packets were already buffered but
Fabrice Bellard's avatar
Fabrice Bellard committed
425 426
       not decoded, for example to get the codec parameters in mpeg
       streams */
427 428
    struct AVPacketList *packet_buffer;

429
    /** decoding: position of the first frame of the component, in
430 431
       AV_TIME_BASE fractional seconds. NEVER set this value directly:
       it is deduced from the AVStream values.  */
432
    int64_t start_time;
433
    /** decoding: duration of the stream, in AV_TIME_BASE fractional
434 435 436
       seconds. NEVER set this value directly: it is deduced from the
       AVStream values.  */
    int64_t duration;
437
    /** decoding: total file size. 0 if unknown */
438
    int64_t file_size;
439
    /** decoding: total stream bitrate in bit/s, 0 if not
440 441 442
       available. Never set it directly if the file_size and the
       duration are known as ffmpeg can compute it automatically. */
    int bit_rate;
443 444 445 446 447 448 449 450

    /* av_read_frame() support */
    AVStream *cur_st;
    const uint8_t *cur_ptr;
    int cur_len;
    AVPacket cur_pkt;

    /* av_seek_frame() support */
451
    int64_t data_offset; /** offset of the first packet */
452
    int index_built;
453

454 455
    int mux_rate;
    int packet_size;
456 457
    int preload;
    int max_delay;
458

459 460
#define AVFMT_NOOUTPUTLOOP -1
#define AVFMT_INFINITEOUTPUTLOOP 0
461
    /** number of times to loop output in formats that support it */
462
    int loop_output;
463

464 465
    int flags;
#define AVFMT_FLAG_GENPTS       0x0001 ///< generate pts if missing even if it requires parsing future frames
466
#define AVFMT_FLAG_IGNIDX       0x0002 ///< ignore index
467
#define AVFMT_FLAG_NONBLOCK     0x0004 ///< do not block when reading packets from input
468 469

    int loop_input;
470
    /** decoding: size of data to probe; encoding unused */
471
    unsigned int probesize;
472 473 474 475 476

    /**
     * maximum duration in AV_TIME_BASE units over which the input should be analyzed in av_find_stream_info()
     */
    int max_analyze_duration;
477 478 479

    const uint8_t *key;
    int keylen;
480 481 482

    unsigned int nb_programs;
    AVProgram **programs;
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498

    /**
     * Forced video codec_id.
     * demuxing: set by user
     */
    enum CodecID video_codec_id;
    /**
     * Forced audio codec_id.
     * demuxing: set by user
     */
    enum CodecID audio_codec_id;
    /**
     * Forced subtitle codec_id.
     * demuxing: set by user
     */
    enum CodecID subtitle_codec_id;
499 500 501 502 503 504 505 506 507 508 509 510

    /**
     * Maximum amount of memory in bytes to use per stream for the index.
     * If the needed index exceeds this size entries will be discarded as
     * needed to maintain a smaller size. This can lead to slower or less
     * accurate seeking (depends on demuxer).
     * Demuxers for which a full in memory index is mandatory will ignore
     * this.
     * muxing  : unused
     * demuxing: set by user
     */
    unsigned int max_index_size;
511 512 513 514 515 516

    /**
     * Maximum ammount of memory in bytes to use for buffering frames that are
     * obtained from real-time capture devices.
     */
    unsigned int max_picture_buffer;
Fabrice Bellard's avatar
Fabrice Bellard committed
517 518 519 520 521 522 523
} AVFormatContext;

typedef struct AVPacketList {
    AVPacket pkt;
    struct AVPacketList *next;
} AVPacketList;

524
#if LIBAVFORMAT_VERSION_INT < (53<<16)
525 526
extern AVInputFormat *first_iformat;
extern AVOutputFormat *first_oformat;
527 528 529 530
#endif

AVInputFormat  *av_iformat_next(AVInputFormat  *f);
AVOutputFormat *av_oformat_next(AVOutputFormat *f);
Fabrice Bellard's avatar
Fabrice Bellard committed
531

532
enum CodecID av_guess_image2_codec(const char *filename);
533

534 535
/* XXX: use automatic init with either ELF sections or C file parser */
/* modules */
Fabrice Bellard's avatar
Fabrice Bellard committed
536

537 538 539
/* utils.c */
void av_register_input_format(AVInputFormat *format);
void av_register_output_format(AVOutputFormat *format);
540
AVOutputFormat *guess_stream_format(const char *short_name,
541
                                    const char *filename, const char *mime_type);
542
AVOutputFormat *guess_format(const char *short_name,
543
                             const char *filename, const char *mime_type);
544 545 546 547

/**
 * Guesses the codec id based upon muxer and filename.
 */
548
enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
549
                            const char *filename, const char *mime_type, enum CodecType type);
Fabrice Bellard's avatar
Fabrice Bellard committed
550

551
/**
552 553 554
 * Send a nice hexadecimal dump of a buffer to the specified file stream.
 *
 * @param f The file stream pointer where the dump should be sent to.
555 556
 * @param buf buffer
 * @param size buffer size
557 558
 *
 * @see av_hex_dump_log, av_pkt_dump, av_pkt_dump_log
559
 */
560
void av_hex_dump(FILE *f, uint8_t *buf, int size);
561 562

/**
563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579
 * Send a nice hexadecimal dump of a buffer to the log.
 *
 * @param avcl A pointer to an arbitrary struct of which the first field is a
 * pointer to an AVClass struct.
 * @param level The importance level of the message, lower values signifying
 * higher importance.
 * @param buf buffer
 * @param size buffer size
 *
 * @see av_hex_dump, av_pkt_dump, av_pkt_dump_log
 */
void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);

/**
 * Send a nice dump of a packet to the specified file stream.
 *
 * @param f The file stream pointer where the dump should be sent to.
580 581 582
 * @param pkt packet to dump
 * @param dump_payload true if the payload must be displayed too
 */
583
void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
Fabrice Bellard's avatar
Fabrice Bellard committed
584

585 586 587 588 589 590 591 592 593 594 595 596
/**
 * Send a nice dump of a packet to the log.
 *
 * @param avcl A pointer to an arbitrary struct of which the first field is a
 * pointer to an AVClass struct.
 * @param level The importance level of the message, lower values signifying
 * higher importance.
 * @param pkt packet to dump
 * @param dump_payload true if the payload must be displayed too
 */
void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);

Fabrice Bellard's avatar
Fabrice Bellard committed
597
void av_register_all(void);
Fabrice Bellard's avatar
Fabrice Bellard committed
598

599
/** codec tag <-> codec id */
600 601
enum CodecID av_codec_get_id(const struct AVCodecTag **tags, unsigned int tag);
unsigned int av_codec_get_tag(const struct AVCodecTag **tags, enum CodecID id);
602

603
/* media file input */
604 605 606 607

/**
 * finds AVInputFormat based on input format's short name.
 */
608
AVInputFormat *av_find_input_format(const char *short_name);
609 610 611 612 613 614 615

/**
 * Guess file format.
 *
 * @param is_opened whether the file is already opened, determines whether
 *                  demuxers with or without AVFMT_NOFILE are probed
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
616
AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
617 618 619 620 621

/**
 * Allocates all the structures needed to read an input stream.
 *        This does not open the needed codecs for decoding the stream[s].
 */
622 623
int av_open_input_stream(AVFormatContext **ic_ptr,
                         ByteIOContext *pb, const char *filename,
624
                         AVInputFormat *fmt, AVFormatParameters *ap);
625 626

/**
Ramiro Polla's avatar
Typos  
Ramiro Polla committed
627
 * Open a media file as input. The codecs are not opened. Only the file
628 629 630 631 632 633
 * header (if present) is read.
 *
 * @param ic_ptr the opened media file handle is put here
 * @param filename filename to open.
 * @param fmt if non NULL, force the file format to use
 * @param buf_size optional buffer size (zero if default is OK)
Diego Biurrun's avatar
Diego Biurrun committed
634
 * @param ap additional parameters needed when opening the file (NULL if default)
635 636
 * @return 0 if OK. AVERROR_xxx otherwise.
 */
637
int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
638 639 640
                       AVInputFormat *fmt,
                       int buf_size,
                       AVFormatParameters *ap);
641 642
/**
 * Allocate an AVFormatContext.
Diego Biurrun's avatar
Diego Biurrun committed
643
 * Can be freed with av_free() but do not forget to free everything you
644 645
 * explicitly allocated as well!
 */
646
AVFormatContext *av_alloc_format_context(void);
647

648 649 650 651 652 653 654 655 656 657
/**
 * Read packets of a media file to get stream information. This
 * is useful for file formats with no headers such as MPEG. This
 * function also computes the real frame rate in case of mpeg2 repeat
 * frame mode.
 * The logical file position is not changed by this function;
 * examined packets may be buffered for later processing.
 *
 * @param ic media file handle
 * @return >=0 if OK. AVERROR_xxx if error.
Panagiotis Issaris's avatar
Typo  
Panagiotis Issaris committed
658
 * @todo Let user decide somehow what information is needed so we do not waste time getting stuff the user does not need.
659
 */
660
int av_find_stream_info(AVFormatContext *ic);
661 662 663 664

/**
 * Read a transport packet from a media file.
 *
Ramiro Polla's avatar
Typos  
Ramiro Polla committed
665
 * This function is obsolete and should never be used.
666 667 668 669 670 671
 * Use av_read_frame() instead.
 *
 * @param s media file handle
 * @param pkt is filled
 * @return 0 if OK. AVERROR_xxx if error.
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
672
int av_read_packet(AVFormatContext *s, AVPacket *pkt);
673 674 675 676 677 678 679 680 681 682 683 684 685

/**
 * Return the next frame of a stream.
 *
 * The returned packet is valid
 * until the next av_read_frame() or until av_close_input_file() and
 * must be freed with av_free_packet. For video, the packet contains
 * exactly one frame. For audio, it contains an integer number of
 * frames if each frame has a known fixed size (e.g. PCM or ADPCM
 * data). If the audio frames have a variable size (e.g. MPEG audio),
 * then it contains one frame.
 *
 * pkt->pts, pkt->dts and pkt->duration are always set to correct
686
 * values in AVStream.timebase units (and guessed if the format cannot
687 688 689 690 691 692
 * provided them). pkt->pts can be AV_NOPTS_VALUE if the video format
 * has B frames, so it is better to rely on pkt->dts if you do not
 * decompress the payload.
 *
 * @return 0 if OK, < 0 if error or end of file.
 */
693
int av_read_frame(AVFormatContext *s, AVPacket *pkt);
694 695 696 697 698 699 700 701 702 703 704 705

/**
 * Seek to the key frame at timestamp.
 * 'timestamp' in 'stream_index'.
 * @param stream_index If stream_index is (-1), a default
 * stream is selected, and timestamp is automatically converted
 * from AV_TIME_BASE units to the stream specific time_base.
 * @param timestamp timestamp in AVStream.time_base units
 *        or if there is no stream specified then in AV_TIME_BASE units
 * @param flags flags which select direction and seeking mode
 * @return >= 0 on success
 */
706
int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags);
707 708 709 710 711

/**
 * start playing a network based stream (e.g. RTSP stream) at the
 * current position
 */
712
int av_read_play(AVFormatContext *s);
713 714 715 716 717 718

/**
 * Pause a network based stream (e.g. RTSP stream).
 *
 * Use av_read_play() to resume it.
 */
719
int av_read_pause(AVFormatContext *s);
720

721 722 723 724 725 726
/**
 * Free a AVFormatContext allocated by av_open_input_stream.
 * @param s context to free
 */
void av_close_input_stream(AVFormatContext *s);

727 728 729 730 731
/**
 * Close a media file (but not its codecs).
 *
 * @param s media file handle
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
732
void av_close_input_file(AVFormatContext *s);
733 734 735 736 737 738 739 740 741 742 743

/**
 * Add a new stream to a media file.
 *
 * Can only be called in the read_header() function. If the flag
 * AVFMTCTX_NOHEADER is in the format context, then new streams
 * can be added in read_packet too.
 *
 * @param s media file handle
 * @param id file format dependent stream id
 */
744
AVStream *av_new_stream(AVFormatContext *s, int id);
745
AVProgram *av_new_program(AVFormatContext *s, int id);
746 747 748 749 750 751 752 753 754 755

/**
 * Set the pts for a given stream.
 *
 * @param s stream
 * @param pts_wrap_bits number of bits effectively used by the pts
 *        (used for wrap control, 33 is the value for MPEG)
 * @param pts_num numerator to convert to seconds (MPEG: 1)
 * @param pts_den denominator to convert to seconds (MPEG: 90000)
 */
756
void av_set_pts_info(AVStream *s, int pts_wrap_bits,
Fabrice Bellard's avatar
Fabrice Bellard committed
757
                     int pts_num, int pts_den);
Fabrice Bellard's avatar
Fabrice Bellard committed
758

759 760
#define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
#define AVSEEK_FLAG_BYTE     2 ///< seeking based on position in bytes
761
#define AVSEEK_FLAG_ANY      4 ///< seek to any frame, even non keyframes
762

763
int av_find_default_stream_index(AVFormatContext *s);
764 765 766 767 768 769 770 771 772

/**
 * Gets the index for a specific timestamp.
 * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond to
 *                 the timestamp which is <= the requested one, if backward is 0
 *                 then it will be >=
 *              if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
 * @return < 0 if no such timestamp could be found
 */
773
int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
774

775 776 777 778 779 780 781 782 783
/**
 * Ensures the index uses less memory than the maximum specified in
 * AVFormatContext.max_index_size, by discarding entries if it grows
 * too large.
 * This function is not part of the public API and should only be called
 * by demuxers.
 */
void ff_reduce_index(AVFormatContext *s, int stream_index);

784 785 786 787 788
/**
 * Add a index entry into a sorted list updateing if it is already there.
 *
 * @param timestamp timestamp in the timebase of the given stream
 */
789
int av_add_index_entry(AVStream *st,
Michael Niedermayer's avatar
Michael Niedermayer committed
790
                       int64_t pos, int64_t timestamp, int size, int distance, int flags);
791 792 793

/**
 * Does a binary search using av_index_search_timestamp() and AVCodec.read_timestamp().
Diego Biurrun's avatar
Diego Biurrun committed
794
 * This is not supposed to be called directly by a user application, but by demuxers.
795 796 797
 * @param target_ts target timestamp in the time base of the given stream
 * @param stream_index stream number
 */
798
int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags);
799 800 801 802 803

/**
 * Updates cur_dts of all streams based on given timestamp and AVStream.
 *
 * Stream ref_st unchanged, others set cur_dts in their native timebase
Diego Biurrun's avatar
Diego Biurrun committed
804
 * only needed for timestamp wrapping or if (dts not set and pts!=dts).
805 806 807
 * @param timestamp new dts expressed in time_base of param ref_st
 * @param ref_st reference stream giving time_base of param timestamp
 */
808
void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
809 810 811

/**
 * Does a binary search using read_timestamp().
Diego Biurrun's avatar
Diego Biurrun committed
812
 * This is not supposed to be called directly by a user application, but by demuxers.
813 814 815
 * @param target_ts target timestamp in the time base of the given stream
 * @param stream_index stream number
 */
816
int64_t av_gen_search(AVFormatContext *s, int stream_index, int64_t target_ts, int64_t pos_min, int64_t pos_max, int64_t pos_limit, int64_t ts_min, int64_t ts_max, int flags, int64_t *ts_ret, int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t ));
817

818
/** media file output */
819
int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
820 821

/**
Diego Biurrun's avatar
Diego Biurrun committed
822 823
 * Allocate the stream private data and write the stream header to an
 * output media file.
824 825 826 827
 *
 * @param s media file handle
 * @return 0 if OK. AVERROR_xxx if error.
 */