FFmpeg
Data Structures | Enumerations | Functions
AVPacketSideData

Types and functions for working with AVPacketSideData. More...

Data Structures

struct  AVPacketSideData
 This structure stores auxiliary information for decoding, presenting, or otherwise processing the coded stream. More...
 

Enumerations

enum  AVPacketSideDataType {
  AV_PKT_DATA_PALETTE, AV_PKT_DATA_NEW_EXTRADATA, AV_PKT_DATA_PARAM_CHANGE, AV_PKT_DATA_H263_MB_INFO,
  AV_PKT_DATA_REPLAYGAIN, AV_PKT_DATA_DISPLAYMATRIX, AV_PKT_DATA_STEREO3D, AV_PKT_DATA_AUDIO_SERVICE_TYPE,
  AV_PKT_DATA_QUALITY_STATS, AV_PKT_DATA_FALLBACK_TRACK, AV_PKT_DATA_CPB_PROPERTIES, AV_PKT_DATA_SKIP_SAMPLES,
  AV_PKT_DATA_JP_DUALMONO, AV_PKT_DATA_STRINGS_METADATA, AV_PKT_DATA_SUBTITLE_POSITION, AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL,
  AV_PKT_DATA_WEBVTT_IDENTIFIER, AV_PKT_DATA_WEBVTT_SETTINGS, AV_PKT_DATA_METADATA_UPDATE, AV_PKT_DATA_MPEGTS_STREAM_ID,
  AV_PKT_DATA_MASTERING_DISPLAY_METADATA, AV_PKT_DATA_SPHERICAL, AV_PKT_DATA_CONTENT_LIGHT_LEVEL, AV_PKT_DATA_A53_CC,
  AV_PKT_DATA_ENCRYPTION_INIT_INFO, AV_PKT_DATA_ENCRYPTION_INFO, AV_PKT_DATA_AFD, AV_PKT_DATA_PRFT,
  AV_PKT_DATA_ICC_PROFILE, AV_PKT_DATA_DOVI_CONF, AV_PKT_DATA_S12M_TIMECODE, AV_PKT_DATA_DYNAMIC_HDR10_PLUS,
  AV_PKT_DATA_IAMF_MIX_GAIN_PARAM, AV_PKT_DATA_IAMF_DEMIXING_INFO_PARAM, AV_PKT_DATA_IAMF_RECON_GAIN_INFO_PARAM, AV_PKT_DATA_AMBIENT_VIEWING_ENVIRONMENT,
  AV_PKT_DATA_NB
}
 

Functions

AVPacketSideDataav_packet_side_data_new (AVPacketSideData **psd, int *pnb_sd, enum AVPacketSideDataType type, size_t size, int flags)
 Allocate a new packet side data. More...
 
AVPacketSideDataav_packet_side_data_add (AVPacketSideData **sd, int *nb_sd, enum AVPacketSideDataType type, void *data, size_t size, int flags)
 Wrap existing data as packet side data. More...
 
const AVPacketSideDataav_packet_side_data_get (const AVPacketSideData *sd, int nb_sd, enum AVPacketSideDataType type)
 Get side information from a side data array. More...
 
void av_packet_side_data_remove (AVPacketSideData *sd, int *nb_sd, enum AVPacketSideDataType type)
 Remove side data of the given type from a side data array. More...
 
void av_packet_side_data_free (AVPacketSideData **sd, int *nb_sd)
 Convenience function to free all the side data stored in an array, and the array itself. More...
 
const char * av_packet_side_data_name (enum AVPacketSideDataType type)
 

Detailed Description

Types and functions for working with AVPacketSideData.

Enumeration Type Documentation

◆ AVPacketSideDataType

Enumerator
AV_PKT_DATA_PALETTE 

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_NEW_EXTRADATA 

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_PARAM_CHANGE 

An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows:

u32le param_flags
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
AV_PKT_DATA_H263_MB_INFO 

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:

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
AV_PKT_DATA_REPLAYGAIN 

This side data should be associated with an audio stream and contains ReplayGain information in form of the AVReplayGain struct.

AV_PKT_DATA_DISPLAYMATRIX 

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_STEREO3D 

