123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525 |
- @chapter Bitstream Filters
- @c man begin BITSTREAM FILTERS
- When you configure your FFmpeg build, all the supported bitstream
- filters are enabled by default. You can list all available ones using
- the configure option @code{--list-bsfs}.
- You can disable all the bitstream filters using the configure option
- @code{--disable-bsfs}, and selectively enable any bitstream filter using
- the option @code{--enable-bsf=BSF}, or you can disable a particular
- bitstream filter using the option @code{--disable-bsf=BSF}.
- The option @code{-bsfs} of the ff* tools will display the list of
- all the supported bitstream filters included in your build.
- The ff* tools have a -bsf option applied per stream, taking a
- comma-separated list of filters, whose parameters follow the filter
- name after a '='.
- @example
- ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT
- @end example
- Below is a description of the currently available bitstream filters,
- with their parameters, if any.
- @section aac_adtstoasc
- Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration
- bitstream.
- This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4
- ADTS header and removes the ADTS header.
- This filter is required for example when copying an AAC stream from a
- raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or
- to MOV/MP4 files and related formats such as 3GP or M4A. Please note
- that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats.
- @section chomp
- Remove zero padding at the end of a packet.
- @section dca_core
- Extract the core from a DCA/DTS stream, dropping extensions such as
- DTS-HD.
- @section dump_extra
- Add extradata to the beginning of the filtered packets.
- @table @option
- @item freq
- The additional argument specifies which packets should be filtered.
- It accepts the values:
- @table @samp
- @item k
- @item keyframe
- add extradata to all key packets
- @item e
- @item all
- add extradata to all packets
- @end table
- @end table
- If not specified it is assumed @samp{e}.
- For example the following @command{ffmpeg} command forces a global
- header (thus disabling individual packet headers) in the H.264 packets
- generated by the @code{libx264} encoder, but corrects them by adding
- the header stored in extradata to the key packets:
- @example
- ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts
- @end example
- @section eac3_core
- Extract the core from a E-AC-3 stream, dropping extra channels.
- @section extract_extradata
- Extract the in-band extradata.
- Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers,
- or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part
- of the bitstream containing the coded frames) or "out of band" (e.g. on the
- container level). This latter form is called "extradata" in FFmpeg terminology.
- This bitstream filter detects the in-band headers and makes them available as
- extradata.
- @table @option
- @item remove
- When this option is enabled, the long-term headers are removed from the
- bitstream after extraction.
- @end table
- @section filter_units
- Remove units with types in or not in a given set from the stream.
- @table @option
- @item pass_types
- List of unit types or ranges of unit types to pass through while removing
- all others. This is specified as a '|'-separated list of unit type values
- or ranges of values with '-'.
- @item remove_types
- Identical to @option{pass_types}, except the units in the given set
- removed and all others passed through.
- @end table
- Extradata is unchanged by this transformation, but note that if the stream
- contains inline parameter sets then the output may be unusable if they are
- removed.
- For example, to remove all non-VCL NAL units from an H.264 stream:
- @example
- ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT
- @end example
- To remove all AUDs, SEI and filler from an H.265 stream:
- @example
- ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT
- @end example
- @section hapqa_extract
- Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file.
- @table @option
- @item texture
- Specifies the texture to keep.
- @table @option
- @item color
- @item alpha
- @end table
- @end table
- Convert HAPQA to HAPQ
- @example
- ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov
- @end example
- Convert HAPQA to HAPAlphaOnly
- @example
- ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=alpha -tag:v HapA -metadata:s:v:0 encoder="HAPAlpha Only" hapalphaonly_file.mov
- @end example
- @section h264_metadata
- Modify metadata embedded in an H.264 stream.
- @table @option
- @item aud
- Insert or remove AUD NAL units in all access units of the stream.
- @table @samp
- @item insert
- @item remove
- @end table
- @item sample_aspect_ratio
- Set the sample aspect ratio of the stream in the VUI parameters.
- @item video_format
- @item video_full_range_flag
- Set the video format in the stream (see H.264 section E.2.1 and
- table E-2).
- @item colour_primaries
- @item transfer_characteristics
- @item matrix_coefficients
- Set the colour description in the stream (see H.264 section E.2.1
- and tables E-3, E-4 and E-5).
- @item chroma_sample_loc_type
- Set the chroma sample location in the stream (see H.264 section
- E.2.1 and figure E-1).
- @item tick_rate
- Set the tick rate (num_units_in_tick / time_scale) in the VUI
- parameters. This is the smallest time unit representable in the
- stream, and in many cases represents the field rate of the stream
- (double the frame rate).
- @item fixed_frame_rate_flag
- Set whether the stream has fixed framerate - typically this indicates
- that the framerate is exactly half the tick rate, but the exact
- meaning is dependent on interlacing and the picture structure (see
- H.264 section E.2.1 and table E-6).
- @item crop_left
- @item crop_right
- @item crop_top
- @item crop_bottom
- Set the frame cropping offsets in the SPS. These values will replace
- the current ones if the stream is already cropped.
- These fields are set in pixels. Note that some sizes may not be
- representable if the chroma is subsampled or the stream is interlaced
- (see H.264 section 7.4.2.1.1).
- @item sei_user_data
- Insert a string as SEI unregistered user data. The argument must
- be of the form @emph{UUID+string}, where the UUID is as hex digits
- possibly separated by hyphens, and the string can be anything.
- For example, @samp{086f3693-b7b3-4f2c-9653-21492feee5b8+hello} will
- insert the string ``hello'' associated with the given UUID.
- @item delete_filler
- Deletes both filler NAL units and filler SEI messages.
- @end table
- @section h264_mp4toannexb
- Convert an H.264 bitstream from length prefixed mode to start code
- prefixed mode (as defined in the Annex B of the ITU-T H.264
- specification).
- This is required by some streaming formats, typically the MPEG-2
- transport stream format (muxer @code{mpegts}).
- For example to remux an MP4 file containing an H.264 stream to mpegts
- format with @command{ffmpeg}, you can use the command:
- @example
- ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
- @end example
- Please note that this filter is auto-inserted for MPEG-TS (muxer
- @code{mpegts}) and raw H.264 (muxer @code{h264}) output formats.
- @section h264_redundant_pps
- This applies a specific fixup to some Blu-ray streams which contain
- redundant PPSs modifying irrelevant parameters of the stream which
- confuse other transformations which require correct extradata.
- A new single global PPS is created, and all of the redundant PPSs
- within the stream are removed.
- @section hevc_metadata
- Modify metadata embedded in an HEVC stream.
- @table @option
- @item aud
- Insert or remove AUD NAL units in all access units of the stream.
- @table @samp
- @item insert
- @item remove
- @end table
- @item sample_aspect_ratio
- Set the sample aspect ratio in the stream in the VUI parameters.
- @item video_format
- @item video_full_range_flag
- Set the video format in the stream (see H.265 section E.3.1 and
- table E.2).
- @item colour_primaries
- @item transfer_characteristics
- @item matrix_coefficients
- Set the colour description in the stream (see H.265 section E.3.1
- and tables E.3, E.4 and E.5).
- @item chroma_sample_loc_type
- Set the chroma sample location in the stream (see H.265 section
- E.3.1 and figure E.1).
- @item tick_rate
- Set the tick rate in the VPS and VUI parameters (num_units_in_tick /
- time_scale). Combined with @option{num_ticks_poc_diff_one}, this can
- set a constant framerate in the stream. Note that it is likely to be
- overridden by container parameters when the stream is in a container.
- @item num_ticks_poc_diff_one
- Set poc_proportional_to_timing_flag in VPS and VUI and use this value
- to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and
- E.3.1). Ignored if @option{tick_rate} is not also set.
- @item crop_left
- @item crop_right
- @item crop_top
- @item crop_bottom
- Set the conformance window cropping offsets in the SPS. These values
- will replace the current ones if the stream is already cropped.
- These fields are set in pixels. Note that some sizes may not be
- representable if the chroma is subsampled (H.265 section 7.4.3.2.1).
- @end table
- @section hevc_mp4toannexb
- Convert an HEVC/H.265 bitstream from length prefixed mode to start code
- prefixed mode (as defined in the Annex B of the ITU-T H.265
- specification).
- This is required by some streaming formats, typically the MPEG-2
- transport stream format (muxer @code{mpegts}).
- For example to remux an MP4 file containing an HEVC stream to mpegts
- format with @command{ffmpeg}, you can use the command:
- @example
- ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
- @end example
- Please note that this filter is auto-inserted for MPEG-TS (muxer
- @code{mpegts}) and raw HEVC/H.265 (muxer @code{h265} or
- @code{hevc}) output formats.
- @section imxdump
- Modifies the bitstream to fit in MOV and to be usable by the Final Cut
- Pro decoder. This filter only applies to the mpeg2video codec, and is
- likely not needed for Final Cut Pro 7 and newer with the appropriate
- @option{-tag:v}.
- For example, to remux 30 MB/sec NTSC IMX to MOV:
- @example
- ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
- @end example
- @section mjpeg2jpeg
- Convert MJPEG/AVI1 packets to full JPEG/JFIF packets.
- MJPEG is a video codec wherein each video frame is essentially a
- JPEG image. The individual frames can be extracted without loss,
- e.g. by
- @example
- ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
- @end example
- Unfortunately, these chunks are incomplete JPEG images, because
- they lack the DHT segment required for decoding. Quoting from
- @url{http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml}:
- Avery Lee, writing in the rec.video.desktop newsgroup in 2001,
- commented that "MJPEG, or at least the MJPEG in AVIs having the
- MJPG fourcc, is restricted JPEG with a fixed -- and *omitted* --
- Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2,
- and it must use basic Huffman encoding, not arithmetic or
- progressive. . . . You can indeed extract the MJPEG frames and
- decode them with a regular JPEG decoder, but you have to prepend
- the DHT segment to them, or else the decoder won't have any idea
- how to decompress the data. The exact table necessary is given in
- the OpenDML spec."
- This bitstream filter patches the header of frames extracted from an MJPEG
- stream (carrying the AVI1 header ID and lacking a DHT segment) to
- produce fully qualified JPEG images.
- @example
- ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
- exiftran -i -9 frame*.jpg
- ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
- @end example
- @section mjpegadump
- Add an MJPEG A header to the bitstream, to enable decoding by
- Quicktime.
- @anchor{mov2textsub}
- @section mov2textsub
- Extract a representable text file from MOV subtitles, stripping the
- metadata header from each subtitle packet.
- See also the @ref{text2movsub} filter.
- @section mp3decomp
- Decompress non-standard compressed MP3 audio headers.
- @section mpeg2_metadata
- Modify metadata embedded in an MPEG-2 stream.
- @table @option
- @item display_aspect_ratio
- Set the display aspect ratio in the stream.
- The following fixed values are supported:
- @table @option
- @item 4/3
- @item 16/9
- @item 221/100
- @end table
- Any other value will result in square pixels being signalled instead
- (see H.262 section 6.3.3 and table 6-3).
- @item frame_rate
- Set the frame rate in the stream. This is constructed from a table
- of known values combined with a small multiplier and divisor - if
- the supplied value is not exactly representable, the nearest
- representable value will be used instead (see H.262 section 6.3.3
- and table 6-4).
- @item video_format
- Set the video format in the stream (see H.262 section 6.3.6 and
- table 6-6).
- @item colour_primaries
- @item transfer_characteristics
- @item matrix_coefficients
- Set the colour description in the stream (see H.262 section 6.3.6
- and tables 6-7, 6-8 and 6-9).
- @end table
- @section mpeg4_unpack_bframes
- Unpack DivX-style packed B-frames.
- DivX-style packed B-frames are not valid MPEG-4 and were only a
- workaround for the broken Video for Windows subsystem.
- They use more space, can cause minor AV sync issues, require more
- CPU power to decode (unless the player has some decoded picture queue
- to compensate the 2,0,2,0 frame per packet style) and cause
- trouble if copied into a standard container like mp4 or mpeg-ps/ts,
- because MPEG-4 decoders may not be able to decode them, since they are
- not valid MPEG-4.
- For example to fix an AVI file containing an MPEG-4 stream with
- DivX-style packed B-frames using @command{ffmpeg}, you can use the command:
- @example
- ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
- @end example
- @section noise
- Damages the contents of packets or simply drops them without damaging the
- container. Can be used for fuzzing or testing error resilience/concealment.
- Parameters:
- @table @option
- @item amount
- A numeral string, whose value is related to how often output bytes will
- be modified. Therefore, values below or equal to 0 are forbidden, and
- the lower the more frequent bytes will be modified, with 1 meaning
- every byte is modified.
- @item dropamount
- A numeral string, whose value is related to how often packets will be dropped.
- Therefore, values below or equal to 0 are forbidden, and the lower the more
- frequent packets will be dropped, with 1 meaning every packet is dropped.
- @end table
- The following example applies the modification to every byte but does not drop
- any packets.
- @example
- ffmpeg -i INPUT -c copy -bsf noise[=1] output.mkv
- @end example
- @section null
- This bitstream filter passes the packets through unchanged.
- @section remove_extra
- Remove extradata from packets.
- It accepts the following parameter:
- @table @option
- @item freq
- Set which frame types to remove extradata from.
- @table @samp
- @item k
- Remove extradata from non-keyframes only.
- @item keyframe
- Remove extradata from keyframes only.
- @item e, all
- Remove extradata from all frames.
- @end table
- @end table
- @anchor{text2movsub}
- @section text2movsub
- Convert text subtitles to MOV subtitles (as used by the @code{mov_text}
- codec) with metadata headers.
- See also the @ref{mov2textsub} filter.
- @section trace_headers
- Log trace output containing all syntax elements in the coded stream
- headers (everything above the level of individual coded blocks).
- This can be useful for debugging low-level stream issues.
- Supports H.264, H.265 and MPEG-2.
- @section vp9_superframe
- Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This
- fixes merging of split/segmented VP9 streams where the alt-ref frame
- was split from its visible counterpart.
- @section vp9_superframe_split
- Split VP9 superframes into single frames.
- @section vp9_raw_reorder
- Given a VP9 stream with correct timestamps but possibly out of order,
- insert additional show-existing-frame packets to correct the ordering.
- @c man end BITSTREAM FILTERS
|