/*

 * copyright (c) 2001 Fabrice Bellard

 *

 * This file is part of Libav.

 *

 * Libav is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * Libav is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with Libav; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

 */

#ifndef AVFORMAT_AVFORMAT_H

#define AVFORMAT_AVFORMAT_H

/**

 * @file

 * @ingroup libavf

 * Main libavformat public API header

 */

/**

 * @defgroup libavf I/O and Muxing/Demuxing Library

 * @{

 *

 * Libavformat (lavf) is a library for dealing with various media container

 * formats. Its main two purposes are demuxing - i.e. splitting a media file

 * into component streams, and the reverse process of muxing - writing supplied

 * data in a specified container format. It also has an @ref lavf_io

 * "I/O module" which supports a number of protocols for accessing the data (e.g.

 * file, tcp, http and others). Before using lavf, you need to call

 * av_register_all() to register all compiled muxers, demuxers and protocols.

 * Unless you are absolutely sure you won't use libavformat's network

 * capabilities, you should also call avformat_network_init().

 *

 * A supported input format is described by an AVInputFormat struct, conversely

 * an output format is described by AVOutputFormat. You can iterate over all

 * registered input/output formats using the av_iformat_next() /

 * av_oformat_next() functions. The protocols layer is not part of the public

 * API, so you can only get the names of supported protocols with the

 * avio_enum_protocols() function.

 *

 * Main lavf structure used for both muxing and demuxing is AVFormatContext,

 * which exports all information about the file being read or written. As with

 * most Libav structures, its size is not part of public ABI, so it cannot be

 * allocated on stack or directly with av_malloc(). To create an

 * AVFormatContext, use avformat_alloc_context() (some functions, like

 * avformat_open_input() might do that for you).

 *

 * Most importantly an AVFormatContext contains:

 * @li the @ref AVFormatContext.iformat "input" or @ref AVFormatContext.oformat

 * "output" format. It is either autodetected or set by user for input;

 * always set by user for output.

 * @li an @ref AVFormatContext.streams "array" of AVStreams, which describe all

 * elementary streams stored in the file. AVStreams are typically referred to

 * using their index in this array.

 * @li an @ref AVFormatContext.pb "I/O context". It is either opened by lavf or

 * set by user for input, always set by user for output (unless you are dealing

 * with an AVFMT_NOFILE format).

 *

 * @section lavf_options Passing options to (de)muxers

 * Lavf allows to configure muxers and demuxers using the @ref avoptions

 * mechanism. Generic (format-independent) libavformat options are provided by

 * AVFormatContext, they can be examined from a user program by calling

 * av_opt_next() / av_opt_find() on an allocated AVFormatContext (or its AVClass

 * from avformat_get_class()). Private (format-specific) options are provided by

 * AVFormatContext.priv_data if and only if AVInputFormat.priv_class /

 * AVOutputFormat.priv_class of the corresponding format struct is non-NULL.

 * Further options may be provided by the @ref AVFormatContext.pb "I/O context",

 * if its AVClass is non-NULL, and the protocols layer. See the discussion on

 * nesting in @ref avoptions documentation to learn how to access those.

 *

 * @defgroup lavf_decoding Demuxing

 * @{

 * Demuxers read a media file and split it into chunks of data (@em packets). A

 * @ref AVPacket "packet" contains one or more encoded frames which belongs to a

 * single elementary stream. In the lavf API this process is represented by the

 * avformat_open_input() function for opening a file, av_read_frame() for

 * reading a single packet and finally avformat_close_input(), which does the

 * cleanup.

 *

 * @section lavf_decoding_open Opening a media file

 * The minimum information required to open a file is its URL or filename, which

 * is passed to avformat_open_input(), as in the following code:

 * @code

 * const char    *url = "in.mp3";

 * AVFormatContext *s = NULL;

 * int ret = avformat_open_input(&s, url, NULL, NULL);

 * if (ret < 0)

 *     abort();

 * @endcode

 * The above code attempts to allocate an AVFormatContext, open the

 * specified file (autodetecting the format) and read the header, exporting the

 * information stored there into s. Some formats do not have a header or do not

 * store enough information there, so it is recommended that you call the

 * avformat_find_stream_info() function which tries to read and decode a few

 * frames to find missing information.

 *

 * In some cases you might want to preallocate an AVFormatContext yourself with

 * avformat_alloc_context() and do some tweaking on it before passing it to

 * avformat_open_input(). One such case is when you want to use custom functions

 * for reading input data instead of lavf internal I/O layer.

 * To do that, create your own AVIOContext with avio_alloc_context(), passing

 * your reading callbacks to it. Then set the @em pb field of your

 * AVFormatContext to newly created AVIOContext.

 *

 * Since the format of the opened file is in general not known until after

 * avformat_open_input() has returned, it is not possible to set demuxer private

 * options on a preallocated context. Instead, the options should be passed to

 * avformat_open_input() wrapped in an AVDictionary:

 * @code

 * AVDictionary *options = NULL;

 * av_dict_set(&options, "video_size", "640x480", 0);

 * av_dict_set(&options, "pixel_format", "rgb24", 0);

 *

 * if (avformat_open_input(&s, url, NULL, &options) < 0)

 *     abort();

 * av_dict_free(&options);

 * @endcode

 * This code passes the private options 'video_size' and 'pixel_format' to the

 * demuxer. They would be necessary for e.g. the rawvideo demuxer, since it

 * cannot know how to interpret raw video data otherwise. If the format turns

 * out to be something different than raw video, those options will not be

 * recognized by the demuxer and therefore will not be applied. Such unrecognized

 * options are then returned in the options dictionary (recognized options are

 * consumed). The calling program can handle such unrecognized options as it

 * wishes, e.g.

 * @code

 * AVDictionaryEntry *e;

 * if (e = av_dict_get(options, "", NULL, AV_DICT_IGNORE_SUFFIX)) {

 *     fprintf(stderr, "Option %s not recognized by the demuxer.\n", e->key);

 *     abort();

 * }

 * @endcode

 *

 * After you have finished reading the file, you must close it with

 * avformat_close_input(). It will free everything associated with the file.

 *

 * @section lavf_decoding_read Reading from an opened file

 * Reading data from an opened AVFormatContext is done by repeatedly calling

 * av_read_frame() on it. Each call, if successful, will return an AVPacket

 * containing encoded data for one AVStream, identified by

 * AVPacket.stream_index. This packet may be passed straight into the libavcodec

 * decoding functions avcodec_decode_video2(), avcodec_decode_audio4() or

 * avcodec_decode_subtitle2() if the caller wishes to decode the data.

 *

 * AVPacket.pts, AVPacket.dts and AVPacket.duration timing information will be

 * set if known. They may also be unset (i.e. AV_NOPTS_VALUE for

 * pts/dts, 0 for duration) if the stream does not provide them. The timing

 * information will be in AVStream.time_base units, i.e. it has to be

 * multiplied by the timebase to convert them to seconds.

 *

 * The packet data belongs to the demuxer and is invalid after the next call to

 * av_read_frame(). The user must free the packet with av_free_packet() before

 * calling av_read_frame() again or closing the file.

 *

 * @section lavf_decoding_seek Seeking

 * @}

 *

 * @defgroup lavf_encoding Muxing

 * @{

 * @}

 *

 * @defgroup lavf_io I/O Read/Write

 * @{

 * @}

 *

 * @defgroup lavf_codec Demuxers

 * @{

 * @defgroup lavf_codec_native Native Demuxers

 * @{

 * @}

 * @defgroup lavf_codec_wrappers External library wrappers

 * @{

 * @}

 * @}

 * @defgroup lavf_protos I/O Protocols

 * @{

 * @}

 * @defgroup lavf_internal Internal

 * @{

 * @}

 * @}

 *

 */

