/* * AVPacket public API * * This file is part of FFmpeg. * * FFmpeg 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. * * FFmpeg 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 FFmpeg; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef AVCODEC_PACKET_H #define AVCODEC_PACKET_H #include <stddef.h> #include <stdint.h> #include "libavutil/attributes.h" #include "libavutil/buffer.h" #include "libavutil/dict.h" #include "libavutil/rational.h" #include "libavcodec/version.h" /** * @defgroup lavc_packet AVPacket * * Types and functions for working with AVPacket. * @{ */ enum AVPacketSideDataType { /** * An AV_PKT_DATA_PALETTE side data packet contains exactly AVPALETTE_SIZE * bytes worth of palette. This side data signals that a new palette is * present. */ AV_PKT_DATA_PALETTE, /** * The AV_PKT_DATA_NEW_EXTRADATA is used to notify the codec or the format * that the extradata buffer was changed and the receiving side should * act upon it appropriately. The new extradata is embedded in the side * data buffer and should be immediately used for processing the current * frame or packet. */ AV_PKT_DATA_NEW_EXTRADATA, /** * An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows: * @code * u32le param_flags * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT) * s32le channel_count * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT) * u64le channel_layout * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE) * s32le sample_rate * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS) * s32le width * s32le height * @endcode */ AV_PKT_DATA_PARAM_CHANGE, /** * An AV_PKT_DATA_H263_MB_INFO side data packet contains a number of * structures with info about macroblocks relevant to splitting the * packet into smaller packets on macroblock edges (e.g. as for RFC 2190). * That is, it does not necessarily contain info about all macroblocks, * as long as the distance between macroblocks in the info is smaller * than the target payload size. * Each MB info structure is 12 bytes, and is laid out as follows: * @code * u32le bit offset from the start of the packet * u8 current quantizer at the start of the macroblock * u8 GOB number * u16le macroblock address within the GOB * u8 horizontal MV predictor * u8 vertical MV predictor * u8 horizontal MV predictor for block number 3 * u8 vertical MV predictor for block number 3 * @endcode */ AV_PKT_DATA_H263_MB_INFO, /** * This side data should be associated with an audio stream and contains * ReplayGain information in form of the AVReplayGain struct. */ AV_PKT_DATA_REPLAYGAIN, /** * This side data contains a 3x3 transformation matrix describing an affine * transformation that needs to be applied to the decoded video frames for * correct presentation. * * See libavutil/display.h for a detailed description of the data. */ AV_PKT_DATA_DISPLAYMATRIX, /** * This side data should be associated with a video stream and contains * Stereoscopic 3D information in form of the AVStereo3D struct. */ AV_PKT_DATA_STEREO3D, /** * This side data should be associated with an audio stream and corresponds * to enum AVAudioServiceType. */ AV_PKT_DATA_AUDIO_SERVICE_TYPE, /** * This side data contains quality related information from the encoder. * @code * u32le quality factor of the compressed frame. Allowed range is between 1 (good) and FF_LAMBDA_MAX (bad). * u8 picture type * u8 error count * u16 reserved * u64le[error count] sum of squared differences between encoder in and output * @endcode */ AV_PKT_DATA_QUALITY_STATS, /** * This side data contains an integer value representing the stream index * of a "fallback" track. A fallback track indicates an alternate * track to use when the current track can not be decoded for some reason. * e.g. no decoder available for codec. */ AV_PKT_DATA_FALLBACK_TRACK, /** * This side data corresponds to the AVCPBProperties struct. */ AV_PKT_DATA_CPB_PROPERTIES, /** * Recommmends skipping the specified number of samples * @code * u32le number of samples to skip from start of this packet * u32le number of samples to skip from end of this packet * u8 reason for start skip * u8 reason for end skip (0=padding silence, 1=convergence) * @endcode */ AV_PKT_DATA_SKIP_SAMPLES, /** * An AV_PKT_DATA_JP_DUALMONO side data packet indicates that * the packet may contain "dual mono" audio specific to Japanese DTV * and if it is true, recommends only the selected channel to be used. * @code * u8 selected channels (0=mail/left, 1=sub/right, 2=both) * @endcode */ AV_PKT_DATA_JP_DUALMONO, /** * A list of zero terminated key/value strings. There is no end marker for * the list, so it is required to rely on the side data size to stop. */ AV_PKT_DATA_STRINGS_METADATA, /** * Subtitle event position * @code * u32le x1 * u32le y1 * u32le x2 * u32le y2 * @endcode */ AV_PKT_DATA_SUBTITLE_POSITION, /** * Data found in BlockAdditional element of matroska container. There is * no end marker for the data, so it is required to rely on the side data * size to recognize the end. 8 byte id (as found in BlockAddId) followed * by data. */ AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL, /** * The optional first identifier line of a WebVTT cue. */ AV_PKT_DATA_WEBVTT_IDENTIFIER, /** * The optional settings (rendering instructions) that immediately * follow the timestamp specifier of a WebVTT cue. */ AV_PKT_DATA_WEBVTT_SETTINGS, /** * A list of zero terminated key/value strings. There is no end marker for * the list, so it is required to rely on the side data size to stop. This * side data includes updated metadata which appeared in the stream. */ AV_PKT_DATA_METADATA_UPDATE, /** * MPEGTS stream ID as uint8_t, this is required to pass the stream ID * information from the demuxer to the corresponding muxer. */ AV_PKT_DATA_MPEGTS_STREAM_ID, /** * Mastering display metadata (based on SMPTE-2086:2014). This metadata * should be associated with a video stream and contains data in the form * of the AVMasteringDisplayMetadata struct. */ AV_PKT_DATA_MASTERING_DISPLAY_METADATA, /** * This side data should be associated with a video stream and corresponds * to the AVSphericalMapping structure. */ AV_PKT_DATA_SPHERICAL, /** * Content light level (based on CTA-861.3). This metadata should be * associated with a video stream and contains data in the form of the * AVContentLightMetadata struct. */ AV_PKT_DATA_CONTENT_LIGHT_LEVEL, /** * ATSC A53 Part 4 Closed Captions. This metadata should be associated with * a video stream. A53 CC bitstream is stored as uint8_t in AVPacketSideData.data. * The number of bytes of CC data is AVPacketSideData.size. */ AV_PKT_DATA_A53_CC, /** * This side data is encryption initialization data. * The format is not part of ABI, use av_encryption_init_info_* methods to * access. */ AV_PKT_DATA_ENCRYPTION_INIT_INFO, /** * This side data contains encryption info for how to decrypt the packet. * The format is not part of ABI, use av_encryption_info_* methods to access. */ AV_PKT_DATA_ENCRYPTION_INFO, /** * Active Format Description data consisting of a single byte as specified * in ETSI TS 101 154 using AVActiveFormatDescription enum. */ AV_PKT_DATA_AFD, /** * Producer Reference Time data corresponding to the AVProducerReferenceTime struct, * usually exported by some encoders (on demand through the prft flag set in the * AVCodecContext export_side_data field). */ AV_PKT_DATA_PRFT, /** * ICC profile data consisting of an opaque octet buffer following the * format described by ISO 15076-1. */ AV_PKT_DATA_ICC_PROFILE, /** * DOVI configuration * ref: * dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2, section 2.2 * dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2, section 3.3 * Tags are stored in struct AVDOVIDecoderConfigurationRecord. */ AV_PKT_DATA_DOVI_CONF, /** * The number of side data types. * This is not part of the public API/ABI in the sense that it may * change when new side data types are added. * This must stay the last enum value. * If its value becomes huge, some code using it * needs to be updated as it assumes it to be smaller than other limits. */ AV_PKT_DATA_NB }; #define AV_PKT_DATA_QUALITY_FACTOR AV_PKT_DATA_QUALITY_STATS //DEPRECATED typedef struct AVPacketSideData { uint8_t *data; int size; enum AVPacketSideDataType type; } AVPacketSideData; /** * This structure stores compressed data. It is typically exported by demuxers * and then passed as input to decoders, or received as output from encoders and * then passed to muxers. * * For video, it should typically contain one compressed frame. For audio it may * contain several compressed frames. Encoders are allowed to output empty * packets, with no compressed data, containing only side data * (e.g. to update some stream parameters at the end of encoding). * * AVPacket is one of the few structs in FFmpeg, whose size is a part of public * ABI. Thus it may be allocated on stack and no new fields can be added to it * without libavcodec and libavformat major bump. * * The semantics of data ownership depends on the buf field. * If it is set, the packet data is dynamically allocated and is * valid indefinitely until a call to av_packet_unref() reduces the * reference count to 0. * * If the buf field is not set av_packet_ref() would make a copy instead * of increasing the reference count. * * The side data is always allocated with av_malloc(), copied by * av_packet_ref() and freed by av_packet_unref(). * * @see av_packet_ref * @see av_packet_unref */ typedef struct AVPacket { /** * A reference to the reference-counted buffer where the packet data is * stored. * May be NULL, then the packet data is not reference-counted. */ AVBufferRef *buf; /** * Presentation timestamp in AVStream->time_base units; the time at which * the decompressed packet will be presented to the user. * Can be AV_NOPTS_VALUE if it is not stored in the file. * pts MUST be larger or equal to dts as presentation cannot happen before * decompression, unless one wants to view hex dumps. Some formats misuse * the terms dts and pts/cts to mean something different. Such timestamps * must be converted to true pts/dts before they are stored in AVPacket. */ int64_t pts; /** * Decompression timestamp in AVStream->time_base units; the time at which * the packet is decompressed. * Can be AV_NOPTS_VALUE if it is not stored in the file. */ int64_t dts; uint8_t *data; int size; int stream_index; /** * A combination of AV_PKT_FLAG values */ int flags; /** * Additional packet data that can be provided by the container. * Packet can contain several types of side information. */ AVPacketSideData *side_data; int side_data_elems; /** * Duration of this packet in AVStream->time_base units, 0 if unknown. * Equals next_pts - this_pts in presentation order. */ int64_t duration; int64_t pos; ///< byte position in stream, -1 if unknown #if FF_API_CONVERGENCE_DURATION /** * @deprecated Same as the duration field, but as int64_t. This was required * for Matroska subtitles, whose duration values could overflow when the * duration field was still an int. */ attribute_deprecated int64_t convergence_duration; #endif } AVPacket; #define AV_PKT_FLAG_KEY 0x0001 ///< The packet contains a keyframe #define AV_PKT_FLAG_CORRUPT 0x0002 ///< The packet content is corrupted /** * Flag is used to discard packets which are required to maintain valid * decoder state but are not required for output and should be dropped * after decoding. **/ #define AV_PKT_FLAG_DISCARD 0x0004 /** * The packet comes from a trusted source. * * Otherwise-unsafe constructs such as arbitrary pointers to data * outside the packet may be followed. */ #define AV_PKT_FLAG_TRUSTED 0x0008 /** * Flag is used to indicate packets that contain frames that can * be discarded by the decoder. I.e. Non-reference frames. */ #define AV_PKT_FLAG_DISPOSABLE 0x0010 enum AVSideDataParamChangeFlags { AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT = 0x0001, AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT = 0x0002, AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE = 0x0004, AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS = 0x0008, }; /** * Allocate an AVPacket and set its fields to default values. The resulting * struct must be freed using av_packet_free(). * * @return An AVPacket filled with default values or NULL on failure. * * @note this only allocates the AVPacket itself, not the data buffers. Those * must be allocated through other means such as av_new_packet. * * @see av_new_packet */ AVPacket *av_packet_alloc(void); /** * Create a new packet that references the same data as src. * * This is a shortcut for av_packet_alloc()+av_packet_ref(). * * @return newly created AVPacket on success, NULL on error. * * @see av_packet_alloc * @see av_packet_ref */ AVPacket *av_packet_clone(const AVPacket *src); /** * Free the packet, if the packet is reference counted, it will be * unreferenced first. * * @param pkt packet to be freed. The pointer will be set to NULL. * @note passing NULL is a no-op. */ void av_packet_free(AVPacket **pkt); /** * Initialize optional fields of a packet with default values. * * Note, this does not touch the data and size members, which have to be * initialized separately. * * @param pkt packet */ void av_init_packet(AVPacket *pkt); /** * Allocate the payload of a packet and initialize its fields with * default values. * * @param pkt packet * @param size wanted payload size * @return 0 if OK, AVERROR_xxx otherwise */ int av_new_packet(AVPacket *pkt, int size); /** * Reduce packet size, correctly zeroing padding * * @param pkt packet * @param size new size */ void av_shrink_packet(AVPacket *pkt, int size); /** * Increase packet size, correctly zeroing padding * * @param pkt packet * @param grow_by number of bytes by which to increase the size of the packet */ int av_grow_packet(AVPacket *pkt, int grow_by); /** * Initialize a reference-counted packet from av_malloc()ed data. * * @param pkt packet to be initialized. This function will set the data, size, * and buf fields, all others are left untouched. * @param data Data allocated by av_malloc() to be used as packet data. If this * function returns successfully, the data is owned by the underlying AVBuffer. * The caller may not access the data through other means. * @param size size of data in bytes, without the padding. I.e. the full buffer * size is assumed to be size + AV_INPUT_BUFFER_PADDING_SIZE. * * @return 0 on success, a negative AVERROR on error */ int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size); #if FF_API_AVPACKET_OLD_API /** * @warning This is a hack - the packet memory allocation stuff is broken. The * packet is allocated if it was not really allocated. * * @deprecated Use av_packet_ref or av_packet_make_refcounted */ attribute_deprecated int av_dup_packet(AVPacket *pkt); /** * Copy packet, including contents * * @return 0 on success, negative AVERROR on fail * * @deprecated Use av_packet_ref */ attribute_deprecated int av_copy_packet(AVPacket *dst, const AVPacket *src); /** * Copy packet side data * * @return 0 on success, negative AVERROR on fail * * @deprecated Use av_packet_copy_props */ attribute_deprecated int av_copy_packet_side_data(AVPacket *dst, const AVPacket *src); /** * Free a packet. * * @deprecated Use av_packet_unref * * @param pkt packet to free */ attribute_deprecated void av_free_packet(AVPacket *pkt); #endif /** * Allocate new information of a packet. * * @param pkt packet * @param type side information type * @param size side information size * @return pointer to fresh allocated data or NULL otherwise */ uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type, int size); /** * Wrap an existing array as a packet side data. * * @param pkt packet * @param type side information type * @param data the side data array. It must be allocated with the av_malloc() * family of functions. The ownership of the data is transferred to * pkt. * @param size side information size * @return a non-negative number on success, a negative AVERROR code on * failure. On failure, the packet is unchanged and the data remains * owned by the caller. */ int av_packet_add_side_data(AVPacket *pkt, enum AVPacketSideDataType type, uint8_t *data, size_t size); /** * Shrink the already allocated side data buffer * * @param pkt packet * @param type side information type * @param size new side information size * @return 0 on success, < 0 on failure */ int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type, int size); /** * Get side information from packet. * * @param pkt packet * @param type desired side information type * @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_packet_get_side_data(const AVPacket *pkt, enum AVPacketSideDataType type, int *size); #if FF_API_MERGE_SD_API attribute_deprecated int av_packet_merge_side_data(AVPacket *pkt); attribute_deprecated int av_packet_split_side_data(AVPacket *pkt); #endif const char *av_packet_side_data_name(enum AVPacketSideDataType type); /** * Pack a dictionary for use in side_data. * * @param dict The dictionary to pack. * @param size pointer to store the size of the returned data * @return pointer to data if successful, NULL otherwise */ uint8_t *av_packet_pack_dictionary(AVDictionary *dict, int *size); /** * Unpack a dictionary from side_data. * * @param data data from side_data * @param size size of the data * @param dict the metadata storage dictionary * @return 0 on success, < 0 on failure */ int av_packet_unpack_dictionary(const uint8_t *data, int size, AVDictionary **dict); /** * Convenience function to free all the side data stored. * All the other fields stay untouched. * * @param pkt packet */ void av_packet_free_side_data(AVPacket *pkt); /** * Setup a new reference to the data described by a given packet * * If src is reference-counted, setup dst as a new reference to the * buffer in src. Otherwise allocate a new buffer in dst and copy the * data from src into it. * * All the other fields are copied from src. * * @see av_packet_unref * * @param dst Destination packet. Will be completely overwritten. * @param src Source packet * * @return 0 on success, a negative AVERROR on error. On error, dst * will be blank (as if returned by av_packet_alloc()). */ int av_packet_ref(AVPacket *dst, const AVPacket *src); /** * Wipe the packet. * * Unreference the buffer referenced by the packet and reset the * remaining packet fields to their default values. * * @param pkt The packet to be unreferenced. */ void av_packet_unref(AVPacket *pkt); /** * Move every field in src to dst and reset src. * * @see av_packet_unref * * @param src Source packet, will be reset * @param dst Destination packet */ void av_packet_move_ref(AVPacket *dst, AVPacket *src); /** * Copy only "properties" fields from src to dst. * * Properties for the purpose of this function are all the fields * beside those related to the packet data (buf, data, size) * * @param dst Destination packet * @param src Source packet * * @return 0 on success AVERROR on failure. */ int av_packet_copy_props(AVPacket *dst, const AVPacket *src); /** * Ensure the data described by a given packet is reference counted. * * @note This function does not ensure that the reference will be writable. * Use av_packet_make_writable instead for that purpose. * * @see av_packet_ref * @see av_packet_make_writable * * @param pkt packet whose data should be made reference counted. * * @return 0 on success, a negative AVERROR on error. On failure, the * packet is unchanged. */ int av_packet_make_refcounted(AVPacket *pkt); /** * Create a writable reference for the data described by a given packet, * avoiding data copy if possible. * * @param pkt Packet whose data should be made writable. * * @return 0 on success, a negative AVERROR on failure. On failure, the * packet is unchanged. */ int av_packet_make_writable(AVPacket *pkt); /** * Convert valid timing fields (timestamps / durations) in a packet from one * timebase to another. Timestamps with unknown values (AV_NOPTS_VALUE) will be * ignored. * * @param pkt packet on which the conversion will be performed * @param tb_src source timebase, in which the timing fields in pkt are * expressed * @param tb_dst destination timebase, to which the timing fields will be * converted */ void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst); /** * @} */ #endif // AVCODEC_PACKET_H