X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=libavformat%2Favformat.h;h=fdaffa5bf41b6ed83fa4f7acebcf04ed796296fd;hb=cb46a6bcbcb85b3910cc0cce78399686ab8efff6;hp=4ea1b5ab727b35663a23310f72a56046d9424ea0;hpb=ecb3d6edc3b756cc1d40b1073f244b581ef5bcfb;p=ffmpeg diff --git a/libavformat/avformat.h b/libavformat/avformat.h index 4ea1b5ab727..2b42fb7fad9 100644 --- a/libavformat/avformat.h +++ b/libavformat/avformat.h @@ -36,17 +36,15 @@ * 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. + * file, tcp, http and others). * 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. + * input/output formats using the av_demuxer_iterate / av_muxer_iterate() 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 @@ -172,14 +170,9 @@ * information will be in AVStream.time_base units, i.e. it has to be * multiplied by the timebase to convert them to seconds. * - * If AVPacket.buf is set on the returned packet, then the packet is - * allocated dynamically and the user may keep it indefinitely. - * Otherwise, if AVPacket.buf is NULL, the packet data is backed by a - * static storage somewhere inside the demuxer and the packet is only valid - * until the next av_read_frame() call or closing the file. If the caller - * requires a longer lifetime, av_dup_packet() will make an av_malloc()ed copy - * of it. - * In both cases, the packet must be freed with av_packet_unref() when it is no + * A packet returned by av_read_frame() is always reference-counted, + * i.e. AVPacket.buf is set and the user may keep it indefinitely. + * The packet must be freed with av_packet_unref() when it is no * longer needed. * * @section lavf_decoding_seek Seeking @@ -363,7 +356,7 @@ struct AVDeviceCapabilitiesQuery; * sorting will have '-sort' appended. E.g. artist="The Beatles", * artist-sort="Beatles, The". * - Some protocols and demuxers support metadata updates. After a successful - * call to av_read_packet(), AVFormatContext.event_flags or AVStream.event_flags + * call to av_read_frame(), AVFormatContext.event_flags or AVStream.event_flags * will be updated to indicate if metadata changed. In order to detect metadata * changes on a stream, you need to loop through all streams in the AVFormatContext * and check their individual event_flags. @@ -532,7 +525,18 @@ typedef struct AVOutputFormat { * New public fields should be added right above. ***************************************************************** */ - struct AVOutputFormat *next; + /** + * The ff_const59 define is not part of the public API and will + * be removed without further warning. + */ +#if FF_API_AVIOFORMAT +#define ff_const59 +#else +#define ff_const59 const +#endif +#if FF_API_NEXT + ff_const59 struct AVOutputFormat *next; +#endif /** * size of private data so that it can be allocated in the wrapper */ @@ -549,7 +553,8 @@ typedef struct AVOutputFormat { int (*write_packet)(struct AVFormatContext *, AVPacket *pkt); int (*write_trailer)(struct AVFormatContext *); /** - * Currently only used to set pixel format if not YUV420P. + * A format-specific function for interleavement. + * If unset, packets will be interleaved by dts. */ int (*interleave_packet)(struct AVFormatContext *, AVPacket *out, AVPacket *in, int flush); @@ -646,7 +651,7 @@ typedef struct AVInputFormat { /** * Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_SHOW_IDS, - * AVFMT_GENERIC_INDEX, AVFMT_TS_DISCONT, AVFMT_NOBINSEARCH, + * AVFMT_NOTIMESTAMPS, AVFMT_GENERIC_INDEX, AVFMT_TS_DISCONT, AVFMT_NOBINSEARCH, * AVFMT_NOGENSEARCH, AVFMT_NO_BYTE_SEEK, AVFMT_SEEK_TO_PTS. */ int flags; @@ -676,7 +681,9 @@ typedef struct AVInputFormat { * New public fields should be added right above. ***************************************************************** */ - struct AVInputFormat *next; +#if FF_API_NEXT + ff_const59 struct AVInputFormat *next; +#endif /** * Raw demuxers store their codec ID here. @@ -693,7 +700,7 @@ typedef struct AVInputFormat { * 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 *); + int (*read_probe)(const AVProbeData *); /** * Read the format header and initialize the AVFormatContext @@ -708,8 +715,7 @@ typedef struct AVInputFormat { * 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 + * Upon returning an error, pkt must be unreferenced by the caller. */ int (*read_packet)(struct AVFormatContext *, AVPacket *pkt); @@ -845,6 +851,8 @@ typedef struct AVStreamInternal AVStreamInternal; #define AV_DISPOSITION_CAPTIONS 0x10000 #define AV_DISPOSITION_DESCRIPTIONS 0x20000 #define AV_DISPOSITION_METADATA 0x40000 +#define AV_DISPOSITION_DEPENDENT 0x80000 ///< dependent audio stream (mix_type=0 in mpegts) +#define AV_DISPOSITION_STILL_IMAGE 0x100000 ///< still images in video stream (still_picture_flag=1 in mpegts) /** * Options for behavior on timestamp wrap detection. @@ -969,12 +977,30 @@ typedef struct AVStream { int nb_side_data; /** - * Flags for the user to detect events happening on the stream. Flags must - * be cleared by the user once the event has been handled. - * A combination of AVSTREAM_EVENT_FLAG_*. + * Flags indicating events happening on the stream, a combination of + * AVSTREAM_EVENT_FLAG_*. + * + * - demuxing: may be set by the demuxer in avformat_open_input(), + * avformat_find_stream_info() and av_read_frame(). Flags must be cleared + * by the user once the event has been handled. + * - muxing: may be set by the user after avformat_write_header(). to + * indicate a user-triggered event. The muxer will clear the flags for + * events it has handled in av_[interleaved]_write_frame(). */ int event_flags; -#define AVSTREAM_EVENT_FLAG_METADATA_UPDATED 0x0001 ///< The call resulted in updated metadata. +/** + * - demuxing: the demuxer read new metadata from the file and updated + * AVStream.metadata accordingly + * - muxing: the user updated AVStream.metadata and wishes the muxer to write + * it into the file + */ +#define AVSTREAM_EVENT_FLAG_METADATA_UPDATED 0x0001 +/** + * - demuxing: new packets for this stream were read from the file. This + * event is informational only and does not guarantee that new packets + * for this stream will necessarily be returned from av_read_frame(). + */ +#define AVSTREAM_EVENT_FLAG_NEW_PACKETS (1 << 1) /** * Real base framerate of the stream. @@ -1019,38 +1045,10 @@ typedef struct AVStream { ***************************************************************** */ -#define MAX_STD_TIMEBASES (30*12+30+3+6) - /** - * Stream information used internally by avformat_find_stream_info() - */ - struct { - int64_t last_dts; - int64_t duration_gcd; - int duration_count; - int64_t rfps_duration_sum; - double (*duration_error)[2][MAX_STD_TIMEBASES]; - int64_t codec_info_duration; - int64_t codec_info_duration_fields; - int frame_delay_evidence; - - /** - * 0 -> decoder has not been searched for yet. - * >0 -> decoder found - * <0 -> decoder with codec_id == -found_decoder has not been found - */ - int found_decoder; - - int64_t last_duration; - - /** - * Those are used for average framerate estimation. - */ - int64_t fps_first_dts; - int fps_first_dts_idx; - int64_t fps_last_dts; - int fps_last_dts_idx; - - } *info; +#if LIBAVFORMAT_VERSION_MAJOR < 59 + // kept for ABI compatibility only, do not access in any way + void *unused; +#endif int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */ @@ -1101,6 +1099,13 @@ typedef struct AVStream { */ int stream_identifier; + /** + * Details of the MPEG-TS program which created this stream. + */ + int program_num; + int pmt_version; + int pmt_stream_idx; + int64_t interleaver_chunk_size; int64_t interleaver_chunk_duration; @@ -1109,7 +1114,6 @@ typedef struct AVStream { * -1 -> probing finished * 0 -> no probing requested * rest -> perform probing with request_probe being the minimum score to accept. - * NOT PART OF PUBLIC API */ int request_probe; /** @@ -1147,65 +1151,6 @@ typedef struct AVStream { */ int64_t last_discard_sample; - /** - * Number of internally decoded frames, used internally in libavformat, do not access - * its lifetime differs from info which is why it is not in that structure. - */ - int nb_decoded_frames; - - /** - * Timestamp offset added to timestamps before muxing - * NOT PART OF PUBLIC API - */ - int64_t mux_ts_offset; - - /** - * Internal data to check for wrapping of the time stamp - */ - int64_t pts_wrap_reference; - - /** - * Options for behavior, when a wrap is detected. - * - * Defined by AV_PTS_WRAP_ values. - * - * If correction is enabled, there are two possibilities: - * If the first time stamp is near the wrap point, the wrap offset - * will be subtracted, which will create negative time stamps. - * Otherwise the offset will be added. - */ - int pts_wrap_behavior; - - /** - * Internal data to prevent doing update_initial_durations() twice - */ - int update_initial_durations_done; - - /** - * Internal data to generate dts from pts - */ - int64_t pts_reorder_error[MAX_REORDER_DELAY+1]; - uint8_t pts_reorder_error_count[MAX_REORDER_DELAY+1]; - - /** - * Internal data to analyze DTS and detect faulty mpeg streams - */ - int64_t last_dts_for_order_check; - uint8_t dts_ordered; - uint8_t dts_misordered; - - /** - * Internal data to inject global side data - */ - int inject_global_side_data; - - /** - * display aspect ratio (0 if unknown) - * - encoding: unused - * - decoding: Set by libavformat to calculate sample_aspect_ratio internally - */ - AVRational display_aspect_ratio; - /** * An opaque field for libavformat internal usage. * Must not be accessed in any way by callers. @@ -1258,6 +1203,7 @@ typedef struct AVProgram { int program_num; int pmt_pid; int pcr_pid; + int pmt_version; /***************************************************************** * All fields below this line are not part of the public API. They @@ -1336,14 +1282,14 @@ typedef struct AVFormatContext { * * Demuxing only, set by avformat_open_input(). */ - struct AVInputFormat *iformat; + ff_const59 struct AVInputFormat *iformat; /** * The output container format. * * Muxing only, must be set by the caller before avformat_write_header(). */ - struct AVOutputFormat *oformat; + ff_const59 struct AVOutputFormat *oformat; /** * Format private data. This is an AVOptions-enabled struct @@ -1473,7 +1419,9 @@ typedef struct AVFormatContext { * This flag is mainly intended for testing. */ #define AVFMT_FLAG_BITEXACT 0x0400 -#define AVFMT_FLAG_MP4A_LATM 0x8000 ///< Enable RTP MP4A-LATM payload +#if FF_API_LAVF_MP4A_LATM +#define AVFMT_FLAG_MP4A_LATM 0x8000 ///< Deprecated, does nothing. +#endif #define AVFMT_FLAG_SORT_DTS 0x10000 ///< try to interleave outputted packets by dts (using this flag can slow demuxing down) #define AVFMT_FLAG_PRIV_OPT 0x20000 ///< Enable use of private options by delaying codec open (this could be made default once all code is converted) #if FF_API_LAVF_KEEPSIDE_FLAG @@ -1633,12 +1581,24 @@ typedef struct AVFormatContext { int strict_std_compliance; /** - * Flags for the user to detect events happening on the file. Flags must - * be cleared by the user once the event has been handled. - * A combination of AVFMT_EVENT_FLAG_*. + * Flags indicating events happening on the file, a combination of + * AVFMT_EVENT_FLAG_*. + * + * - demuxing: may be set by the demuxer in avformat_open_input(), + * avformat_find_stream_info() and av_read_frame(). Flags must be cleared + * by the user once the event has been handled. + * - muxing: may be set by the user after avformat_write_header() to + * indicate a user-triggered event. The muxer will clear the flags for + * events it has handled in av_[interleaved]_write_frame(). */ int event_flags; -#define AVFMT_EVENT_FLAG_METADATA_UPDATED 0x0001 ///< The call resulted in updated metadata. +/** + * - demuxing: the demuxer read new metadata from the file and updated + * AVFormatContext.metadata accordingly + * - muxing: the user updated AVFormatContext.metadata and wishes the muxer to + * write it into the file + */ +#define AVFMT_EVENT_FLAG_METADATA_UPDATED 0x0001 /** * Maximum number of packets to read while waiting for the first timestamp. @@ -1925,6 +1885,20 @@ typedef struct AVFormatContext { * - decoding: set by user */ int max_streams; + + /** + * Skip duration calcuation in estimate_timings_from_pts. + * - encoding: unused + * - decoding: set by user + */ + int skip_estimate_duration_from_pts; + + /** + * Maximum number of packets that can be probed + * - encoding: unused + * - decoding: set by user + */ + int max_probe_packets; } AVFormatContext; #if FF_API_FORMAT_GET_SET @@ -1981,12 +1955,6 @@ void av_format_inject_global_side_data(AVFormatContext *s); */ enum AVDurationEstimationMethod av_fmt_ctx_get_duration_estimation_method(const AVFormatContext* ctx); -typedef struct AVPacketList { - AVPacket pkt; - struct AVPacketList *next; -} AVPacketList; - - /** * @defgroup lavf_core Core functions * @ingroup libavf @@ -2163,7 +2131,8 @@ uint8_t *av_stream_new_side_data(AVStream *stream, * * @param stream stream * @param type desired side information type - * @param size pointer for side information size to store (optional) + * @param size If supplied, *size will be set to the size of the side data + * or to zero if the desired side data is not present. * @return pointer to data if present or NULL otherwise */ uint8_t *av_stream_get_side_data(const AVStream *stream, @@ -2192,7 +2161,7 @@ AVProgram *av_new_program(AVFormatContext *s, int id); * @return >= 0 in case of success, a negative AVERROR code in case of * failure */ -int avformat_alloc_output_context2(AVFormatContext **ctx, AVOutputFormat *oformat, +int avformat_alloc_output_context2(AVFormatContext **ctx, ff_const59 AVOutputFormat *oformat, const char *format_name, const char *filename); /** @@ -2203,7 +2172,7 @@ int avformat_alloc_output_context2(AVFormatContext **ctx, AVOutputFormat *oforma /** * Find AVInputFormat based on the short name of the input format. */ -AVInputFormat *av_find_input_format(const char *short_name); +ff_const59 AVInputFormat *av_find_input_format(const char *short_name); /** * Guess the file format. @@ -2212,7 +2181,7 @@ AVInputFormat *av_find_input_format(const char *short_name); * @param is_opened Whether the file is already opened; determines whether * demuxers with or without AVFMT_NOFILE are probed. */ -AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened); +ff_const59 AVInputFormat *av_probe_input_format(ff_const59 AVProbeData *pd, int is_opened); /** * Guess the file format. @@ -2226,7 +2195,7 @@ AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened); * If the score is <= AVPROBE_SCORE_MAX / 4 it is recommended * to retry with a larger probe buffer. */ -AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max); +ff_const59 AVInputFormat *av_probe_input_format2(ff_const59 AVProbeData *pd, int is_opened, int *score_max); /** * Guess the file format. @@ -2235,7 +2204,7 @@ AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score * demuxers with or without AVFMT_NOFILE are probed. * @param score_ret The score of the best detection. */ -AVInputFormat *av_probe_input_format3(AVProbeData *pd, int is_opened, int *score_ret); +ff_const59 AVInputFormat *av_probe_input_format3(ff_const59 AVProbeData *pd, int is_opened, int *score_ret); /** * Probe a bytestream to determine the input format. Each time a probe returns @@ -2253,14 +2222,14 @@ AVInputFormat *av_probe_input_format3(AVProbeData *pd, int is_opened, int *score * the maximal score is AVPROBE_SCORE_MAX * AVERROR code otherwise */ -int av_probe_input_buffer2(AVIOContext *pb, AVInputFormat **fmt, +int av_probe_input_buffer2(AVIOContext *pb, ff_const59 AVInputFormat **fmt, const char *url, void *logctx, unsigned int offset, unsigned int max_probe_size); /** * Like av_probe_input_buffer2() but returns 0 on success */ -int av_probe_input_buffer(AVIOContext *pb, AVInputFormat **fmt, +int av_probe_input_buffer(AVIOContext *pb, ff_const59 AVInputFormat **fmt, const char *url, void *logctx, unsigned int offset, unsigned int max_probe_size); @@ -2283,7 +2252,7 @@ int av_probe_input_buffer(AVIOContext *pb, AVInputFormat **fmt, * * @note If you want to use custom IO, preallocate the format context and set its pb field. */ -int avformat_open_input(AVFormatContext **ps, const char *url, AVInputFormat *fmt, AVDictionary **options); +int avformat_open_input(AVFormatContext **ps, const char *url, ff_const59 AVInputFormat *fmt, AVDictionary **options); attribute_deprecated int av_demuxer_open(AVFormatContext *ic); @@ -2364,13 +2333,12 @@ int av_find_best_stream(AVFormatContext *ic, * omit invalid data between valid frames so as to give the decoder the maximum * information possible for decoding. * - * If pkt->buf is NULL, then the packet is valid until the next - * av_read_frame() or until avformat_close_input(). Otherwise the packet - * is valid indefinitely. In both cases the packet must be freed with - * av_packet_unref when it is no longer needed. For video, the packet contains - * exactly one frame. For audio, it contains an integer number of frames if each - * frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames - * have a variable size (e.g. MPEG audio), then it contains one frame. + * On success, the returned packet is reference-counted (pkt->buf is set) and + * valid indefinitely. The packet must be freed with av_packet_unref() when + * it is no longer needed. For video, the packet contains exactly one frame. + * For audio, it contains an integer number of frames if each frame has + * a known fixed size (e.g. PCM or ADPCM data). If the audio frames have + * a variable size (e.g. MPEG audio), then it contains one frame. * * pkt->pts, pkt->dts and pkt->duration are always set to correct * values in AVStream.time_base units (and guessed if the format cannot @@ -2378,7 +2346,11 @@ int av_find_best_stream(AVFormatContext *ic, * has B-frames, so it is better to rely on pkt->dts if you do not * decompress the payload. * - * @return 0 if OK, < 0 on error or end of file + * @return 0 if OK, < 0 on error or end of file. On error, pkt will be blank + * (as if it came from av_packet_alloc()). + * + * @note pkt will be initialized, so it may be uninitialized, but it must not + * contain data that needs to be freed. */ int av_read_frame(AVFormatContext *s, AVPacket *pkt); @@ -2423,8 +2395,6 @@ int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, * @return >=0 on success, error code otherwise * * @note This is part of the new seek API which is still under construction. - * Thus do not use this yet. It may change at any time, do not expect - * ABI compatibility yet! */ int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags); @@ -2611,9 +2581,9 @@ int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); * Write an uncoded frame to an output media file. * * The frame must be correctly interleaved according to the container - * specification; if not, then av_interleaved_write_frame() must be used. + * specification; if not, av_interleaved_write_uncoded_frame() must be used. * - * See av_interleaved_write_frame() for details. + * See av_interleaved_write_uncoded_frame() for details. */ int av_write_uncoded_frame(AVFormatContext *s, int stream_index, AVFrame *frame); @@ -2668,14 +2638,14 @@ int av_write_trailer(AVFormatContext *s); * @param mime_type if non-NULL checks if mime_type matches with the * MIME type of the registered formats */ -AVOutputFormat *av_guess_format(const char *short_name, +ff_const59 AVOutputFormat *av_guess_format(const char *short_name, const char *filename, const char *mime_type); /** * Guess the codec ID based upon muxer and filename. */ -enum AVCodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name, +enum AVCodecID av_guess_codec(ff_const59 AVOutputFormat *fmt, const char *short_name, const char *filename, const char *mime_type, enum AVMediaType type);