#include <time.h>

#include <stdio.h>  /* FILE */

#include "libavcodec/avcodec.h"

#include "libavutil/dict.h"

#include "libavutil/log.h"

#include "avio.h"

#include "libavformat/version.h"

#if FF_API_AV_GETTIME

#include "libavutil/time.h"

#endif

struct AVFormatContext;

/**

 * @defgroup metadata_api Public Metadata API

 * @{

 * @ingroup libavf

 * The metadata API allows libavformat to export metadata tags to a client

 * application when demuxing. Conversely it allows a client application to

 * set metadata when muxing.

 *

 * Metadata is exported or set as pairs of key/value strings in the 'metadata'

 * fields of the AVFormatContext, AVStream, AVChapter and AVProgram structs

 * using the @ref lavu_dict "AVDictionary" API. Like all strings in Libav,

 * metadata is assumed to be UTF-8 encoded Unicode. Note that metadata

 * exported by demuxers isn't checked to be valid UTF-8 in most cases.

 *

 * Important concepts to keep in mind:

 * -  Keys are unique; there can never be 2 tags with the same key. This is

 *    also meant semantically, i.e., a demuxer should not knowingly produce

 *    several keys that are literally different but semantically identical.

 *    E.g., key=Author5, key=Author6. In this example, all authors must be

 *    placed in the same tag.

 * -  Metadata is flat, not hierarchical; there are no subtags. If you

 *    want to store, e.g., the email address of the child of producer Alice

 *    and actor Bob, that could have key=alice_and_bobs_childs_email_address.

 * -  Several modifiers can be applied to the tag name. This is done by

 *    appending a dash character ('-') and the modifier name in the order

 *    they appear in the list below -- e.g. foo-eng-sort, not foo-sort-eng.

 *    -  language -- a tag whose value is localized for a particular language

 *       is appended with the ISO 639-2/B 3-letter language code.

 *       For example: Author-ger=Michael, Author-eng=Mike

 *       The original/default language is in the unqualified "Author" tag.

 *       A demuxer should set a default if it sets any translated tag.

 *    -  sorting  -- a modified version of a tag that should be used for

 *       sorting will have '-sort' appended. E.g. artist="The Beatles",

 *       artist-sort="Beatles, The".

 *

 * -  Demuxers attempt to export metadata in a generic format, however tags

 *    with no generic equivalents are left as they are stored in the container.

 *    Follows a list of generic tag names:

 *

 @verbatim

 album        -- name of the set this work belongs to

 album_artist -- main creator of the set/album, if different from artist.

                 e.g. "Various Artists" for compilation albums.

 artist       -- main creator of the work

 comment      -- any additional description of the file.

 composer     -- who composed the work, if different from artist.

 copyright    -- name of copyright holder.

 creation_time-- date when the file was created, preferably in ISO 8601.

 date         -- date when the work was created, preferably in ISO 8601.

 disc         -- number of a subset, e.g. disc in a multi-disc collection.

 encoder      -- name/settings of the software/hardware that produced the file.

 encoded_by   -- person/group who created the file.

 filename     -- original name of the file.

 genre        -- <self-evident>.

 language     -- main language in which the work is performed, preferably

                 in ISO 639-2 format. Multiple languages can be specified by

                 separating them with commas.

 performer    -- artist who performed the work, if different from artist.

                 E.g for "Also sprach Zarathustra", artist would be "Richard

                 Strauss" and performer "London Philharmonic Orchestra".

 publisher    -- name of the label/publisher.

 service_name     -- name of the service in broadcasting (channel name).

 service_provider -- name of the service provider in broadcasting.

 title        -- name of the work.

 track        -- number of this work in the set, can be in form current/total.

 variant_bitrate -- the total bitrate of the bitrate variant that the current stream is part of

 @endverbatim

 *

 * Look in the examples section for an application example how to use the Metadata API.

 *

 * @}

 */

