doc: fix incorrect reference to xsd_compliant option
[ffmpeg.git] / doc / bitstream_filters.texi
index 58ebddd..7d7e975 100644 (file)
@@ -13,42 +13,59 @@ 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.
 
-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 MPEG-4 Audio Specific Configuration
-bitstream filter.
+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 is required for example when copying an AAC stream from a raw
-ADTS AAC container to a FLV or a MOV/MP4 file.
+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 a
-add extradata to all key packets, but only if @var{local_header} is
-set in the @option{flags2} codec context field
-
 @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{k}.
+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
@@ -58,6 +75,148 @@ the header stored in extradata to the key packets:
 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
@@ -65,7 +224,7 @@ 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 ("mpegts").
+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:
@@ -74,6 +233,92 @@ format with @command{ffmpeg}, you can use the command:
 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
@@ -124,21 +369,183 @@ exiftran -i -9 frame*.jpg
 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
 
-@section movsub
+Decompress non-standard compressed MP3 audio headers.
 
-@section mp3_header_decompress
+@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 without damaging the container. Can be
-used for fuzzing or testing error resilience/concealment.
+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 output.mkv
+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, MPEG-2 and VP9.
+
+@section vp9_metadata
+
+Modify metadata embedded in a VP9 stream.
+
+@table @option
+@item color_space
+Set the color space value in the frame header.
+@table @samp
+@item unknown
+@item bt601
+@item bt709
+@item smpte170
+@item smpte240
+@item bt2020
+@item rgb
+@end table
+
+@item color_range
+Set the color range value in the frame header.  Note that this cannot
+be set in RGB streams.
+@table @samp
+@item tv
+@item pc
+@end table
+@end table
+
+@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