generic-library/ffmpeg
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

spelling/wording/grammar

Browse Source 
Originally committed as revision 15440 to svn://svn.ffmpeg.org/ffmpeg/trunk
This commit is contained in:
Diego Biurrun 2008-09-27 19:51:53 +00:00
parent fff5e687a1
commit 4f57fa8c03
1 changed files with 158 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

312
libavformat/avformat.h
View File

@ -50,18 +50,18 @@ unsigned avformat_version(void);
typedef struct AVPacket { typedef struct AVPacket {
/** /**
* Presentation time stamp in time_base units. * Presentation timestamp in time_base units.
* This is the time at which the decompressed packet will be presented * This is the time at which the decompressed packet will be presented
* to the user. * to the user.
* Can be AV_NOPTS_VALUE if it is not stored in the file. * Can be AV_NOPTS_VALUE if it is not stored in the file.
* pts MUST be larger or equal to dts as presentation can not happen before * pts MUST be larger or equal to dts as presentation cannot happen before
* decompression, unless one wants to view hex dumps. Some formats misuse * decompression, unless one wants to view hex dumps. Some formats misuse
* the terms dts and pts/cts to mean something different, these timestamps * the terms dts and pts/cts to mean something different, these timestamps
* must be converted to true pts/dts before they are stored in AVPacket. * must be converted to true pts/dts before they are stored in AVPacket.
*/ */
int64_t pts; int64_t pts;
/** /**
* Decompression time stamp in time_base units. * Decompression timestamp in time_base units.
* This is the time at which the packet is decompressed. * This is the time at which the packet is decompressed.
* Can be AV_NOPTS_VALUE if it is not stored in the file. * Can be AV_NOPTS_VALUE if it is not stored in the file.
*/ */
@ -80,17 +80,17 @@ typedef struct AVPacket {
int64_t pos; ///< byte position in stream, -1 if unknown int64_t pos; ///< byte position in stream, -1 if unknown
/** /**
* This is the time difference in stream timebase units from the pts of this * Time difference in stream time base units from the pts of this
* packet to the point at which the output from the decoder has converged * packet to the point at which the output from the decoder has converged
* independent from the availability * independent from the availability of previous frames. That is, the
* of previous frames (that is the frames are virtually identical no matter * frames are virtually identical no matter if decoding started from
* if decoding started from the very first frame or from this keyframe). * the very first frame or from this keyframe.
* is AV_NOPTS_VALUE if unknown. * Is AV_NOPTS_VALUE if unknown.
* This field is not the display duration of the current packet. * This field is not the display duration of the current packet.
* *
* The purpose of this field is to allow seeking in streams that have no * The purpose of this field is to allow seeking in streams that have no
* keyframes in the conventional sense. It corresponds to the * keyframes in the conventional sense. It corresponds to the
* recovery point SEI in H.264 and match_time_delta in nut. It also is * recovery point SEI in H.264 and match_time_delta in NUT. It is also
* essential for some types of subtitle streams to ensure that all * essential for some types of subtitle streams to ensure that all
* subtitles are correctly displayed after seeking. * subtitles are correctly displayed after seeking.
*/ */
@ -106,38 +106,40 @@ void av_destruct_packet_nofree(AVPacket *pkt);
void av_destruct_packet(AVPacket *pkt); void av_destruct_packet(AVPacket *pkt);
/** /**
* Initialize optional fields of a packet to default values. * Initialize optional fields of a packet with default values.
* *
* @param pkt packet * @param pkt packet
*/ */
void av_init_packet(AVPacket *pkt); void av_init_packet(AVPacket *pkt);
/** /**
* Allocate the payload of a packet and initialize its fields to default values. * Allocate the payload of a packet and initialize its fields with
* default values.
* *
* @param pkt packet * @param pkt packet
* @param size wanted payload size * @param size wanted payload size
* @return 0 if OK. AVERROR_xxx otherwise. * @return 0 if OK, AVERROR_xxx otherwise
*/ */
int av_new_packet(AVPacket *pkt, int size); int av_new_packet(AVPacket *pkt, int size);
/** /**
* Allocate and read the payload of a packet and initialize its fields to default values. * Allocate and read the payload of a packet and initialize its fields with
* default values.
* *
* @param pkt packet * @param pkt packet
* @param size wanted payload size * @param size desired payload size
* @return >0 (read size) if OK. AVERROR_xxx otherwise. * @return >0 (read size) if OK, AVERROR_xxx otherwise
*/ */
int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size); int av_get_packet(ByteIOContext *s, AVPacket *pkt, int size);
/** /**
* @warning This is a hack - the packet memory allocation stuff is broken. The * @warning This is a hack - the packet memory allocation stuff is broken. The
* packet is allocated if it was not really allocated * packet is allocated if it was not really allocated.
*/ */
int av_dup_packet(AVPacket *pkt); int av_dup_packet(AVPacket *pkt);
/** /**
* Free a packet * Free a packet.
* *
* @param pkt packet to free * @param pkt packet to free
*/ */
@ -152,9 +154,9 @@ static inline void av_free_packet(AVPacket *pkt)
/* fractional numbers for exact pts handling */ /* fractional numbers for exact pts handling */
/** /**
* the exact value of the fractional number is: 'val + num / den'. * The exact value of the fractional number is: 'val + num / den'.
* num is assumed to be such as 0 <= num < den * num is assumed to be 0 <= num < den.
* @deprecated Use AVRational instead * @deprecated Use AVRational instead.
*/ */
typedef struct AVFrac { typedef struct AVFrac {
int64_t val, num, den; int64_t val, num, den;
@ -167,14 +169,14 @@ struct AVCodecTag;
struct AVFormatContext; struct AVFormatContext;
/** this structure contains the data a format has to probe a file */ /** This structure contains the data a format has to probe a file. */
typedef struct AVProbeData { typedef struct AVProbeData {
const char *filename; const char *filename;
unsigned char *buf; unsigned char *buf;
int buf_size; int buf_size;
} AVProbeData; } AVProbeData;
#define AVPROBE_SCORE_MAX 100 ///< max score, half of that is used for file extension based detection #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 #define AVPROBE_PADDING_SIZE 32 ///< extra allocated bytes at the end of the probe buffer
typedef struct AVFormatParameters { typedef struct AVFormatParameters {
@ -184,14 +186,14 @@ typedef struct AVFormatParameters {
int width; int width;
int height; int height;
enum PixelFormat pix_fmt; enum PixelFormat pix_fmt;
int channel; /**< used to select dv channel */ int channel; /**< Used to select DV channel. */
const char *standard; /**< tv standard, NTSC, PAL, SECAM */ const char *standard; /**< TV standard, NTSC, PAL, SECAM */
unsigned int mpeg2ts_raw:1; /**< force raw MPEG2 transport stream output, if possible */ unsigned int mpeg2ts_raw:1; /**< Force raw MPEG-2 transport stream output, if possible. */
unsigned int mpeg2ts_compute_pcr:1; /**< compute exact PCR for each transport unsigned int mpeg2ts_compute_pcr:1; /**< Compute exact PCR for each transport
stream packet (only meaningful if stream packet (only meaningful if
mpeg2ts_raw is TRUE) */ mpeg2ts_raw is TRUE). */
unsigned int initial_pause:1; /**< do not begin to play the stream unsigned int initial_pause:1; /**< Do not begin to play the stream
immediately (RTSP only) */ immediately (RTSP only). */
unsigned int prealloced_context:1; unsigned int prealloced_context:1;
#if LIBAVFORMAT_VERSION_INT < (53<<16) #if LIBAVFORMAT_VERSION_INT < (53<<16)
enum CodecID video_codec_id; enum CodecID video_codec_id;
@ -199,16 +201,16 @@ typedef struct AVFormatParameters {
#endif #endif
} AVFormatParameters; } AVFormatParameters;
//! demuxer will use url_fopen, no opened file should be provided by the caller //! Demuxer will use url_fopen, no opened file should be provided by the caller.
#define AVFMT_NOFILE 0x0001 #define AVFMT_NOFILE 0x0001
#define AVFMT_NEEDNUMBER 0x0002 /**< needs '%d' in filename */ #define AVFMT_NEEDNUMBER 0x0002 /**< Needs '%d' in filename. */
#define AVFMT_SHOW_IDS 0x0008 /**< show format stream IDs numbers */ #define AVFMT_SHOW_IDS 0x0008 /**< Show format stream IDs numbers. */
#define AVFMT_RAWPICTURE 0x0020 /**< format wants AVPicture structure for #define AVFMT_RAWPICTURE 0x0020 /**< Format wants AVPicture structure for
raw picture data */ raw picture data. */
#define AVFMT_GLOBALHEADER 0x0040 /**< format wants global header */ #define AVFMT_GLOBALHEADER 0x0040 /**< Format wants global header. */
#define AVFMT_NOTIMESTAMPS 0x0080 /**< format does not need / have any timestamps */ #define AVFMT_NOTIMESTAMPS 0x0080 /**< Format does not need / have any timestamps. */
#define AVFMT_GENERIC_INDEX 0x0100 /**< use generic index building code */ #define AVFMT_GENERIC_INDEX 0x0100 /**< Use generic index building code. */
#define AVFMT_TS_DISCONT 0x0200 /**< format allows timestamo discontinuities */ #define AVFMT_TS_DISCONT 0x0200 /**< Format allows timestamp discontinuities. */
typedef struct AVOutputFormat { typedef struct AVOutputFormat {
const char *name; const char *name;
@ -219,8 +221,8 @@ typedef struct AVOutputFormat {
*/ */
const char *long_name; const char *long_name;
const char *mime_type; const char *mime_type;
const char *extensions; /**< comma separated filename extensions */ const char *extensions; /**< comma-separated filename extensions */
/** size of private data so that it can be allocated in the wrapper */ /** Size of private data so that it can be allocated in the wrapper. */
int priv_data_size; int priv_data_size;
/* output support */ /* output support */
enum CodecID audio_codec; /**< default audio codec */ enum CodecID audio_codec; /**< default audio codec */
@ -230,7 +232,7 @@ typedef struct AVOutputFormat {
int (*write_trailer)(struct AVFormatContext *); int (*write_trailer)(struct AVFormatContext *);
/** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */ /** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER, AVFMT_GLOBALHEADER */
int flags; int flags;
/** currently only used to set pixel format if not YUV420P */ /** Currently only used to set pixel format if not YUV420P. */
int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *); int (*set_parameters)(struct AVFormatContext *, AVFormatParameters *);
int (*interleave_packet)(struct AVFormatContext *, AVPacket *out, AVPacket *in, int flush); int (*interleave_packet)(struct AVFormatContext *, AVPacket *out, AVPacket *in, int flush);
@ -254,7 +256,7 @@ typedef struct AVInputFormat {
* to define it. * to define it.
*/ */
const char *long_name; const char *long_name;
/** size of private data so that it can be allocated in the wrapper */ /** Size of private data so that it can be allocated in the wrapper. */
int priv_data_size; int priv_data_size;
/** /**
* Tell if a given file has a chance of being parsed by this format. * Tell if a given file has a chance of being parsed by this format.
@ -262,22 +264,22 @@ typedef struct AVInputFormat {
* big so you do not have to check for that unless you need more. * big so you do not have to check for that unless you need more.
*/ */
int (*read_probe)(AVProbeData *); int (*read_probe)(AVProbeData *);
/** read the format header and initialize the AVFormatContext /** Read the format header and initialize the AVFormatContext
structure. Return 0 if OK. 'ap' if non NULL contains structure. Return 0 if OK. 'ap' if non-NULL contains
additional paramters. Only used in raw format right additional parameters. Only used in raw format right
now. 'av_new_stream' should be called to create new streams. */ now. 'av_new_stream' should be called to create new streams. */
int (*read_header)(struct AVFormatContext *, int (*read_header)(struct AVFormatContext *,
AVFormatParameters *ap); AVFormatParameters *ap);
/** read one packet and put it in 'pkt'. pts and flags are also /** Read one packet and put it in 'pkt'. pts and flags are also
set. 'av_new_stream' can be called only if the flag set. 'av_new_stream' can be called only if the flag
AVFMTCTX_NOHEADER is used. */ AVFMTCTX_NOHEADER is used. */
int (*read_packet)(struct AVFormatContext *, AVPacket *pkt); int (*read_packet)(struct AVFormatContext *, AVPacket *pkt);
/** close the stream. The AVFormatContext and AVStreams are not /** Close the stream. The AVFormatContext and AVStreams are not
freed by this function */ freed by this function */
int (*read_close)(struct AVFormatContext *); int (*read_close)(struct AVFormatContext *);
/** /**
* seek to a given timestamp relative to the frames in * Seek to a given timestamp relative to the frames in
* stream component stream_index * stream component stream_index.
* @param stream_index must not be -1 * @param stream_index must not be -1
* @param flags selects which direction should be preferred if no exact * @param flags selects which direction should be preferred if no exact
* match is available * match is available
@ -286,26 +288,26 @@ typedef struct AVInputFormat {
int (*read_seek)(struct AVFormatContext *, int (*read_seek)(struct AVFormatContext *,
int stream_index, int64_t timestamp, int flags); int stream_index, int64_t timestamp, int flags);
/** /**
* gets the next timestamp in stream[stream_index].time_base units. * Gets the next timestamp in stream[stream_index].time_base units.
* @return the timestamp or AV_NOPTS_VALUE if an error occurred * @return the timestamp or AV_NOPTS_VALUE if an error occurred
*/ */
int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index, int64_t (*read_timestamp)(struct AVFormatContext *s, int stream_index,
int64_t *pos, int64_t pos_limit); int64_t *pos, int64_t pos_limit);
/** can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER */ /** Can use flags: AVFMT_NOFILE, AVFMT_NEEDNUMBER. */
int flags; int flags;
/** if extensions are defined, then no probe is done. You should /** If extensions are defined, then no probe is done. You should
usually not use extension format guessing because it is not usually not use extension format guessing because it is not
reliable enough */ reliable enough */
const char *extensions; const char *extensions;
/** general purpose read only value that the format can use */ /** General purpose read-only value that the format can use. */
int value; int value;
/** start/resume playing - only meaningful if using a network based format /** Start/resume playing - only meaningful if using a network-based format
(RTSP) */ (RTSP). */
int (*read_play)(struct AVFormatContext *); int (*read_play)(struct AVFormatContext *);
/** pause playing - only meaningful if using a network based format /** Pause playing - only meaningful if using a network-based format
(RTSP) */ (RTSP). */
int (*read_pause)(struct AVFormatContext *); int (*read_pause)(struct AVFormatContext *);
const struct AVCodecTag * const *codec_tag; const struct AVCodecTag * const *codec_tag;
@ -317,7 +319,7 @@ typedef struct AVInputFormat {
enum AVStreamParseType { enum AVStreamParseType {
AVSTREAM_PARSE_NONE, AVSTREAM_PARSE_NONE,
AVSTREAM_PARSE_FULL, /**< full parsing and repack */ AVSTREAM_PARSE_FULL, /**< full parsing and repack */
AVSTREAM_PARSE_HEADERS, /**< only parse headers, don't repack */ AVSTREAM_PARSE_HEADERS, /**< Only parse headers, do not repack. */
AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on packet boundary */ AVSTREAM_PARSE_TIMESTAMPS, /**< full parsing and interpolation of timestamps for frames not starting on packet boundary */
}; };
@ -326,8 +328,8 @@ typedef struct AVIndexEntry {
int64_t timestamp; int64_t timestamp;
#define AVINDEX_KEYFRAME 0x0001 #define AVINDEX_KEYFRAME 0x0001
int flags:2; int flags:2;
int size:30; //Yeah, trying to keep the size of this small to reduce memory requirements (it is 24 vs 32 byte due to possible 8byte align). 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).
int min_distance; /**< min distance between this and the previous keyframe, used to avoid unneeded searching */ int min_distance; /**< Minimum distance between this and the previous keyframe, used to avoid unneeded searching. */
} AVIndexEntry; } AVIndexEntry;
#define AV_DISPOSITION_DEFAULT 0x0001 #define AV_DISPOSITION_DEFAULT 0x0001
@ -346,37 +348,36 @@ typedef struct AVIndexEntry {
*/ */
typedef struct AVStream { typedef struct AVStream {
int index; /**< stream index in AVFormatContext */ int index; /**< stream index in AVFormatContext */
int id; /**< format specific stream id */ int id; /**< format-specific stream ID */
AVCodecContext *codec; /**< codec context */ AVCodecContext *codec; /**< codec context */
/** /**
* Real base frame rate of the stream. * Real base frame rate of the stream.
* This is the lowest frame rate with which all timestamps can be * This is the lowest frame rate with which all timestamps can be
* represented accurately (it is the least common multiple of all * represented accurately (it is the least common multiple of all
* frame rates in the stream), Note, this value is just a guess! * frame rates in the stream). Note, this value is just a guess!
* For example if the timebase is 1/90000 and all frames have either * For example if the time base is 1/90000 and all frames have either
* approximately 3600 or 1800 timer ticks then r_frame_rate will be 50/1. * approximately 3600 or 1800 timer ticks, then r_frame_rate will be 50/1.
*/ */
AVRational r_frame_rate; AVRational r_frame_rate;
void *priv_data; void *priv_data;
/* internal data used in av_find_stream_info() */ /* internal data used in av_find_stream_info() */
int64_t first_dts; int64_t first_dts;
/** encoding: PTS generation when outputing stream */ /** encoding: pts generation when outputting stream */
struct AVFrac pts; struct AVFrac pts;
/** /**
* This is the fundamental unit of time (in seconds) in terms * This is the fundamental unit of time (in seconds) in terms
* of which frame timestamps are represented. For fixed-fps content, * of which frame timestamps are represented. For fixed-fps content,
* timebase should be 1/frame rate and timestamp increments should be * time base should be 1/frame rate and timestamp increments should be 1.
* identically 1.
*/ */
AVRational time_base; AVRational time_base;
int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */ int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
/* ffmpeg.c private use */ /* ffmpeg.c private use */
int stream_copy; /**< if set, just copy stream */ int stream_copy; /**< If set, just copy stream. */
enum AVDiscard discard; ///< selects which packets can be discarded at will and do not need to be demuxed enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
//FIXME move stuff to a flags field? //FIXME move stuff to a flags field?
/** quality, as it has been removed from AVCodecContext and put in AVVideoFrame /** Quality, as it has been removed from AVCodecContext and put in AVVideoFrame.
* MN: dunno if that is the right place for it */ * MN: dunno if that is the right place for it */
float quality; float quality;
/** /**
@ -391,7 +392,7 @@ typedef struct AVStream {
/** /**
* Decoding: duration of the stream, in stream time base. * Decoding: duration of the stream, in stream time base.
* If a source file does not specify a duration, but does specify * If a source file does not specify a duration, but does specify
* a bitrate, this value will be estimates from bit rate and file size. * a bitrate, this value will be estimated from bitrate and file size.
*/ */
int64_t duration; int64_t duration;
@ -405,8 +406,8 @@ typedef struct AVStream {
int last_IP_duration; int last_IP_duration;
int64_t last_IP_pts; int64_t last_IP_pts;
/* av_seek_frame() support */ /* av_seek_frame() support */
AVIndexEntry *index_entries; /**< only used if the format does not AVIndexEntry *index_entries; /**< Only used if the format does not
support seeking natively */ support seeking natively. */
int nb_index_entries; int nb_index_entries;
unsigned int index_entries_allocated_size; unsigned int index_entries_allocated_size;
@ -418,7 +419,7 @@ typedef struct AVStream {
char *filename; /**< source filename of the stream */ char *filename; /**< source filename of the stream */
int disposition; /**< AV_DISPOSITION_* bitfield */ int disposition; /**< AV_DISPOSITION_* bit field */
AVProbeData probe_data; AVProbeData probe_data;
#define MAX_REORDER_DELAY 16 #define MAX_REORDER_DELAY 16
@ -442,8 +443,8 @@ typedef struct AVStream {
*/ */
typedef struct AVProgram { typedef struct AVProgram {
int id; int id;
char *provider_name; ///< Network name for DVB streams char *provider_name; ///< network name for DVB streams
char *name; ///< Service name for DVB streams char *name; ///< service name for DVB streams
int flags; int flags;
enum AVDiscard discard; ///< selects which program to discard and which to feed to the caller enum AVDiscard discard; ///< selects which program to discard and which to feed to the caller
unsigned int *stream_index; unsigned int *stream_index;
@ -454,8 +455,8 @@ typedef struct AVProgram {
(streams are added dynamically) */ (streams are added dynamically) */
typedef struct AVChapter { typedef struct AVChapter {
int id; ///< Unique id to identify the chapter int id; ///< unique ID to identify the chapter
AVRational time_base; ///< Timebase in which the start/end timestamps are specified AVRational time_base; ///< time base in which the start/end timestamps are specified
int64_t start, end; ///< chapter start/end time in time_base units int64_t start, end; ///< chapter start/end time in time_base units
char *title; ///< chapter title char *title; ///< chapter title
} AVChapter; } AVChapter;
@ -463,15 +464,15 @@ typedef struct AVChapter {
#define MAX_STREAMS 20 #define MAX_STREAMS 20
/** /**
* format I/O context. * Format I/O context.
* New fields can be added to the end with minor version bumps. * New fields can be added to the end with minor version bumps.
* Removal, reordering and changes to existing fields require a major * Removal, reordering and changes to existing fields require a major
* version bump. * version bump.
* sizeof(AVFormatContext) must not be used outside libav*. * sizeof(AVFormatContext) must not be used outside libav*.
*/ */
typedef struct AVFormatContext { typedef struct AVFormatContext {
const AVClass *av_class; /**< set by av_alloc_format_context */ const AVClass *av_class; /**< Set by av_alloc_format_context. */
/* can only be iformat or oformat, not both at the same time */ /* Can only be iformat or oformat, not both at the same time. */
struct AVInputFormat *iformat; struct AVInputFormat *iformat;
struct AVOutputFormat *oformat; struct AVOutputFormat *oformat;
void *priv_data; void *priv_data;
@ -490,24 +491,24 @@ typedef struct AVFormatContext {
int track; /**< track number, 0 if none */ int track; /**< track number, 0 if none */
char genre[32]; /**< ID3 genre */ char genre[32]; /**< ID3 genre */
int ctx_flags; /**< format specific flags, see AVFMTCTX_xx */ int ctx_flags; /**< Format-specific flags, see AVFMTCTX_xx */
/* private data for pts handling (do not modify directly) */ /* private data for pts handling (do not modify directly). */
/** This buffer is only needed when packets were already buffered but /** This buffer is only needed when packets were already buffered but
not decoded, for example to get the codec parameters in mpeg not decoded, for example to get the codec parameters in MPEG
streams */ streams. */
struct AVPacketList *packet_buffer; struct AVPacketList *packet_buffer;
/** decoding: position of the first frame of the component, in /** Decoding: position of the first frame of the component, in
AV_TIME_BASE fractional seconds. NEVER set this value directly: AV_TIME_BASE fractional seconds. NEVER set this value directly:
it is deduced from the AVStream values. */ It is deduced from the AVStream values. */
int64_t start_time; int64_t start_time;
/** decoding: duration of the stream, in AV_TIME_BASE fractional /** Decoding: duration of the stream, in AV_TIME_BASE fractional
seconds. NEVER set this value directly: it is deduced from the seconds. NEVER set this value directly: it is deduced from the
AVStream values. */ AVStream values. */
int64_t duration; int64_t duration;
/** decoding: total file size. 0 if unknown */ /** decoding: total file size, 0 if unknown */
int64_t file_size; int64_t file_size;
/** decoding: total stream bitrate in bit/s, 0 if not /** Decoding: total stream bitrate in bit/s, 0 if not
available. Never set it directly if the file_size and the available. Never set it directly if the file_size and the
duration are known as ffmpeg can compute it automatically. */ duration are known as ffmpeg can compute it automatically. */
int bit_rate; int bit_rate;
@ -533,16 +534,17 @@ typedef struct AVFormatContext {
int loop_output; int loop_output;
int flags; int flags;
#define AVFMT_FLAG_GENPTS 0x0001 ///< generate pts if missing even if it requires parsing future frames #define AVFMT_FLAG_GENPTS 0x0001 ///< Generate pts if missing even if it requires parsing future frames.
#define AVFMT_FLAG_IGNIDX 0x0002 ///< ignore index #define AVFMT_FLAG_IGNIDX 0x0002 ///< Ignore index.
#define AVFMT_FLAG_NONBLOCK 0x0004 ///< do not block when reading packets from input #define AVFMT_FLAG_NONBLOCK 0x0004 ///< Do not block when reading packets from input.
int loop_input; int loop_input;
/** decoding: size of data to probe; encoding unused */ /** Decoding: size of data to probe; encoding: unused. */
unsigned int probesize; unsigned int probesize;
/** /**
* maximum duration in AV_TIME_BASE units over which the input should be analyzed in av_find_stream_info() * Maximum time (in AV_TIME_BASE units) during which the input should
* be analyzed in av_find_stream_info().
*/ */
int max_analyze_duration; int max_analyze_duration;
@ -554,26 +556,26 @@ typedef struct AVFormatContext {
/** /**
* Forced video codec_id. * Forced video codec_id.
* demuxing: set by user * Demuxing: Set by user.
*/ */
enum CodecID video_codec_id; enum CodecID video_codec_id;
/** /**
* Forced audio codec_id. * Forced audio codec_id.
* demuxing: set by user * Demuxing: Set by user.
*/ */
enum CodecID audio_codec_id; enum CodecID audio_codec_id;
/** /**
* Forced subtitle codec_id. * Forced subtitle codec_id.
* demuxing: set by user * Demuxing: Set by user.
*/ */
enum CodecID subtitle_codec_id; enum CodecID subtitle_codec_id;
/** /**
* Maximum amount of memory in bytes to use per stream for the index. * Maximum amount of memory in bytes to use per stream for the index.
* If the needed index exceeds this size entries will be discarded as * If the needed index exceeds this size, entries will be discarded as
* needed to maintain a smaller size. This can lead to slower or less * needed to maintain a smaller size. This can lead to slower or less
* accurate seeking (depends on demuxer). * accurate seeking (depends on demuxer).
* Demuxers for which a full in memory index is mandatory will ignore * Demuxers for which a full in-memory index is mandatory will ignore
* this. * this.
* muxing : unused * muxing : unused
* demuxing: set by user * demuxing: set by user
@ -582,7 +584,7 @@ typedef struct AVFormatContext {
/** /**
* Maximum amount of memory in bytes to use for buffering frames * Maximum amount of memory in bytes to use for buffering frames
* obtained from real-time capture devices. * obtained from realtime capture devices.
*/ */
unsigned int max_picture_buffer; unsigned int max_picture_buffer;
@ -590,13 +592,13 @@ typedef struct AVFormatContext {
AVChapter **chapters; AVChapter **chapters;
/** /**
* Flags to enable debuging. * Flags to enable debugging.
*/ */
int debug; int debug;
#define FF_FDEBUG_TS 0x0001 #define FF_FDEBUG_TS 0x0001
/** /**
* raw packets from the demuxer, prior to parsing and decoding. * Raw packets from the demuxer, prior to parsing and decoding.
* This buffer is used for buffering packets until the codec can * This buffer is used for buffering packets until the codec can
* be identified, as parsing cannot be done without knowing the * be identified, as parsing cannot be done without knowing the
* codec. * codec.
@ -634,7 +636,7 @@ AVOutputFormat *guess_format(const char *short_name,
const char *filename, const char *mime_type); const char *filename, const char *mime_type);
/** /**
* Guesses the codec id based upon muxer and filename. * Guesses the codec ID based upon muxer and filename.
*/ */
enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name, enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
const char *filename, const char *mime_type, enum CodecType type); const char *filename, const char *mime_type, enum CodecType type);
@ -669,7 +671,7 @@ void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
* *
* @param f The file stream pointer where the dump should be sent to. * @param f The file stream pointer where the dump should be sent to.
* @param pkt packet to dump * @param pkt packet to dump
* @param dump_payload true if the payload must be displayed too * @param dump_payload True if the payload must be displayed, too.
*/ */
void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload); void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
@ -681,7 +683,7 @@ void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
* @param level The importance level of the message, lower values signifying * @param level The importance level of the message, lower values signifying
* higher importance. * higher importance.
* @param pkt packet to dump * @param pkt packet to dump
* @param dump_payload true if the payload must be displayed too * @param dump_payload True if the payload must be displayed, too.
*/ */
void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload); void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
@ -694,15 +696,15 @@ unsigned int av_codec_get_tag(const struct AVCodecTag **tags, enum CodecID id);
/* media file input */ /* media file input */
/** /**
* finds AVInputFormat based on input format's short name. * Finds AVInputFormat based on the short name of the input format.
*/ */
AVInputFormat *av_find_input_format(const char *short_name); AVInputFormat *av_find_input_format(const char *short_name);
/** /**
* Guess file format. * Guess file format.
* *
* @param is_opened whether the file is already opened, determines whether * @param is_opened Whether the file is already opened; determines whether
* demuxers with or without AVFMT_NOFILE are probed * demuxers with or without AVFMT_NOFILE are probed.
*/ */
AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened); AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
@ -718,12 +720,12 @@ int av_open_input_stream(AVFormatContext **ic_ptr,
* Open a media file as input. The codecs are not opened. Only the file * Open a media file as input. The codecs are not opened. Only the file
* header (if present) is read. * header (if present) is read.
* *
* @param ic_ptr the opened media file handle is put here * @param ic_ptr The opened media file handle is put here.
* @param filename filename to open. * @param filename filename to open
* @param fmt if non NULL, force the file format to use * @param fmt If non-NULL, force the file format to use.
* @param buf_size optional buffer size (zero if default is OK) * @param buf_size optional buffer size (zero if default is OK)
* @param ap additional parameters needed when opening the file (NULL if default) * @param ap Additional parameters needed when opening the file (NULL if default).
* @return 0 if OK. AVERROR_xxx otherwise. * @return 0 if OK, AVERROR_xxx otherwise
*/ */
int av_open_input_file(AVFormatContext **ic_ptr, const char *filename, int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
AVInputFormat *fmt, AVInputFormat *fmt,
@ -739,14 +741,15 @@ AVFormatContext *av_alloc_format_context(void);
/** /**
* Read packets of a media file to get stream information. This * Read packets of a media file to get stream information. This
* is useful for file formats with no headers such as MPEG. This * is useful for file formats with no headers such as MPEG. This
* function also computes the real frame rate in case of mpeg2 repeat * function also computes the real frame rate in case of MPEG-2 repeat
* frame mode. * frame mode.
* The logical file position is not changed by this function; * The logical file position is not changed by this function;
* examined packets may be buffered for later processing. * examined packets may be buffered for later processing.
* *
* @param ic media file handle * @param ic media file handle
* @return >=0 if OK. AVERROR_xxx if error. * @return >=0 if OK, AVERROR_xxx on error
* @todo Let user decide somehow what information is needed so we do not waste time getting stuff the user does not need. * @todo Let the user decide somehow what information is needed so that
* we do not waste time getting stuff the user does not need.
*/ */
int av_find_stream_info(AVFormatContext *ic); int av_find_stream_info(AVFormatContext *ic);
@ -758,7 +761,7 @@ int av_find_stream_info(AVFormatContext *ic);
* *
* @param s media file handle * @param s media file handle
* @param pkt is filled * @param pkt is filled
* @return 0 if OK. AVERROR_xxx if error. * @return 0 if OK, AVERROR_xxx on error
*/ */
int av_read_packet(AVFormatContext *s, AVPacket *pkt); int av_read_packet(AVFormatContext *s, AVPacket *pkt);
@ -775,11 +778,11 @@ int av_read_packet(AVFormatContext *s, AVPacket *pkt);
* *
* pkt->pts, pkt->dts and pkt->duration are always set to correct * pkt->pts, pkt->dts and pkt->duration are always set to correct
* values in AVStream.timebase units (and guessed if the format cannot * values in AVStream.timebase units (and guessed if the format cannot
* provided them). pkt->pts can be AV_NOPTS_VALUE if the video format * provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
* has B frames, so it is better to rely on pkt->dts if you do not * has B-frames, so it is better to rely on pkt->dts if you do not
* decompress the payload. * decompress the payload.
* *
* @return 0 if OK, < 0 if error or end of file. * @return 0 if OK, < 0 on error or end of file
*/ */
int av_read_frame(AVFormatContext *s, AVPacket *pkt); int av_read_frame(AVFormatContext *s, AVPacket *pkt);
@ -789,16 +792,16 @@ int av_read_frame(AVFormatContext *s, AVPacket *pkt);
* @param stream_index If stream_index is (-1), a default * @param stream_index If stream_index is (-1), a default
* stream is selected, and timestamp is automatically converted * stream is selected, and timestamp is automatically converted
* from AV_TIME_BASE units to the stream specific time_base. * from AV_TIME_BASE units to the stream specific time_base.
* @param timestamp timestamp in AVStream.time_base units * @param timestamp Timestamp in AVStream.time_base units
* or if there is no stream specified then in AV_TIME_BASE units * or, if no stream is specified, in AV_TIME_BASE units.
* @param flags flags which select direction and seeking mode * @param flags flags which select direction and seeking mode
* @return >= 0 on success * @return >= 0 on success
*/ */
int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags); int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp, int flags);
/** /**
* start playing a network based stream (e.g. RTSP stream) at the * Start playing a network based stream (e.g. RTSP stream) at the
* current position * current position.
*/ */
int av_read_play(AVFormatContext *s); int av_read_play(AVFormatContext *s);
@ -830,7 +833,7 @@ void av_close_input_file(AVFormatContext *s);
* can be added in read_packet too. * can be added in read_packet too.
* *
* @param s media file handle * @param s media file handle
* @param id file format dependent stream id * @param id file-format-dependent stream ID
*/ */
AVStream *av_new_stream(AVFormatContext *s, int id); AVStream *av_new_stream(AVFormatContext *s, int id);
AVProgram *av_new_program(AVFormatContext *s, int id); AVProgram *av_new_program(AVFormatContext *s, int id);
@ -838,15 +841,15 @@ AVProgram *av_new_program(AVFormatContext *s, int id);
/** /**
* Add a new chapter. * Add a new chapter.
* This function is NOT part of the public API * This function is NOT part of the public API
* and should be ONLY used by demuxers. * and should ONLY be used by demuxers.
* *
* @param s media file handle * @param s media file handle
* @param id unique id for this chapter * @param id unique ID for this chapter
* @param start chapter start time in time_base units * @param start chapter start time in time_base units
* @param end chapter end time in time_base units * @param end chapter end time in time_base units
* @param title chapter title * @param title chapter title
* *
* @return AVChapter or NULL if error. * @return AVChapter or NULL on error
*/ */
AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base, int64_t start, int64_t end, const char *title); AVChapter *ff_new_chapter(AVFormatContext *s, int id, AVRational time_base, int64_t start, int64_t end, const char *title);
@ -864,15 +867,15 @@ void av_set_pts_info(AVStream *s, int pts_wrap_bits,
#define AVSEEK_FLAG_BACKWARD 1 ///< seek backward #define AVSEEK_FLAG_BACKWARD 1 ///< seek backward
#define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes #define AVSEEK_FLAG_BYTE 2 ///< seeking based on position in bytes
#define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non keyframes #define AVSEEK_FLAG_ANY 4 ///< seek to any frame, even non-keyframes
int av_find_default_stream_index(AVFormatContext *s); int av_find_default_stream_index(AVFormatContext *s);
/** /**
* Gets the index for a specific timestamp. * Gets the index for a specific timestamp.
* @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond to * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
* the timestamp which is <= the requested one, if backward is 0 * to the timestamp which is <= the requested one, if backward
* then it will be >= * is 0, then it will be >=
* if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise * if AVSEEK_FLAG_ANY seek to any frame, only keyframes otherwise
* @return < 0 if no such timestamp could be found * @return < 0 if no such timestamp could be found
*/ */
@ -888,9 +891,10 @@ int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
void ff_reduce_index(AVFormatContext *s, int stream_index); void ff_reduce_index(AVFormatContext *s, int stream_index);
/** /**
* Add a index entry into a sorted list updateing if it is already there. * Add an index entry into a sorted list. Update the entry if the list
* already contains it.
* *
* @param timestamp timestamp in the timebase of the given stream * @param timestamp timestamp in the time base of the given stream
*/ */
int av_add_index_entry(AVStream *st, int av_add_index_entry(AVStream *st,
int64_t pos, int64_t timestamp, int size, int distance, int flags); int64_t pos, int64_t timestamp, int size, int distance, int flags);
@ -904,10 +908,10 @@ int av_add_index_entry(AVStream *st,
int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags); int av_seek_frame_binary(AVFormatContext *s, int stream_index, int64_t target_ts, int flags);
/** /**
* Updates cur_dts of all streams based on given timestamp and AVStream. * Updates cur_dts of all streams based on the given timestamp and AVStream.
* *
* Stream ref_st unchanged, others set cur_dts in their native timebase * Stream ref_st unchanged, others set cur_dts in their native time base.
* only needed for timestamp wrapping or if (dts not set and pts!=dts). * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
* @param timestamp new dts expressed in time_base of param ref_st * @param timestamp new dts expressed in time_base of param ref_st
* @param ref_st reference stream giving time_base of param timestamp * @param ref_st reference stream giving time_base of param timestamp
*/ */
@ -929,7 +933,7 @@ int av_set_parameters(AVFormatContext *s, AVFormatParameters *ap);
* output media file. * output media file.
* *
* @param s media file handle * @param s media file handle
* @return 0 if OK. AVERROR_xxx if error. * @return 0 if OK, AVERROR_xxx on error
*/ */
int av_write_header(AVFormatContext *s); int av_write_header(AVFormatContext *s);
@ -938,11 +942,11 @@ int av_write_header(AVFormatContext *s);
* *
* The packet shall contain one audio or video frame. * The packet shall contain one audio or video frame.
* The packet must be correctly interleaved according to the container specification, * The packet must be correctly interleaved according to the container specification,
* if not then av_interleaved_write_frame must be used * if not then av_interleaved_write_frame must be used.
* *
* @param s media file handle * @param s media file handle
* @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ... * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ...
* @return < 0 if error, = 0 if OK, 1 if end of stream wanted. * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
*/ */
int av_write_frame(AVFormatContext *s, AVPacket *pkt); int av_write_frame(AVFormatContext *s, AVPacket *pkt);
@ -958,12 +962,12 @@ int av_write_frame(AVFormatContext *s, AVPacket *pkt);
* *
* @param s media file handle * @param s media file handle
* @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ... * @param pkt the packet, which contains the stream_index, buf/buf_size, dts/pts, ...
* @return < 0 if error, = 0 if OK, 1 if end of stream wanted. * @return < 0 on error, = 0 if OK, 1 if end of stream wanted
*/ */
int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt); int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
/** /**
* Interleave a packet per DTS in an output media file. * Interleave a packet per dts in an output media file.
* *
* Packets with pkt->destruct == av_destruct_packet will be freed inside this function, * Packets with pkt->destruct == av_destruct_packet will be freed inside this function,
* so they cannot be used after it, note calling av_free_packet() on them is still safe. * so they cannot be used after it, note calling av_free_packet() on them is still safe.
@ -985,7 +989,7 @@ int av_interleave_packet_per_dts(AVFormatContext *s, AVPacket *out, AVPacket *pk
* May only be called after a successful call to av_write_header. * May only be called after a successful call to av_write_header.
* *
* @param s media file handle * @param s media file handle
* @return 0 if OK. AVERROR_xxx if error. * @return 0 if OK, AVERROR_xxx on error
*/ */
int av_write_trailer(AVFormatContext *s); int av_write_trailer(AVFormatContext *s);
@ -995,7 +999,7 @@ void dump_format(AVFormatContext *ic,
int is_output); int is_output);
/** /**
* parses width and height out of string str. * Parses width and height out of string str.
* @deprecated Use av_parse_video_frame_size instead. * @deprecated Use av_parse_video_frame_size instead.
*/ */
attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr, const char *str); attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr, const char *str);
@ -1013,9 +1017,9 @@ attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
* @code * @code
* [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]} * [{YYYY-MM-DD|YYYYMMDD}]{T| }{HH[:MM[:SS[.m...]]][Z]|HH[MM[SS[.m...]]][Z]}
* @endcode * @endcode
* Time is localtime unless Z is appended, in which case it is * Time is local time unless Z is appended, in which case it is
* interpreted as UTC. * interpreted as UTC.
* If the year-month-day part isn't specified it takes the current * If the year-month-day part is not specified it takes the current
* year-month-day. * year-month-day.
* Returns the number of microseconds since 1st of January, 1970 up to * Returns the number of microseconds since 1st of January, 1970 up to
* the time of the parsed date or INT64_MIN if \p datestr cannot be * the time of the parsed date or INT64_MIN if \p datestr cannot be
@ -1037,7 +1041,7 @@ int64_t parse_date(const char *datestr, int duration);
/** Gets the current time in microseconds. */ /** Gets the current time in microseconds. */
int64_t av_gettime(void); int64_t av_gettime(void);
/* ffm specific for ffserver */ /* ffm-specific for ffserver */
#define FFM_PACKET_SIZE 4096 #define FFM_PACKET_SIZE 4096
offset_t ffm_read_write_index(int fd); offset_t ffm_read_write_index(int fd);
void ffm_write_write_index(int fd, offset_t pos); void ffm_write_write_index(int fd, offset_t pos);
@ -1053,7 +1057,7 @@ int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
/** /**
* Returns in 'buf' the path with '%d' replaced by number. * Returns in 'buf' the path with '%d' replaced by number.
*
* Also handles the '%0nd' format where 'n' is the total number * Also handles the '%0nd' format where 'n' is the total number
* of digits and '%%'. * of digits and '%%'.
* *
@ -1061,7 +1065,7 @@ int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
* @param buf_size destination buffer size * @param buf_size destination buffer size
* @param path numbered sequence string * @param path numbered sequence string
* @param number frame number * @param number frame number
* @return 0 if OK, -1 if format error. * @return 0 if OK, -1 on format error
*/ */
int av_get_frame_filename(char *buf, int buf_size, int av_get_frame_filename(char *buf, int buf_size,
const char *path, int number); const char *path, int number);
@ -1070,7 +1074,7 @@ int av_get_frame_filename(char *buf, int buf_size,
* Check whether filename actually is a numbered sequence generator. * Check whether filename actually is a numbered sequence generator.
* *
* @param filename possible numbered sequence string * @param filename possible numbered sequence string
* @return 1 if a valid numbered sequence string, 0 otherwise. * @return 1 if a valid numbered sequence string, 0 otherwise
*/ */
int av_filename_number_test(const char *filename); int av_filename_number_test(const char *filename);
@ -1081,12 +1085,12 @@ int av_filename_number_test(const char *filename);
* array is composed by only one context, such context can contain * array is composed by only one context, such context can contain
* multiple AVStreams (one AVStream per RTP stream). Otherwise, * multiple AVStreams (one AVStream per RTP stream). Otherwise,
* all the contexts in the array (an AVCodecContext per RTP stream) * all the contexts in the array (an AVCodecContext per RTP stream)
* must contain only one AVStream * must contain only one AVStream.
* @param n_files number of AVCodecContexts contained in ac * @param n_files number of AVCodecContexts contained in ac
* @param buff buffer where the SDP will be stored (must be allocated by * @param buff buffer where the SDP will be stored (must be allocated by
* the caller * the caller)
* @param size the size of the buffer * @param size the size of the buffer
* @return 0 if OK. AVERROR_xxx if error. * @return 0 if OK, AVERROR_xxx on error
*/ */
int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size); int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);