compress: Document and sanity-check command line options.
[paraslash.git] / m4 / lls / filter_cmd.suite.m4
1 [suite filter_cmd]
2 caption = filters
3 [subcommand aacdec]
4 purpose = decode an aac stream
5 [subcommand amp]
6 purpose = amplify (scale) a raw audio stream
7 [option amp]
8 short_opt = a
9 summary = amplification value
10 typestr = number
11 arg_info = required_arg
12 arg_type = uint32
13 default_val = 32
14 [help]
15 The amplification value determines the scaling factor by which the
16 amplitude of the audio stream is multiplied. The formula for the
17 scaling factor is
18
19 factor = 1 + amp / 64.
20
21 For example, an amplification value of zero results in a scaling factor
22 of one while an amplification value of 64 means to double the volume.
23 [/help]
24 [subcommand compress]
25 purpose = dynamically adjust the volume of an audio stream
26 [option blocksize]
27 short_opt = b
28 summary = adjust volume after each block of size 2**bits (1-31)
29 typestr = bits
30 arg_info = required_arg
31 arg_type = uint32
32 default_val = 15
33 [help]
34 Larger blocksize means fewer volume adjustments per time unit.
35 [/help]
36 [option aggressiveness]
37 short_opt = a
38 summary = controls the maximum amount to amplify by (1-15)
39 typestr = bits
40 arg_info = required_arg
41 arg_type = uint32
42 default_val = 4
43 [help]
44 This caps the maximal gain factor to 2**bits. The sum of the arguments
45 to --aggressiveness and --inertia (see below) must not exceed 16.
46 [/help]
47 [option inertia]
48 short_opt = i
49 summary = how much inertia ramping has (1-15)
50 typestr = bits
51 arg_info = required_arg
52 arg_type = uint32
53 default_val = 6
54 [help]
55 Larger values cause smaller volume adjustments. See --aggressiveness
56 above.
57 [/help]
58 [option target-level]
59 short_opt = t
60 summary = target signal level (0-32767)
61 typestr = level
62 arg_info = required_arg
63 arg_type = uint32
64 default_val = 20000
65 [help]
66 If the peak of the previous block is less than the target level,
67 volume is increased slightly for the next block. Otherwise it is
68 decreased. The default value is chosen to minimize clipping. There
69 is usually no reason to change it.
70 [/help]
71 [option damp]
72 short_opt = d
73 summary = if non-zero, scale down after normalizing (0-16)
74 typestr = bits
75 arg_info = required_arg
76 arg_type = uint32
77 default_val = 0
78 [help]
79 This scales down the volume of the audio stream by factor 2**bits.
80 This is mostly useful if another audio application (e.g., a video
81 game) is running in parallel and the relative volume of the audio
82 stream is too high.
83 [/help]
84 [subcommand fecdec]
85 purpose = decode a (lossy) input stream using forward error correction
86 [subcommand flacdec]
87 purpose = decode a flac stream
88 [subcommand mp3dec]
89 purpose = decode an mp3 stream
90 [option ignore-crc]
91 short_opt = i
92 summary = ignore CRC information in the audio stream
93 [help]
94 This causes frames with CRC errors to be decoded and played
95 anyway. This option is not recommended, but since some encoders
96 have been known to generate bad CRC information, this option is a
97 work-around to play streams from such encoders.
98 [/help]
99 [subcommand oggdec]
100 purpose = decode an ogg/vorbis stream
101 [subcommand opusdec]
102 purpose = decode an ogg/opus stream
103 [subcommand prebuffer]
104 purpose = delay processing of an audio stream
105 [option duration]
106 short_opt = d
107 summary = length of the prebuffer period
108 typestr = milliseconds
109 arg_info = required_arg
110 arg_type = uint32
111 default_val = 200
112 [help]
113 Wait this many milliseconds before letting data go through. The time
114 interval starts when the first data byte is seen in the input queue.
115 [/help]
116 [option size]
117 short_opt = s
118 summary = amount of data to prebuffer
119 typestr = bytes
120 arg_info = required_arg
121 arg_type = uint32
122 default_val = 0
123 [help]
124 Wait until this many data bytes are available in the input queue. The
125 default value of zero means to not prebuffer by size. If both
126 --duration and --size are given and non-zero, the prebuffer filter
127 waits until both conditions are met.
128 [/help]
129 [subcommand resample]
130 purpose = transform raw audio to a different sample rate
131 [option converter]
132 short_opt = C
133 summary = set conversion algorithm
134 typestr = type
135 arg_info = required_arg
136 arg_type = string
137 values = {
138 # RCT: resample conversion type
139 RCT_BEST = "best",
140 RCT_MEDIUM = "medium",
141 RCT_FASTEST = "fastest",
142 RCT_ZERO_ORDER_HOLD = "zero_order_hold",
143 RCT_LINEAR = "linear"
144 }
145 default_val = medium
146 [help]
147 best: This is a bandlimited interpolator derived from the mathematical
148 sinc function and this is the highest quality sinc based converter,
149 providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels
150 (dB) at a bandwidth of 97%.
151
152 medium: This is another bandlimited interpolator much like the previous
153 one. It has an SNR of 97dB and a bandwidth of 90%. The speed of the
154 conversion is much faster than the previous one.
155
156 fastest: This is the fastest bandlimited interpolator and has an SNR
157 of 97dB and a bandwidth of 80%.
158
159 zero_order_hold: A Zero Order Hold converter (interpolated value
160 is equal to the last value). The quality is poor but the conversion
161 speed is blindlingly fast.
162
163 linear: A linear converter. Again the quality is poor, but the
164 conversion speed is blindingly fast.
165 [/help]
166 [option dest-sample-rate]
167 short_opt = d
168 summary = sample rate to convert to
169 typestr = rate
170 arg_info = required_arg
171 arg_type = uint32
172 default_val = 44100
173 m4_include(channels.m4)
174 m4_include(sample-rate.m4)
175 m4_include(sample-format.m4)
176 [subcommand spxdec]
177 purpose = decode an ogg/speex stream
178 [subcommand sync]
179 purpose = synchronize playback between multiple clients
180 [option buddy]
181 short_opt = b
182 summary = client to synchronize with
183 typestr = url
184 arg_info = required_arg
185 arg_type = string
186 flag multiple
187 [help]
188 This option may be given multiple times, one per buddy. Each value
189 may be given as a host, port pair in either IPv4 or IPv6 form, with
190 port being optional. If no port was specified the listening port (as
191 specified with --port, see below) is used to send the synchronization
192 packet to this buddy.
193 [/help]
194 [option port]
195 short_opt = p
196 summary = UDP port for incoming synchronization packets
197 typestr = portnumber
198 arg_info = required_arg
199 arg_type = uint32
200 default_val = 29900
201 [help]
202 The sync filter expects incoming synchronization packets on this
203 UDP port.
204 [/help]
205 [option timeout]
206 short_opt = t
207 summary = how long to wait for other clients
208 typestr = milliseconds
209 arg_info = required_arg
210 arg_type = uint32
211 default_val = 2000
212 [help]
213 Once the sync filter receives its first chunk of input,
214 a synchronization period of the given number of milliseconds
215 begins. Playback is deferred until a synchronization packet has
216 been received from each defined buddy, or until the end of the
217 period. Buddies which did not send a synchronization packet in time
218 are temporarily disabled and are not waited for during subsequent
219 synchronization periods. They are re-enabled automatically when
220 another synchronization packet arrives.
221 [/help]
222 [subcommand wav]
223 purpose = insert a Microsoft wave header into a raw audio stream
224 [subcommand wmadec]
225 purpose = decode a wma stream