/* packet functions */

/**

 * Allocate and read the payload of a packet and initialize its

 * fields with default values.

 *

 * @param pkt packet

 * @param size desired payload size

 * @return >0 (read size) if OK, AVERROR_xxx otherwise

 */

int av_get_packet(AVIOContext *s, AVPacket *pkt, int size);

/**

 * Read data and append it to the current content of the AVPacket.

 * If pkt->size is 0 this is identical to av_get_packet.

 * Note that this uses av_grow_packet and thus involves a realloc

 * which is inefficient. Thus this function should only be used

 * when there is no reasonable way to know (an upper bound of)

 * the final size.

 *

 * @param pkt packet

 * @param size amount of data to read

 * @return >0 (read size) if OK, AVERROR_xxx otherwise, previous data

 *         will not be lost even if an error occurs.

 */

int av_append_packet(AVIOContext *s, AVPacket *pkt, int size);

/*************************************************/

/* fractional numbers for exact pts handling */

/**

 * The exact value of the fractional number is: 'val + num / den'.

 * num is assumed to be 0 <= num < den.

 */

typedef struct AVFrac {

    int64_t val, num, den;

} AVFrac;

/*************************************************/

/* input/output formats */

struct AVCodecTag;

/**

 * This structure contains the data a format has to probe a file.

 */

