2f3cecde66e83f44dfb5ec72e984e92f8c63d74e
[ffmpeg.git] / doc / encoders.texi
1 @chapter Encoders
2 @c man begin ENCODERS
3
4 Encoders are configured elements in Libav which allow the encoding of
5 multimedia streams.
6
7 When you configure your Libav build, all the supported native encoders
8 are enabled by default. Encoders requiring an external library must be enabled
9 manually via the corresponding @code{--enable-lib} option. You can list all
10 available encoders using the configure option @code{--list-encoders}.
11
12 You can disable all the encoders with the configure option
13 @code{--disable-encoders} and selectively enable / disable single encoders
14 with the options @code{--enable-encoder=@var{ENCODER}} /
15 @code{--disable-encoder=@var{ENCODER}}.
16
17 The option @code{-codecs} of the ff* tools will display the list of
18 enabled encoders.
19
20 A description of some of the currently available encoders follows.
21
22 @section Audio Encoders
23
24 @subsection ac3 and ac3_fixed
25
26 AC-3 audio encoders.
27
28 These encoders implement part of ATSC A/52:2010 and ETSI TS 102 366, as well as
29 the undocumented RealAudio 3 (a.k.a. dnet).
30
31 The @var{ac3} encoder uses floating-point math, while the @var{ac3_fixed}
32 encoder only uses fixed-point integer math. This does not mean that one is
33 always faster, just that one or the other may be better suited to a
34 particular system. The floating-point encoder will generally produce better
35 quality audio for a given bitrate. The @var{ac3_fixed} encoder is not the
36 default codec for any of the output formats, so it must be specified explicitly
37 using the option @code{-acodec ac3_fixed} in order to use it.
38
39 @subheading AC-3 Metadata
40
41 The AC-3 metadata options are used to set parameters that describe the audio,
42 but in most cases do not affect the audio encoding itself. Some of the options
43 do directly affect or influence the decoding and playback of the resulting
44 bitstream, while others are just for informational purposes. A few of the
45 options will add bits to the output stream that could otherwise be used for
46 audio data, and will thus affect the quality of the output. Those will be
47 indicated accordingly with a note in the option list below.
48
49 These parameters are described in detail in several publicly-available
50 documents.
51 @itemize
52 @item @uref{http://www.atsc.org/cms/standards/a_52-2010.pdf,A/52:2010 - Digital Audio Compression (AC-3) (E-AC-3) Standard}
53 @item @uref{http://www.atsc.org/cms/standards/a_54a_with_corr_1.pdf,A/54 - Guide to the Use of the ATSC Digital Television Standard}
54 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/18_Metadata.Guide.pdf,Dolby Metadata Guide}
55 @item @uref{http://www.dolby.com/uploadedFiles/zz-_Shared_Assets/English_PDFs/Professional/46_DDEncodingGuidelines.pdf,Dolby Digital Professional Encoding Guidelines}
56 @end itemize
57
58 @subsubheading Metadata Control Options
59
60 @table @option
61
62 @item -per_frame_metadata @var{boolean}
63 Allow Per-Frame Metadata. Specifies if the encoder should check for changing
64 metadata for each frame.
65 @table @option
66 @item 0
67 The metadata values set at initialization will be used for every frame in the
68 stream. (default)
69 @item 1
70 Metadata values can be changed before encoding each frame.
71 @end table
72
73 @end table
74
75 @subsubheading Downmix Levels
76
77 @table @option
78
79 @item -center_mixlev @var{level}
80 Center Mix Level. The amount of gain the decoder should apply to the center
81 channel when downmixing to stereo. This field will only be written to the
82 bitstream if a center channel is present. The value is specified as a scale
83 factor. There are 3 valid values:
84 @table @option
85 @item 0.707
86 Apply -3dB gain
87 @item 0.595
88 Apply -4.5dB gain (default)
89 @item 0.500
90 Apply -6dB gain
91 @end table
92
93 @item -surround_mixlev @var{level}
94 Surround Mix Level. The amount of gain the decoder should apply to the surround
95 channel(s) when downmixing to stereo. This field will only be written to the
96 bitstream if one or more surround channels are present. The value is specified
97 as a scale factor.  There are 3 valid values:
98 @table @option
99 @item 0.707
100 Apply -3dB gain
101 @item 0.500
102 Apply -6dB gain (default)
103 @item 0.000
104 Silence Surround Channel(s)
105 @end table
106
107 @end table
108
109 @subsubheading Audio Production Information
110 Audio Production Information is optional information describing the mixing
111 environment.  Either none or both of the fields are written to the bitstream.
112
113 @table @option
114
115 @item -mixing_level @var{number}
116 Mixing Level. Specifies peak sound pressure level (SPL) in the production
117 environment when the mix was mastered. Valid values are 80 to 111, or -1 for
118 unknown or not indicated. The default value is -1, but that value cannot be
119 used if the Audio Production Information is written to the bitstream. Therefore,
120 if the @code{room_type} option is not the default value, the @code{mixing_level}
121 option must not be -1.
122
123 @item -room_type @var{type}
124 Room Type. Describes the equalization used during the final mixing session at
125 the studio or on the dubbing stage. A large room is a dubbing stage with the
126 industry standard X-curve equalization; a small room has flat equalization.
127 This field will not be written to the bitstream if both the @code{mixing_level}
128 option and the @code{room_type} option have the default values.
129 @table @option
130 @item 0
131 @itemx notindicated
132 Not Indicated (default)
133 @item 1
134 @itemx large
135 Large Room
136 @item 2
137 @itemx small
138 Small Room
139 @end table
140
141 @end table
142
143 @subsubheading Other Metadata Options
144
145 @table @option
146
147 @item -copyright @var{boolean}
148 Copyright Indicator. Specifies whether a copyright exists for this audio.
149 @table @option
150 @item 0
151 @itemx off
152 No Copyright Exists (default)
153 @item 1
154 @itemx on
155 Copyright Exists
156 @end table
157
158 @item -dialnorm @var{value}
159 Dialogue Normalization. Indicates how far the average dialogue level of the
160 program is below digital 100% full scale (0 dBFS). This parameter determines a
161 level shift during audio reproduction that sets the average volume of the
162 dialogue to a preset level. The goal is to match volume level between program
163 sources. A value of -31dB will result in no volume level change, relative to
164 the source volume, during audio reproduction. Valid values are whole numbers in
165 the range -31 to -1, with -31 being the default.
166
167 @item -dsur_mode @var{mode}
168 Dolby Surround Mode. Specifies whether the stereo signal uses Dolby Surround
169 (Pro Logic). This field will only be written to the bitstream if the audio
170 stream is stereo. Using this option does @b{NOT} mean the encoder will actually
171 apply Dolby Surround processing.
172 @table @option
173 @item 0
174 @itemx notindicated
175 Not Indicated (default)
176 @item 1
177 @itemx off
178 Not Dolby Surround Encoded
179 @item 2
180 @itemx on
181 Dolby Surround Encoded
182 @end table
183
184 @item -original @var{boolean}
185 Original Bit Stream Indicator. Specifies whether this audio is from the
186 original source and not a copy.
187 @table @option
188 @item 0
189 @itemx off
190 Not Original Source
191 @item 1
192 @itemx on
193 Original Source (default)
194 @end table
195
196 @end table
197
198 @subsubheading Extended Bitstream Information
199 The extended bitstream options are part of the Alternate Bit Stream Syntax as
200 specified in Annex D of the A/52:2010 standard. It is grouped into 2 parts.
201 If any one parameter in a group is specified, all values in that group will be
202 written to the bitstream.  Default values are used for those that are written
203 but have not been specified.  If the mixing levels are written, the decoder
204 will use these values instead of the ones specified in the @code{center_mixlev}
205 and @code{surround_mixlev} options if it supports the Alternate Bit Stream
206 Syntax.
207
208 @subsubheading Extended Bitstream Information - Part 1
209
210 @table @option
211
212 @item -dmix_mode @var{mode}
213 Preferred Stereo Downmix Mode. Allows the user to select either Lt/Rt
214 (Dolby Surround) or Lo/Ro (normal stereo) as the preferred stereo downmix mode.
215 @table @option
216 @item 0
217 @itemx notindicated
218 Not Indicated (default)
219 @item 1
220 @itemx ltrt
221 Lt/Rt Downmix Preferred
222 @item 2
223 @itemx loro
224 Lo/Ro Downmix Preferred
225 @end table
226
227 @item -ltrt_cmixlev @var{level}
228 Lt/Rt Center Mix Level. The amount of gain the decoder should apply to the
229 center channel when downmixing to stereo in Lt/Rt mode.
230 @table @option
231 @item 1.414
232 Apply +3dB gain
233 @item 1.189
234 Apply +1.5dB gain
235 @item 1.000
236 Apply 0dB gain
237 @item 0.841
238 Apply -1.5dB gain
239 @item 0.707
240 Apply -3.0dB gain
241 @item 0.595
242 Apply -4.5dB gain (default)
243 @item 0.500
244 Apply -6.0dB gain
245 @item 0.000
246 Silence Center Channel
247 @end table
248
249 @item -ltrt_surmixlev @var{level}
250 Lt/Rt Surround Mix Level. The amount of gain the decoder should apply to the
251 surround channel(s) when downmixing to stereo in Lt/Rt mode.
252 @table @option
253 @item 0.841
254 Apply -1.5dB gain
255 @item 0.707
256 Apply -3.0dB gain
257 @item 0.595
258 Apply -4.5dB gain
259 @item 0.500
260 Apply -6.0dB gain (default)
261 @item 0.000
262 Silence Surround Channel(s)
263 @end table
264
265 @item -loro_cmixlev @var{level}
266 Lo/Ro Center Mix Level. The amount of gain the decoder should apply to the
267 center channel when downmixing to stereo in Lo/Ro mode.
268 @table @option
269 @item 1.414
270 Apply +3dB gain
271 @item 1.189
272 Apply +1.5dB gain
273 @item 1.000
274 Apply 0dB gain
275 @item 0.841
276 Apply -1.5dB gain
277 @item 0.707
278 Apply -3.0dB gain
279 @item 0.595
280 Apply -4.5dB gain (default)
281 @item 0.500
282 Apply -6.0dB gain
283 @item 0.000
284 Silence Center Channel
285 @end table
286
287 @item -loro_surmixlev @var{level}
288 Lo/Ro Surround Mix Level. The amount of gain the decoder should apply to the
289 surround channel(s) when downmixing to stereo in Lo/Ro mode.
290 @table @option
291 @item 0.841
292 Apply -1.5dB gain
293 @item 0.707
294 Apply -3.0dB gain
295 @item 0.595
296 Apply -4.5dB gain
297 @item 0.500
298 Apply -6.0dB gain (default)
299 @item 0.000
300 Silence Surround Channel(s)
301 @end table
302
303 @end table
304
305 @subsubheading Extended Bitstream Information - Part 2
306
307 @table @option
308
309 @item -dsurex_mode @var{mode}
310 Dolby Surround EX Mode. Indicates whether the stream uses Dolby Surround EX
311 (7.1 matrixed to 5.1). Using this option does @b{NOT} mean the encoder will actually
312 apply Dolby Surround EX processing.
313 @table @option
314 @item 0
315 @itemx notindicated
316 Not Indicated (default)
317 @item 1
318 @itemx on
319 Dolby Surround EX On
320 @item 2
321 @itemx off
322 Dolby Surround EX Off
323 @end table
324
325 @item -dheadphone_mode @var{mode}
326 Dolby Headphone Mode. Indicates whether the stream uses Dolby Headphone
327 encoding (multi-channel matrixed to 2.0 for use with headphones). Using this
328 option does @b{NOT} mean the encoder will actually apply Dolby Headphone
329 processing.
330 @table @option
331 @item 0
332 @itemx notindicated
333 Not Indicated (default)
334 @item 1
335 @itemx on
336 Dolby Headphone On
337 @item 2
338 @itemx off
339 Dolby Headphone Off
340 @end table
341
342 @item -ad_conv_type @var{type}
343 A/D Converter Type. Indicates whether the audio has passed through HDCD A/D
344 conversion.
345 @table @option
346 @item 0
347 @itemx standard
348 Standard A/D Converter (default)
349 @item 1
350 @itemx hdcd
351 HDCD A/D Converter
352 @end table
353
354 @end table
355
356 @subheading Other AC-3 Encoding Options
357
358 @table @option
359
360 @item -stereo_rematrixing @var{boolean}
361 Stereo Rematrixing. Enables/Disables use of rematrixing for stereo input. This
362 is an optional AC-3 feature that increases quality by selectively encoding
363 the left/right channels as mid/side. This option is enabled by default, and it
364 is highly recommended that it be left as enabled except for testing purposes.
365
366 @end table
367
368 @c man end ENCODERS