1@chapter Bitstream Filters 2@c man begin BITSTREAM FILTERS 3 4When you configure your FFmpeg build, all the supported bitstream 5filters are enabled by default. You can list all available ones using 6the configure option @code{--list-bsfs}. 7 8You can disable all the bitstream filters using the configure option 9@code{--disable-bsfs}, and selectively enable any bitstream filter using 10the option @code{--enable-bsf=BSF}, or you can disable a particular 11bitstream filter using the option @code{--disable-bsf=BSF}. 12 13The option @code{-bsfs} of the ff* tools will display the list of 14all the supported bitstream filters included in your build. 15 16The ff* tools have a -bsf option applied per stream, taking a 17comma-separated list of filters, whose parameters follow the filter 18name after a '='. 19 20@example 21ffmpeg -i INPUT -c:v copy -bsf:v filter1[=opt1=str1:opt2=str2][,filter2] OUTPUT 22@end example 23 24Below is a description of the currently available bitstream filters, 25with their parameters, if any. 26 27@section aac_adtstoasc 28 29Convert MPEG-2/4 AAC ADTS to an MPEG-4 Audio Specific Configuration 30bitstream. 31 32This filter creates an MPEG-4 AudioSpecificConfig from an MPEG-2/4 33ADTS header and removes the ADTS header. 34 35This filter is required for example when copying an AAC stream from a 36raw ADTS AAC or an MPEG-TS container to MP4A-LATM, to an FLV file, or 37to MOV/MP4 files and related formats such as 3GP or M4A. Please note 38that it is auto-inserted for MP4A-LATM and MOV/MP4 and related formats. 39 40@section av1_metadata 41 42Modify metadata embedded in an AV1 stream. 43 44@table @option 45@item td 46Insert or remove temporal delimiter OBUs in all temporal units of the 47stream. 48 49@table @samp 50@item insert 51Insert a TD at the beginning of every TU which does not already have one. 52@item remove 53Remove the TD from the beginning of every TU which has one. 54@end table 55 56@item color_primaries 57@item transfer_characteristics 58@item matrix_coefficients 59Set the color description fields in the stream (see AV1 section 6.4.2). 60 61@item color_range 62Set the color range in the stream (see AV1 section 6.4.2; note that 63this cannot be set for streams using BT.709 primaries, sRGB transfer 64characteristic and identity (RGB) matrix coefficients). 65@table @samp 66@item tv 67Limited range. 68@item pc 69Full range. 70@end table 71 72@item chroma_sample_position 73Set the chroma sample location in the stream (see AV1 section 6.4.2). 74This can only be set for 4:2:0 streams. 75 76@table @samp 77@item vertical 78Left position (matching the default in MPEG-2 and H.264). 79@item colocated 80Top-left position. 81@end table 82 83@item tick_rate 84Set the tick rate (@emph{num_units_in_display_tick / time_scale}) in 85the timing info in the sequence header. 86@item num_ticks_per_picture 87Set the number of ticks in each picture, to indicate that the stream 88has a fixed framerate. Ignored if @option{tick_rate} is not also set. 89 90@end table 91 92@section chomp 93 94Remove zero padding at the end of a packet. 95 96@section dca_core 97 98Extract the core from a DCA/DTS stream, dropping extensions such as 99DTS-HD. 100 101@section dump_extra 102 103Add extradata to the beginning of the filtered packets. 104 105@table @option 106@item freq 107The additional argument specifies which packets should be filtered. 108It accepts the values: 109@table @samp 110@item k 111@item keyframe 112add extradata to all key packets 113 114@item e 115@item all 116add extradata to all packets 117@end table 118@end table 119 120If not specified it is assumed @samp{e}. 121 122For example the following @command{ffmpeg} command forces a global 123header (thus disabling individual packet headers) in the H.264 packets 124generated by the @code{libx264} encoder, but corrects them by adding 125the header stored in extradata to the key packets: 126@example 127ffmpeg -i INPUT -map 0 -flags:v +global_header -c:v libx264 -bsf:v dump_extra out.ts 128@end example 129 130@section eac3_core 131 132Extract the core from a E-AC-3 stream, dropping extra channels. 133 134@section extract_extradata 135 136Extract the in-band extradata. 137 138Certain codecs allow the long-term headers (e.g. MPEG-2 sequence headers, 139or H.264/HEVC (VPS/)SPS/PPS) to be transmitted either "in-band" (i.e. as a part 140of the bitstream containing the coded frames) or "out of band" (e.g. on the 141container level). This latter form is called "extradata" in FFmpeg terminology. 142 143This bitstream filter detects the in-band headers and makes them available as 144extradata. 145 146@table @option 147@item remove 148When this option is enabled, the long-term headers are removed from the 149bitstream after extraction. 150@end table 151 152@section filter_units 153 154Remove units with types in or not in a given set from the stream. 155 156@table @option 157@item pass_types 158List of unit types or ranges of unit types to pass through while removing 159all others. This is specified as a '|'-separated list of unit type values 160or ranges of values with '-'. 161 162@item remove_types 163Identical to @option{pass_types}, except the units in the given set 164removed and all others passed through. 165@end table 166 167Extradata is unchanged by this transformation, but note that if the stream 168contains inline parameter sets then the output may be unusable if they are 169removed. 170 171For example, to remove all non-VCL NAL units from an H.264 stream: 172@example 173ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=pass_types=1-5' OUTPUT 174@end example 175 176To remove all AUDs, SEI and filler from an H.265 stream: 177@example 178ffmpeg -i INPUT -c:v copy -bsf:v 'filter_units=remove_types=35|38-40' OUTPUT 179@end example 180 181@section hapqa_extract 182 183Extract Rgb or Alpha part of an HAPQA file, without recompression, in order to create an HAPQ or an HAPAlphaOnly file. 184 185@table @option 186@item texture 187Specifies the texture to keep. 188 189@table @option 190@item color 191@item alpha 192@end table 193 194@end table 195 196Convert HAPQA to HAPQ 197@example 198ffmpeg -i hapqa_inputfile.mov -c copy -bsf:v hapqa_extract=texture=color -tag:v HapY -metadata:s:v:0 encoder="HAPQ" hapq_file.mov 199@end example 200 201Convert HAPQA to HAPAlphaOnly 202@example 203ffmpeg -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 204@end example 205 206@section h264_metadata 207 208Modify metadata embedded in an H.264 stream. 209 210@table @option 211@item aud 212Insert or remove AUD NAL units in all access units of the stream. 213 214@table @samp 215@item insert 216@item remove 217@end table 218 219@item sample_aspect_ratio 220Set the sample aspect ratio of the stream in the VUI parameters. 221 222@item video_format 223@item video_full_range_flag 224Set the video format in the stream (see H.264 section E.2.1 and 225table E-2). 226 227@item colour_primaries 228@item transfer_characteristics 229@item matrix_coefficients 230Set the colour description in the stream (see H.264 section E.2.1 231and tables E-3, E-4 and E-5). 232 233@item chroma_sample_loc_type 234Set the chroma sample location in the stream (see H.264 section 235E.2.1 and figure E-1). 236 237@item tick_rate 238Set the tick rate (num_units_in_tick / time_scale) in the VUI 239parameters. This is the smallest time unit representable in the 240stream, and in many cases represents the field rate of the stream 241(double the frame rate). 242@item fixed_frame_rate_flag 243Set whether the stream has fixed framerate - typically this indicates 244that the framerate is exactly half the tick rate, but the exact 245meaning is dependent on interlacing and the picture structure (see 246H.264 section E.2.1 and table E-6). 247 248@item crop_left 249@item crop_right 250@item crop_top 251@item crop_bottom 252Set the frame cropping offsets in the SPS. These values will replace 253the current ones if the stream is already cropped. 254 255These fields are set in pixels. Note that some sizes may not be 256representable if the chroma is subsampled or the stream is interlaced 257(see H.264 section 7.4.2.1.1). 258 259@item sei_user_data 260Insert a string as SEI unregistered user data. The argument must 261be of the form @emph{UUID+string}, where the UUID is as hex digits 262possibly separated by hyphens, and the string can be anything. 263 264For example, @samp{086f3693-b7b3-4f2c-9653-21492feee5b8+hello} will 265insert the string ``hello'' associated with the given UUID. 266 267@item delete_filler 268Deletes both filler NAL units and filler SEI messages. 269 270@item level 271Set the level in the SPS. Refer to H.264 section A.3 and tables A-1 272to A-5. 273 274The argument must be the name of a level (for example, @samp{4.2}), a 275level_idc value (for example, @samp{42}), or the special name @samp{auto} 276indicating that the filter should attempt to guess the level from the 277input stream properties. 278 279@end table 280 281@section h264_mp4toannexb 282 283Convert an H.264 bitstream from length prefixed mode to start code 284prefixed mode (as defined in the Annex B of the ITU-T H.264 285specification). 286 287This is required by some streaming formats, typically the MPEG-2 288transport stream format (muxer @code{mpegts}). 289 290For example to remux an MP4 file containing an H.264 stream to mpegts 291format with @command{ffmpeg}, you can use the command: 292 293@example 294ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts 295@end example 296 297Please note that this filter is auto-inserted for MPEG-TS (muxer 298@code{mpegts}) and raw H.264 (muxer @code{h264}) output formats. 299 300@section h264_redundant_pps 301 302This applies a specific fixup to some Blu-ray streams which contain 303redundant PPSs modifying irrelevant parameters of the stream which 304confuse other transformations which require correct extradata. 305 306A new single global PPS is created, and all of the redundant PPSs 307within the stream are removed. 308 309@section hevc_metadata 310 311Modify metadata embedded in an HEVC stream. 312 313@table @option 314@item aud 315Insert or remove AUD NAL units in all access units of the stream. 316 317@table @samp 318@item insert 319@item remove 320@end table 321 322@item sample_aspect_ratio 323Set the sample aspect ratio in the stream in the VUI parameters. 324 325@item video_format 326@item video_full_range_flag 327Set the video format in the stream (see H.265 section E.3.1 and 328table E.2). 329 330@item colour_primaries 331@item transfer_characteristics 332@item matrix_coefficients 333Set the colour description in the stream (see H.265 section E.3.1 334and tables E.3, E.4 and E.5). 335 336@item chroma_sample_loc_type 337Set the chroma sample location in the stream (see H.265 section 338E.3.1 and figure E.1). 339 340@item tick_rate 341Set the tick rate in the VPS and VUI parameters (num_units_in_tick / 342time_scale). Combined with @option{num_ticks_poc_diff_one}, this can 343set a constant framerate in the stream. Note that it is likely to be 344overridden by container parameters when the stream is in a container. 345 346@item num_ticks_poc_diff_one 347Set poc_proportional_to_timing_flag in VPS and VUI and use this value 348to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and 349E.3.1). Ignored if @option{tick_rate} is not also set. 350 351@item crop_left 352@item crop_right 353@item crop_top 354@item crop_bottom 355Set the conformance window cropping offsets in the SPS. These values 356will replace the current ones if the stream is already cropped. 357 358These fields are set in pixels. Note that some sizes may not be 359representable if the chroma is subsampled (H.265 section 7.4.3.2.1). 360 361@end table 362 363@section hevc_mp4toannexb 364 365Convert an HEVC/H.265 bitstream from length prefixed mode to start code 366prefixed mode (as defined in the Annex B of the ITU-T H.265 367specification). 368 369This is required by some streaming formats, typically the MPEG-2 370transport stream format (muxer @code{mpegts}). 371 372For example to remux an MP4 file containing an HEVC stream to mpegts 373format with @command{ffmpeg}, you can use the command: 374 375@example 376ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts 377@end example 378 379Please note that this filter is auto-inserted for MPEG-TS (muxer 380@code{mpegts}) and raw HEVC/H.265 (muxer @code{h265} or 381@code{hevc}) output formats. 382 383@section imxdump 384 385Modifies the bitstream to fit in MOV and to be usable by the Final Cut 386Pro decoder. This filter only applies to the mpeg2video codec, and is 387likely not needed for Final Cut Pro 7 and newer with the appropriate 388@option{-tag:v}. 389 390For example, to remux 30 MB/sec NTSC IMX to MOV: 391 392@example 393ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov 394@end example 395 396@section mjpeg2jpeg 397 398Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. 399 400MJPEG is a video codec wherein each video frame is essentially a 401JPEG image. The individual frames can be extracted without loss, 402e.g. by 403 404@example 405ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg 406@end example 407 408Unfortunately, these chunks are incomplete JPEG images, because 409they lack the DHT segment required for decoding. Quoting from 410@url{http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml}: 411 412Avery Lee, writing in the rec.video.desktop newsgroup in 2001, 413commented that "MJPEG, or at least the MJPEG in AVIs having the 414MJPG fourcc, is restricted JPEG with a fixed -- and *omitted* -- 415Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, 416and it must use basic Huffman encoding, not arithmetic or 417progressive. . . . You can indeed extract the MJPEG frames and 418decode them with a regular JPEG decoder, but you have to prepend 419the DHT segment to them, or else the decoder won't have any idea 420how to decompress the data. The exact table necessary is given in 421the OpenDML spec." 422 423This bitstream filter patches the header of frames extracted from an MJPEG 424stream (carrying the AVI1 header ID and lacking a DHT segment) to 425produce fully qualified JPEG images. 426 427@example 428ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg 429exiftran -i -9 frame*.jpg 430ffmpeg -i frame_%d.jpg -c:v copy rotated.avi 431@end example 432 433@section mjpegadump 434 435Add an MJPEG A header to the bitstream, to enable decoding by 436Quicktime. 437 438@anchor{mov2textsub} 439@section mov2textsub 440 441Extract a representable text file from MOV subtitles, stripping the 442metadata header from each subtitle packet. 443 444See also the @ref{text2movsub} filter. 445 446@section mp3decomp 447 448Decompress non-standard compressed MP3 audio headers. 449 450@section mpeg2_metadata 451 452Modify metadata embedded in an MPEG-2 stream. 453 454@table @option 455@item display_aspect_ratio 456Set the display aspect ratio in the stream. 457 458The following fixed values are supported: 459@table @option 460@item 4/3 461@item 16/9 462@item 221/100 463@end table 464Any other value will result in square pixels being signalled instead 465(see H.262 section 6.3.3 and table 6-3). 466 467@item frame_rate 468Set the frame rate in the stream. This is constructed from a table 469of known values combined with a small multiplier and divisor - if 470the supplied value is not exactly representable, the nearest 471representable value will be used instead (see H.262 section 6.3.3 472and table 6-4). 473 474@item video_format 475Set the video format in the stream (see H.262 section 6.3.6 and 476table 6-6). 477 478@item colour_primaries 479@item transfer_characteristics 480@item matrix_coefficients 481Set the colour description in the stream (see H.262 section 6.3.6 482and tables 6-7, 6-8 and 6-9). 483 484@end table 485 486@section mpeg4_unpack_bframes 487 488Unpack DivX-style packed B-frames. 489 490DivX-style packed B-frames are not valid MPEG-4 and were only a 491workaround for the broken Video for Windows subsystem. 492They use more space, can cause minor AV sync issues, require more 493CPU power to decode (unless the player has some decoded picture queue 494to compensate the 2,0,2,0 frame per packet style) and cause 495trouble if copied into a standard container like mp4 or mpeg-ps/ts, 496because MPEG-4 decoders may not be able to decode them, since they are 497not valid MPEG-4. 498 499For example to fix an AVI file containing an MPEG-4 stream with 500DivX-style packed B-frames using @command{ffmpeg}, you can use the command: 501 502@example 503ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi 504@end example 505 506@section noise 507 508Damages the contents of packets or simply drops them without damaging the 509container. Can be used for fuzzing or testing error resilience/concealment. 510 511Parameters: 512@table @option 513@item amount 514A numeral string, whose value is related to how often output bytes will 515be modified. Therefore, values below or equal to 0 are forbidden, and 516the lower the more frequent bytes will be modified, with 1 meaning 517every byte is modified. 518@item dropamount 519A numeral string, whose value is related to how often packets will be dropped. 520Therefore, values below or equal to 0 are forbidden, and the lower the more 521frequent packets will be dropped, with 1 meaning every packet is dropped. 522@end table 523 524The following example applies the modification to every byte but does not drop 525any packets. 526@example 527ffmpeg -i INPUT -c copy -bsf noise[=1] output.mkv 528@end example 529 530@section null 531This bitstream filter passes the packets through unchanged. 532 533@section remove_extra 534 535Remove extradata from packets. 536 537It accepts the following parameter: 538@table @option 539@item freq 540Set which frame types to remove extradata from. 541 542@table @samp 543@item k 544Remove extradata from non-keyframes only. 545 546@item keyframe 547Remove extradata from keyframes only. 548 549@item e, all 550Remove extradata from all frames. 551 552@end table 553@end table 554 555@anchor{text2movsub} 556@section text2movsub 557 558Convert text subtitles to MOV subtitles (as used by the @code{mov_text} 559codec) with metadata headers. 560 561See also the @ref{mov2textsub} filter. 562 563@section trace_headers 564 565Log trace output containing all syntax elements in the coded stream 566headers (everything above the level of individual coded blocks). 567This can be useful for debugging low-level stream issues. 568 569Supports H.264, H.265, MPEG-2 and VP9. 570 571@section vp9_metadata 572 573Modify metadata embedded in a VP9 stream. 574 575@table @option 576@item color_space 577Set the color space value in the frame header. 578@table @samp 579@item unknown 580@item bt601 581@item bt709 582@item smpte170 583@item smpte240 584@item bt2020 585@item rgb 586@end table 587 588@item color_range 589Set the color range value in the frame header. Note that this cannot 590be set in RGB streams. 591@table @samp 592@item tv 593@item pc 594@end table 595@end table 596 597@section vp9_superframe 598 599Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This 600fixes merging of split/segmented VP9 streams where the alt-ref frame 601was split from its visible counterpart. 602 603@section vp9_superframe_split 604 605Split VP9 superframes into single frames. 606 607@section vp9_raw_reorder 608 609Given a VP9 stream with correct timestamps but possibly out of order, 610insert additional show-existing-frame packets to correct the ordering. 611 612@c man end BITSTREAM FILTERS 613