add FF_API_UDP_GET_FILE define to disable the deprecated udp_get_file_handle()
[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 AVFORMAT_AVFORMAT_H
22 #define AVFORMAT_AVFORMAT_H
23
24 #define LIBAVFORMAT_VERSION_MAJOR 52
25 #define LIBAVFORMAT_VERSION_MINOR 82
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 /**
39  * Those FF_API_* defines are not part of public API.
40  * They may change, break or disappear at any time.
41  */
42 #ifndef FF_API_MAX_STREAMS
43 #define FF_API_MAX_STREAMS   (LIBAVFORMAT_VERSION_MAJOR < 53)
44 #endif
45 #ifndef FF_API_OLD_METADATA
46 #define FF_API_OLD_METADATA  (LIBAVFORMAT_VERSION_MAJOR < 53)
47 #endif
48 #ifndef FF_API_URL_CLASS
49 #define FF_API_URL_CLASS     (LIBAVFORMAT_VERSION_MAJOR >= 53)
50 #endif
51 #ifndef FF_API_URL_RESETBUF
52 #define FF_API_URL_RESETBUF       (LIBAVFORMAT_VERSION_MAJOR < 53)
53 #endif
54 #ifndef FF_API_REGISTER_PROTOCOL
55 #define FF_API_REGISTER_PROTOCOL  (LIBAVFORMAT_VERSION_MAJOR < 53)
56 #endif
57 #ifndef FF_API_GUESS_FORMAT
58 #define FF_API_GUESS_FORMAT       (LIBAVFORMAT_VERSION_MAJOR < 53)
59 #endif
60 #ifndef FF_API_UDP_GET_FILE
61 #define FF_API_UDP_GET_FILE       (LIBAVFORMAT_VERSION_MAJOR < 53)
62 #endif
63
64 /**
65  * I return the LIBAVFORMAT_VERSION_INT constant.  You got
66  * a fucking problem with that, douchebag?
67  */
68 unsigned avformat_version(void);
69
70 /**
71  * Return the libavformat build-time configuration.
72  */
73 const char *avformat_configuration(void);
74
75 /**
76  * Return the libavformat license.
77  */
78 const char *avformat_license(void);
79
80 #include <time.h>
81 #include <stdio.h>  /* FILE */
82 #include "libavcodec/avcodec.h"
83
84 #include "avio.h"
85
86 struct AVFormatContext;
87
88
89 /*
90  * Public Metadata API.
91  * The metadata API allows libavformat to export metadata tags to a client
92  * application using a sequence of key/value pairs. Like all strings in FFmpeg,
93  * metadata must be stored as UTF-8 encoded Unicode. Note that metadata
94  * exported by demuxers isn't checked to be valid UTF-8 in most cases.
95  * Important concepts to keep in mind:
96  * 1. Keys are unique; there can never be 2 tags with the same key. This is
97  *    also meant semantically, i.e., a demuxer should not knowingly produce
98  *    several keys that are literally different but semantically identical.
99  *    E.g., key=Author5, key=Author6. In this example, all authors must be
100  *    placed in the same tag.
101  * 2. Metadata is flat, not hierarchical; there are no subtags. If you
102  *    want to store, e.g., the email address of the child of producer Alice
103  *    and actor Bob, that could have key=alice_and_bobs_childs_email_address.
104  * 3. Several modifiers can be applied to the tag name. This is done by
105  *    appending a dash character ('-') and the modifier name in the order
106  *    they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.
107  *    a) language -- a tag whose value is localized for a particular language
108  *       is appended with the ISO 639-2/B 3-letter language code.
109  *       For example: Author-ger=Michael, Author-eng=Mike
110  *       The original/default language is in the unqualified "Author" tag.
111  *       A demuxer should set a default if it sets any translated tag.
112  *    b) sorting  -- a modified version of a tag that should be used for
113  *       sorting will have '-sort' appended. E.g. artist="The Beatles",
114  *       artist-sort="Beatles, The".
115  *
116  * 4. Tag names are normally exported exactly as stored in the container to
117  *    allow lossless remuxing to the same format. For container-independent
118  *    handling of metadata, av_metadata_conv() can convert it to ffmpeg generic
119  *    format. Follows a list of generic tag names:
120  *
121  * album        -- name of the set this work belongs to
122  * album_artist -- main creator of the set/album, if different from artist.
123  *                 e.g. "Various Artists" for compilation albums.
124  * artist       -- main creator of the work
125  * comment      -- any additional description of the file.
126  * composer     -- who composed the work, if different from artist.
127  * copyright    -- name of copyright holder.
128  * date         -- date when the work was created, preferably in ISO 8601.
129  * disc         -- number of a subset, e.g. disc in a multi-disc collection.
130  * encoder      -- name/settings of the software/hardware that produced the file.
131  * encoded_by   -- person/group who created the file.
132  * filename     -- original name of the file.
133  * genre        -- <self-evident>.
134  * language     -- main language in which the work is performed, preferably
135  *                 in ISO 639-2 format.
136  * performer    -- artist who performed the work, if different from artist.
137  *                 E.g for "Also sprach Zarathustra", artist would be "Richard
138  *                 Strauss" and performer "London Philharmonic Orchestra".
139  * publisher    -- name of the label/publisher.
140  * title        -- name of the work.
141  * track        -- number of this work in the set, can be in form current/total.
142  */
143
144 #define AV_METADATA_MATCH_CASE      1
145 #define AV_METADATA_IGNORE_SUFFIX   2
146 #define AV_METADATA_DONT_STRDUP_KEY 4
147 #define AV_METADATA_DONT_STRDUP_VAL 8
148 #define AV_METADATA_DONT_OVERWRITE 16   ///< Don't overwrite existing tags.
149
150 typedef struct {
151     char *key;
152     char *value;
153 }AVMetadataTag;
154
155 typedef struct AVMetadata AVMetadata;
156 typedef struct AVMetadataConv AVMetadataConv;
157
158 /**
159  * Get a metadata element with matching key.
160  *
161  * @param prev Set to the previous matching element to find the next.
162  *             If set to NULL the first matching element is returned.
163  * @param flags Allows case as well as suffix-insensitive comparisons.
164  * @return Found tag or NULL, changing key or value leads to undefined behavior.
165  */
166 AVMetadataTag *
167 av_metadata_get(AVMetadata *m, const char *key, const AVMetadataTag *prev, int flags);
168
169 #if FF_API_OLD_METADATA
170 /**
171  * Set the given tag in *pm, overwriting an existing tag.
172  *
173  * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
174  * a metadata struct is allocated and put in *pm.
175  * @param key tag key to add to *pm (will be av_strduped)
176  * @param value tag value to add to *pm (will be av_strduped)
177  * @return >= 0 on success otherwise an error code <0
178  * @deprecated Use av_metadata_set2() instead.
179  */
180 attribute_deprecated int av_metadata_set(AVMetadata **pm, const char *key, const char *value);
181 #endif
182
183 /**
184  * Set the given tag in *pm, overwriting an existing tag.
185  *
186  * @param pm pointer to a pointer to a metadata struct. If *pm is NULL
187  * a metadata struct is allocated and put in *pm.
188  * @param key tag key to add to *pm (will be av_strduped depending on flags)
189  * @param value tag value to add to *pm (will be av_strduped depending on flags).
190  *        Passing a NULL value will cause an existing tag to be deleted.
191  * @return >= 0 on success otherwise an error code <0
192  */
193 int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
194
195 /**
196  * Convert all the metadata sets from ctx according to the source and
197  * destination conversion tables. If one of the tables is NULL, then
198  * tags are converted to/from ffmpeg generic tag names.
199  *
200  * @param d_conv destination tags format conversion table
201  * @param s_conv source tags format conversion table
202  */
203 void av_metadata_conv(struct AVFormatContext *ctx, const AVMetadataConv *d_conv,
204                                                    const AVMetadataConv *s_conv);
205
206 /**
207  * Free all the memory allocated for an AVMetadata struct.
208  */
209 void av_metadata_free(AVMetadata **m);
210
211
212 /* packet functions */
213
214
215 /**
216  * Allocate and read the payload of a packet and initialize its
217  * fields with default values.
218  *
219  * @param pkt packet
220  * @param size desired payload size
221  * @return >0 (read size) if OK, AVERROR_xxx otherwise
222  */
223 int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
224
225
226 /*************************************************/
227 /* fractional numbers for exact pts handling */
228
229 /**
230  * The exact value of the fractional number is: 'val + num / den'.
231  * num is assumed to be 0 <= num < den.
232  */
233 typedef struct AVFrac {
234     int64_t val, num, den;
235 } AVFrac;
236
237 /*************************************************/
238 /* input/output formats */
239
240 struct AVCodecTag;
241
242 /**
243  * This structure contains the data a format has to probe a file.
244  */
245 typedef struct AVProbeData {
246     const char *filename;
247     unsigned char *buf; /**< Buffer must have AVPROBE_PADDING_SIZE of extra allocated bytes filled with zero. */
248     int buf_size;       /**< Size of buf except extra allocated bytes */
249 } AVProbeData;
250
251 #define AVPROBE_SCORE_MAX 100               ///< maximum score, half of that is used for file-extension-based detection
252 #define AVPROBE_PADDING_SIZE 32             ///< extra allocated bytes at the end of the probe buffer
253
254 typedef struct AVFormatParameters {
255     AVRational time_base;
256     int sample_rate;
257     int channels;
258     int width;
259     int height;
260     enum PixelFormat pix_fmt;
261     int channel; /**< Used to select DV channel. */
262     const char *standard; /**< TV standard, NTSC, PAL, SECAM */
263     unsigned int mpeg2ts_raw:1;  /**< Force raw MPEG-2 transport stream output, if possible. */
264     unsigned int mpeg2ts_compute_pcr:1; /**< Compute exact PCR for each transport
265                                             stream packet (only meaningful if
266                                             mpeg2ts_raw is TRUE). */
267     unsigned int initial_pause:1;       /**< Do not begin to play the stream
268                                             immediately (RTSP only). */
269     unsigned int prealloced_context:1;
270 #if LIBAVFORMAT_VERSION_INT < (53<<16)
271     attribute_deprecated enum CodecID video_codec_id;
272     attribute_deprecated enum CodecID audio_codec_id;
273 #endif
274 } AVFormatParameters;
275
276 //! Demuxer will use url_fopen, no opened file should be provided by the caller.
277 #define AVFMT_NOFILE        0x0001
278 #define AVFMT_NEEDNUMBER    0x0002 /**< Needs '%d' in filename. */
279 #define AVFMT_SHOW_IDS      0x0008 /**< Show format stream IDs numbers. */
280 #define AVFMT_RAWPICTURE    0x0020 /**< Format wants AVPicture structure for
281                                       raw picture data. */
282 #define AVFMT_GLOBALHEADER  0x0040 /**< Format wants global header. */
283 #define AVFMT_NOTIMESTAMPS  0x0080 /**< Format does not need / have any timestamps. */
284 #define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */
285 #define AVFMT_TS_DISCONT    0x0200 /**< Format allows timestamp discontinuities. */
286 #define AVFMT_VARIABLE_FPS  0x0400 /**< Format allows variable fps. */
287 #define AVFMT_NODIMENSIONS  0x0800 /**< Format does not need width/height */
288
289 typedef struct AVOutputFormat {
290     const char *name;
291     /**
292      * Descriptive name for the format, meant to be more human-readable
293      * than name. You should use the NULL_IF_CONFIG_SMALL() macro
294      * to define it.
295      */
296     const char *long_name;
297     const char *mime_type;
298     const char *extensions; /**< comma-separated filename extensions */
299     /**
300      * size of private data so that it can be allocated in the wrapper
301      */
302     int priv_data_size;
303     /* output support */
304     enum CodecID audio_codec; /**< default audio codec */
305     enum CodecID video_codec; /**< default video codec */
306     int (*write_header)(struct AVFormatContext *);
307     int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);
308     int (*write_trailer)(struct AVFormatContext *);
309     /**
310      * can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER
311      */
312     int flags;
313     /**
314      * Currently only used to set pixel format if not YUV420P.
315      */
316     int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
317     int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,
318                              AVPacket *in, int flush);
319
320     /**
321      * List of supported codec_id-codec_tag pairs, ordered by "better
322      * choice first". The arrays are all terminated by CODEC_ID_NONE.
323      */
324     const struct AVCodecTag * const *codec_tag;
325
326     enum CodecID subtitle_codec; /**< default subtitle codec */
327
328     const AVMetadataConv *metadata_conv;
329
330     /* private fields */
331     struct AVOutputFormat *next;
332 } AVOutputFormat;
333
334 typedef struct AVInputFormat {
335     /**
336      * A comma separated list of short names for the format. New names
337      * may be appended with a minor bump.
338      */
339     const char *name;
340
341     /**
342      * Descriptive name for the format, meant to be more human-readable
343      * than name. You should use the NULL_IF_CONFIG_SMALL() macro
344      * to define it.
345      */
346     const char *long_name;
347
348     /**
349      * Size of private data so that it can be allocated in the wrapper.
350      */
351     int priv_data_size;
352
353     /**
354      * Tell if a given file has a chance of being parsed as this format.
355      * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes
356      * big so you do not have to check for that unless you need more.
357      */
358     int (*read_probe)(AVProbeData *);
359
360     /**
361      * Read the format header and initialize the AVFormatContext
362      * structure. Return 0 if OK. 'ap' if non-NULL contains
363      * additional parameters. Only used in raw format right
364      * now. 'av_new_stream' should be called to create new streams.
365      */
366     int (*read_header)(struct AVFormatContext *,
367                        AVFormatParameters *ap);
368
369     /**
370      * Read one packet and put it in 'pkt'. pts and flags are also
371      * set. 'av_new_stream' can be called only if the flag
372      * AVFMTCTX_NOHEADER is used and only in the calling thread (not in a
373      * background thread).
374      * @return 0 on success, < 0 on error.
375      *         When returning an error, pkt must not have been allocated
376      *         or must be freed before returning
377      */
378     int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
379
380     /**
381      * Close the stream. The AVFormatContext and AVStreams are not
382      * freed by this function
383      */
384     int (*read_close)(struct AVFormatContext *);
385
386 #if LIBAVFORMAT_VERSION_MAJOR < 53
387     /**
388      * Seek to a given timestamp relative to the frames in
389      * stream component stream_index.
390      * @param stream_index Must not be -1.
391      * @param flags Selects which direction should be preferred if no exact
392      *              match is available.
393      * @return >= 0 on success (but not necessarily the new offset)
394      */
395     attribute_deprecated int (*read_seek)(struct AVFormatContext *,
396                                           int stream_index, int64_t timestamp, int flags);
397 #endif
398     /**
399      * Gets the next timestamp in stream[stream_index].time_base units.
400      * @return the timestamp or AV_NOPTS_VALUE if an error occurred
401      */
402     int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
403                               int64_t *pos, int64_t pos_limit);
404
405     /**
406      * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER.
407      */
408     int flags;
409
410     /**
411      * If extensions are defined, then no probe is done. You should
412      * usually not use extension format guessing because it is not
413      * reliable enough
414      */
415     const char *extensions;
416
417     /**
418      * General purpose read-only value that the format can use.
419      */
420     int value;
421
422     /**
423      * Start/resume playing - only meaningful if using a network-based format
424      * (RTSP).
425      */
426     int (*read_play)(struct AVFormatContext *);
427
428     /**
429      * Pause playing - only meaningful if using a network-based format
430      * (RTSP).
431      */
432     int (*read_pause)(struct AVFormatContext *);
433
434     const struct AVCodecTag * const *codec_tag;
435
436     /**
437      * Seek to timestamp ts.
438      * Seeking will be done so that the point from which all active streams
439      * can be presented successfully will be closest to ts and within min/max_ts.
440      * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
441      */
442     int (*read_seek2)(struct AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
443
444     const AVMetadataConv *metadata_conv;
445
446     /* private fields */
447     struct AVInputFormat *next;
448 } AVInputFormat;
449
450 enum AVStreamParseType {
451     AVSTREAM_PARSE_NONE,
452     AVSTREAM_PARSE_FULL,       /**< full parsing and repack */
453     AVSTREAM_PARSE_HEADERS,    /**< Only parse headers, do not repack. */
454     AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on a packet boundary */
455     AVSTREAM_PARSE_FULL_ONCE,  /**< full parsing and repack of the first frame only, only implemented for H.264 currently */
456 };
457
458 typedef struct AVIndexEntry {
459     int64_t pos;
460     int64_t timestamp;
461 #define AVINDEX_KEYFRAME 0x0001
462     int flags:2;
463     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).
464     int min_distance;         /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */
465 } AVIndexEntry;
466
467 #define AV_DISPOSITION_DEFAULT   0x0001
468 #define AV_DISPOSITION_DUB       0x0002
469 #define AV_DISPOSITION_ORIGINAL  0x0004
470 #define AV_DISPOSITION_COMMENT   0x0008
471 #define AV_DISPOSITION_LYRICS    0x0010
472 #define AV_DISPOSITION_KARAOKE   0x0020
473
474 /**
475  * Track should be used during playback by default.
476  * Useful for subtitle track that should be displayed
477  * even when user did not explicitly ask for subtitles.
478  */
479 #define AV_DISPOSITION_FORCED    0x0040
480
481 /**
482  * Stream structure.
483  * New fields can be added to the end with minor version bumps.
484  * Removal, reordering and changes to existing fields require a major
485  * version bump.
486  * sizeof(AVStream) must not be used outside libav*.
487  */
488 typedef struct AVStream {
489     int index;    /**< stream index in AVFormatContext */
490     int id;       /**< format-specific stream ID */
491     AVCodecContext *codec; /**< codec context */
492     /**
493      * Real base framerate of the stream.
494      * This is the lowest framerate with which all timestamps can be
495      * represented accurately (it is the least common multiple of all
496      * framerates in the stream). Note, this value is just a guess!
497      * For example, if the time base is 1/90000 and all frames have either
498      * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
499      */
500     AVRational r_frame_rate;
501     void *priv_data;
502
503     /* internal data used in av_find_stream_info() */
504     int64_t first_dts;
505
506     /**
507      * encoding: pts generation when outputting stream
508      */
509     struct AVFrac pts;
510
511     /**
512      * This is the fundamental unit of time (in seconds) in terms
513      * of which frame timestamps are represented. For fixed-fps content,
514      * time base should be 1/framerate and timestamp increments should be 1.
515      */
516     AVRational time_base;
517     int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
518     /* ffmpeg.c private use */
519     int stream_copy; /**< If set, just copy stream. */
520     enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
521
522     //FIXME move stuff to a flags field?
523     /**
524      * Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
525      * MN: dunno if that is the right place for it
526      */
527     float quality;
528
529     /**
530      * Decoding: pts of the first frame of the stream, in stream time base.
531      * Only set this if you are absolutely 100% sure that the value you set
532      * it to really is the pts of the first frame.
533      * This may be undefined (AV_NOPTS_VALUE).
534      * @note The ASF header does NOT contain a correct start_time the ASF
535      * demuxer must NOT set this.
536      */
537     int64_t start_time;
538
539     /**
540      * Decoding: duration of the stream, in stream time base.
541      * If a source file does not specify a duration, but does specify
542      * a bitrate, this value will be estimated from bitrate and file size.
543      */
544     int64_t duration;
545
546 #if FF_API_OLD_METADATA
547     attribute_deprecated char language[4]; /**< ISO 639-2/B 3-letter language code (empty string if undefined) */
548 #endif
549
550     /* av_read_frame() support */
551     enum AVStreamParseType need_parsing;
552     struct AVCodecParserContext *parser;
553
554     int64_t cur_dts;
555     int last_IP_duration;
556     int64_t last_IP_pts;
557     /* av_seek_frame() support */
558     AVIndexEntry *index_entries; /**< Only used if the format does not
559                                     support seeking natively. */
560     int nb_index_entries;
561     unsigned int index_entries_allocated_size;
562
563     int64_t nb_frames;                 ///< number of frames in this stream if known or 0
564
565 #if LIBAVFORMAT_VERSION_INT < (53<<16)
566     attribute_deprecated int64_t unused[4+1];
567 #endif
568
569 #if FF_API_OLD_METADATA
570     attribute_deprecated char *filename; /**< source filename of the stream */
571 #endif
572
573     int disposition; /**< AV_DISPOSITION_* bit field */
574
575     AVProbeData probe_data;
576 #define MAX_REORDER_DELAY 16
577     int64_t pts_buffer[MAX_REORDER_DELAY+1];
578
579     /**
580      * sample aspect ratio (0 if unknown)
581      * - encoding: Set by user.
582      * - decoding: Set by libavformat.
583      */
584     AVRational sample_aspect_ratio;
585
586     AVMetadata *metadata;
587
588     /* Intended mostly for av_read_frame() support. Not supposed to be used by */
589     /* external applications; try to use something else if at all possible.    */
590     const uint8_t *cur_ptr;
591     int cur_len;
592     AVPacket cur_pkt;
593
594     // Timestamp generation support:
595     /**
596      * Timestamp corresponding to the last dts sync point.
597      *
598      * Initialized when AVCodecParserContext.dts_sync_point >= 0 and
599      * a DTS is received from the underlying container. Otherwise set to
600      * AV_NOPTS_VALUE by default.
601      */
602     int64_t reference_dts;
603
604     /**
605      * Number of packets to buffer for codec probing
606      * NOT PART OF PUBLIC API
607      */
608 #define MAX_PROBE_PACKETS 2500
609     int probe_packets;
610
611     /**
612      * last packet in packet_buffer for this stream when muxing.
613      * used internally, NOT PART OF PUBLIC API, dont read or write from outside of libav*
614      */
615     struct AVPacketList *last_in_packet_buffer;
616
617     /**
618      * Average framerate
619      */
620     AVRational avg_frame_rate;
621
622     /**
623      * Number of frames that have been demuxed during av_find_stream_info()
624      */
625     int codec_info_nb_frames;
626
627     /**
628      * Stream informations used internally by av_find_stream_info()
629      */
630 #define MAX_STD_TIMEBASES (60*12+5)
631     struct {
632         int64_t last_dts;
633         int64_t duration_gcd;
634         int duration_count;
635         double duration_error[MAX_STD_TIMEBASES];
636         int64_t codec_info_duration;
637     } *info;
638 } AVStream;
639
640 #define AV_PROGRAM_RUNNING 1
641
642 /**
643  * New fields can be added to the end with minor version bumps.
644  * Removal, reordering and changes to existing fields require a major
645  * version bump.
646  * sizeof(AVProgram) must not be used outside libav*.
647  */
648 typedef struct AVProgram {
649     int            id;
650 #if FF_API_OLD_METADATA
651     attribute_deprecated char           *provider_name; ///< network name for DVB streams
652     attribute_deprecated char           *name;          ///< service name for DVB streams
653 #endif
654     int            flags;
655     enum AVDiscard discard;        ///< selects which program to discard and which to feed to the caller
656     unsigned int   *stream_index;
657     unsigned int   nb_stream_indexes;
658     AVMetadata *metadata;
659 } AVProgram;
660
661 #define AVFMTCTX_NOHEADER      0x0001 /**< signal that no header is present
662                                          (streams are added dynamically) */
663
664 typedef struct AVChapter {
665     int id;                 ///< unique ID to identify the chapter
666     AVRational time_base;   ///< time base in which the start/end timestamps are specified
667     int64_t start, end;     ///< chapter start/end time in time_base units
668 #if FF_API_OLD_METADATA
669     attribute_deprecated char *title;            ///< chapter title
670 #endif
671     AVMetadata *metadata;
672 } AVChapter;
673
674 #if FF_API_MAX_STREAMS
675 #define MAX_STREAMS 20
676 #endif
677
678 /**
679  * Format I/O context.
680  * New fields can be added to the end with minor version bumps.
681  * Removal, reordering and changes to existing fields require a major
682  * version bump.
683  * sizeof(AVFormatContext) must not be used outside libav*.
684  */
685 typedef struct AVFormatContext {
686     const AVClass *av_class; /**< Set by avformat_alloc_context. */
687     /* Can only be iformat or oformat, not both at the same time. */
688     struct AVInputFormat *iformat;
689     struct AVOutputFormat *oformat;
690     void *priv_data;
691     ByteIOContext *pb;
692     unsigned int nb_streams;
693 #if FF_API_MAX_STREAMS
694     AVStream *streams[MAX_STREAMS];
695 #else
696     AVStream **streams;
697 #endif
698     char filename[1024]; /**< input or output filename */
699     /* stream info */
700     int64_t timestamp;
701 #if FF_API_OLD_METADATA
702     attribute_deprecated char title[512];
703     attribute_deprecated char author[512];
704     attribute_deprecated char copyright[512];
705     attribute_deprecated char comment[512];
706     attribute_deprecated char album[512];
707     attribute_deprecated int year;  /**< ID3 year, 0 if none */
708     attribute_deprecated int track; /**< track number, 0 if none */
709     attribute_deprecated char genre[32]; /**< ID3 genre */
710 #endif
711
712     int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
713     /* private data for pts handling (do not modify directly). */
714     /**
715      * This buffer is only needed when packets were already buffered but
716      * not decoded, for example to get the codec parameters in MPEG
717      * streams.
718      */
719     struct AVPacketList *packet_buffer;
720
721     /**
722      * Decoding: position of the first frame of the component, in
723      * AV_TIME_BASE fractional seconds. NEVER set this value directly:
724      * It is deduced from the AVStream values.
725      */
726     int64_t start_time;
727
728     /**
729      * Decoding: duration of the stream, in AV_TIME_BASE fractional
730      * seconds. Only set this value if you know none of the individual stream
731      * durations and also dont set any of them. This is deduced from the
732      * AVStream values if not set.
733      */
734     int64_t duration;
735
736     /**
737      * decoding: total file size, 0 if unknown
738      */
739     int64_t file_size;
740
741     /**
742      * Decoding: total stream bitrate in bit/s, 0 if not
743      * available. Never set it directly if the file_size and the
744      * duration are known as FFmpeg can compute it automatically.
745      */
746     int bit_rate;
747
748     /* av_read_frame() support */
749     AVStream *cur_st;
750 #if LIBAVFORMAT_VERSION_INT < (53<<16)
751     const uint8_t *cur_ptr_deprecated;
752     int cur_len_deprecated;
753     AVPacket cur_pkt_deprecated;
754 #endif
755
756     /* av_seek_frame() support */
757     int64_t data_offset; /**< offset of the first packet */
758     int index_built;
759
760     int mux_rate;
761     unsigned int packet_size;
762     int preload;
763     int max_delay;
764
765 #define AVFMT_NOOUTPUTLOOP -1
766 #define AVFMT_INFINITEOUTPUTLOOP 0
767     /**
768      * number of times to loop output in formats that support it
769      */
770     int loop_output;
771
772     int flags;
773 #define AVFMT_FLAG_GENPTS       0x0001 ///< Generate missing pts even if it requires parsing future frames.
774 #define AVFMT_FLAG_IGNIDX       0x0002 ///< Ignore index.
775 #define AVFMT_FLAG_NONBLOCK     0x0004 ///< Do not block when reading packets from input.
776 #define AVFMT_FLAG_IGNDTS       0x0008 ///< Ignore DTS on frames that contain both DTS & PTS
777 #define AVFMT_FLAG_NOFILLIN     0x0010 ///< Do not infer any values from other values, just return what is stored in the container
778 #define AVFMT_FLAG_NOPARSE      0x0020 ///< Do not use AVParsers, you also must set AVFMT_FLAG_NOFILLIN as the fillin code works on frames and no parsing -> no frames. Also seeking to frames can not work if parsing to find frame boundaries has been disabled
779 #define AVFMT_FLAG_RTP_HINT     0x0040 ///< Add RTP hinting to the output file
780
781     int loop_input;
782
783     /**
784      * decoding: size of data to probe; encoding: unused.
785      */
786     unsigned int probesize;
787
788     /**
789      * Maximum time (in AV_TIME_BASE units) during which the input should
790      * be analyzed in av_find_stream_info().
791      */
792     int max_analyze_duration;
793
794     const uint8_t *key;
795     int keylen;
796
797     unsigned int nb_programs;
798     AVProgram **programs;
799
800     /**
801      * Forced video codec_id.
802      * Demuxing: Set by user.
803      */
804     enum CodecID video_codec_id;
805
806     /**
807      * Forced audio codec_id.
808      * Demuxing: Set by user.
809      */
810     enum CodecID audio_codec_id;
811
812     /**
813      * Forced subtitle codec_id.
814      * Demuxing: Set by user.
815      */
816     enum CodecID subtitle_codec_id;
817
818     /**
819      * Maximum amount of memory in bytes to use for the index of each stream.
820      * If the index exceeds this size, entries will be discarded as
821      * needed to maintain a smaller size. This can lead to slower or less
822      * accurate seeking (depends on demuxer).
823      * Demuxers for which a full in-memory index is mandatory will ignore
824      * this.
825      * muxing  : unused
826      * demuxing: set by user
827      */
828     unsigned int max_index_size;
829
830     /**
831      * Maximum amount of memory in bytes to use for buffering frames
832      * obtained from realtime capture devices.
833      */
834     unsigned int max_picture_buffer;
835
836     unsigned int nb_chapters;
837     AVChapter **chapters;
838
839     /**
840      * Flags to enable debugging.
841      */
842     int debug;
843 #define FF_FDEBUG_TS        0x0001
844
845     /**
846      * Raw packets from the demuxer, prior to parsing and decoding.
847      * This buffer is used for buffering packets until the codec can
848      * be identified, as parsing cannot be done without knowing the
849      * codec.
850      */
851     struct AVPacketList *raw_packet_buffer;
852     struct AVPacketList *raw_packet_buffer_end;
853
854     struct AVPacketList *packet_buffer_end;
855
856     AVMetadata *metadata;
857
858     /**
859      * Remaining size available for raw_packet_buffer, in bytes.
860      * NOT PART OF PUBLIC API
861      */
862 #define RAW_PACKET_BUFFER_SIZE 2500000
863     int raw_packet_buffer_remaining_size;
864
865     /**
866      * Start time of the stream in real world time, in microseconds
867      * since the unix epoch (00:00 1st January 1970). That is, pts=0
868      * in the stream was captured at this real world time.
869      * - encoding: Set by user.
870      * - decoding: Unused.
871      */
872     int64_t start_time_realtime;
873 } AVFormatContext;
874
875 typedef struct AVPacketList {
876     AVPacket pkt;
877     struct AVPacketList *next;
878 } AVPacketList;
879
880 #if LIBAVFORMAT_VERSION_INT < (53<<16)
881 attribute_deprecated extern AVInputFormat *first_iformat;
882 attribute_deprecated extern AVOutputFormat *first_oformat;
883 #endif
884
885 /**
886  * If f is NULL, returns the first registered input format,
887  * if f is non-NULL, returns the next registered input format after f
888  * or NULL if f is the last one.
889  */
890 AVInputFormat  *av_iformat_next(AVInputFormat  *f);
891
892 /**
893  * If f is NULL, returns the first registered output format,
894  * if f is non-NULL, returns the next registered output format after f
895  * or NULL if f is the last one.
896  */
897 AVOutputFormat *av_oformat_next(AVOutputFormat *f);
898
899 enum CodecID av_guess_image2_codec(const char *filename);
900
901 /* XXX: Use automatic init with either ELF sections or C file parser */
902 /* modules. */
903
904 /* utils.c */
905 void av_register_input_format(AVInputFormat *format);
906 void av_register_output_format(AVOutputFormat *format);
907 #if FF_API_GUESS_FORMAT
908 attribute_deprecated AVOutputFormat *guess_stream_format(const char *short_name,
909                                     const char *filename,
910                                     const char *mime_type);
911
912 /**
913  * @deprecated Use av_guess_format() instead.
914  */
915 attribute_deprecated AVOutputFormat *guess_format(const char *short_name,
916                                                   const char *filename,
917                                                   const char *mime_type);
918 #endif
919
920 /**
921  * Return the output format in the list of registered output formats
922  * which best matches the provided parameters, or return NULL if
923  * there is no match.
924  *
925  * @param short_name if non-NULL checks if short_name matches with the
926  * names of the registered formats
927  * @param filename if non-NULL checks if filename terminates with the
928  * extensions of the registered formats
929  * @param mime_type if non-NULL checks if mime_type matches with the
930  * MIME type of the registered formats
931  */
932 AVOutputFormat *av_guess_format(const char *short_name,
933                                 const char *filename,
934                                 const char *mime_type);
935
936 /**
937  * Guess the codec ID based upon muxer and filename.
938  */
939 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
940                             const char *filename, const char *mime_type,
941                             enum AVMediaType type);
942
943 /**
944  * Send a nice hexadecimal dump of a buffer to the specified file stream.
945  *
946  * @param f The file stream pointer where the dump should be sent to.
947  * @param buf buffer
948  * @param size buffer size
949  *
950  * @see av_hex_dump_log, av_pkt_dump, av_pkt_dump_log
951  */
952 void av_hex_dump(FILE *f, uint8_t *buf, int size);
953
954 /**
955  * Send a nice hexadecimal dump of a buffer to the log.
956  *
957  * @param avcl A pointer to an arbitrary struct of which the first field is a
958  * pointer to an AVClass struct.
959  * @param level The importance level of the message, lower values signifying
960  * higher importance.
961  * @param buf buffer
962  * @param size buffer size
963  *
964  * @see av_hex_dump, av_pkt_dump, av_pkt_dump_log
965  */
966 void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
967
968 /**
969  * Send a nice dump of a packet to the specified file stream.
970  *
971  * @param f The file stream pointer where the dump should be sent to.
972  * @param pkt packet to dump
973  * @param dump_payload True if the payload must be displayed, too.
974  */
975 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
976
977 /**
978  * Send a nice dump of a packet to the log.
979  *
980  * @param avcl A pointer to an arbitrary struct of which the first field is a
981  * pointer to an AVClass struct.
982  * @param level The importance level of the message, lower values signifying
983  * higher importance.
984  * @param pkt packet to dump
985  * @param dump_payload True if the payload must be displayed, too.
986  */
987 void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
988
989 /**
990  * Initialize libavformat and register all the muxers, demuxers and
991  * protocols. If you do not call this function, then you can select
992  * exactly which formats you want to support.
993  *
994  * @see av_register_input_format()
995  * @see av_register_output_format()
996  * @see av_register_protocol()
997  */
998 void av_register_all(void);
999
1000 /**
1001  * Get the CodecID for the given codec tag tag.
1002  * If no codec id is found returns CODEC_ID_NONE.
1003  *
1004  * @param tags list of supported codec_id-codec_tag pairs, as stored
1005  * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
1006  */
1007 enum CodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
1008
1009 /**
1010  * Get the codec tag for the given codec id id.
1011  * If no codec tag is found returns 0.
1012  *
1013  * @param tags list of supported codec_id-codec_tag pairs, as stored
1014  * in AVInputFormat.codec_tag and AVOutputFormat.codec_tag
1015  */
1016 unsigned int av_codec_get_tag(const struct AVCodecTag * const *tags, enum CodecID id);
1017
1018 /* media file input */
1019
1020 /**
1021  * Find AVInputFormat based on the short name of the input format.
1022  */
1023 AVInputFormat *av_find_input_format(const char *short_name);
1024
1025 /**
1026  * Guess the file format.
1027  *
1028  * @param is_opened Whether the file is already opened; determines whether
1029  *                  demuxers with or without AVFMT_NOFILE are probed.
1030  */
1031 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
1032
1033 /**
1034  * Guess the file format.
1035  *
1036  * @param is_opened Whether the file is already opened; determines whether
1037  *                  demuxers with or without AVFMT_NOFILE are probed.
1038  * @param score_max A probe score larger that this is required to accept a
1039  *                  detection, the variable is set to the actual detection
1040  *                  score afterwards.
1041  *                  If the score is <= AVPROBE_SCORE_MAX / 4 it is recommended
1042  *                  to retry with a larger probe buffer.
1043  */
1044 AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max);
1045
1046 /**
1047  * Allocate all the structures needed to read an input stream.
1048  *        This does not open the needed codecs for decoding the stream[s].
1049  */
1050 int av_open_input_stream(AVFormatContext **ic_ptr,
1051                          ByteIOContext *pb, const char *filename,
1052                          AVInputFormat *fmt, AVFormatParameters *ap);
1053
1054 /**
1055  * Open a media file as input. The codecs are not opened. Only the file
1056  * header (if present) is read.
1057  *
1058  * @param ic_ptr The opened media file handle is put here.
1059  * @param filename filename to open
1060  * @param fmt If non-NULL, force the file format to use.
1061  * @param buf_size optional buffer size (zero if default is OK)
1062  * @param ap Additional parameters needed when opening the file
1063  *           (NULL if default).
1064  * @return 0 if OK, AVERROR_xxx otherwise
1065  */
1066 int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
1067                        AVInputFormat *fmt,
1068                        int buf_size,
1069                        AVFormatParameters *ap);
1070
1071 #if LIBAVFORMAT_VERSION_MAJOR < 53
1072 /**
1073  * @deprecated Use avformat_alloc_context() instead.
1074  */
1075 attribute_deprecated AVFormatContext *av_alloc_format_context(void);
1076 #endif
1077
1078 /**
1079  * Allocate an AVFormatContext.
1080  * Can be freed with av_free() but do not forget to free everything you
1081  * explicitly allocated as well!
1082  */
1083 AVFormatContext *avformat_alloc_context(void);
1084
1085 /**
1086  * Read packets of a media file to get stream information. This
1087  * is useful for file formats with no headers such as MPEG. This
1088  * function also computes the real framerate in case of MPEG-2 repeat
1089  * frame mode.
1090  * The logical file position is not changed by this function;
1091  * examined packets may be buffered for later processing.
1092  *
1093  * @param ic media file handle
1094  * @return >=0 if OK, AVERROR_xxx on error
1095  * @todo Let the user decide somehow what information is needed so that
1096  *       we do not waste time getting stuff the user does not need.
1097  */
1098 int av_find_stream_info(AVFormatContext *ic);
1099
1100 /**
1101  * Read a transport packet from a media file.
1102  *
1103  * This function is obsolete and should never be used.
1104  * Use av_read_frame() instead.
1105  *
1106  * @param s media file handle
1107  * @param pkt is filled
1108  * @return 0 if OK, AVERROR_xxx on error
1109  */
1110 int av_read_packet(AVFormatContext *s, AVPacket *pkt);
1111
1112 /**
1113  * Return the next frame of a stream.
1114  * This function returns what is stored in the file, and does not validate
1115  * that what is there are valid frames for the decoder. It will split what is
1116  * stored in the file into frames and return one for each call. It will not
1117  * omit invalid data between valid frames so as to give the decoder the maximum
1118  * information possible for decoding.
1119  *
1120  * The returned packet is valid
1121  * until the next av_read_frame() or until av_close_input_file() and
1122  * must be freed with av_free_packet. For video, the packet contains
1123  * exactly one frame. For audio, it contains an integer number of
1124  * frames if each frame has a known fixed size (e.g. PCM or ADPCM
1125  * data). If the audio frames have a variable size (e.g. MPEG audio),
1126  * then it contains one frame.
1127  *
1128  * pkt->pts, pkt->dts and pkt->duration are always set to correct
1129  * values in AVStream.time_base units (and guessed if the format cannot
1130  * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
1131  * has B-frames, so it is better to rely on pkt->dts if you do not
1132  * decompress the payload.
1133  *
1134  * @return 0 if OK, < 0 on error or end of file
1135  */
1136 int av_read_frame(AVFormatContext *s, AVPacket *pkt);
1137
1138 /**
1139  * Seek to the keyframe at timestamp.
1140  * 'timestamp' in 'stream_index'.
1141  * @param stream_index If stream_index is (-1), a default
1142  * stream is selected, and timestamp is automatically converted
1143  * from AV_TIME_BASE units to the stream specific time_base.
1144  * @param timestamp Timestamp in AVStream.time_base units
1145  *        or, if no stream is specified, in AV_TIME_BASE units.
1146  * @param flags flags which select direction and seeking mode
1147  * @return >= 0 on success
1148  */
1149 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
1150                   int flags);
1151
1152 /**
1153  * Seek to timestamp ts.
1154  * Seeking will be done so that the point from which all active streams
1155  * can be presented successfully will be closest to ts and within min/max_ts.
1156  * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
1157  *
1158  * If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and
1159  * are the file position (this may not be supported by all demuxers).
1160  * If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames
1161  * in the stream with stream_index (this may not be supported by all demuxers).
1162  * Otherwise all timestamps are in units of the stream selected by stream_index
1163  * or if stream_index is -1, in AV_TIME_BASE units.
1164  * If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
1165  * keyframes (this may not be supported by all demuxers).
1166  *
1167  * @param stream_index index of the stream which is used as time base reference
1168  * @param min_ts smallest acceptable timestamp
1169  * @param ts target timestamp
1170  * @param max_ts largest acceptable timestamp
1171  * @param flags flags
1172  * @return >=0 on success, error code otherwise
1173  *
1174  * @note This is part of the new seek API which is still under construction.
1175  *       Thus do not use this yet. It may change at any time, do not expect
1176  *       ABI compatibility yet!
1177  */
1178 int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
1179
1180 /**
1181  * Start playing a network-based stream (e.g. RTSP stream) at the
1182  * current position.
1183  */
1184 int av_read_play(AVFormatContext *s);
1185
1186 /**
1187  * Pause a network-based stream (e.g. RTSP stream).
1188  *
1189  * Use av_read_play() to resume it.
1190  */
1191 int av_read_pause(AVFormatContext *s);
1192
1193 /**
1194  * Free a AVFormatContext allocated by av_open_input_stream.
1195  * @param s context to free
1196  */
1197 void av_close_input_stream(AVFormatContext *s);
1198
1199 /**
1200  * Close a media file (but not its codecs).
1201  *
1202  * @param s media file handle
1203  */
1204 void av_close_input_file(AVFormatContext *s);
1205
1206 /**
1207  * Add a new stream to a media file.
1208  *
1209  * Can only be called in the read_header() function. If the flag
1210  * AVFMTCTX_NOHEADER is in the format context, then new streams
1211  * can be added in read_packet too.
1212  *
1213  * @param s media file handle
1214  * @param id file-format-dependent stream ID
1215  */
1216 AVStream *av_new_stream(AVFormatContext *s, int id);
1217 AVProgram *av_new_program(AVFormatContext *s, int id);
1218
1219 /**
1220  * Add a new chapter.
1221  * This function is NOT part of the public API
1222  * and should ONLY be used by demuxers.
1223  *
1224  * @param s media file handle
1225  * @param id unique ID for this chapter
1226  * @param start chapter start time in time_base units
1227  * @param end chapter end time in time_base units
1228  * @param title chapter title
1229  *
1230  * @return AVChapter or NULL on error
1231  */
1232 AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base,
1233                           int64_t start, int64_t end, const char *title);
1234
1235 /**
1236  * Set the pts for a given stream.
1237  *
1238  * @param s stream
1239  * @param pts_wrap_bits number of bits effectively used by the pts
1240  *        (used for wrap control, 33 is the value for MPEG)
1241  * @param pts_num numerator to convert to seconds (MPEG: 1)
1242  * @param pts_den denominator to convert to seconds (MPEG: 90000)
1243  */
1244 void av_set_pts_info(AVStream *s, int pts_wrap_bits,
1245                      unsigned int pts_num, unsigned int pts_den);
1246
1247 #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
1248 #define AVSEEK_FLAG_BYTE     2 ///< seeking based on position in bytes
1249 #define AVSEEK_FLAG_ANY      4 ///< seek to any frame, even non-keyframes
1250 #define AVSEEK_FLAG_FRAME    8 ///< seeking based on frame number
1251
1252 int av_find_default_stream_index(AVFormatContext *s);
1253
1254 /**
1255  * Get the index for a specific timestamp.
1256  * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
1257  *                 to the timestamp which is <= the requested one, if backward
1258  *                 is 0, then it will be >=
1259  *              if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
1260  * @return < 0 if no such timestamp could be found
1261  */
1262 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
1263
1264 /**
1265  * Ensure the index uses less memory than the maximum specified in
1266  * AVFormatContext.max_index_size by discarding entries if it grows
1267  * too large.
1268  * This function is not part of the public API and should only be called
1269  * by demuxers.
1270  */
1271 void ff_reduce_index(AVFormatContext *s, int stream_index);
1272
1273 /**
1274  * Add an index entry into a sorted list. Update the entry if the list
1275  * already contains it.
1276  *
1277  * @param timestamp timestamp in the time base of the given stream
1278  */
1279 int av_add_index_entry(AVStream *st, int64_t pos, int64_t timestamp,
1280                        int size, int distance, int flags);
1281
1282 /**
1283  * Perform a binary search using av_index_search_timestamp() and
1284  * AVInputFormat.read_timestamp().
1285  * This is not supposed to be called directly by a user application,
1286  * but by demuxers.
1287  * @param target_ts target timestamp in the time base of the given stream
1288  * @param stream_index stream number
1289  */
1290 int av_seek_frame_binary(AVFormatContext *s, int stream_index,
1291                          int64_t target_ts, int flags);
1292
1293 /**
1294  * Update cur_dts of all streams based on the given timestamp and AVStream.
1295  *
1296  * Stream ref_st unchanged, others set cur_dts in their native time base.
1297  * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
1298  * @param timestamp new dts expressed in time_base of param ref_st
1299  * @param ref_st reference stream giving time_base of param timestamp
1300  */
1301 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
1302
1303 /**
1304  * Perform a binary search using read_timestamp().
1305  * This is not supposed to be called directly by a user application,
1306  * but by demuxers.
1307  * @param target_ts target timestamp in the time base of the given stream
1308  * @param stream_index stream number
1309  */
1310 int64_t av_gen_search(AVFormatContext *s, int stream_index,
1311                       int64_t target_ts, int64_t pos_min,
1312                       int64_t pos_max, int64_t pos_limit,
1313                       int64_t ts_min, int64_t ts_max,
1314                       int flags, int64_t *ts_ret,
1315                       int64_t (*read_timestamp)(struct AVFormatContext *, int , int64_t *, int64_t ));
1316
1317 /**
1318  * media file output
1319  */
1320 int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
1321
1322 /**
1323  * Split a URL string into components.
1324  *
1325  * The pointers to buffers for storing individual components may be null,
1326  * in order to ignore that component. Buffers for components not found are
1327  * set to empty strings. If the port is not found, it is set to a negative
1328  * value.
1329  *
1330  * @param proto the buffer for the protocol
1331  * @param proto_size the size of the proto buffer
1332  * @param authorization the buffer for the authorization
1333  * @param authorization_size the size of the authorization buffer
1334  * @param hostname the buffer for the host name
1335  * @param hostname_size the size of the hostname buffer
1336  * @param port_ptr a pointer to store the port number in
1337  * @param path the buffer for the path
1338  * @param path_size the size of the path buffer
1339  * @param url the URL to split
1340  */
1341 void av_url_split(char *proto,         int proto_size,
1342                   char *authorization, int authorization_size,
1343                   char *hostname,      int hostname_size,
1344                   int *port_ptr,
1345                   char *path,          int path_size,
1346                   const char *url);
1347
1348 /**
1349  * Allocate the stream private data and write the stream header to an
1350  * output media file.
1351  *
1352  * @param s media file handle
1353  * @return 0 if OK, AVERROR_xxx on error
1354  */
1355 int av_write_header(AVFormatContext *s);
1356
1357 /**
1358  * Write a packet to an output media file.
1359  *
1360  * The packet shall contain one audio or video frame.
1361  * The packet must be correctly interleaved according to the container
1362  * specification, if not then av_interleaved_write_frame must be used.
1363  *
1364  * @param s media file handle
1365  * @param pkt The packet, which contains the stream_index, buf/buf_size,
1366               dts/pts, ...
1367  * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
1368  */
1369 int av_write_frame(AVFormatContext *s, AVPacket *pkt);
1370
1371 /**
1372  * Write a packet to an output media file ensuring correct interleaving.
1373  *
1374  * The packet must contain one audio or video frame.
1375  * If the packets are already correctly interleaved, the application should
1376  * call av_write_frame() instead as it is slightly faster. It is also important
1377  * to keep in mind that completely non-interleaved input will need huge amounts
1378  * of memory to interleave with this, so it is preferable to interleave at the
1379  * demuxer level.
1380  *
1381  * @param s media file handle
1382  * @param pkt The packet, which contains the stream_index, buf/buf_size,
1383               dts/pts, ...
1384  * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
1385  */
1386 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
1387
1388 /**
1389  * Interleave a packet per dts in an output media file.
1390  *
1391  * Packets with pkt->destruct == av_destruct_packet will be freed inside this
1392  * function, so they cannot be used after it. Note that calling av_free_packet()
1393  * on them is still safe.
1394  *
1395  * @param s media file handle
1396  * @param out the interleaved packet will be output here
1397  * @param pkt the input packet
1398  * @param flush 1 if no further packets are available as input and all
1399  *              remaining packets should be output
1400  * @return 1 if a packet was output, 0 if no packet could be output,
1401  *         < 0 if an error occurred
1402  */
1403 int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out,
1404                                  AVPacket *pkt, int flush);
1405
1406 /**
1407  * Write the stream trailer to an output media file and free the
1408  * file private data.
1409  *
1410  * May only be called after a successful call to av_write_header.
1411  *
1412  * @param s media file handle
1413  * @return 0 if OK, AVERROR_xxx on error
1414  */
1415 int av_write_trailer(AVFormatContext *s);
1416
1417 void dump_format(AVFormatContext *ic,
1418                  int index,
1419                  const char *url,
1420                  int is_output);
1421
1422 #if LIBAVFORMAT_VERSION_MAJOR < 53
1423 /**
1424  * Parse width and height out of string str.
1425  * @deprecated Use av_parse_video_frame_size instead.
1426  */
1427 attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr,
1428                                           const char *str);
1429
1430 /**
1431  * Convert framerate from a string to a fraction.
1432  * @deprecated Use av_parse_video_frame_rate instead.
1433  */
1434 attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
1435                                           const char *arg);
1436 #endif
1437
1438 /**
1439  * Parse datestr and return a corresponding number of microseconds.
1440  * @param datestr String representing a date or a duration.
1441  * - If a date the syntax is:
1442  * @code
1443  *  now|{[{YYYY-MM-DD|YYYYMMDD}[T|t| ]]{{HH[:MM[:SS[.m...]]]}|{HH[MM[SS[.m...]]]}}[Z|z]}
1444  * @endcode
1445  * If the value is "now" it takes the current time.
1446  * Time is local time unless Z is appended, in which case it is
1447  * interpreted as UTC.
1448  * If the year-month-day part is not specified it takes the current
1449  * year-month-day.
1450  * @return the number of microseconds since 1st of January, 1970 up to
1451  * the time of the parsed date or INT64_MIN if datestr cannot be
1452  * successfully parsed.
1453  * - If a duration the syntax is:
1454  * @code
1455  *  [-]HH[:MM[:SS[.m...]]]
1456  *  [-]S+[.m...]
1457  * @endcode
1458  * @return the number of microseconds contained in a time interval
1459  * with the specified duration or INT64_MIN if datestr cannot be
1460  * successfully parsed.
1461  * @param duration Flag which tells how to interpret datestr, if
1462  * not zero datestr is interpreted as a duration, otherwise as a
1463  * date.
1464  */
1465 int64_t parse_date(const char *datestr, int duration);
1466
1467 /**
1468  * Get the current time in microseconds.
1469  */
1470 int64_t av_gettime(void);
1471
1472 /* ffm-specific for ffserver */
1473 #define FFM_PACKET_SIZE 4096
1474 int64_t ffm_read_write_index(int fd);
1475 int ffm_write_write_index(int fd, int64_t pos);
1476 void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size);
1477
1478 /**
1479  * Attempt to find a specific tag in a URL.
1480  *
1481  * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
1482  * Return 1 if found.
1483  */
1484 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
1485
1486 /**
1487  * Return in 'buf' the path with '%d' replaced by a number.
1488  *
1489  * Also handles the '%0nd' format where 'n' is the total number
1490  * of digits and '%%'.
1491  *
1492  * @param buf destination buffer
1493  * @param buf_size destination buffer size
1494  * @param path numbered sequence string
1495  * @param number frame number
1496  * @return 0 if OK, -1 on format error
1497  */
1498 int av_get_frame_filename(char *buf, int buf_size,
1499                           const char *path, int number);
1500
1501 /**
1502  * Check whether filename actually is a numbered sequence generator.
1503  *
1504  * @param filename possible numbered sequence string
1505  * @return 1 if a valid numbered sequence string, 0 otherwise
1506  */
1507 int av_filename_number_test(const char *filename);
1508
1509 /**
1510  * Generate an SDP for an RTP session.
1511  *
1512  * @param ac array of AVFormatContexts describing the RTP streams. If the
1513  *           array is composed by only one context, such context can contain
1514  *           multiple AVStreams (one AVStream per RTP stream). Otherwise,
1515  *           all the contexts in the array (an AVCodecContext per RTP stream)
1516  *           must contain only one AVStream.
1517  * @param n_files number of AVCodecContexts contained in ac
1518  * @param buff buffer where the SDP will be stored (must be allocated by
1519  *             the caller)
1520  * @param size the size of the buffer
1521  * @return 0 if OK, AVERROR_xxx on error
1522  */
1523 int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
1524
1525 /**
1526  * Return a positive value if the given filename has one of the given
1527  * extensions, 0 otherwise.
1528  *
1529  * @param extensions a comma-separated list of filename extensions
1530  */
1531 int av_match_ext(const char *filename, const char *extensions);
1532
1533 #endif /* AVFORMAT_AVFORMAT_H */