blob: 947c31dae84e417dbfabb2a7666cc5529423a9b4
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_mp4toannexb |
96 | |
97 | Convert an H.264 bitstream from length prefixed mode to start code |
98 | prefixed mode (as defined in the Annex B of the ITU-T H.264 |
99 | specification). |
100 | |
101 | This is required by some streaming formats, typically the MPEG-2 |
102 | transport stream format (muxer @code{mpegts}). |
103 | |
104 | For example to remux an MP4 file containing an H.264 stream to mpegts |
105 | format with @command{ffmpeg}, you can use the command: |
106 | |
107 | @example |
108 | ffmpeg -i INPUT.mp4 -codec copy -bsf:v h264_mp4toannexb OUTPUT.ts |
109 | @end example |
110 | |
111 | Please note that this filter is auto-inserted for MPEG-TS (muxer |
112 | @code{mpegts}) and raw H.264 (muxer @code{h264}) output formats. |
113 | |
114 | @section hevc_mp4toannexb |
115 | |
116 | Convert an HEVC/H.265 bitstream from length prefixed mode to start code |
117 | prefixed mode (as defined in the Annex B of the ITU-T H.265 |
118 | specification). |
119 | |
120 | This is required by some streaming formats, typically the MPEG-2 |
121 | transport stream format (muxer @code{mpegts}). |
122 | |
123 | For example to remux an MP4 file containing an HEVC stream to mpegts |
124 | format with @command{ffmpeg}, you can use the command: |
125 | |
126 | @example |
127 | ffmpeg -i INPUT.mp4 -codec copy -bsf:v hevc_mp4toannexb OUTPUT.ts |
128 | @end example |
129 | |
130 | Please note that this filter is auto-inserted for MPEG-TS (muxer |
131 | @code{mpegts}) and raw HEVC/H.265 (muxer @code{h265} or |
132 | @code{hevc}) output formats. |
133 | |
134 | @section imxdump |
135 | |
136 | Modifies the bitstream to fit in MOV and to be usable by the Final Cut |
137 | Pro decoder. This filter only applies to the mpeg2video codec, and is |
138 | likely not needed for Final Cut Pro 7 and newer with the appropriate |
139 | @option{-tag:v}. |
140 | |
141 | For example, to remux 30 MB/sec NTSC IMX to MOV: |
142 | |
143 | @example |
144 | ffmpeg -i input.mxf -c copy -bsf:v imxdump -tag:v mx3n output.mov |
145 | @end example |
146 | |
147 | @section mjpeg2jpeg |
148 | |
149 | Convert MJPEG/AVI1 packets to full JPEG/JFIF packets. |
150 | |
151 | MJPEG is a video codec wherein each video frame is essentially a |
152 | JPEG image. The individual frames can be extracted without loss, |
153 | e.g. by |
154 | |
155 | @example |
156 | ffmpeg -i ../some_mjpeg.avi -c:v copy frames_%d.jpg |
157 | @end example |
158 | |
159 | Unfortunately, these chunks are incomplete JPEG images, because |
160 | they lack the DHT segment required for decoding. Quoting from |
161 | @url{http://www.digitalpreservation.gov/formats/fdd/fdd000063.shtml}: |
162 | |
163 | Avery Lee, writing in the rec.video.desktop newsgroup in 2001, |
164 | commented that "MJPEG, or at least the MJPEG in AVIs having the |
165 | MJPG fourcc, is restricted JPEG with a fixed -- and *omitted* -- |
166 | Huffman table. The JPEG must be YCbCr colorspace, it must be 4:2:2, |
167 | and it must use basic Huffman encoding, not arithmetic or |
168 | progressive. . . . You can indeed extract the MJPEG frames and |
169 | decode them with a regular JPEG decoder, but you have to prepend |
170 | the DHT segment to them, or else the decoder won't have any idea |
171 | how to decompress the data. The exact table necessary is given in |
172 | the OpenDML spec." |
173 | |
174 | This bitstream filter patches the header of frames extracted from an MJPEG |
175 | stream (carrying the AVI1 header ID and lacking a DHT segment) to |
176 | produce fully qualified JPEG images. |
177 | |
178 | @example |
179 | ffmpeg -i mjpeg-movie.avi -c:v copy -bsf:v mjpeg2jpeg frame_%d.jpg |
180 | exiftran -i -9 frame*.jpg |
181 | ffmpeg -i frame_%d.jpg -c:v copy rotated.avi |
182 | @end example |
183 | |
184 | @section mjpegadump |
185 | |
186 | Add an MJPEG A header to the bitstream, to enable decoding by |
187 | Quicktime. |
188 | |
189 | @anchor{mov2textsub} |
190 | @section mov2textsub |
191 | |
192 | Extract a representable text file from MOV subtitles, stripping the |
193 | metadata header from each subtitle packet. |
194 | |
195 | See also the @ref{text2movsub} filter. |
196 | |
197 | @section mp3decomp |
198 | |
199 | Decompress non-standard compressed MP3 audio headers. |
200 | |
201 | @section mpeg4_unpack_bframes |
202 | |
203 | Unpack DivX-style packed B-frames. |
204 | |
205 | DivX-style packed B-frames are not valid MPEG-4 and were only a |
206 | workaround for the broken Video for Windows subsystem. |
207 | They use more space, can cause minor AV sync issues, require more |
208 | CPU power to decode (unless the player has some decoded picture queue |
209 | to compensate the 2,0,2,0 frame per packet style) and cause |
210 | trouble if copied into a standard container like mp4 or mpeg-ps/ts, |
211 | because MPEG-4 decoders may not be able to decode them, since they are |
212 | not valid MPEG-4. |
213 | |
214 | For example to fix an AVI file containing an MPEG-4 stream with |
215 | DivX-style packed B-frames using @command{ffmpeg}, you can use the command: |
216 | |
217 | @example |
218 | ffmpeg -i INPUT.avi -codec copy -bsf:v mpeg4_unpack_bframes OUTPUT.avi |
219 | @end example |
220 | |
221 | @section noise |
222 | |
223 | Damages the contents of packets without damaging the container. Can be |
224 | used for fuzzing or testing error resilience/concealment. |
225 | |
226 | Parameters: |
227 | A numeral string, whose value is related to how often output bytes will |
228 | be modified. Therefore, values below or equal to 0 are forbidden, and |
229 | the lower the more frequent bytes will be modified, with 1 meaning |
230 | every byte is modified. |
231 | |
232 | @example |
233 | ffmpeg -i INPUT -c copy -bsf noise[=1] output.mkv |
234 | @end example |
235 | applies the modification to every byte. |
236 | |
237 | @section remove_extra |
238 | |
239 | Remove extradata from packets. |
240 | |
241 | It accepts the following parameter: |
242 | @table @option |
243 | @item freq |
244 | Set which frame types to remove extradata from. |
245 | |
246 | @table @samp |
247 | @item k |
248 | Remove extradata from non-keyframes only. |
249 | |
250 | @item keyframe |
251 | Remove extradata from keyframes only. |
252 | |
253 | @item e, all |
254 | Remove extradata from all frames. |
255 | |
256 | @end table |
257 | @end table |
258 | |
259 | @anchor{text2movsub} |
260 | @section text2movsub |
261 | |
262 | Convert text subtitles to MOV subtitles (as used by the @code{mov_text} |
263 | codec) with metadata headers. |
264 | |
265 | See also the @ref{mov2textsub} filter. |
266 | |
267 | @section vp9_superframe |
268 | |
269 | Merge VP9 invisible (alt-ref) frames back into VP9 superframes. This |
270 | fixes merging of split/segmented VP9 streams where the alt-ref frame |
271 | was split from its visible counterpart. |
272 | |
273 | @c man end BITSTREAM FILTERS |
274 |