packet.h (29718B)
1 /* 2 * AVPacket public API 3 * 4 * This file is part of FFmpeg. 5 * 6 * FFmpeg is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * FFmpeg is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with FFmpeg; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 */ 20 21 #ifndef AVCODEC_PACKET_H 22 #define AVCODEC_PACKET_H 23 24 #include <stddef.h> 25 #include <stdint.h> 26 27 #include "libavutil/attributes.h" 28 #include "libavutil/buffer.h" 29 #include "libavutil/dict.h" 30 #include "libavutil/rational.h" 31 #include "libavutil/version.h" 32 33 #include "libavcodec/version_major.h" 34 35 /** 36 * @defgroup lavc_packet_side_data AVPacketSideData 37 * 38 * Types and functions for working with AVPacketSideData. 39 * @{ 40 */ 41 enum AVPacketSideDataType { 42 /** 43 * An AV_PKT_DATA_PALETTE side data packet contains exactly AVPALETTE_SIZE 44 * bytes worth of palette. This side data signals that a new palette is 45 * present. 46 */ 47 AV_PKT_DATA_PALETTE, 48 49 /** 50 * The AV_PKT_DATA_NEW_EXTRADATA is used to notify the codec or the format 51 * that the extradata buffer was changed and the receiving side should 52 * act upon it appropriately. The new extradata is embedded in the side 53 * data buffer and should be immediately used for processing the current 54 * frame or packet. 55 */ 56 AV_PKT_DATA_NEW_EXTRADATA, 57 58 /** 59 * An AV_PKT_DATA_PARAM_CHANGE side data packet is laid out as follows: 60 * @code 61 * u32le param_flags 62 * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_COUNT) 63 * s32le channel_count 64 * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_CHANNEL_LAYOUT) 65 * u64le channel_layout 66 * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE) 67 * s32le sample_rate 68 * if (param_flags & AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS) 69 * s32le width 70 * s32le height 71 * @endcode 72 */ 73 AV_PKT_DATA_PARAM_CHANGE, 74 75 /** 76 * An AV_PKT_DATA_H263_MB_INFO side data packet contains a number of 77 * structures with info about macroblocks relevant to splitting the 78 * packet into smaller packets on macroblock edges (e.g. as for RFC 2190). 79 * That is, it does not necessarily contain info about all macroblocks, 80 * as long as the distance between macroblocks in the info is smaller 81 * than the target payload size. 82 * Each MB info structure is 12 bytes, and is laid out as follows: 83 * @code 84 * u32le bit offset from the start of the packet 85 * u8 current quantizer at the start of the macroblock 86 * u8 GOB number 87 * u16le macroblock address within the GOB 88 * u8 horizontal MV predictor 89 * u8 vertical MV predictor 90 * u8 horizontal MV predictor for block number 3 91 * u8 vertical MV predictor for block number 3 92 * @endcode 93 */ 94 AV_PKT_DATA_H263_MB_INFO, 95 96 /** 97 * This side data should be associated with an audio stream and contains 98 * ReplayGain information in form of the AVReplayGain struct. 99 */ 100 AV_PKT_DATA_REPLAYGAIN, 101 102 /** 103 * This side data contains a 3x3 transformation matrix describing an affine 104 * transformation that needs to be applied to the decoded video frames for 105 * correct presentation. 106 * 107 * See libavutil/display.h for a detailed description of the data. 108 */ 109 AV_PKT_DATA_DISPLAYMATRIX, 110 111 /** 112 * This side data should be associated with a video stream and contains 113 * Stereoscopic 3D information in form of the AVStereo3D struct. 114 */ 115 AV_PKT_DATA_STEREO3D, 116 117 /** 118 * This side data should be associated with an audio stream and corresponds 119 * to enum AVAudioServiceType. 120 */ 121 AV_PKT_DATA_AUDIO_SERVICE_TYPE, 122 123 /** 124 * This side data contains quality related information from the encoder. 125 * @code 126 * u32le quality factor of the compressed frame. Allowed range is between 1 (good) and FF_LAMBDA_MAX (bad). 127 * u8 picture type 128 * u8 error count 129 * u16 reserved 130 * u64le[error count] sum of squared differences between encoder in and output 131 * @endcode 132 */ 133 AV_PKT_DATA_QUALITY_STATS, 134 135 /** 136 * This side data contains an integer value representing the stream index 137 * of a "fallback" track. A fallback track indicates an alternate 138 * track to use when the current track can not be decoded for some reason. 139 * e.g. no decoder available for codec. 140 */ 141 AV_PKT_DATA_FALLBACK_TRACK, 142 143 /** 144 * This side data corresponds to the AVCPBProperties struct. 145 */ 146 AV_PKT_DATA_CPB_PROPERTIES, 147 148 /** 149 * Recommmends skipping the specified number of samples 150 * @code 151 * u32le number of samples to skip from start of this packet 152 * u32le number of samples to skip from end of this packet 153 * u8 reason for start skip 154 * u8 reason for end skip (0=padding silence, 1=convergence) 155 * @endcode 156 */ 157 AV_PKT_DATA_SKIP_SAMPLES, 158 159 /** 160 * An AV_PKT_DATA_JP_DUALMONO side data packet indicates that 161 * the packet may contain "dual mono" audio specific to Japanese DTV 162 * and if it is true, recommends only the selected channel to be used. 163 * @code 164 * u8 selected channels (0=main/left, 1=sub/right, 2=both) 165 * @endcode 166 */ 167 AV_PKT_DATA_JP_DUALMONO, 168 169 /** 170 * A list of zero terminated key/value strings. There is no end marker for 171 * the list, so it is required to rely on the side data size to stop. 172 */ 173 AV_PKT_DATA_STRINGS_METADATA, 174 175 /** 176 * Subtitle event position 177 * @code 178 * u32le x1 179 * u32le y1 180 * u32le x2 181 * u32le y2 182 * @endcode 183 */ 184 AV_PKT_DATA_SUBTITLE_POSITION, 185 186 /** 187 * Data found in BlockAdditional element of matroska container. There is 188 * no end marker for the data, so it is required to rely on the side data 189 * size to recognize the end. 8 byte id (as found in BlockAddId) followed 190 * by data. 191 */ 192 AV_PKT_DATA_MATROSKA_BLOCKADDITIONAL, 193 194 /** 195 * The optional first identifier line of a WebVTT cue. 196 */ 197 AV_PKT_DATA_WEBVTT_IDENTIFIER, 198 199 /** 200 * The optional settings (rendering instructions) that immediately 201 * follow the timestamp specifier of a WebVTT cue. 202 */ 203 AV_PKT_DATA_WEBVTT_SETTINGS, 204 205 /** 206 * A list of zero terminated key/value strings. There is no end marker for 207 * the list, so it is required to rely on the side data size to stop. This 208 * side data includes updated metadata which appeared in the stream. 209 */ 210 AV_PKT_DATA_METADATA_UPDATE, 211 212 /** 213 * MPEGTS stream ID as uint8_t, this is required to pass the stream ID 214 * information from the demuxer to the corresponding muxer. 215 */ 216 AV_PKT_DATA_MPEGTS_STREAM_ID, 217 218 /** 219 * Mastering display metadata (based on SMPTE-2086:2014). This metadata 220 * should be associated with a video stream and contains data in the form 221 * of the AVMasteringDisplayMetadata struct. 222 */ 223 AV_PKT_DATA_MASTERING_DISPLAY_METADATA, 224 225 /** 226 * This side data should be associated with a video stream and corresponds 227 * to the AVSphericalMapping structure. 228 */ 229 AV_PKT_DATA_SPHERICAL, 230 231 /** 232 * Content light level (based on CTA-861.3). This metadata should be 233 * associated with a video stream and contains data in the form of the 234 * AVContentLightMetadata struct. 235 */ 236 AV_PKT_DATA_CONTENT_LIGHT_LEVEL, 237 238 /** 239 * ATSC A53 Part 4 Closed Captions. This metadata should be associated with 240 * a video stream. A53 CC bitstream is stored as uint8_t in AVPacketSideData.data. 241 * The number of bytes of CC data is AVPacketSideData.size. 242 */ 243 AV_PKT_DATA_A53_CC, 244 245 /** 246 * This side data is encryption initialization data. 247 * The format is not part of ABI, use av_encryption_init_info_* methods to 248 * access. 249 */ 250 AV_PKT_DATA_ENCRYPTION_INIT_INFO, 251 252 /** 253 * This side data contains encryption info for how to decrypt the packet. 254 * The format is not part of ABI, use av_encryption_info_* methods to access. 255 */ 256 AV_PKT_DATA_ENCRYPTION_INFO, 257 258 /** 259 * Active Format Description data consisting of a single byte as specified 260 * in ETSI TS 101 154 using AVActiveFormatDescription enum. 261 */ 262 AV_PKT_DATA_AFD, 263 264 /** 265 * Producer Reference Time data corresponding to the AVProducerReferenceTime struct, 266 * usually exported by some encoders (on demand through the prft flag set in the 267 * AVCodecContext export_side_data field). 268 */ 269 AV_PKT_DATA_PRFT, 270 271 /** 272 * ICC profile data consisting of an opaque octet buffer following the 273 * format described by ISO 15076-1. 274 */ 275 AV_PKT_DATA_ICC_PROFILE, 276 277 /** 278 * DOVI configuration 279 * ref: 280 * dolby-vision-bitstreams-within-the-iso-base-media-file-format-v2.1.2, section 2.2 281 * dolby-vision-bitstreams-in-mpeg-2-transport-stream-multiplex-v1.2, section 3.3 282 * Tags are stored in struct AVDOVIDecoderConfigurationRecord. 283 */ 284 AV_PKT_DATA_DOVI_CONF, 285 286 /** 287 * Timecode which conforms to SMPTE ST 12-1:2014. The data is an array of 4 uint32_t 288 * where the first uint32_t describes how many (1-3) of the other timecodes are used. 289 * The timecode format is described in the documentation of av_timecode_get_smpte_from_framenum() 290 * function in libavutil/timecode.h. 291 */ 292 AV_PKT_DATA_S12M_TIMECODE, 293 294 /** 295 * HDR10+ dynamic metadata associated with a video frame. The metadata is in 296 * the form of the AVDynamicHDRPlus struct and contains 297 * information for color volume transform - application 4 of 298 * SMPTE 2094-40:2016 standard. 299 */ 300 AV_PKT_DATA_DYNAMIC_HDR10_PLUS, 301 302 /** 303 * IAMF Mix Gain Parameter Data associated with the audio frame. This metadata 304 * is in the form of the AVIAMFParamDefinition struct and contains information 305 * defined in sections 3.6.1 and 3.8.1 of the Immersive Audio Model and 306 * Formats standard. 307 */ 308 AV_PKT_DATA_IAMF_MIX_GAIN_PARAM, 309 310 /** 311 * IAMF Demixing Info Parameter Data associated with the audio frame. This 312 * metadata is in the form of the AVIAMFParamDefinition struct and contains 313 * information defined in sections 3.6.1 and 3.8.2 of the Immersive Audio Model 314 * and Formats standard. 315 */ 316 AV_PKT_DATA_IAMF_DEMIXING_INFO_PARAM, 317 318 /** 319 * IAMF Recon Gain Info Parameter Data associated with the audio frame. This 320 * metadata is in the form of the AVIAMFParamDefinition struct and contains 321 * information defined in sections 3.6.1 and 3.8.3 of the Immersive Audio Model 322 * and Formats standard. 323 */ 324 AV_PKT_DATA_IAMF_RECON_GAIN_INFO_PARAM, 325 326 /** 327 * Ambient viewing environment metadata, as defined by H.274. This metadata 328 * should be associated with a video stream and contains data in the form 329 * of the AVAmbientViewingEnvironment struct. 330 */ 331 AV_PKT_DATA_AMBIENT_VIEWING_ENVIRONMENT, 332 333 /** 334 * The number of side data types. 335 * This is not part of the public API/ABI in the sense that it may 336 * change when new side data types are added. 337 * This must stay the last enum value. 338 * If its value becomes huge, some code using it 339 * needs to be updated as it assumes it to be smaller than other limits. 340 */ 341 AV_PKT_DATA_NB 342 }; 343 344 #define AV_PKT_DATA_QUALITY_FACTOR AV_PKT_DATA_QUALITY_STATS //DEPRECATED 345 346 /** 347 * This structure stores auxiliary information for decoding, presenting, or 348 * otherwise processing the coded stream. It is typically exported by demuxers 349 * and encoders and can be fed to decoders and muxers either in a per packet 350 * basis, or as global side data (applying to the entire coded stream). 351 * 352 * Global side data is handled as follows: 353 * - During demuxing, it may be exported through 354 * @ref AVStream.codecpar.side_data "AVStream's codec parameters", which can 355 * then be passed as input to decoders through the 356 * @ref AVCodecContext.coded_side_data "decoder context's side data", for 357 * initialization. 358 * - For muxing, it can be fed through @ref AVStream.codecpar.side_data 359 * "AVStream's codec parameters", typically the output of encoders through 360 * the @ref AVCodecContext.coded_side_data "encoder context's side data", for 361 * initialization. 362 * 363 * Packet specific side data is handled as follows: 364 * - During demuxing, it may be exported through @ref AVPacket.side_data 365 * "AVPacket's side data", which can then be passed as input to decoders. 366 * - For muxing, it can be fed through @ref AVPacket.side_data "AVPacket's 367 * side data", typically the output of encoders. 368 * 369 * Different modules may accept or export different types of side data 370 * depending on media type and codec. Refer to @ref AVPacketSideDataType for a 371 * list of defined types and where they may be found or used. 372 */ 373 typedef struct AVPacketSideData { 374 uint8_t *data; 375 size_t size; 376 enum AVPacketSideDataType type; 377 } AVPacketSideData; 378 379 /** 380 * Allocate a new packet side data. 381 * 382 * @param sd pointer to an array of side data to which the side data should 383 * be added. *sd may be NULL, in which case the array will be 384 * initialized. 385 * @param nb_sd pointer to an integer containing the number of entries in 386 * the array. The integer value will be increased by 1 on success. 387 * @param type side data type 388 * @param size desired side data size 389 * @param flags currently unused. Must be zero 390 * 391 * @return pointer to freshly allocated side data on success, or NULL otherwise. 392 */ 393 AVPacketSideData *av_packet_side_data_new(AVPacketSideData **psd, int *pnb_sd, 394 enum AVPacketSideDataType type, 395 size_t size, int flags); 396 397 /** 398 * Wrap existing data as packet side data. 399 * 400 * @param sd pointer to an array of side data to which the side data should 401 * be added. *sd may be NULL, in which case the array will be 402 * initialized 403 * @param nb_sd pointer to an integer containing the number of entries in 404 * the array. The integer value will be increased by 1 on success. 405 * @param type side data type 406 * @param data a data array. It must be allocated with the av_malloc() family 407 * of functions. The ownership of the data is transferred to the 408 * side data array on success 409 * @param size size of the data array 410 * @param flags currently unused. Must be zero 411 * 412 * @return pointer to freshly allocated side data on success, or NULL otherwise 413 * On failure, the side data array is unchanged and the data remains 414 * owned by the caller. 415 */ 416 AVPacketSideData *av_packet_side_data_add(AVPacketSideData **sd, int *nb_sd, 417 enum AVPacketSideDataType type, 418 void *data, size_t size, int flags); 419 420 /** 421 * Get side information from a side data array. 422 * 423 * @param sd the array from which the side data should be fetched 424 * @param nb_sd value containing the number of entries in the array. 425 * @param type desired side information type 426 * 427 * @return pointer to side data if present or NULL otherwise 428 */ 429 const AVPacketSideData *av_packet_side_data_get(const AVPacketSideData *sd, 430 int nb_sd, 431 enum AVPacketSideDataType type); 432 433 /** 434 * Remove side data of the given type from a side data array. 435 * 436 * @param sd the array from which the side data should be removed 437 * @param nb_sd pointer to an integer containing the number of entries in 438 * the array. Will be reduced by the amount of entries removed 439 * upon return 440 * @param type side information type 441 */ 442 void av_packet_side_data_remove(AVPacketSideData *sd, int *nb_sd, 443 enum AVPacketSideDataType type); 444 445 /** 446 * Convenience function to free all the side data stored in an array, and 447 * the array itself. 448 * 449 * @param sd pointer to array of side data to free. Will be set to NULL 450 * upon return. 451 * @param nb_sd pointer to an integer containing the number of entries in 452 * the array. Will be set to 0 upon return. 453 */ 454 void av_packet_side_data_free(AVPacketSideData **sd, int *nb_sd); 455 456 const char *av_packet_side_data_name(enum AVPacketSideDataType type); 457 458 /** 459 * @} 460 */ 461 462 /** 463 * @defgroup lavc_packet AVPacket 464 * 465 * Types and functions for working with AVPacket. 466 * @{ 467 */ 468 469 /** 470 * This structure stores compressed data. It is typically exported by demuxers 471 * and then passed as input to decoders, or received as output from encoders and 472 * then passed to muxers. 473 * 474 * For video, it should typically contain one compressed frame. For audio it may 475 * contain several compressed frames. Encoders are allowed to output empty 476 * packets, with no compressed data, containing only side data 477 * (e.g. to update some stream parameters at the end of encoding). 478 * 479 * The semantics of data ownership depends on the buf field. 480 * If it is set, the packet data is dynamically allocated and is 481 * valid indefinitely until a call to av_packet_unref() reduces the 482 * reference count to 0. 483 * 484 * If the buf field is not set av_packet_ref() would make a copy instead 485 * of increasing the reference count. 486 * 487 * The side data is always allocated with av_malloc(), copied by 488 * av_packet_ref() and freed by av_packet_unref(). 489 * 490 * sizeof(AVPacket) being a part of the public ABI is deprecated. once 491 * av_init_packet() is removed, new packets will only be able to be allocated 492 * with av_packet_alloc(), and new fields may be added to the end of the struct 493 * with a minor bump. 494 * 495 * @see av_packet_alloc 496 * @see av_packet_ref 497 * @see av_packet_unref 498 */ 499 typedef struct AVPacket { 500 /** 501 * A reference to the reference-counted buffer where the packet data is 502 * stored. 503 * May be NULL, then the packet data is not reference-counted. 504 */ 505 AVBufferRef *buf; 506 /** 507 * Presentation timestamp in AVStream->time_base units; the time at which 508 * the decompressed packet will be presented to the user. 509 * Can be AV_NOPTS_VALUE if it is not stored in the file. 510 * pts MUST be larger or equal to dts as presentation cannot happen before 511 * decompression, unless one wants to view hex dumps. Some formats misuse 512 * the terms dts and pts/cts to mean something different. Such timestamps 513 * must be converted to true pts/dts before they are stored in AVPacket. 514 */ 515 int64_t pts; 516 /** 517 * Decompression timestamp in AVStream->time_base units; the time at which 518 * the packet is decompressed. 519 * Can be AV_NOPTS_VALUE if it is not stored in the file. 520 */ 521 int64_t dts; 522 uint8_t *data; 523 int size; 524 int stream_index; 525 /** 526 * A combination of AV_PKT_FLAG values 527 */ 528 int flags; 529 /** 530 * Additional packet data that can be provided by the container. 531 * Packet can contain several types of side information. 532 */ 533 AVPacketSideData *side_data; 534 int side_data_elems; 535 536 /** 537 * Duration of this packet in AVStream->time_base units, 0 if unknown. 538 * Equals next_pts - this_pts in presentation order. 539 */ 540 int64_t duration; 541 542 int64_t pos; ///< byte position in stream, -1 if unknown 543 544 /** 545 * for some private data of the user 546 */ 547 void *opaque; 548 549 /** 550 * AVBufferRef for free use by the API user. FFmpeg will never check the 551 * contents of the buffer ref. FFmpeg calls av_buffer_unref() on it when 552 * the packet is unreferenced. av_packet_copy_props() calls create a new 553 * reference with av_buffer_ref() for the target packet's opaque_ref field. 554 * 555 * This is unrelated to the opaque field, although it serves a similar 556 * purpose. 557 */ 558 AVBufferRef *opaque_ref; 559 560 /** 561 * Time base of the packet's timestamps. 562 * In the future, this field may be set on packets output by encoders or 563 * demuxers, but its value will be by default ignored on input to decoders 564 * or muxers. 565 */ 566 AVRational time_base; 567 } AVPacket; 568 569 #if FF_API_INIT_PACKET 570 attribute_deprecated 571 typedef struct AVPacketList { 572 AVPacket pkt; 573 struct AVPacketList *next; 574 } AVPacketList; 575 #endif 576 577 #define AV_PKT_FLAG_KEY 0x0001 ///< The packet contains a keyframe 578 #define AV_PKT_FLAG_CORRUPT 0x0002 ///< The packet content is corrupted 579 /** 580 * Flag is used to discard packets which are required to maintain valid 581 * decoder state but are not required for output and should be dropped 582 * after decoding. 583 **/ 584 #define AV_PKT_FLAG_DISCARD 0x0004 585 /** 586 * The packet comes from a trusted source. 587 * 588 * Otherwise-unsafe constructs such as arbitrary pointers to data 589 * outside the packet may be followed. 590 */ 591 #define AV_PKT_FLAG_TRUSTED 0x0008 592 /** 593 * Flag is used to indicate packets that contain frames that can 594 * be discarded by the decoder. I.e. Non-reference frames. 595 */ 596 #define AV_PKT_FLAG_DISPOSABLE 0x0010 597 598 enum AVSideDataParamChangeFlags { 599 AV_SIDE_DATA_PARAM_CHANGE_SAMPLE_RATE = 0x0004, 600 AV_SIDE_DATA_PARAM_CHANGE_DIMENSIONS = 0x0008, 601 }; 602 603 /** 604 * Allocate an AVPacket and set its fields to default values. The resulting 605 * struct must be freed using av_packet_free(). 606 * 607 * @return An AVPacket filled with default values or NULL on failure. 608 * 609 * @note this only allocates the AVPacket itself, not the data buffers. Those 610 * must be allocated through other means such as av_new_packet. 611 * 612 * @see av_new_packet 613 */ 614 AVPacket *av_packet_alloc(void); 615 616 /** 617 * Create a new packet that references the same data as src. 618 * 619 * This is a shortcut for av_packet_alloc()+av_packet_ref(). 620 * 621 * @return newly created AVPacket on success, NULL on error. 622 * 623 * @see av_packet_alloc 624 * @see av_packet_ref 625 */ 626 AVPacket *av_packet_clone(const AVPacket *src); 627 628 /** 629 * Free the packet, if the packet is reference counted, it will be 630 * unreferenced first. 631 * 632 * @param pkt packet to be freed. The pointer will be set to NULL. 633 * @note passing NULL is a no-op. 634 */ 635 void av_packet_free(AVPacket **pkt); 636 637 #if FF_API_INIT_PACKET 638 /** 639 * Initialize optional fields of a packet with default values. 640 * 641 * Note, this does not touch the data and size members, which have to be 642 * initialized separately. 643 * 644 * @param pkt packet 645 * 646 * @see av_packet_alloc 647 * @see av_packet_unref 648 * 649 * @deprecated This function is deprecated. Once it's removed, 650 sizeof(AVPacket) will not be a part of the ABI anymore. 651 */ 652 attribute_deprecated 653 void av_init_packet(AVPacket *pkt); 654 #endif 655 656 /** 657 * Allocate the payload of a packet and initialize its fields with 658 * default values. 659 * 660 * @param pkt packet 661 * @param size wanted payload size 662 * @return 0 if OK, AVERROR_xxx otherwise 663 */ 664 int av_new_packet(AVPacket *pkt, int size); 665 666 /** 667 * Reduce packet size, correctly zeroing padding 668 * 669 * @param pkt packet 670 * @param size new size 671 */ 672 void av_shrink_packet(AVPacket *pkt, int size); 673 674 /** 675 * Increase packet size, correctly zeroing padding 676 * 677 * @param pkt packet 678 * @param grow_by number of bytes by which to increase the size of the packet 679 */ 680 int av_grow_packet(AVPacket *pkt, int grow_by); 681 682 /** 683 * Initialize a reference-counted packet from av_malloc()ed data. 684 * 685 * @param pkt packet to be initialized. This function will set the data, size, 686 * and buf fields, all others are left untouched. 687 * @param data Data allocated by av_malloc() to be used as packet data. If this 688 * function returns successfully, the data is owned by the underlying AVBuffer. 689 * The caller may not access the data through other means. 690 * @param size size of data in bytes, without the padding. I.e. the full buffer 691 * size is assumed to be size + AV_INPUT_BUFFER_PADDING_SIZE. 692 * 693 * @return 0 on success, a negative AVERROR on error 694 */ 695 int av_packet_from_data(AVPacket *pkt, uint8_t *data, int size); 696 697 /** 698 * Allocate new information of a packet. 699 * 700 * @param pkt packet 701 * @param type side information type 702 * @param size side information size 703 * @return pointer to fresh allocated data or NULL otherwise 704 */ 705 uint8_t* av_packet_new_side_data(AVPacket *pkt, enum AVPacketSideDataType type, 706 size_t size); 707 708 /** 709 * Wrap an existing array as a packet side data. 710 * 711 * @param pkt packet 712 * @param type side information type 713 * @param data the side data array. It must be allocated with the av_malloc() 714 * family of functions. The ownership of the data is transferred to 715 * pkt. 716 * @param size side information size 717 * @return a non-negative number on success, a negative AVERROR code on 718 * failure. On failure, the packet is unchanged and the data remains 719 * owned by the caller. 720 */ 721 int av_packet_add_side_data(AVPacket *pkt, enum AVPacketSideDataType type, 722 uint8_t *data, size_t size); 723 724 /** 725 * Shrink the already allocated side data buffer 726 * 727 * @param pkt packet 728 * @param type side information type 729 * @param size new side information size 730 * @return 0 on success, < 0 on failure 731 */ 732 int av_packet_shrink_side_data(AVPacket *pkt, enum AVPacketSideDataType type, 733 size_t size); 734 735 /** 736 * Get side information from packet. 737 * 738 * @param pkt packet 739 * @param type desired side information type 740 * @param size If supplied, *size will be set to the size of the side data 741 * or to zero if the desired side data is not present. 742 * @return pointer to data if present or NULL otherwise 743 */ 744 uint8_t* av_packet_get_side_data(const AVPacket *pkt, enum AVPacketSideDataType type, 745 size_t *size); 746 747 /** 748 * Pack a dictionary for use in side_data. 749 * 750 * @param dict The dictionary to pack. 751 * @param size pointer to store the size of the returned data 752 * @return pointer to data if successful, NULL otherwise 753 */ 754 uint8_t *av_packet_pack_dictionary(AVDictionary *dict, size_t *size); 755 /** 756 * Unpack a dictionary from side_data. 757 * 758 * @param data data from side_data 759 * @param size size of the data 760 * @param dict the metadata storage dictionary 761 * @return 0 on success, < 0 on failure 762 */ 763 int av_packet_unpack_dictionary(const uint8_t *data, size_t size, 764 AVDictionary **dict); 765 766 /** 767 * Convenience function to free all the side data stored. 768 * All the other fields stay untouched. 769 * 770 * @param pkt packet 771 */ 772 void av_packet_free_side_data(AVPacket *pkt); 773 774 /** 775 * Setup a new reference to the data described by a given packet 776 * 777 * If src is reference-counted, setup dst as a new reference to the 778 * buffer in src. Otherwise allocate a new buffer in dst and copy the 779 * data from src into it. 780 * 781 * All the other fields are copied from src. 782 * 783 * @see av_packet_unref 784 * 785 * @param dst Destination packet. Will be completely overwritten. 786 * @param src Source packet 787 * 788 * @return 0 on success, a negative AVERROR on error. On error, dst 789 * will be blank (as if returned by av_packet_alloc()). 790 */ 791 int av_packet_ref(AVPacket *dst, const AVPacket *src); 792 793 /** 794 * Wipe the packet. 795 * 796 * Unreference the buffer referenced by the packet and reset the 797 * remaining packet fields to their default values. 798 * 799 * @param pkt The packet to be unreferenced. 800 */ 801 void av_packet_unref(AVPacket *pkt); 802 803 /** 804 * Move every field in src to dst and reset src. 805 * 806 * @see av_packet_unref 807 * 808 * @param src Source packet, will be reset 809 * @param dst Destination packet 810 */ 811 void av_packet_move_ref(AVPacket *dst, AVPacket *src); 812 813 /** 814 * Copy only "properties" fields from src to dst. 815 * 816 * Properties for the purpose of this function are all the fields 817 * beside those related to the packet data (buf, data, size) 818 * 819 * @param dst Destination packet 820 * @param src Source packet 821 * 822 * @return 0 on success AVERROR on failure. 823 */ 824 int av_packet_copy_props(AVPacket *dst, const AVPacket *src); 825 826 /** 827 * Ensure the data described by a given packet is reference counted. 828 * 829 * @note This function does not ensure that the reference will be writable. 830 * Use av_packet_make_writable instead for that purpose. 831 * 832 * @see av_packet_ref 833 * @see av_packet_make_writable 834 * 835 * @param pkt packet whose data should be made reference counted. 836 * 837 * @return 0 on success, a negative AVERROR on error. On failure, the 838 * packet is unchanged. 839 */ 840 int av_packet_make_refcounted(AVPacket *pkt); 841 842 /** 843 * Create a writable reference for the data described by a given packet, 844 * avoiding data copy if possible. 845 * 846 * @param pkt Packet whose data should be made writable. 847 * 848 * @return 0 on success, a negative AVERROR on failure. On failure, the 849 * packet is unchanged. 850 */ 851 int av_packet_make_writable(AVPacket *pkt); 852 853 /** 854 * Convert valid timing fields (timestamps / durations) in a packet from one 855 * timebase to another. Timestamps with unknown values (AV_NOPTS_VALUE) will be 856 * ignored. 857 * 858 * @param pkt packet on which the conversion will be performed 859 * @param tb_src source timebase, in which the timing fields in pkt are 860 * expressed 861 * @param tb_dst destination timebase, to which the timing fields will be 862 * converted 863 */ 864 void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst); 865 866 /** 867 * @} 868 */ 869 870 #endif // AVCODEC_PACKET_H