h264_metadata: Add option to set the level of the stream
[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 @item level
219 Set the level in the SPS.  Refer to H.264 section A.3 and tables A-1
220 to A-5.
221
222 The argument must be the name of a level (for example, @samp{4.2}), a
223 level_idc value (for example, @samp{42}), or the special name @samp{auto}
224 indicating that the filter should attempt to guess the level from the
225 input stream properties.
226
227 @end table
228
229 @section h264_mp4toannexb
230
231 Convert an H.264 bitstream from length prefixed mode to start code
232 prefixed mode (as defined in the Annex B of the ITU-T H.264
233 specification).
234
235 This is required by some streaming formats, typically the MPEG-2
236 transport stream format (muxer @code{mpegts}).
237
238 For example to remux an MP4 file containing an H.264 stream to mpegts
239 format with @command{ffmpeg}, you can use the command:
240
241 @example
242 ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts
243 @end example
244
245 Please note that this filter is auto-inserted for MPEG-TS (muxer
246 @code{mpegts}) and raw H.264 (muxer @code{h264}) output formats.
247
248 @section h264_redundant_pps
249
250 This applies a specific fixup to some Blu-ray streams which contain
251 redundant PPSs modifying irrelevant parameters of the stream which
252 confuse other transformations which require correct extradata.
253
254 A new single global PPS is created, and all of the redundant PPSs
255 within the stream are removed.
256
257 @section hevc_metadata
258
259 Modify metadata embedded in an HEVC stream.
260
261 @table @option
262 @item aud
263 Insert or remove AUD NAL units in all access units of the stream.
264
265 @table @samp
266 @item insert
267 @item remove
268 @end table
269
270 @item sample_aspect_ratio
271 Set the sample aspect ratio in the stream in the VUI parameters.
272
273 @item video_format
274 @item video_full_range_flag
275 Set the video format in the stream (see H.265 section E.3.1 and
276 table E.2).
277
278 @item colour_primaries
279 @item transfer_characteristics
280 @item matrix_coefficients
281 Set the colour description in the stream (see H.265 section E.3.1
282 and tables E.3, E.4 and E.5).
283
284 @item chroma_sample_loc_type
285 Set the chroma sample location in the stream (see H.265 section
286 E.3.1 and figure E.1).
287
288 @item tick_rate
289 Set the tick rate in the VPS and VUI parameters (num_units_in_tick /
290 time_scale).  Combined with @option{num_ticks_poc_diff_one}, this can
291 set a constant framerate in the stream.  Note that it is likely to be
292 overridden by container parameters when the stream is in a container.
293
294 @item num_ticks_poc_diff_one
295 Set poc_proportional_to_timing_flag in VPS and VUI and use this value
296 to set num_ticks_poc_diff_one_minus1 (see H.265 sections 7.4.3.1 and
297 E.3.1).  Ignored if @option{tick_rate} is not also set.
298
299 @item crop_left
300 @item crop_right
301 @item crop_top
302 @item crop_bottom
303 Set the conformance window cropping offsets in the SPS.  These values
304 will replace the current ones if the stream is already cropped.
305
306 These fields are set in pixels.  Note that some sizes may not be
307 representable if the chroma is subsampled (H.265 section 7.4.3.2.1).
308
309 @end table
310
311 @section hevc_mp4toannexb
312
313 Convert an HEVC/H.265 bitstream from length prefixed mode to start code
314 prefixed mode (as defined in the Annex B of the ITU-T H.265
315 specification).
316
317 This is required by some streaming formats, typically the MPEG-2
318 transport stream format (muxer @code{mpegts}).
319
320 For example to remux an MP4 file containing an HEVC stream to mpegts
321 format with @command{ffmpeg}, you can use the command:
322
323 @example
324 ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts
325 @end example
326
327 Please note that this filter is auto-inserted for MPEG-TS (muxer
328 @code{mpegts}) and raw HEVC/H.265 (muxer @code{h265} or
329 @code{hevc}) output formats.
330
331 @section imxdump
332
333 Modifies the bitstream to fit in MOV and to be usable by the Final Cut
334 Pro decoder. This filter only applies to the mpeg2video codec, and is
335 likely not needed for Final Cut Pro 7 and newer with the appropriate
336 @option{-tag:v}.
337
338 For example, to remux 30 MB/sec NTSC IMX to MOV:
339
340 @example
341 ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov
342 @end example
343
344 @section mjpeg2jpeg
345
346 Convert MJPEG/AVI1 packets to full JPEG/JFIF packets.
347
348 MJPEG is a video codec wherein each video frame is essentially a
349 JPEG image. The individual frames can be extracted without loss,
350 e.g. by
351
352 @example
353 ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg
354 @end example
355
356 Unfortunately, these chunks are incomplete JPEG images, because
357 they lack the DHT segment required for decoding. Quoting from
358 @url{http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml}:
359
360 Avery Lee, writing in the rec.video.desktop newsgroup in 2001,
361 commented that "MJPEG, or at least the MJPEG in AVIs having the
362 MJPG fourcc, is restricted JPEG with a fixed -- and *omitted* --
363 Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2,
364 and it must use basic Huffman encoding, not arithmetic or
365 progressive. . . . You can indeed extract the MJPEG frames and
366 decode them with a regular JPEG decoder, but you have to prepend
367 the DHT segment to them, or else the decoder won't have any idea
368 how to decompress the data. The exact table necessary is given in
369 the OpenDML spec."
370
371 This bitstream filter patches the header of frames extracted from an MJPEG
372 stream (carrying the AVI1 header ID and lacking a DHT segment) to
373 produce fully qualified JPEG images.
374
375 @example
376 ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg
377 exiftran -i -9 frame*.jpg
378 ffmpeg -i frame_%d.jpg -c:v copy rotated.avi
379 @end example
380
381 @section mjpegadump
382
383 Add an MJPEG A header to the bitstream, to enable decoding by
384 Quicktime.
385
386 @anchor{mov2textsub}
387 @section mov2textsub
388
389 Extract a representable text file from MOV subtitles, stripping the
390 metadata header from each subtitle packet.
391
392 See also the @ref{text2movsub} filter.
393
394 @section mp3decomp
395
396 Decompress non-standard compressed MP3 audio headers.
397
398 @section mpeg2_metadata
399
400 Modify metadata embedded in an MPEG-2 stream.
401
402 @table @option
403 @item display_aspect_ratio
404 Set the display aspect ratio in the stream.
405
406 The following fixed values are supported:
407 @table @option
408 @item 4/3
409 @item 16/9
410 @item 221/100
411 @end table
412 Any other value will result in square pixels being signalled instead
413 (see H.262 section 6.3.3 and table 6-3).
414
415 @item frame_rate
416 Set the frame rate in the stream.  This is constructed from a table
417 of known values combined with a small multiplier and divisor - if
418 the supplied value is not exactly representable, the nearest
419 representable value will be used instead (see H.262 section 6.3.3
420 and table 6-4).
421
422 @item video_format
423 Set the video format in the stream (see H.262 section 6.3.6 and
424 table 6-6).
425
426 @item colour_primaries
427 @item transfer_characteristics
428 @item matrix_coefficients
429 Set the colour description in the stream (see H.262 section 6.3.6
430 and tables 6-7, 6-8 and 6-9).
431
432 @end table
433
434 @section mpeg4_unpack_bframes
435
436 Unpack DivX-style packed B-frames.
437
438 DivX-style packed B-frames are not valid MPEG-4 and were only a
439 workaround for the broken Video for Windows subsystem.
440 They use more space, can cause minor AV sync issues, require more
441 CPU power to decode (unless the player has some decoded picture queue
442 to compensate the 2,0,2,0 frame per packet style) and cause
443 trouble if copied into a standard container like mp4 or mpeg-ps/ts,
444 because MPEG-4 decoders may not be able to decode them, since they are
445 not valid MPEG-4.
446
447 For example to fix an AVI file containing an MPEG-4 stream with
448 DivX-style packed B-frames using @command{ffmpeg}, you can use the command:
449
450 @example
451 ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi
452 @end example
453
454 @section noise
455
456 Damages the contents of packets or simply drops them without damaging the
457 container. Can be used for fuzzing or testing error resilience/concealment.
458
459 Parameters:
460 @table @option
461 @item amount
462 A numeral string, whose value is related to how often output bytes will
463 be modified. Therefore, values below or equal to 0 are forbidden, and
464 the lower the more frequent bytes will be modified, with 1 meaning
465 every byte is modified.
466 @item dropamount
467 A numeral string, whose value is related to how often packets will be dropped.
468 Therefore, values below or equal to 0 are forbidden, and the lower the more
469 frequent packets will be dropped, with 1 meaning every packet is dropped.
470 @end table
471
472 The following example applies the modification to every byte but does not drop
473 any packets.
474 @example
475 ffmpeg -i INPUT -c copy -bsf noise[=1] output.mkv
476 @end example
477
478 @section null
479 This bitstream filter passes the packets through unchanged.
480
481 @section remove_extra
482
483 Remove extradata from packets.
484
485 It accepts the following parameter:
486 @table @option
487 @item freq
488 Set which frame types to remove extradata from.
489
490 @table @samp
491 @item k
492 Remove extradata from non-keyframes only.
493
494 @item keyframe
495 Remove extradata from keyframes only.
496
497 @item e, all
498 Remove extradata from all frames.
499
500 @end table
501 @end table
502
503 @anchor{text2movsub}
504 @section text2movsub
505
506 Convert text subtitles to MOV subtitles (as used by the @code{mov_text}
507 codec) with metadata headers.
508
509 See also the @ref{mov2textsub} filter.
510
511 @section trace_headers
512
513 Log trace output containing all syntax elements in the coded stream
514 headers (everything above the level of individual coded blocks).
515 This can be useful for debugging low-level stream issues.
516
517 Supports H.264, H.265, MPEG-2 and VP9.
518
519 @section vp9_metadata
520
521 Modify metadata embedded in a VP9 stream.
522
523 @table @option
524 @item color_space
525 Set the color space value in the frame header.
526 @table @samp
527 @item unknown
528 @item bt601
529 @item bt709
530 @item smpte170
531 @item smpte240
532 @item bt2020
533 @item rgb
534 @end table
535
536 @item color_range
537 Set the color range value in the frame header.  Note that this cannot
538 be set in RGB streams.
539 @table @samp
540 @item tv
541 @item pc
542 @end table
543 @end table
544
545 @section vp9_superframe
546
547 Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This
548 fixes merging of split/segmented VP9 streams where the alt-ref frame
549 was split from its visible counterpart.
550
551 @section vp9_superframe_split
552
553 Split VP9 superframes into single frames.
554
555 @section vp9_raw_reorder
556
557 Given a VP9 stream with correct timestamps but possibly out of order,
558 insert additional show-existing-frame packets to correct the ordering.
559
560 @c man end BITSTREAM FILTERS