typedef struct AVProbeData {

    const char *filename;

    unsigned char *buf; /**< Buffer must have AVPROBE_PADDING_SIZE of extra allocated bytes filled with zero. */

    int buf_size;       /**< Size of buf except extra allocated bytes */

} AVProbeData;

#define AVPROBE_SCORE_MAX 100               ///< maximum score, half of that is used for file-extension-based detection

#define AVPROBE_PADDING_SIZE 32             ///< extra allocated bytes at the end of the probe buffer

/// Demuxer will use avio_open, no opened file should be provided by the caller.

#define AVFMT_NOFILE        0x0001

#define AVFMT_NEEDNUMBER    0x0002 /**< Needs '%d' in filename. */

#define AVFMT_SHOW_IDS      0x0008 /**< Show format stream IDs numbers. */

#define AVFMT_RAWPICTURE    0x0020 /**< Format wants AVPicture structure for

                                      raw picture data. */

#define AVFMT_GLOBALHEADER  0x0040 /**< Format wants global header. */

#define AVFMT_NOTIMESTAMPS  0x0080 /**< Format does not need / have any timestamps. */

#define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */

#define AVFMT_TS_DISCONT    0x0200 /**< Format allows timestamp discontinuities. Note, muxers always require valid (monotone) timestamps */

#define AVFMT_VARIABLE_FPS  0x0400 /**< Format allows variable fps. */

#define AVFMT_NODIMENSIONS  0x0800 /**< Format does not need width/height */

#define AVFMT_NOSTREAMS     0x1000 /**< Format does not require any streams */

#define AVFMT_NOBINSEARCH   0x2000 /**< Format does not allow to fallback to binary search via read_timestamp */

#define AVFMT_NOGENSEARCH   0x4000 /**< Format does not allow to fallback to generic search */

#define AVFMT_NO_BYTE_SEEK  0x8000 /**< Format does not allow seeking by bytes */

#define AVFMT_ALLOW_FLUSH  0x10000 /**< Format allows flushing. If not set, the muxer will not receive a NULL packet in the write_packet function. */

#define AVFMT_TS_NONSTRICT 0x20000 /**< Format does not require strictly

                                        increasing timestamps, but they must

                                        still be monotonic */

/**

 * @addtogroup lavf_encoding

 * @{

 */