This side data should be associated with a video stream and contains Stereoscopic 3D information in form of the AVStereo3D struct.

AV_PKT_DATA_AUDIO_SERVICE_TYPE 

This side data should be associated with an audio stream and corresponds to enum AVAudioServiceType.

AV_PKT_DATA_QUALITY_STATS 

This side data contains quality related information from the encoder.

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
AV_PKT_DATA_FALLBACK_TRACK 

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_CPB_PROPERTIES 

This side data corresponds to the AVCPBProperties struct.

AV_PKT_DATA_SKIP_SAMPLES 

Recommmends skipping the specified number of samples.

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)
AV_PKT_DATA_JP_DUALMONO 

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.

u8 selected channels (0=main/left, 1=sub/right, 2=both)
AV_PKT_DATA_STRINGS_METADATA 

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_SUBTITLE_POSITION 

Subtitle event position.

u32le x1
u32le y1
u32le x2
u32le y2
AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL 

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_WEBVTT_IDENTIFIER 

The optional first identifier line of a WebVTT cue.

AV_PKT_DATA_WEBVTT_SETTINGS 

The optional settings (rendering instructions) that immediately follow the timestamp specifier of a WebVTT cue.

AV_PKT_DATA_METADATA_UPDATE 

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_MPEGTS_STREAM_ID 

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_MASTERING_DISPLAY_METADATA 

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_SPHERICAL 

This side data should be associated with a video stream and corresponds to the AVSphericalMapping structure.

AV_PKT_DATA_CONTENT_LIGHT_LEVEL 

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_A53_CC 

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_ENCRYPTION_INIT_INFO 

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_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_AFD 

Active Format Description data consisting of a single byte as specified in ETSI TS 101 154 using AVActiveFormatDescription enum.

AV_PKT_DATA_PRFT 

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_ICC_PROFILE 

ICC profile data consisting of an opaque octet buffer following the format described by ISO 15076-1.

AV_PKT_DATA_DOVI_CONF 

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_S12M_TIMECODE 

Timecode which conforms to SMPTE ST 12-1:2014.

The data is an array of 4 uint32_t where the first uint32_t describes how many (1-3) of the other timecodes are used. The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() function in libavutil/timecode.h.

AV_PKT_DATA_DYNAMIC_HDR10_PLUS 

HDR10+ dynamic metadata associated with a video frame.

The metadata is in the form of the AVDynamicHDRPlus struct and contains information for color volume transform - application 4 of SMPTE 2094-40:2016 standard.

AV_PKT_DATA_IAMF_MIX_GAIN_PARAM 

IAMF Mix Gain Parameter Data associated with the audio frame.

This metadata is in the form of the AVIAMFParamDefinition struct and contains information defined in sections 3.6.1 and 3.8.1 of the Immersive Audio Model and Formats standard.

AV_PKT_DATA_IAMF_DEMIXING_INFO_PARAM 

IAMF Demixing Info Parameter Data associated with the audio frame.

This metadata is in the form of the AVIAMFParamDefinition struct and contains information defined in sections 3.6.1 and 3.8.2 of the Immersive Audio Model and Formats standard.

AV_PKT_DATA_IAMF_RECON_GAIN_INFO_PARAM 

IAMF Recon Gain Info Parameter Data associated with the audio frame.

This metadata is in the form of the AVIAMFParamDefinition struct and contains information defined in sections 3.6.1 and 3.8.3 of the Immersive Audio Model and Formats standard.

AV_PKT_DATA_AMBIENT_VIEWING_ENVIRONMENT 

Ambient viewing environment metadata, as defined by H.274.

This metadata should be associated with a video stream and contains data in the form of the AVAmbientViewingEnvironment struct.

AV_PKT_DATA_NB 

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.

Definition at line 41 of file packet.h.

Function Documentation

◆ av_packet_side_data_new()

AVPacketSideData* av_packet_side_data_new ( AVPacketSideData **  psd,
int pnb_sd,
enum AVPacketSideDataType  type,
size_t  size,
int  flags 
)

Allocate a new packet side data.

