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