typedef struct AVOutputFormat {

    const char *name;

    /**

     * Descriptive name for the format, meant to be more human-readable

     * than name. You should use the NULL_IF_CONFIG_SMALL() macro

     * to define it.

     */

    const char *long_name;

    const char *mime_type;

    const char *extensions; /**< comma-separated filename extensions */

    /* output support */

    enum AVCodecID audio_codec;    /**< default audio codec */

    enum AVCodecID video_codec;    /**< default video codec */

    enum AVCodecID subtitle_codec; /**< default subtitle codec */

    /**

     * can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_RAWPICTURE,

     * AVFMT_GLOBALHEADER, AVFMT_NOTIMESTAMPS, AVFMT_VARIABLE_FPS,

     * AVFMT_NODIMENSIONS, AVFMT_NOSTREAMS, AVFMT_ALLOW_FLUSH,

     * AVFMT_TS_NONSTRICT

     */

    int flags;

    /**

     * List of supported codec_id-codec_tag pairs, ordered by "better

     * choice first". The arrays are all terminated by AV_CODEC_ID_NONE.

     */

    const struct AVCodecTag * const *codec_tag;

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

    /*****************************************************************

     * No fields below this line are part of the public API. They

     * may not be used outside of libavformat and can be changed and

     * removed at will.

     * New public fields should be added right above.

     *****************************************************************

     */

    struct AVOutputFormat *next;

    /**

     * size of private data so that it can be allocated in the wrapper

     */

    int priv_data_size;

    int (*write_header)(struct AVFormatContext *);

    /**

     * Write a packet. If AVFMT_ALLOW_FLUSH is set in flags,

     * pkt can be NULL in order to flush data buffered in the muxer.

     * When flushing, return 0 if there still is more data to flush,

     * or 1 if everything was flushed and there is no more buffered

     * data.

     */

    int (*write_packet)(struct AVFormatContext *, AVPacket *pkt);

    int (*write_trailer)(struct AVFormatContext *);

    /**

     * Currently only used to set pixel format if not YUV420P.

     */

    int (*interleave_packet)(struct AVFormatContext *, AVPacket *out,

                             AVPacket *in, int flush);

    /**

     * Test if the given codec can be stored in this container.

     *

     * @return 1 if the codec is supported, 0 if it is not.

     *         A negative number if unknown.

     */

    int (*query_codec)(enum AVCodecID id, int std_compliance);

} AVOutputFormat;

/**

 * @}

 */

/**

 * @addtogroup lavf_decoding

 * @{

 */

typedef struct AVInputFormat {

    /**

     * A comma separated list of short names for the format. New names

     * may be appended with a minor bump.

     */

    const char *name;

    /**

     * Descriptive name for the format, meant to be more human-readable

     * than name. You should use the NULL_IF_CONFIG_SMALL() macro

     * to define it.

     */

    const char *long_name;

    /**

     * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_SHOW_IDS,

     * AVFMT_GENERIC_INDEX, AVFMT_TS_DISCONT, AVFMT_NOBINSEARCH,

     * AVFMT_NOGENSEARCH, AVFMT_NO_BYTE_SEEK.

     */

    int flags;

    /**

     * If extensions are defined, then no probe is done. You should

     * usually not use extension format guessing because it is not

     * reliable enough

     */

    const char *extensions;

    const struct AVCodecTag * const *codec_tag;

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

    /*****************************************************************

     * No fields below this line are part of the public API. They

     * may not be used outside of libavformat and can be changed and

     * removed at will.

     * New public fields should be added right above.

     *****************************************************************

     */

    struct AVInputFormat *next;

    /**

     * Raw demuxers store their codec ID here.

     */

    int raw_codec_id;

    /**

     * Size of private data so that it can be allocated in the wrapper.

     */

    int priv_data_size;

    /**

     * Tell if a given file has a chance of being parsed as this format.

     * The buffer provided is guaranteed to be AVPROBE_PADDING_SIZE bytes

     * big so you do not have to check for that unless you need more.

     */

    int (*read_probe)(AVProbeData *);

    /**

     * Read the format header and initialize the AVFormatContext

     * structure. Return 0 if OK. Only used in raw format right

     * now. 'avformat_new_stream' should be called to create new streams.

     */

    int (*read_header)(struct AVFormatContext *);

    /**

     * Read one packet and put it in 'pkt'. pts and flags are also

     * set. 'avformat_new_stream' can be called only if the flag

     * AVFMTCTX_NOHEADER is used and only in the calling thread (not in a

     * background thread).

     * @return 0 on success, < 0 on error.

     *         When returning an error, pkt must not have been allocated

     *         or must be freed before returning

     */

    int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);

    /**

     * Close the stream. The AVFormatContext and AVStreams are not

     * freed by this function

     */

    int (*read_close)(struct AVFormatContext *);

    /**

     * Seek to a given timestamp relative to the frames in

     * stream component stream_index.

     * @param stream_index Must not be -1.

     * @param flags Selects which direction should be preferred if no exact

     *              match is available.

     * @return >= 0 on success (but not necessarily the new offset)