FFmpeg
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Macros | Enumerations | Functions
Decoding
Encoding/Decoding Library

Modules

 Frame parsing
 

Macros

#define FF_INPUT_BUFFER_PADDING_SIZE   32
 Required number of additionally allocated bytes at the end of the input bitstream for decoding.
 

Enumerations

enum  AVDiscard {
  AVDISCARD_NONE =-16, AVDISCARD_DEFAULT = 0, AVDISCARD_NONREF = 8, AVDISCARD_BIDIR = 16,
  AVDISCARD_NONINTRA = 24, AVDISCARD_NONKEY = 32, AVDISCARD_ALL = 48
}
 

Functions

AVCodecavcodec_find_decoder (enum AVCodecID id)
 Find a registered decoder with a matching codec ID.
 
AVCodecavcodec_find_decoder_by_name (const char *name)
 Find a registered decoder with the specified name.
 
attribute_deprecated int avcodec_default_get_buffer (AVCodecContext *s, AVFrame *pic)
 
attribute_deprecated void avcodec_default_release_buffer (AVCodecContext *s, AVFrame *pic)
 
attribute_deprecated int avcodec_default_reget_buffer (AVCodecContext *s, AVFrame *pic)
 
int avcodec_default_get_buffer2 (AVCodecContext *s, AVFrame *frame, int flags)
 The default callback for AVCodecContext.get_buffer2().
 
attribute_deprecated unsigned avcodec_get_edge_width (void)
 Return the amount of padding in pixels which the get_buffer callback must provide around the edge of the image for codecs which do not have the CODEC_FLAG_EMU_EDGE flag.
 
void avcodec_align_dimensions (AVCodecContext *s, int *width, int *height)
 Modify width and height values so that they will result in a memory buffer that is acceptable for the codec if you do not use any horizontal padding.
 
void avcodec_align_dimensions2 (AVCodecContext *s, int *width, int *height, int linesize_align[AV_NUM_DATA_POINTERS])
 Modify width and height values so that they will result in a memory buffer that is acceptable for the codec if you also ensure that all line sizes are a multiple of the respective linesize_align[i].
 
int avcodec_enum_to_chroma_pos (int *xpos, int *ypos, enum AVChromaLocation pos)
 Converts AVChromaLocation to swscale x/y chroma position.
 
enum AVChromaLocation avcodec_chroma_pos_to_enum (int xpos, int ypos)
 Converts swscale x/y chroma position to AVChromaLocation.
 
attribute_deprecated int avcodec_decode_audio3 (AVCodecContext *avctx, int16_t *samples, int *frame_size_ptr, AVPacket *avpkt)
 Wrapper function which calls avcodec_decode_audio4.
 
int avcodec_decode_audio4 (AVCodecContext *avctx, AVFrame *frame, int *got_frame_ptr, const AVPacket *avpkt)
 Decode the audio frame of size avpkt->size from avpkt->data into frame.
 
int avcodec_decode_video2 (AVCodecContext *avctx, AVFrame *picture, int *got_picture_ptr, const AVPacket *avpkt)
 Decode the video frame of size avpkt->size from avpkt->data into picture.
 
int avcodec_decode_subtitle2 (AVCodecContext *avctx, AVSubtitle *sub, int *got_sub_ptr, AVPacket *avpkt)
 Decode a subtitle message.
 

Detailed Description

Macro Definition Documentation

#define FF_INPUT_BUFFER_PADDING_SIZE   32

Required number of additionally allocated bytes at the end of the input bitstream for decoding.

This is mainly needed because some optimized bitstream readers read 32 or 64 bit at once and could read over the end.
Note: If the first 23 bits of the additional bytes are not 0, then damaged MPEG bitstreams could cause overread and segfault.

Examples:
decoding_encoding.c, and qsvdec.c.

Definition at line 628 of file avcodec.h.

