Add missing header #includes.
[ffmpeg.git] / libavformat / avformat.h
1 /*
2  * copyright (c) 2001 Fabrice Bellard
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * 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  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20
21 #ifndef FFMPEG_AVFORMAT_H
22 #define FFMPEG_AVFORMAT_H
23
24 #define LIBAVFORMAT_VERSION_MAJOR 52
25 #define LIBAVFORMAT_VERSION_MINOR 18
26 #define LIBAVFORMAT_VERSION_MICRO  0
27
28 #define LIBAVFORMAT_VERSION_INT AV_VERSION_INT(LIBAVFORMAT_VERSION_MAJOR, \
29                                                LIBAVFORMAT_VERSION_MINOR, \
30                                                LIBAVFORMAT_VERSION_MICRO)
31 #define LIBAVFORMAT_VERSION     AV_VERSION(LIBAVFORMAT_VERSION_MAJOR,   \
32                                            LIBAVFORMAT_VERSION_MINOR,   \
33                                            LIBAVFORMAT_VERSION_MICRO)
34 #define LIBAVFORMAT_BUILD       LIBAVFORMAT_VERSION_INT
35
36 #define LIBAVFORMAT_IDENT       "Lavf" AV_STRINGIFY(LIBAVFORMAT_VERSION)
37
38 #include <stdint.h>
39 #include <time.h>
40 #include <stdio.h>  /* FILE */
41 #include "libavcodec/avcodec.h"
42
43 #include "avio.h"
44
45 /* packet functions */
46
47 typedef struct AVPacket {
48     /**
49      * Presentation time stamp in time_base units.
50      * This is the time at which the decompressed packet will be presented
51      * to the user.
52      * Can be AV_NOPTS_VALUE if it is not stored in the file.
53      * pts MUST be larger or equal to dts as presentation can not happen before
54      * decompression, unless one wants to view hex dumps. Some formats misuse
55      * the terms dts and pts/cts to mean something different, these timestamps
56      * must be converted to true pts/dts before they are stored in AVPacket.
57      */
58     int64_t pts;
59     /**
60      * Decompression time stamp in time_base units.
61      * This is the time at which the packet is decompressed.
62      * Can be AV_NOPTS_VALUE if it is not stored in the file.
63      */
64     int64_t dts;
65     uint8_t *data;
66     int   size;
67     int   stream_index;
68     int   flags;
69     int   duration;                         ///< presentation duration in time_base units (0 if not available)
70     void  (*destruct)(struct AVPacket *);
71     void  *priv;
72     int64_t pos;                            ///< byte position in stream, -1 if unknown
73 } AVPacket;
74 #define PKT_FLAG_KEY   0x0001
75
76 void av_destruct_packet_nofree(AVPacket *pkt);
77
78 /**
79  * Default packet destructor.
80  */
81 void av_destruct_packet(AVPacket *pkt);
82
83 /**
84  * Initialize optional fields of a packet to default values.
85  *
86  * @param pkt packet
87  */
88 void av_init_packet(AVPacket *pkt);
89
90 /**
91  * Allocate the payload of a packet and initialize its fields to default values.
92  *
93  * @param pkt packet
94  * @param size wanted payload size
95  * @return 0 if OK. AVERROR_xxx otherwise.
96  */
97 int av_new_packet(AVPacket *pkt, int size);
98
99 /**
100  * Allocate and read the payload of a packet and initialize its fields to default values.
101  *
102  * @param pkt packet
103  * @param size wanted payload size
104  * @return >0 (read size) if OK. AVERROR_xxx otherwise.
105  */
106 int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
107
108 /**
109  * @warning This is a hack - the packet memory allocation stuff is broken. The
110  * packet is allocated if it was not really allocated
111  */
112 int av_dup_packet(AVPacket *pkt);
113
114 /**
115  * Free a packet
116  *
117  * @param pkt packet to free
118  */
119 static inline void av_free_packet(AVPacket *pkt)
120 {
121     if (pkt && pkt->destruct) {
122         pkt->destruct(pkt);
123     }
124 }
125
126 /*************************************************/
127 /* fractional numbers for exact pts handling */
128
129 /**
130  * the exact value of the fractional number is: 'val + num / den'.
131  * num is assumed to be such as 0 <= num < den
132  * @deprecated Use AVRational instead
133 */
134 typedef struct AVFrac {
135     int64_t val, num, den;
136 } AVFrac attribute_deprecated;
137
138 /*************************************************/
139 /* input/output formats */
140
141 struct AVCodecTag;
142
143 struct AVFormatContext;
144
145 /** this structure contains the data a format has to probe a file */
146 typedef struct AVProbeData {
147     const char *filename;
148     unsigned char *buf;
149     int buf_size;
150 } AVProbeData;
151
152 #define AVPROBE_SCORE_MAX 100               ///< max score, half of that is used for file extension based detection
153 #define AVPROBE_PADDING_SIZE 32             ///< extra allocated bytes at the end of the probe buffer
154
155 typedef struct AVFormatParameters {
156     AVRational time_base;
157     int sample_rate;
158     int channels;
159     int width;
160     int height;
161     enum PixelFormat pix_fmt;
162     int channel; /**< used to select dv channel */
163     const char *standard; /**< tv standard, NTSC, PAL, SECAM */
164     unsigned int mpeg2ts_raw:1;  /**< force raw MPEG2 transport stream output, if possible */
165     unsigned int mpeg2ts_compute_pcr:1; /**< compute exact PCR for each transport
166                                             stream packet (only meaningful if
167                                             mpeg2ts_raw is TRUE) */
168     unsigned int initial_pause:1;       /**< do not begin to play the stream
169                                             immediately (RTSP only) */
170     unsigned int prealloced_context:1;
171 #if LIBAVFORMAT_VERSION_INT < (53<<16)
172     enum CodecID video_codec_id;
173     enum CodecID audio_codec_id;
174 #endif
175 } AVFormatParameters;
176
177 //! demuxer will use url_fopen, no opened file should be provided by the caller
178 #define AVFMT_NOFILE        0x0001
179 #define AVFMT_NEEDNUMBER    0x0002 /**< needs '%d' in filename */
180 #define AVFMT_SHOW_IDS      0x0008 /**< show format stream IDs numbers */
181 #define AVFMT_RAWPICTURE    0x0020 /**< format wants AVPicture structure for
182                                       raw picture data */
183 #define AVFMT_GLOBALHEADER  0x0040 /**< format wants global header */
184 #define AVFMT_NOTIMESTAMPS  0x0080 /**< format does not need / have any timestamps */
185 #define AVFMT_GENERIC_INDEX 0x0100 /**< use generic index building code */
186
187 typedef struct AVOutputFormat {
188     const char *name;
189     /**
190      * Descriptive name for the format, meant to be more human-readable
191      * than \p name. You \e should use the NULL_IF_CONFIG_SMALL() macro
192      * to define it.
193      */
194     const char *long_name;
195     const char *mime_type;
196     const char *extensions; /**< comma separated filename extensions */
197     /** size of private data so that it can be allocated in the wrapper */
198     int priv_data_size;
199     /* output support */
200     enum CodecID audio_codec; /**< default audio codec */
201     enum CodecID video_codec; /**< default video codec */
202     int (*write_header)(struct AVFormatContext *);
203     int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
204     int (*write_trailer)(struct AVFormatContext *);
205     /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */
206     int flags;
207     /** currently only used to set pixel format if not YUV420P */
208     int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
209     int (*interleave_packet)(struct AVFormatContext *, AVPacket *out, AVPacket *in, int flush);
210
211     /**
212      * list of supported codec_id-codec_tag pairs, ordered by "better choice first"
213      * the arrays are all CODEC_ID_NONE terminated
214      */
215     const struct AVCodecTag **codec_tag;
216
217     enum CodecID subtitle_codec; /**< default subtitle codec */
218
219     /* private fields */
220     struct AVOutputFormat *next;
221 } AVOutputFormat;
222
223 typedef struct AVInputFormat {
224     const char *name;
225     /**
226      * Descriptive name for the format, meant to be more human-readable
227      * than \p name. You \e should use the NULL_IF_CONFIG_SMALL() macro
228      * to define it.
229      */
230     const char *long_name;
231     /** size of private data so that it can be allocated in the wrapper */
232     int priv_data_size;
233     /**
234      * Tell if a given file has a chance of being parsed by this format.
235      * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes
236      * big so you do not have to check for that unless you need more.
237      */
238     int (*read_probe)(AVProbeData *);
239     /** read the format header and initialize the AVFormatContext
240        structure. Return 0 if OK. 'ap' if non NULL contains
241        additional paramters. Only used in raw format right
242        now. 'av_new_stream' should be called to create new streams.  */
243     int (*read_header)(struct AVFormatContext *,
244                        AVFormatParameters *ap);
245     /** read one packet and put it in 'pkt'. pts and flags are also
246        set. 'av_new_stream' can be called only if the flag
247        AVFMTCTX_NOHEADER is used. */
248     int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
249     /** close the stream. The AVFormatContext and AVStreams are not
250        freed by this function */
251     int (*read_close)(struct AVFormatContext *);
252     /**
253      * seek to a given timestamp relative to the frames in
254      * stream component stream_index
255      * @param stream_index must not be -1
256      * @param flags selects which direction should be preferred if no exact
257      *              match is available
258      * @return >= 0 on success (but not necessarily the new offset)
259      */
260     int (*read_seek)(struct AVFormatContext *,
261                      int stream_index, int64_t timestamp, int flags);
262     /**
263      * gets the next timestamp in stream[stream_index].time_base units.
264      * @return the timestamp or AV_NOPTS_VALUE if an error occurred
265      */
266     int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
267                               int64_t *pos, int64_t pos_limit);
268     /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER */
269     int flags;
270     /** if extensions are defined, then no probe is done. You should
271        usually not use extension format guessing because it is not
272        reliable enough */
273     const char *extensions;
274     /** general purpose read only value that the format can use */
275     int value;
276
277     /** start/resume playing - only meaningful if using a network based format
278        (RTSP) */
279     int (*read_play)(struct AVFormatContext *);
280
281     /** pause playing - only meaningful if using a network based format
282        (RTSP) */
283     int (*read_pause)(struct AVFormatContext *);
284
285     const struct AVCodecTag **codec_tag;
286
287     /* private fields */
288     struct AVInputFormat *next;
289 } AVInputFormat;
290
291 enum AVStreamParseType {
292     AVSTREAM_PARSE_NONE,
293     AVSTREAM_PARSE_FULL,       /**< full parsing and repack */
294     AVSTREAM_PARSE_HEADERS,    /**< only parse headers, don't repack */
295     AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on packet boundary */
296 };
297
298 typedef struct AVIndexEntry {
299     int64_t pos;
300     int64_t timestamp;
301 #define AVINDEX_KEYFRAME 0x0001
302     int flags:2;
303     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).
304     int min_distance;         /**< min distance between this and the previous keyframe, used to avoid unneeded searching */
305 } AVIndexEntry;
306
307 #define AV_DISPOSITION_DEFAULT   0x0001
308 #define AV_DISPOSITION_DUB       0x0002
309 #define AV_DISPOSITION_ORIGINAL  0x0004
310 #define AV_DISPOSITION_COMMENT   0x0008
311 #define AV_DISPOSITION_LYRICS    0x0010
312 #define AV_DISPOSITION_KARAOKE   0x0020
313
314 /**
315  * Stream structure.
316  * New fields can be added to the end with minor version bumps.
317  * Removal, reordering and changes to existing fields require a major
318  * version bump.
319  * sizeof(AVStream) must not be used outside libav*.
320  */
321 typedef struct AVStream {
322     int index;    /**< stream index in AVFormatContext */
323     int id;       /**< format specific stream id */
324     AVCodecContext *codec; /**< codec context */
325     /**
326      * Real base frame rate of the stream.
327      * This is the lowest frame rate with which all timestamps can be
328      * represented accurately (it is the least common multiple of all
329      * frame rates in the stream), Note, this value is just a guess!
330      * For example if the timebase is 1/90000 and all frames have either
331      * approximately 3600 or 1800 timer ticks then r_frame_rate will be 50/1.
332      */
333     AVRational r_frame_rate;
334     void *priv_data;
335
336     /* internal data used in av_find_stream_info() */
337     int64_t first_dts;
338     /** encoding: PTS generation when outputing stream */
339     struct AVFrac pts;
340
341     /**
342      * This is the fundamental unit of time (in seconds) in terms
343      * of which frame timestamps are represented. For fixed-fps content,
344      * timebase should be 1/frame rate and timestamp increments should be
345      * identically 1.
346      */
347     AVRational time_base;
348     int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
349     /* ffmpeg.c private use */
350     int stream_copy; /**< if set, just copy stream */
351     enum AVDiscard discard; ///< selects which packets can be discarded at will and do not need to be demuxed
352     //FIXME move stuff to a flags field?
353     /** quality, as it has been removed from AVCodecContext and put in AVVideoFrame
354      * MN: dunno if that is the right place for it */
355     float quality;
356     /**
357      * Decoding: pts of the first frame of the stream, in stream time base.
358      * Only set this if you are absolutely 100% sure that the value you set
359      * it to really is the pts of the first frame.
360      * This may be undefined (AV_NOPTS_VALUE).
361      * @note The ASF header does NOT contain a correct start_time the ASF
362      * demuxer must NOT set this.
363      */
364     int64_t start_time;
365     /**
366      * Decoding: duration of the stream, in stream time base.
367      * If a source file does not specify a duration, but does specify
368      * a bitrate, this value will be estimates from bit rate and file size.
369      */
370     int64_t duration;
371
372     char language[4]; /** ISO 639 3-letter language code (empty string if undefined) */
373
374     /* av_read_frame() support */
375     enum AVStreamParseType need_parsing;
376     struct AVCodecParserContext *parser;
377
378     int64_t cur_dts;
379     int last_IP_duration;
380     int64_t last_IP_pts;
381     /* av_seek_frame() support */
382     AVIndexEntry *index_entries; /**< only used if the format does not
383                                     support seeking natively */
384     int nb_index_entries;
385     unsigned int index_entries_allocated_size;
386
387     int64_t nb_frames;                 ///< number of frames in this stream if known or 0
388
389 #define MAX_REORDER_DELAY 4
390     int64_t pts_buffer[MAX_REORDER_DELAY+1];
391
392     char *filename; /**< source filename of the stream */
393
394     int disposition; /**< AV_DISPOSITION_* bitfield */
395
396     AVProbeData probe_data;
397 } AVStream;
398
399 #define AV_PROGRAM_RUNNING 1
400
401 /**
402  * New fields can be added to the end with minor version bumps.
403  * Removal, reordering and changes to existing fields require a major
404  * version bump.
405  * sizeof(AVProgram) must not be used outside libav*.
406  */
407 typedef struct AVProgram {
408     int            id;
409     char           *provider_name; ///< Network name for DVB streams
410     char           *name;          ///< Service name for DVB streams
411     int            flags;
412     enum AVDiscard discard;        ///< selects which program to discard and which to feed to the caller
413     unsigned int   *stream_index;
414     unsigned int   nb_stream_indexes;
415 } AVProgram;
416
417 #define AVFMTCTX_NOHEADER      0x0001 /**< signal that no header is present
418                                          (streams are added dynamically) */
419
420 typedef struct AVChapter {
421     int id;                 ///< Unique id to identify the chapter
422     AVRational time_base;   ///< Timebase in which the start/end timestamps are specified
423     int64_t start, end;     ///< chapter start/end time in time_base units
424     char *title;            ///< chapter title
425 } AVChapter;
426
427 #define MAX_STREAMS 20
428
429 /**
430  * format I/O context.
431  * New fields can be added to the end with minor version bumps.
432  * Removal, reordering and changes to existing fields require a major
433  * version bump.
434  * sizeof(AVFormatContext) must not be used outside libav*.
435  */
436 typedef struct AVFormatContext {
437     const AVClass *av_class; /**< set by av_alloc_format_context */
438     /* can only be iformat or oformat, not both at the same time */
439     struct AVInputFormat *iformat;
440     struct AVOutputFormat *oformat;
441     void *priv_data;
442     ByteIOContext *pb;
443     unsigned int nb_streams;
444     AVStream *streams[MAX_STREAMS];
445     char filename[1024]; /**< input or output filename */
446     /* stream info */
447     int64_t timestamp;
448     char title[512];
449     char author[512];
450     char copyright[512];
451     char comment[512];
452     char album[512];
453     int year;  /**< ID3 year, 0 if none */
454     int track; /**< track number, 0 if none */
455     char genre[32]; /**< ID3 genre */
456
457     int ctx_flags; /**< format specific flags, see AVFMTCTX_xx */
458     /* private data for pts handling (do not modify directly) */
459     /** This buffer is only needed when packets were already buffered but
460        not decoded, for example to get the codec parameters in mpeg
461        streams */
462     struct AVPacketList *packet_buffer;
463
464     /** decoding: position of the first frame of the component, in
465        AV_TIME_BASE fractional seconds. NEVER set this value directly:
466        it is deduced from the AVStream values.  */
467     int64_t start_time;
468     /** decoding: duration of the stream, in AV_TIME_BASE fractional
469        seconds. NEVER set this value directly: it is deduced from the
470        AVStream values.  */
471     int64_t duration;
472     /** decoding: total file size. 0 if unknown */
473     int64_t file_size;
474     /** decoding: total stream bitrate in bit/s, 0 if not
475        available. Never set it directly if the file_size and the
476        duration are known as ffmpeg can compute it automatically. */
477     int bit_rate;
478
479     /* av_read_frame() support */
480     AVStream *cur_st;
481     const uint8_t *cur_ptr;
482     int cur_len;
483     AVPacket cur_pkt;
484
485     /* av_seek_frame() support */
486     int64_t data_offset; /** offset of the first packet */
487     int index_built;
488
489     int mux_rate;
490     int packet_size;
491     int preload;
492     int max_delay;
493
494 #define AVFMT_NOOUTPUTLOOP -1
495 #define AVFMT_INFINITEOUTPUTLOOP 0
496     /** number of times to loop output in formats that support it */
497     int loop_output;
498
499     int flags;
500 #define AVFMT_FLAG_GENPTS       0x0001 ///< generate pts if missing even if it requires parsing future frames
501 #define AVFMT_FLAG_IGNIDX       0x0002 ///< ignore index
502 #define AVFMT_FLAG_NONBLOCK     0x0004 ///< do not block when reading packets from input
503
504     int loop_input;
505     /** decoding: size of data to probe; encoding unused */
506     unsigned int probesize;
507
508     /**
509      * maximum duration in AV_TIME_BASE units over which the input should be analyzed in av_find_stream_info()
510      */
511     int max_analyze_duration;
512
513     const uint8_t *key;
514     int keylen;
515
516     unsigned int nb_programs;
517     AVProgram **programs;
518
519     /**
520      * Forced video codec_id.
521      * demuxing: set by user
522      */
523     enum CodecID video_codec_id;
524     /**
525      * Forced audio codec_id.
526      * demuxing: set by user
527      */
528     enum CodecID audio_codec_id;
529     /**
530      * Forced subtitle codec_id.
531      * demuxing: set by user
532      */
533     enum CodecID subtitle_codec_id;
534
535     /**
536      * Maximum amount of memory in bytes to use per stream for the index.
537      * If the needed index exceeds this size entries will be discarded as
538      * needed to maintain a smaller size. This can lead to slower or less
539      * accurate seeking (depends on demuxer).
540      * Demuxers for which a full in memory index is mandatory will ignore
541      * this.
542      * muxing  : unused
543      * demuxing: set by user
544      */
545     unsigned int max_index_size;
546
547     /**
548      * Maximum amount of memory in bytes to use for buffering frames
549      * obtained from real-time capture devices.
550      */
551     unsigned int max_picture_buffer;
552
553     unsigned int nb_chapters;
554     AVChapter **chapters;
555
556     /**
557      * Flags to enable debuging.
558      */
559     int debug;
560 #define FF_FDEBUG_TS        0x0001
561
562     /**
563      * raw packets from the demuxer, prior to parsing and decoding.
564      * This buffer is used for buffering packets until the codec can
565      * be identified, as parsing cannot be done without knowing the
566      * codec.
567      */
568     struct AVPacketList *raw_packet_buffer;
569 } AVFormatContext;
570
571 typedef struct AVPacketList {
572     AVPacket pkt;
573     struct AVPacketList *next;
574 } AVPacketList;
575
576 #if LIBAVFORMAT_VERSION_INT < (53<<16)
577 extern AVInputFormat *first_iformat;
578 extern AVOutputFormat *first_oformat;
579 #endif
580
581 AVInputFormat  *av_iformat_next(AVInputFormat  *f);
582 AVOutputFormat *av_oformat_next(AVOutputFormat *f);
583
584 enum CodecID av_guess_image2_codec(const char *filename);
585
586 /* XXX: use automatic init with either ELF sections or C file parser */
587 /* modules */
588
589 /* utils.c */
590 void av_register_input_format(AVInputFormat *format);
591 void av_register_output_format(AVOutputFormat *format);
592 AVOutputFormat *guess_stream_format(const char *short_name,
593                                     const char *filename, const char *mime_type);
594 AVOutputFormat *guess_format(const char *short_name,
595                              const char *filename, const char *mime_type);
596
597 /**
598  * Guesses the codec id based upon muxer and filename.
599  */
600 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
601                             const char *filename, const char *mime_type, enum CodecType type);
602
603 /**
604  * Send a nice hexadecimal dump of a buffer to the specified file stream.
605  *
606  * @param f The file stream pointer where the dump should be sent to.
607  * @param buf buffer
608  * @param size buffer size
609  *
610  * @see av_hex_dump_log, av_pkt_dump, av_pkt_dump_log
611  */
612 void av_hex_dump(FILE *f, uint8_t *buf, int size);
613
614 /**
615  * Send a nice hexadecimal dump of a buffer to the log.
616  *
617  * @param avcl A pointer to an arbitrary struct of which the first field is a
618  * pointer to an AVClass struct.
619  * @param level The importance level of the message, lower values signifying
620  * higher importance.
621  * @param buf buffer
622  * @param size buffer size
623  *
624  * @see av_hex_dump, av_pkt_dump, av_pkt_dump_log
625  */
626 void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
627
628 /**
629  * Send a nice dump of a packet to the specified file stream.
630  *
631  * @param f The file stream pointer where the dump should be sent to.
632  * @param pkt packet to dump
633  * @param dump_payload true if the payload must be displayed too
634  */
635 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
636
637 /**
638  * Send a nice dump of a packet to the log.
639  *
640  * @param avcl A pointer to an arbitrary struct of which the first field is a
641  * pointer to an AVClass struct.
642  * @param level The importance level of the message, lower values signifying
643  * higher importance.
644  * @param pkt packet to dump
645  * @param dump_payload true if the payload must be displayed too
646  */
647 void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
648
649 void av_register_all(void);
650
651 /** codec tag <-> codec id */
652 enum CodecID av_codec_get_id(const struct AVCodecTag **tags, unsigned int tag);
653 unsigned int av_codec_get_tag(const struct AVCodecTag **tags, enum CodecID id);
654
655 /* media file input */
656
657 /**
658  * finds AVInputFormat based on input format's short name.
659  */
660 AVInputFormat *av_find_input_format(const char *short_name);
661
662 /**
663  * Guess file format.
664  *
665  * @param is_opened whether the file is already opened, determines whether
666  *                  demuxers with or without AVFMT_NOFILE are probed
667  */
668 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
669
670 /**
671  * Allocates all the structures needed to read an input stream.
672  *        This does not open the needed codecs for decoding the stream[s].
673  */
674 int av_open_input_stream(AVFormatContext **ic_ptr,
675                          ByteIOContext *pb, const char *filename,
676                          AVInputFormat *fmt, AVFormatParameters *ap);
677
678 /**
679  * Open a media file as input. The codecs are not opened. Only the file
680  * header (if present) is read.
681  *
682  * @param ic_ptr the opened media file handle is put here
683  * @param filename filename to open.
684  * @param fmt if non NULL, force the file format to use
685  * @param buf_size optional buffer size (zero if default is OK)
686  * @param ap additional parameters needed when opening the file (NULL if default)
687  * @return 0 if OK. AVERROR_xxx otherwise.
688  */
689 int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
690                        AVInputFormat *fmt,
691                        int buf_size,
692                        AVFormatParameters *ap);
693 /**
694  * Allocate an AVFormatContext.
695  * Can be freed with av_free() but do not forget to free everything you
696  * explicitly allocated as well!
697  */
698 AVFormatContext *av_alloc_format_context(void);
699
700 /**
701  * Read packets of a media file to get stream information. This
702  * is useful for file formats with no headers such as MPEG. This
703  * function also computes the real frame rate in case of mpeg2 repeat
704  * frame mode.
705  * The logical file position is not changed by this function;
706  * examined packets may be buffered for later processing.
707  *
708  * @param ic media file handle
709  * @return >=0 if OK. AVERROR_xxx if error.
710  * @todo Let user decide somehow what information is needed so we do not waste time getting stuff the user does not need.
711  */
712 int av_find_stream_info(AVFormatContext *ic);
713
714 /**
715  * Read a transport packet from a media file.
716  *
717  * This function is obsolete and should never be used.
718  * Use av_read_frame() instead.
719  *
720  * @param s media file handle
721  * @param pkt is filled
722  * @return 0 if OK. AVERROR_xxx if error.
723  */
724 int av_read_packet(AVFormatContext *s, AVPacket *pkt);
725
726 /**
727  * Return the next frame of a stream.
728  *
729  * The returned packet is valid
730  * until the next av_read_frame() or until av_close_input_file() and
731  * must be freed with av_free_packet. For video, the packet contains
732  * exactly one frame. For audio, it contains an integer number of
733  * frames if each frame has a known fixed size (e.g. PCM or ADPCM
734  * data). If the audio frames have a variable size (e.g. MPEG audio),
735  * then it contains one frame.
736  *
737  * pkt->pts, pkt->dts and pkt->duration are always set to correct
738  * values in AVStream.timebase units (and guessed if the format cannot
739  * provided them). pkt->pts can be AV_NOPTS_VALUE if the video format
740  * has B frames, so it is better to rely on pkt->dts if you do not
741  * decompress the payload.
742  *
743  * @return 0 if OK, < 0 if error or end of file.
744  */
745 int av_read_frame(AVFormatContext *s, AVPacket *pkt);
746
747 /**
748  * Seek to the key frame at timestamp.
749  * 'timestamp' in 'stream_index'.
750  * @param stream_index If stream_index is (-1), a default
751  * stream is selected, and timestamp is automatically converted
752  * from AV_TIME_BASE units to the stream specific time_base.
753  * @param timestamp timestamp in AVStream.time_base units
754  *        or if there is no stream specified then in AV_TIME_BASE units
755  * @param flags flags which select direction and seeking mode
756  * @return >= 0 on success
757  */
758 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags);
759
760 /**
761  * start playing a network based stream (e.g. RTSP stream) at the
762  * current position
763  */
764 int av_read_play(AVFormatContext *s);
765
766 /**
767  * Pause a network based stream (e.g. RTSP stream).
768  *
769  * Use av_read_play() to resume it.
770  */
771 int av_read_pause(AVFormatContext *s);
772
773 /**
774  * Free a AVFormatContext allocated by av_open_input_stream.
775  * @param s context to free
776  */
777 void av_close_input_stream(AVFormatContext *s);
778
779 /**
780  * Close a media file (but not its codecs).
781  *
782  * @param s media file handle
783  */
784 void av_close_input_file(AVFormatContext *s);
785
786 /**
787  * Add a new stream to a media file.
788  *
789  * Can only be called in the read_header() function. If the flag
790  * AVFMTCTX_NOHEADER is in the format context, then new streams
791  * can be added in read_packet too.
792  *
793  * @param s media file handle
794  * @param id file format dependent stream id
795  */
796 AVStream *av_new_stream(AVFormatContext *s, int id);
797 AVProgram *av_new_program(AVFormatContext *s, int id);
798
799 /**
800  * Add a new chapter.
801  * This function is NOT part of the public API
802  * and should be ONLY used by demuxers.
803  *
804  * @param s media file handle
805  * @param id unique id for this chapter
806  * @param start chapter start time in time_base units
807  * @param end chapter end time in time_base units
808  * @param title chapter title
809  *
810  * @return AVChapter or NULL if error.
811  */
812 AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base, int64_t start, int64_t end, const char *title);
813
814 /**
815  * Set the pts for a given stream.
816  *
817  * @param s stream
818  * @param pts_wrap_bits number of bits effectively used by the pts
819  *        (used for wrap control, 33 is the value for MPEG)
820  * @param pts_num numerator to convert to seconds (MPEG: 1)
821  * @param pts_den denominator to convert to seconds (MPEG: 90000)
822  */
823 void av_set_pts_info(AVStream *s, int pts_wrap_bits,
824                      int pts_num, int pts_den);
825
826 #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
827 #define AVSEEK_FLAG_BYTE     2 ///< seeking based on position in bytes
828 #define AVSEEK_FLAG_ANY      4 ///< seek to any frame, even non keyframes
829
830 int av_find_default_stream_index(AVFormatContext *s);
831
832 /**
833  * Gets the index for a specific timestamp.
834  * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond to
835  *                 the timestamp which is <= the requested one, if backward is 0
836  *                 then it will be >=
837  *              if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
838  * @return < 0 if no such timestamp could be found
839  */
840 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
841
842 /**
843  * Ensures the index uses less memory than the maximum specified in
844  * AVFormatContext.max_index_size, by discarding entries if it grows
845  * too large.
846  * This function is not part of the public API and should only be called
847  * by demuxers.
848  */
849 void ff_reduce_index(AVFormatContext *s, int stream_index);
850
851 /**
852  * Add a index entry into a sorted list updateing if it is already there.
853  *
854  * @param timestamp timestamp in the timebase of the given stream
855  */
856 int av_add_index_entry(AVStream *st,
857                        int64_t pos, int64_t timestamp, int size, int distance, int flags);
858
859 /**
860  * Does a binary search using av_index_search_timestamp() and AVCodec.read_timestamp().
861  * This is not supposed to be called directly by a user application, but by demuxers.
862  * @param target_ts target timestamp in the time base of the given stream
863  * @param stream_index stream number
864  */
865 int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags);
866
867 /**
868  * Updates cur_dts of all streams based on given timestamp and AVStream.
869  *
870  * Stream ref_st unchanged, others set cur_dts in their native timebase
871  * only needed for timestamp wrapping or if (dts not set and pts!=dts).
872  * @param timestamp new dts expressed in time_base of param ref_st
873  * @param ref_st reference stream giving time_base of param timestamp
874  */
875 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
876
877 /**
878  * Does a binary search using read_timestamp().
879  * This is not supposed to be called directly by a user application, but by demuxers.
880  * @param target_ts target timestamp in the time base of the given stream
881  * @param stream_index stream number
882  */
883 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 ));
884
885 /** media file output */
886 int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
887
888 /**
889  * Allocate the stream private data and write the stream header to an
890  * output media file.
891  *
892  * @param s media file handle
893  * @return 0 if OK. AVERROR_xxx if error.
894  */
895 int av_write_header(AVFormatContext *s);
896
897 /**
898  * Write a packet to an output media file.
899  *
900  * The packet shall contain one audio or video frame.
901  * The packet must be correctly interleaved according to the container specification,
902  * if not then av_interleaved_write_frame must be used
903  *
904  * @param s media file handle
905  * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ...
906  * @return < 0 if error, = 0 if OK, 1 if end of stream wanted.
907  */
908 int av_write_frame(AVFormatContext *s, AVPacket *pkt);
909
910 /**
911  * Writes a packet to an output media file ensuring correct interleaving.
912  *
913  * The packet must contain one audio or video frame.
914  * If the packets are already correctly interleaved the application should
915  * call av_write_frame() instead as it is slightly faster. It is also important
916  * to keep in mind that completely non-interleaved input will need huge amounts
917  * of memory to interleave with this, so it is preferable to interleave at the
918  * demuxer level.
919  *
920  * @param s media file handle
921  * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ...
922  * @return < 0 if error, = 0 if OK, 1 if end of stream wanted.
923  */
924 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
925
926 /**
927  * Interleave a packet per DTS in an output media file.
928  *
929  * Packets with pkt->destruct == av_destruct_packet will be freed inside this function,
930  * so they cannot be used after it, note calling av_free_packet() on them is still safe.
931  *
932  * @param s media file handle
933  * @param out the interleaved packet will be output here
934  * @param in the input packet
935  * @param flush 1 if no further packets are available as input and all
936  *              remaining packets should be output
937  * @return 1 if a packet was output, 0 if no packet could be output,
938  *         < 0 if an error occurred
939  */
940 int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out, AVPacket *pkt, int flush);
941
942 /**
943  * @brief Write the stream trailer to an output media file and
944  *        free the file private data.
945  *
946  * @param s media file handle
947  * @return 0 if OK. AVERROR_xxx if error.
948  */
949 int av_write_trailer(AVFormatContext *s);
950
951 void dump_format(AVFormatContext *ic,
952                  int index,
953                  const char *url,
954                  int is_output);
955
956 /**
957  * parses width and height out of string str.
958  * @deprecated Use av_parse_video_frame_size instead.
959  */
960 attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr, const char *str);
961
962 /**
963  * Converts frame rate from string to a fraction.
964  * @deprecated Use av_parse_video_frame_rate instead.
965  */
966 attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base, const char *arg);
967
968 /**
969  * Parses \p datestr and returns a corresponding number of microseconds.
970  * @param datestr String representing a date or a duration.
971  * - If a date the syntax is:
972  * @code
973  *  [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}
974  * @endcode
975  * Time is localtime unless Z is appended, in which case it is
976  * interpreted as UTC.
977  * If the year-month-day part isn't specified it takes the current
978  * year-month-day.
979  * Returns the number of microseconds since 1st of January, 1970 up to
980  * the time of the parsed date or INT64_MIN if \p datestr cannot be
981  * successfully parsed.
982  * - If a duration the syntax is:
983  * @code
984  *  [-]HH[:MM[:SS[.m...]]]
985  *  [-]S+[.m...]
986  * @endcode
987  * Returns the number of microseconds contained in a time interval
988  * with the specified duration or INT64_MIN if \p datestr cannot be
989  * successfully parsed.
990  * @param duration Flag which tells how to interpret \p datestr, if
991  * not zero \p datestr is interpreted as a duration, otherwise as a
992  * date.
993  */
994 int64_t parse_date(const char *datestr, int duration);
995
996 int64_t av_gettime(void);
997
998 /* ffm specific for ffserver */
999 #define FFM_PACKET_SIZE 4096
1000 offset_t ffm_read_write_index(int fd);
1001 void ffm_write_write_index(int fd, offset_t pos);
1002 void ffm_set_write_index(AVFormatContext *s, offset_t pos, offset_t file_size);
1003
1004 /**
1005  * Attempts to find a specific tag in a URL.
1006  *
1007  * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
1008  * Return 1 if found.
1009  */
1010 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
1011
1012 /**
1013  * Returns in 'buf' the path with '%d' replaced by number.
1014
1015  * Also handles the '%0nd' format where 'n' is the total number
1016  * of digits and '%%'.
1017  *
1018  * @param buf destination buffer
1019  * @param buf_size destination buffer size
1020  * @param path numbered sequence string
1021  * @param number frame number
1022  * @return 0 if OK, -1 if format error.
1023  */
1024 int av_get_frame_filename(char *buf, int buf_size,
1025                           const char *path, int number);
1026
1027 /**
1028  * Check whether filename actually is a numbered sequence generator.
1029  *
1030  * @param filename possible numbered sequence string
1031  * @return 1 if a valid numbered sequence string, 0 otherwise.
1032  */
1033 int av_filename_number_test(const char *filename);
1034
1035 /**
1036  * Generate an SDP for an RTP session.
1037  *
1038  * @param ac array of AVFormatContexts describing the RTP streams. If the
1039  *           array is composed by only one context, such context can contain
1040  *           multiple AVStreams (one AVStream per RTP stream). Otherwise,
1041  *           all the contexts in the array (an AVCodecContext per RTP stream)
1042  *           must contain only one AVStream
1043  * @param n_files number of AVCodecContexts contained in ac
1044  * @param buff buffer where the SDP will be stored (must be allocated by
1045  *             the caller
1046  * @param size the size of the buffer
1047  * @return 0 if OK. AVERROR_xxx if error.
1048  */
1049 int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
1050
1051 #ifdef HAVE_AV_CONFIG_H
1052
1053 void ff_dynarray_add(unsigned long **tab_ptr, int *nb_ptr, unsigned long elem);
1054
1055 #ifdef __GNUC__
1056 #define dynarray_add(tab, nb_ptr, elem)\
1057 do {\
1058     typeof(tab) _tab = (tab);\
1059     typeof(elem) _elem = (elem);\
1060     (void)sizeof(**_tab == _elem); /* check that types are compatible */\
1061     ff_dynarray_add((unsigned long **)_tab, nb_ptr, (unsigned long)_elem);\
1062 } while(0)
1063 #else
1064 #define dynarray_add(tab, nb_ptr, elem)\
1065 do {\
1066     ff_dynarray_add((unsigned long **)(tab), nb_ptr, (unsigned long)(elem));\
1067 } while(0)
1068 #endif
1069
1070 time_t mktimegm(struct tm *tm);
1071 struct tm *brktimegm(time_t secs, struct tm *tm);
1072 const char *small_strptime(const char *p, const char *fmt,
1073                            struct tm *dt);
1074
1075 struct in_addr;
1076 int resolve_host(struct in_addr *sin_addr, const char *hostname);
1077
1078 void url_split(char *proto, int proto_size,
1079                char *authorization, int authorization_size,
1080                char *hostname, int hostname_size,
1081                int *port_ptr,
1082                char *path, int path_size,
1083                const char *url);
1084
1085 int match_ext(const char *filename, const char *extensions);
1086
1087 #endif /* HAVE_AV_CONFIG_H */
1088
1089 #endif /* FFMPEG_AVFORMAT_H */