add docs for --serial-number
[flac.git] / man / flac.1
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document.  This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "FLAC" "1" "03 September 2002" "" ""
7 .SH NAME
8 flac \- Free Lossless Audio Codec
9 .SH SYNOPSIS
10
11 \fBflac\fR [ \fB\fIOPTION\fB\fR ] \fB\fIinfile\fB\fR \fB\fI...\fB\fR
12
13 .SH "DESCRIPTION"
14 .PP
15 This manual page documents briefly the
16 \fBflac\fR command.
17 .PP
18 This manual page was written for the Debian GNU/Linux
19 distribution because the original program does not have a
20 manual page.  Instead, it has documentation in HTML
21 format; see below.
22 .SH "OPTIONS"
23 .PP
24 A summary of options is included below.  For a complete
25 description, see the HTML documentation.
26 .SS "GENERIC OPTIONS"
27 .TP
28 \fB-v, --version \fR
29 Show the flac version number
30 .TP
31 \fB-h, --help \fR
32 Show basic usage and a list of all options
33 .TP
34 \fB-H, --explain \fR
35 Show detailed explanation of usage and all options
36 .TP
37 \fB-d, --decode \fR
38 Decode (the default behavior is to encode)
39 .TP
40 \fB-t, --test \fR
41 Test a flac encoded file (same as -d
42 except no decoded file is written)
43 .TP
44 \fB-a, --analyze \fR
45 Analyze a flac encoded file (same as -d
46 except an analysis file is written)
47 .TP
48 \fB-c, --stdout \fR
49 Write output to stdout
50 .TP
51 \fB-s, --silent \fR
52 Silent mode (do not write runtime
53 encode/decode statistics to stderr)
54 .TP
55 \fB-o \fIfilename\fB, --output-name=\fIfilename\fB\fR
56 Force the output file name (usually flac just
57 changes the extension).  May only be used when
58 encoding a single file.  May not be used in
59 conjunction with --output-prefix.
60 .TP
61 \fB--output-prefix=\fIstring\fB\fR
62 Prefix each output file name with the given
63 string.  This can be useful for encoding or decoding
64 files to a different directory.  Make sure if your
65 string is a path name that it ends with a trailing
66 `/' (slash).
67 .TP
68 \fB--delete-input-file \fR
69 Automatically delete the input file after a
70 successful encode or decode.  If there was an
71 error (including a verify error) the input file
72 is left intact.
73 .TP
74 \fB--skip=\fI#\fB\fR
75 Skip the specified number of samples at the
76 beginning of the input file (can be used for both
77 encoding and decoding)
78 .SS "ANALYSIS OPTIONS"
79 .TP
80 \fB--residual-text \fR
81 Includes the residual signal in the analysis
82 file.  This will make the file very big, much
83 larger than even the decoded file.
84 .TP
85 \fB--residual-gnuplot \fR
86 Generates a gnuplot file for every subframe;
87 each file will contain the residual distribution
88 of the subframe.  This will create a lot of
89 files.
90 .SS "DECODING OPTIONS"
91 .TP
92 \fB-F, --decode-through-errors \fR
93 By default flac stops decoding with an error
94 and removes the partially decoded file if it
95 encounters a bitstream error.  With -F, errors are
96 still printed but flac will continue decoding to
97 completion.  Note that errors may cause the decoded
98 audio to be missing some samples or have silent
99 sections.
100 .SS "ENCODING OPTIONS"
101 .TP
102 \fB-V, --verify\fR
103 Verify a correct encoding by decoding the
104 output in parallel and comparing to the
105 original
106 .TP
107 \fB--ogg\fR
108 When encoding, generate Ogg-FLAC output instead
109 of native-FLAC.  Ogg-FLAC streams are FLAC streams
110 wrapped in an Ogg transport layer.  The resulting
111 file should have an '.ogg' extension and will still
112 be decodable by flac.
113
114 When decoding, force the input to be treated as
115 Ogg-FLAC.  This is useful when piping input from
116 stdin or when the filename does not end in '.ogg'.
117 .TP
118 \fB--ogg=\fI#\fB\fR
119 When used with --ogg, specifies the serial
120 number to use for the FLAC stream.  When encoding and
121 no serial number is given, flac uses '0'.  When
122 decoding and no number is given, flac uses the serial
123 number of the first page.
124 .TP
125 \fB--lax\fR
126 Allow encoder to generate non-Subset
127 files.
128 .TP
129 \fB--sector-align\fR
130 Align encoding of multiple CD format WAVE
131 files on sector boundaries.  See the HTML
132 documentation for more information.
133 .TP
134 \fB-S {\fI#\fB|\fIX\fB|\fI#x\fB}, --seekpoint={\fI#\fB|\fIX\fB|\fI#x\fB}\fR
135 Include a point or points in a SEEKTABLE.  Using #,
136 a seek point at that sample number is added.  Using
137 X, a placeholder point is added at the end of a the
138 table.  Using #x, # evenly spaced seek points will
139 be added, the first being at sample 0.  You may use
140 many -S options; the resulting SEEKTABLE will be the
141 unique-ified union of all such values.  With no -S
142 options, flac defaults to '-S 100x'.  Use -S- for
143 no SEEKTABLE.  Note: '-S #x' will not work if the
144 encoder can't determine the input size before
145 starting.  Note: if you use '-S #' and # is >=
146 samples in the input, there will be either no seek
147 point entered (if the input size is determinable
148 before encoding starts) or a placeholder point (if
149 input size is not determinable).
150 .TP
151 \fB-P \fI#\fB, --padding=\fI#\fB\fR
152 Tell the encoder to write a PADDING metadata
153 block of the given length (in bytes) after the
154 STREAMINFO block.  This is useful if you plan to
155 tag the file later with an APPLICATION block;
156 instead of having to rewrite the entire file later
157 just to insert your block, you can write directly
158 over the PADDING block.  Note that the total length
159 of the PADDING block will be 4 bytes longer than
160 the length given because of the 4 metadata block
161 header bytes.  You can force no PADDING block at
162 all to be written with -P-, which is the default.
163 .TP
164 \fB-b \fI#\fB, --blocksize=\fI#\fB\fR
165 Specify the block size in samples.  The
166 default is 1152 for -l 0, else 4608; must be one of
167 192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
168 4096, 8192, 16384, or 32768 (unless --lax is used)
169 .TP
170 \fB-m, --mid-side\fR
171 Try mid-side coding for each frame (stereo
172 input only)
173 .TP
174 \fB-M, --adaptive-mid-side\fR
175 Adaptive mid-side coding for all frames (stereo
176 input only)
177 .TP
178 \fB-0..-8, --compression-level-0..--compression-level-8\fR
179 Fastest compression..highest compression
180 (default is -5).  These are synonyms for other
181 options:
182 .RS
183 .TP
184 \fB-0, --compression-level-0\fR
185 Synonymous with -l 0 -b 1152 -r 2,2
186 .TP
187 \fB-1, --compression-level-1\fR
188 Synonymous with -l 0 -b 1152 -M -r 2,2
189 .TP
190 \fB-2, --compression-level-2\fR
191 Synonymous with -l 0 -b 1152 -m -r 3
192 .TP
193 \fB-3, --compression-level-3\fR
194 Synonymous with -l 6 -b 4608 -r 3,3
195 .TP
196 \fB-4, --compression-level-4\fR
197 Synonymous with -l 8 -b 4608 -M -r 3,3
198 .TP
199 \fB-5, --compression-level-5\fR
200 Synonymous with -l 8 -b 4608 -m -r 3,3
201 .TP
202 \fB-6, --compression-level-6\fR
203 Synonymous with -l 8 -b 4608 -m -r 4
204 .TP
205 \fB-7, --compression-level-7\fR
206 Synonymous with -l 8 -b 4608 -m -e -r 6
207 .TP
208 \fB-8, --compression-level-8\fR
209 Synonymous with -l 12 -b 4608 -m -e -r 6
210 .RE
211 .TP
212 \fB--fast\fR
213 Fastest compression.  Currently
214 synonymous with -0.
215 .TP
216 \fB--best\fR
217 Highest compression.  Currently
218 synonymous with -8.
219 .TP
220 \fB-e, --exhaustive-model-search\fR
221 Do exhaustive model search
222 (expensive!)
223 .TP
224 \fB-E, --escape-coding\fR
225 Do escape coding in the entropy coder.  This
226 causes the encoder to use an unencoded representation
227 of the residual in a partition if it is smaller.  It
228 increases the runtime and usually results in an
229 improvement of less than 1%.
230 .TP
231 \fB-l \fI#\fB, --max-lpc-order=\fI#\fB\fR
232 Set the maximum LPC order; 0 means use only the fixed predictors
233 .TP
234 \fB-p, --qlp-coeff-precision-search\fR
235 Do exhaustive search of LP coefficient
236 quantization (expensive!).  Overrides -q;
237 does nothing if using -l 0
238 .TP
239 \fB-q \fI#\fB, --qlp-coeff-precision=\fI#\fB\fR
240 Precision of the quantized linear-predictor
241 coefficients, 0 => let encoder decide (min is 5,
242 default is 0)
243 .TP
244 \fB-r [\fI#\fB,]\fI#\fB, --rice-partition-order=[\fI#\fB,]\fI#\fB\fR
245 Set the [min,]max residual partition order
246 (0..16). min defaults to 0 if unspecified.  Default
247 is -r 3,3.
248 .SS "FORMAT OPTIONS"
249 .TP
250 \fB--endian={\fIbig\fB|\fIlittle\fB}\fR
251 Set the byte order for samples
252 .TP
253 \fB--channels=\fI#\fB\fR
254 Set number of channels.
255 .TP
256 \fB--bps=\fI#\fB\fR
257 Set bits per sample.
258 .TP
259 \fB--sample-rate=\fI#\fB\fR
260 Set sample rate (in Hz).
261 .TP
262 \fB--sign={\fIsigned\fB|\fIunsigned\fB}\fR
263 Set the sign of samples (the default is signed).
264 .TP
265 \fB--force-raw-format\fR
266 Force input (when encoding) or output (when decoding)
267 to be treated as raw samples (even if filename ends
268 in \fI.wav\fR).
269 .SS "NEGATIVE OPTIONS"
270 .TP
271 \fB--no-adaptive-mid-side\fR
272 .TP
273 \fB--no-decode-through-errors\fR
274 .TP
275 \fB--no-delete-input-file\fR
276 .TP
277 \fB--no-escape-coding\fR
278 .TP
279 \fB--no-exhaustive-model-search\fR
280 .TP
281 \fB--no-lax\fR
282 .TP
283 \fB--no-mid-side\fR
284 .TP
285 \fB--no-ogg\fR
286 .TP
287 \fB--no-padding\fR
288 .TP
289 \fB--no-qlp-coeff-precision-search\fR
290 .TP
291 \fB--no-residual-gnuplot\fR
292 .TP
293 \fB--no-residual-text\fR
294 .TP
295 \fB--no-sector-align\fR
296 .TP
297 \fB--no-seektable\fR
298 .TP
299 \fB--no-silent\fR
300 .TP
301 \fB--no-verify\fR
302 These flags can be used to invert the sense
303 of the corresponding normal option.
304 .SH "SEE ALSO"
305 .PP
306 The programs are documented fully by HTML format
307 documentation, available in
308 \fI/usr/share/doc/flac/html\fR on
309 Debian GNU/Linux systems.
310 .SH "AUTHOR"
311 .PP
312 This manual page was written by Matt Zimmerman <mdz@debian.org> for
313 the Debian GNU/Linux system (but may be used by others).