Referenced by a64multi_encode_init(), aac_adtstoasc_filter(), aac_decode_frame(), aac_encode_init(), aac_sync(), aacPlus_encode_init(), ac3_sync(), adpcm_encode_init(), alac_encode_init(), alloc_and_copy(), alloc_buffers(), ape_tag_read_field(), apng_read_header(), append_extradata(), asf_parse_packet(), asf_read_stream_properties(), atrac3_decode_init(), audio_decode_example(), av_fast_padded_malloc(), av_fast_padded_mallocz(), av_grow_packet(), av_packet_from_data(), av_packet_merge_side_data(), av_packet_new_side_data(), av_packet_split_side_data(), av_parser_change(), av_parser_parse2(), av_shrink_packet(), avcodec_copy_context(), avcodec_decode_subtitle2(), avcodec_encode_audio2(), avcodec_encode_video2(), avi_read_header(), avio_close_dyn_buf(), avui_encode_init(), cdxl_decode_frame(), codec_reinit(), cook_decode_init(), dca_parse_params(), decode_frame(), decode_init(), decode_plane(), dshow_add_device(), dts_probe(), dump_extradata(), dv_decode_video_segment(), encode_init(), extract_header(), extract_mpeg4_header(), Faac_encode_init(), ff_alloc_extradata(), ff_alloc_packet2(), ff_avc_write_annexb_extradata(), ff_combine_frame(), ff_flac_parse_picture(), ff_h264_decode_nal(), ff_h264_parse_sprop_parameter_sets(), ff_hevc_extract_rbsp(), ff_id3v2_parse_apic(), ff_mjpeg_find_marker(), ff_mpeg_update_thread_context(), ff_mpv_encode_picture(), ff_parse_mpeg2_descriptor(), fixup_vorbis_headers(), flac_read_header(), flic_decode_frame_8BPP(), flv_queue_extradata(), g2m_init_buffers(), h264_mp4toannexb_filter(), handle_packets(), hevc_parse_sdp_line(), id3_has_changed_values(), iff_read_header(), imc_decode_frame(), imx_dump_header(), init(), jacosub_read_header(), jpg_decode_data(), latm_decode_audio_specific_config(), libopus_encode_init(), libvorbis_encode_init(), libx265_encode_init(), main(), matroska_parse_tracks(), mjpega_dump_header(), mov2textsub(), mov_read_atom_into_extradata(), mov_read_stsz(), mov_realloc_extradata(), mov_rewrite_dvd_sub_extradata(), mov_text_encode_init(), mov_write_dvc1_structs(), mp3_header_decompress(), mpc8_parse_seektable(), mpegts_push_data(), mss2_decode_frame(), mxg_update_cache(), new_pes_packet(), noise(), nvenc_encode_init(), ogg_new_buf(), ogg_new_stream(), ogg_read_page(), ogg_save(), ogm_header(), packet_alloc(), parse_fmtp_config(), parse_packed_headers(), parse_vtrk(), pcx_decode_frame(), qsv_decode_init(), qt_rtp_parse_packet(), rdt_parse_b64buf(), read_apic(), read_header(), read_kuki_chunk(), read_packet(), read_sl_header(), recode_subtitle(), redspark_read_header(), rm_read_audio_stream_info(), sao_edge_filter(), sao_filter_CTB(), shorten_decode_frame(), spdif_write_packet(), Stagefright_init(), svc_encode_init(), tak_read_header(), text2movsub(), theora_header(), tiff_unpack_fax(), transcode_init(), utvideo_encode_init(), vc1_decode_frame(), vc1_decode_init(), vfw_read_header(), video_decode_example(), wma_decode_superframe(), wmv2_encode_init(), write_extradata(), write_frame(), wv_get_value_float(), and xwma_read_header().

Enumeration Type Documentation

enum AVDiscard
Enumerator:
AVDISCARD_NONE 

discard nothing

AVDISCARD_DEFAULT 

discard useless packets like 0 size packets in avi

AVDISCARD_NONREF 

discard all non reference

AVDISCARD_BIDIR 

discard all bidirectional frames

AVDISCARD_NONINTRA 

discard all non intra frames

AVDISCARD_NONKEY 

discard all frames except keyframes

AVDISCARD_ALL 

discard all

Definition at line 658 of file avcodec.h.

Function Documentation

AVCodec* avcodec_find_decoder ( enum AVCodecID  id)
AVCodec* avcodec_find_decoder_by_name ( const char *  name)

Find a registered decoder with the specified name.

Parameters
namename of the requested decoder
Returns
A decoder if one was found, NULL otherwise.
Examples:
qsvdec.c.

