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