diff options
Diffstat (limited to 'doc/bitstream_filters.texi')
| -rw-r--r-- | doc/bitstream_filters.texi | 382 |
1 files changed, 367 insertions, 15 deletions
diff --git a/doc/bitstream_filters.texi b/doc/bitstream_filters.texi index 64f91f4b54..5efb8e0ee8 100644 --- a/doc/bitstream_filters.texi +++ b/doc/bitstream_filters.texi @@ -1,7 +1,7 @@ @chapter Bitstream Filters @c man begin BITSTREAM FILTERS -When you configure your Libav build, all the supported bitstream +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}. @@ -10,16 +10,69 @@ You can disable all the bitstream filters using the configure option 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 av* tools will display the list of +The option @code{-bsfs} of the ff* tools will display the list of all the supported bitstream filters included in your build. -Below is a description of the currently available bitstream filters. +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 -@section dump_extradata +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. + +The additional argument specifies which packets should be filtered. +It accepts the values: +@table @samp +@item a +add extradata to all key packets, but only if @var{local_header} is +set in the @option{flags2} codec context field + +@item k +add extradata to all key packets + +@item e +add extradata to all packets +@end table + +If not specified it is assumed @samp{k}. + +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 extract_extradata @@ -28,7 +81,7 @@ 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 Libav terminology. +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. @@ -39,9 +92,183 @@ When this option is enabled, the long-term headers are removed from the bitstream after extraction. @end table +@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. + +@end table + @section h264_mp4toannexb -@section imx_dump_header +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 @@ -52,7 +279,7 @@ JPEG image. The individual frames can be extracted without loss, e.g. by @example -avconv -i ../some_mjpeg.avi -c:v copy frames_%d.jpg +ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg @end example Unfortunately, these chunks are incomplete JPEG images, because @@ -75,29 +302,154 @@ stream (carrying the AVI1 header ID and lacking a DHT segment) to produce fully qualified JPEG images. @example -avconv -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg +ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg exiftran -i -9 frame*.jpg -avconv -i frame_%d.jpg -c:v copy rotated.avi +ffmpeg -i frame_%d.jpg -c:v copy rotated.avi @end example -@section mjpega_dump_header +@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 -@section movsub +Unpack DivX-style packed B-frames. -@section mp3_header_compress +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. -@section mp3_header_decompress +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_extradata +@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 -Combine VP9 frames into superframes. +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 |