avformat: add support to force specific AVCodecs
[ffmpeg.git] / doc / resampler.texi
1 @chapter Resampler Options
2 @c man begin RESAMPLER OPTIONS
3
4 The audio resampler supports the following named options.
5
6 Options may be set by specifying -@var{option} @var{value} in the
7 FFmpeg tools, @var{option}=@var{value} for the aresample filter,
8 by setting the value explicitly in the
9 @code{SwrContext} options or using the @file{libavutil/opt.h} API for
10 programmatic use.
11
12 @table @option
13
14 @item ich, in_channel_count
15 Set the number of input channels. Default value is 0. Setting this
16 value is not mandatory if the corresponding channel layout
17 @option{in_channel_layout} is set.
18
19 @item och, out_channel_count
20 Set the number of output channels. Default value is 0. Setting this
21 value is not mandatory if the corresponding channel layout
22 @option{out_channel_layout} is set.
23
24 @item uch, used_channel_count
25 Set the number of used input channels. Default value is 0. This option is
26 only used for special remapping.
27
28 @item isr, in_sample_rate
29 Set the input sample rate. Default value is 0.
30
31 @item osr, out_sample_rate
32 Set the output sample rate. Default value is 0.
33
34 @item isf, in_sample_fmt
35 Specify the input sample format. It is set by default to @code{none}.
36
37 @item osf, out_sample_fmt
38 Specify the output sample format. It is set by default to @code{none}.
39
40 @item tsf, internal_sample_fmt
41 Set the internal sample format. Default value is @code{none}.
42 This will automatically be chosen when it is not explicitly set.
43
44 @item icl, in_channel_layout
45 Set the input channel layout.
46
47 @item ocl, out_channel_layout
48 Set the output channel layout.
49
50 @item clev, center_mix_level
51 Set the center mix level. It is a value expressed in deciBel, and must be
52 in the interval [-32,32].
53
54 @item slev, surround_mix_level
55 Set the surround mix level. It is a value expressed in deciBel, and must
56 be in the interval [-32,32].
57
58 @item lfe_mix_level
59 Set LFE mix into non LFE level. It is used when there is a LFE input but no
60 LFE output. It is a value expressed in deciBel, and must
61 be in the interval [-32,32].
62
63 @item rmvol, rematrix_volume
64 Set rematrix volume. Default value is 1.0.
65
66 @item rematrix_maxval
67 Set maximum output value for rematrixing.
68 This can be used to prevent clipping vs. preventing volumn reduction
69 A value of 1.0 prevents cliping.
70
71 @item flags, swr_flags
72 Set flags used by the converter. Default value is 0.
73
74 It supports the following individual flags:
75 @table @option
76 @item res
77 force resampling, this flag forces resampling to be used even when the
78 input and output sample rates match.
79 @end table
80
81 @item dither_scale
82 Set the dither scale. Default value is 1.
83
84 @item dither_method
85 Set dither method. Default value is 0.
86
87 Supported values:
88 @table @samp
89 @item rectangular
90 select rectangular dither
91 @item triangular
92 select triangular dither
93 @item triangular_hp
94 select triangular dither with high pass
95 @item lipshitz
96 select lipshitz noise shaping dither
97 @item shibata
98 select shibata noise shaping dither
99 @item low_shibata
100 select low shibata noise shaping dither
101 @item high_shibata
102 select high shibata noise shaping dither
103 @item f_weighted
104 select f-weighted noise shaping dither
105 @item modified_e_weighted
106 select modified-e-weighted noise shaping dither
107 @item improved_e_weighted
108 select improved-e-weighted noise shaping dither
109
110 @end table
111
112 @item resampler
113 Set resampling engine. Default value is swr.
114
115 Supported values:
116 @table @samp
117 @item swr
118 select the native SW Resampler; filter options precision and cheby are not
119 applicable in this case.
120 @item soxr
121 select the SoX Resampler (where available); compensation, and filter options
122 filter_size, phase_shift, filter_type & kaiser_beta, are not applicable in this
123 case.
124 @end table
125
126 @item filter_size
127 For swr only, set resampling filter size, default value is 32.
128
129 @item phase_shift
130 For swr only, set resampling phase shift, default value is 10, and must be in
131 the interval [0,30].
132
133 @item linear_interp
134 Use Linear Interpolation if set to 1, default value is 0.
135
136 @item cutoff
137 Set cutoff frequency (swr: 6dB point; soxr: 0dB point) ratio; must be a float
138 value between 0 and 1.  Default value is 0.97 with swr, and 0.91 with soxr
139 (which, with a sample-rate of 44100, preserves the entire audio band to 20kHz).
140
141 @item precision
142 For soxr only, the precision in bits to which the resampled signal will be
143 calculated.  The default value of 20 (which, with suitable dithering, is
144 appropriate for a destination bit-depth of 16) gives SoX's 'High Quality'; a
145 value of 28 gives SoX's 'Very High Quality'.
146
147 @item cheby
148 For soxr only, selects passband rolloff none (Chebyshev) & higher-precision
149 approximation for 'irrational' ratios. Default value is 0.
150
151 @item async
152 For swr only, simple 1 parameter audio sync to timestamps using stretching,
153 squeezing, filling and trimming. Setting this to 1 will enable filling and
154 trimming, larger values represent the maximum amount in samples that the data
155 may be stretched or squeezed for each second.
156 Default value is 0, thus no compensation is applied to make the samples match
157 the audio timestamps.
158
159 @item first_pts
160 For swr only, assume the first pts should be this value. The time unit is 1 / sample rate.
161 This allows for padding/trimming at the start of stream. By default, no
162 assumption is made about the first frame's expected pts, so no padding or
163 trimming is done. For example, this could be set to 0 to pad the beginning with
164 silence if an audio stream starts after the video stream or to trim any samples
165 with a negative pts due to encoder delay.
166
167 @item min_comp
168 For swr only, set the minimum difference between timestamps and audio data (in
169 seconds) to trigger stretching/squeezing/filling or trimming of the
170 data to make it match the timestamps. The default is that
171 stretching/squeezing/filling and trimming is disabled
172 (@option{min_comp} = @code{FLT_MAX}).
173
174 @item min_hard_comp
175 For swr only, set the minimum difference between timestamps and audio data (in
176 seconds) to trigger adding/dropping samples to make it match the
177 timestamps.  This option effectively is a threshold to select between
178 hard (trim/fill) and soft (squeeze/stretch) compensation. Note that
179 all compensation is by default disabled through @option{min_comp}.
180 The default is 0.1.
181
182 @item comp_duration
183 For swr only, set duration (in seconds) over which data is stretched/squeezed
184 to make it match the timestamps. Must be a non-negative double float value,
185 default value is 1.0.
186
187 @item max_soft_comp
188 For swr only, set maximum factor by which data is stretched/squeezed to make it
189 match the timestamps. Must be a non-negative double float value, default value
190 is 0.
191
192 @item matrix_encoding
193 Select matrixed stereo encoding.
194
195 It accepts the following values:
196 @table @samp
197 @item none
198 select none
199 @item dolby
200 select Dolby
201 @item dplii
202 select Dolby Pro Logic II
203 @end table
204
205 Default value is @code{none}.
206
207 @item filter_type
208 For swr only, select resampling filter type. This only affects resampling
209 operations.
210
211 It accepts the following values:
212 @table @samp
213 @item cubic
214 select cubic
215 @item blackman_nuttall
216 select Blackman Nuttall Windowed Sinc
217 @item kaiser
218 select Kaiser Windowed Sinc
219 @end table
220
221 @item kaiser_beta
222 For swr only, set Kaiser Window Beta value. Must be an integer in the
223 interval [2,16], default value is 9.
224
225 @item output_sample_bits
226 For swr only, set number of used output sample bits for dithering. Must be an integer in the
227 interval [0,64], default value is 0, which means it's not used.
228
229 @end table
230
231 @c man end RESAMPLER OPTIONS