Definition at line 2939 of file utils.c.

Referenced by find_codec_or_die(), main(), show_help_codec(), stream_component_open(), and v4l2_read_header().

attribute_deprecated int avcodec_default_get_buffer ( AVCodecContext s,
AVFrame pic 
)

Definition at line 837 of file utils.c.

Referenced by avcodec_decode_audio3().

attribute_deprecated void avcodec_default_release_buffer ( AVCodecContext s,
AVFrame pic 
)

Definition at line 1086 of file utils.c.

Referenced by avcodec_decode_audio3().

attribute_deprecated int avcodec_default_reget_buffer ( AVCodecContext s,
AVFrame pic 
)

Definition at line 1093 of file utils.c.

int avcodec_default_get_buffer2 ( AVCodecContext s,
AVFrame frame,
int  flags 
)

The default callback for AVCodecContext.get_buffer2().

It is made public so it can be called by custom get_buffer2() implementations for decoders without CODEC_CAP_DR1 set.

Definition at line 715 of file utils.c.

Referenced by alloc_frame_buffer(), avcodec_default_get_buffer(), avcodec_get_context_defaults3(), ff_thread_release_buffer(), get_buffer(), submit_packet(), and thread_get_buffer_internal().

attribute_deprecated unsigned avcodec_get_edge_width ( void  )

Return the amount of padding in pixels which the get_buffer callback must provide around the edge of the image for codecs which do not have the CODEC_FLAG_EMU_EDGE flag.

Returns
Required padding in pixels.
Deprecated:
CODEC_FLAG_EMU_EDGE is deprecated, so this function is no longer needed

Definition at line 213 of file utils.c.

void avcodec_align_dimensions ( AVCodecContext s,
int *  width,
int *  height 
)

Modify width and height values so that they will result in a memory buffer that is acceptable for the codec if you do not use any horizontal padding.

May only be used if a codec with CODEC_CAP_DR1 has been opened.

Definition at line 436 of file utils.c.

void avcodec_align_dimensions2 ( AVCodecContext s,
int *  width,
int *  height,
int  linesize_align[AV_NUM_DATA_POINTERS] 
)

Modify width and height values so that they will result in a memory buffer that is acceptable for the codec if you also ensure that all line sizes are a multiple of the respective linesize_align[i].

May only be used if a codec with CODEC_CAP_DR1 has been opened.

Definition at line 279 of file utils.c.

Referenced by avcodec_align_dimensions(), and update_frame_pool().

int avcodec_enum_to_chroma_pos ( int *  xpos,
int *  ypos,
enum AVChromaLocation  pos 
)

Converts AVChromaLocation to swscale x/y chroma position.

The positions represent the chroma (0,0) position in a coordinates system with luma (0,0) representing the origin and luma(1,1) representing 256,256

Parameters
xposhorizontal chroma sample position
yposvertical chroma sample position

Definition at line 451 of file utils.c.

Referenced by avcodec_chroma_pos_to_enum().

enum AVChromaLocation avcodec_chroma_pos_to_enum ( int  xpos,
int  ypos 
)

Converts swscale x/y chroma position to AVChromaLocation.

The positions represent the chroma (0,0) position in a coordinates system with luma (0,0) representing the origin and luma(1,1) representing 256,256

Parameters
xposhorizontal chroma sample position
yposvertical chroma sample position

Definition at line 463 of file utils.c.

attribute_deprecated int avcodec_decode_audio3 ( AVCodecContext avctx,
int16_t *  samples,
int *  frame_size_ptr,
AVPacket avpkt 
)

Wrapper function which calls avcodec_decode_audio4.

Deprecated:
Use avcodec_decode_audio4 instead.

Decode the audio frame of size avpkt->size from avpkt->data into samples. Some decoders may support multiple frames in a single AVPacket, such decoders would then just decode the first frame. In this case, avcodec_decode_audio3 has to be called again with an AVPacket that contains the remaining data in order to decode the second frame etc. If no frame could be outputted, frame_size_ptr is zero. Otherwise, it is the decompressed frame size in bytes.