Parameters
sdpointer to an array of side data to which the side data should be added. *sd may be NULL, in which case the array will be initialized.
nb_sdpointer to an integer containing the number of entries in the array. The integer value will be increased by 1 on success.
typeside data type
sizedesired side data size
flagscurrently unused. Must be zero
Returns
pointer to freshly allocated side data on success, or NULL otherwise.

Definition at line 704 of file packet.c.

Referenced by add_display_matrix(), add_display_matrix_to_stream(), ff_encode_preinit(), ff_replaygain_export_raw(), flv_update_video_color_info(), init_muxer(), mov_read_colr(), mov_read_dac3(), mov_read_dec3(), parse_mca_labels(), and streamcopy_init().

◆ av_packet_side_data_add()

AVPacketSideData* av_packet_side_data_add ( AVPacketSideData **  sd,
int nb_sd,
enum AVPacketSideDataType  type,
void *  data,
size_t  size,
int  flags 
)

Wrap existing data as packet side data.

Parameters
sdpointer to an array of side data to which the side data should be added. *sd may be NULL, in which case the array will be initialized
nb_sdpointer to an integer containing the number of entries in the array. The integer value will be increased by 1 on success.
typeside data type
dataa data array. It must be allocated with the av_malloc() family of functions. The ownership of the data is transferred to the side data array on success
sizesize of the data array
flagscurrently unused. Must be zero
Returns
pointer to freshly allocated side data on success, or NULL otherwise On failure, the side data array is unchanged and the data remains owned by the caller.

Definition at line 697 of file packet.c.

Referenced by avformat_find_stream_info(), ff_dovi_configure(), ff_isom_parse_dvcc_dvvc(), ff_parse_mpeg2_descriptor(), flv_update_video_color_info(), mov_read_header(), mov_read_pssh(), and mxf_parse_structural_metadata().

◆ av_packet_side_data_get()

const AVPacketSideData* av_packet_side_data_get ( const AVPacketSideData sd,
int  nb_sd,
enum AVPacketSideDataType  type 
)

Get side information from a side data array.

Parameters
sdthe array from which the side data should be fetched
nb_sdvalue containing the number of entries in the array.
typedesired side information type
Returns
pointer to side data if present or NULL otherwise

Definition at line 654 of file packet.c.

Referenced by calculate_mpeg4_bit_rates(), configure_video_filters(), ff_encode_preinit(), flv_write_metadata_packet(), get_stream_bit_rate(), mkv_handle_rotation(), mkv_handle_spherical(), mkv_write_blockadditionmapping(), mkv_write_stereo_mode(), mkv_write_video_color(), mov_read_pssh(), mov_write_amve_tag(), mov_write_clli_tag(), mov_write_colr_tag(), mov_write_ftyp_tag(), mov_write_mdcv_tag(), mov_write_moov_tag(), mov_write_tkhd_tag(), mov_write_video_tag(), mp3_update_xing(), mpeg_mux_init(), mxf_write_cdci_common(), and mxf_write_primer_pack().

◆ av_packet_side_data_remove()

void av_packet_side_data_remove ( AVPacketSideData sd,
int nb_sd,
enum AVPacketSideDataType  type 
)

Remove side data of the given type from a side data array.

Parameters
sdthe array from which the side data should be removed
nb_sdpointer to an integer containing the number of entries in the array. Will be reduced by the amount of entries removed upon return
typeside information type

Definition at line 726 of file packet.c.

◆ av_packet_side_data_free()

void av_packet_side_data_free ( AVPacketSideData **  sd,
int nb_sd 
)

Convenience function to free all the side data stored in an array, and the array itself.

Parameters
sdpointer to array of side data to free. Will be set to NULL upon return.
nb_sdpointer to an integer containing the number of entries in the array. Will be set to 0 upon return.

Definition at line 742 of file packet.c.

Referenced by avcodec_parameters_to_context(), and codec_parameters_reset().

◆ av_packet_side_data_name()

const char* av_packet_side_data_name ( enum AVPacketSideDataType  type)

Definition at line 269 of file packet.c.

Referenced by get_packet_side_data_type(), print_pkt_side_data(), and setup_side_data_entry().