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 */
41enum 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 */
373typedef 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 */
393AVPacketSideData *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 */
416AVPacketSideData *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 */
429const 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 */
442void 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 */
454void av_packet_side_data_free(AVPacketSideData **sd, int *nb_sd);
455
456const 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 */
499typedef 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
570attribute_deprecated
571typedef 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
598enum 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 */
614AVPacket *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 */
626AVPacket *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 */
635void 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 */
652attribute_deprecated
653void 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 */
664int 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 */
672void 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 */
680int 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 */
695int 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 */
705uint8_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 */
721int 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 */
732int 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 */
744uint8_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 */
754uint8_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 */
763int 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 */
772void 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 */
791int 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 */
801void 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 */
811void 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 */
824int 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 */
840int 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 */
851int 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 */
864void av_packet_rescale_ts(AVPacket *pkt, AVRational tb_src, AVRational tb_dst);
865
866/**
867 * @}
868 */
869
870#endif // AVCODEC_PACKET_H
871