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