Warning
You must set frame_size_ptr to the allocated size of the output buffer before calling avcodec_decode_audio3().
The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than the actual read bytes because some optimized bitstream readers read 32 or 64 bits at once and could read over the end.
The end of the input buffer avpkt->data should be set to 0 to ensure that no overreading happens for damaged MPEG streams.
You must not provide a custom get_buffer() when using avcodec_decode_audio3(). Doing so will override it with avcodec_default_get_buffer. Use avcodec_decode_audio4() instead, which does allow the application to provide a custom get_buffer().
Note
You might have to align the input buffer avpkt->data and output buffer samples. The alignment requirements depend on the CPU: On some CPUs it isn't necessary at all, on others it won't work at all if not aligned and on others it will work but it will have an impact on performance.

In practice, avpkt->data should have 4 byte alignment at minimum and samples should be 16 byte aligned unless the CPU doesn't need it (AltiVec and SSE do).

Note
Codecs which have the CODEC_CAP_DELAY capability set have a delay between input and output, these need to be fed with avpkt->data=NULL, avpkt->size=0 at the end to return the remaining frames.
Parameters
avctxthe codec context
[out]samplesthe output buffer, sample type in avctx->sample_fmt If the sample format is planar, each channel plane will be the same size, with no padding between channels.
[in,out]frame_size_ptrthe output buffer size in bytes
[in]avpktThe input AVPacket containing the input buffer. You can create such packet with av_init_packet() and by then setting data and size, some decoders might in addition need other fields. All decoders are designed to use the least fields possible though.
Returns
On error a negative value is returned, otherwise the number of bytes used or zero if no frame data was decompressed (used) from the input AVPacket.

Definition at line 2430 of file utils.c.

int avcodec_decode_audio4 ( AVCodecContext avctx,
AVFrame frame,
int *  got_frame_ptr,
const AVPacket avpkt 
)

Decode the audio frame of size avpkt->size from avpkt->data into frame.

Some decoders may support multiple frames in a single AVPacket. Such decoders would then just decode the first frame and the return value would be less than the packet size. In this case, avcodec_decode_audio4 has to be called again with an AVPacket containing the remaining data in order to decode the second frame, etc... Even if no frames are returned, the packet needs to be fed to the decoder with remaining data until it is completely consumed or an error occurs.

Some decoders (those marked with CODEC_CAP_DELAY) have a delay between input and output. This means that for some packets they will not immediately produce decoded output and need to be flushed at the end of decoding to get all the decoded data. Flushing is done by calling this function with packets with avpkt->data set to NULL and avpkt->size set to 0 until it stops returning samples. It is safe to flush even those decoders that are not marked with CODEC_CAP_DELAY, then no samples will be returned.

Warning
The input buffer, avpkt->data must be FF_INPUT_BUFFER_PADDING_SIZE larger than the actual read bytes because some optimized bitstream readers read 32 or 64 bits at once and could read over the end.
Note
The AVCodecContext MUST have been opened with avcodec_open2() before packets may be fed to the decoder.
Parameters
avctxthe codec context
[out]frameThe AVFrame in which to store decoded audio samples. The decoder will allocate a buffer for the decoded frame by calling the AVCodecContext.get_buffer2() callback. When AVCodecContext.refcounted_frames is set to 1, the frame is reference counted and the returned reference belongs to the caller. The caller must release the frame using av_frame_unref() when the frame is no longer needed. The caller may safely write to the frame if av_frame_is_writable() returns 1. When AVCodecContext.refcounted_frames is set to 0, the returned reference belongs to the decoder and is valid only until the next call to this function or until closing or flushing the decoder. The caller may not write to it.
[out]got_frame_ptrZero if no frame could be decoded, otherwise it is non-zero. Note that this field being set to zero does not mean that an error has occurred. For decoders with CODEC_CAP_DELAY set, no given decode call is guaranteed to produce a frame.
[in]avpktThe input AVPacket containing the input buffer. At least avpkt->data and avpkt->size should be set. Some decoders might also require additional fields to be set.
Returns
A negative error code is returned if an error occurred during decoding, otherwise the number of bytes consumed from the input AVPacket is returned.
Examples:
decoding_encoding.c, demuxing_decoding.c, filtering_audio.c, transcode_aac.c, and transcoding.c.

Definition at line 2482 of file utils.c.

Referenced by audio_decode_example(), avcodec_decode_audio3(), decode_audio(), decode_audio_frame(), decode_packet(), decoder_decode_frame(), main(), movie_push_frame(), process_frame(), try_decode_frame(), and wrap().

int avcodec_decode_video2 ( AVCodecContext avctx,
AVFrame picture,
int *  got_picture_ptr,
const AVPacket avpkt 
)

Decode the video frame of size avpkt->size from avpkt->data into picture.

Some decoders may support multiple frames in a single AVPacket, such decoders would then just decode the first frame.

Warning
The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than the actual read bytes because some optimized bitstream readers read 32 or 64 bits at once and could read over the end.
The end of the input buffer buf should be set to 0 to ensure that no overreading happens for damaged MPEG streams.
Note
Codecs which have the CODEC_CAP_DELAY capability set have a delay between input and output, these need to be fed with avpkt->data=NULL, avpkt->size=0 at the end to return the remaining frames.
The AVCodecContext MUST have been opened with avcodec_open2() before packets may be fed to the decoder.
Parameters
avctxthe codec context
[out]pictureThe AVFrame in which the decoded video frame will be stored. Use av_frame_alloc() to get an AVFrame. The codec will allocate memory for the actual bitmap by calling the AVCodecContext.get_buffer2() callback. When AVCodecContext.refcounted_frames is set to 1, the frame is reference counted and the returned reference belongs to the caller. The caller must release the frame using av_frame_unref() when the frame is no longer needed. The caller may safely write to the frame if av_frame_is_writable() returns 1. When AVCodecContext.refcounted_frames is set to 0, the returned reference belongs to the decoder and is valid only until the next call to this function or until closing or flushing the decoder. The caller may not write to it.
[in]avpktThe input AVPacket containing the input buffer. You can create such packet with av_init_packet() and by then setting data and size, some decoders might in addition need other fields like flags&AV_PKT_FLAG_KEY. All decoders are designed to use the least fields possible.
[in,out]got_picture_ptrZero if no frame could be decompressed, otherwise, it is nonzero.
Returns
On error a negative value is returned, otherwise the number of bytes used or zero if no frame could be decompressed.
Examples:
decoding_encoding.c, demuxing_decoding.c, filtering_video.c, qsvdec.c, and transcoding.c.

Definition at line 2336 of file utils.c.

Referenced by decode_packet(), decode_video(), decode_write_frame(), decoder_decode_frame(), ff_load_image(), main(), movie_push_frame(), process_frame(), smvjpeg_decode_frame(), try_decode_frame(), and wrap().

int avcodec_decode_subtitle2 ( AVCodecContext avctx,
AVSubtitle sub,
int *  got_sub_ptr,
AVPacket avpkt 
)

Decode a subtitle message.

Return a negative value on error, otherwise return the number of bytes used. If no subtitle could be decompressed, got_sub_ptr is zero. Otherwise, the subtitle is stored in *sub. Note that CODEC_CAP_DR1 is not available for subtitle codecs. This is for simplicity, because the performance difference is expect to be negligible and reusing a get_buffer written for video codecs would probably perform badly due to a potentially very different allocation pattern.

Some decoders (those marked with CODEC_CAP_DELAY) have a delay between input and output. This means that for some packets they will not immediately produce decoded output and need to be flushed at the end of decoding to get all the decoded data. Flushing is done by calling this function with packets with avpkt->data set to NULL and avpkt->size set to 0 until it stops returning subtitles. It is safe to flush even those decoders that are not marked with CODEC_CAP_DELAY, then no subtitles will be returned.

Note
The AVCodecContext MUST have been opened with avcodec_open2() before packets may be fed to the decoder.
Parameters
avctxthe codec context
[out]subThe Preallocated AVSubtitle in which the decoded subtitle will be stored, must be freed with avsubtitle_free if *got_sub_ptr is set.
[in,out]got_sub_ptrZero if no subtitle could be decompressed, otherwise, it is nonzero.
[in]avpktThe input AVPacket containing the input buffer.

Definition at line 2713 of file utils.c.

Referenced by decoder_decode_frame(), process_frame(), transcode_subtitles(), try_decode_frame(), and wrap().