update verbiage about -P, now that the default is -P 4096
[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" "10 January 2003" "" ""
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 "GENERAL 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|\fImm:ss.ss\fB}\fR
75 Skip over the first number of samples of the input.
76 This works for both encoding and decoding, but not
77 testing.  The alternative form mm:ss.ss can be used
78 to specify minutes, seconds, and fractions of a
79 second.
80 .TP
81 \fB--until={\fI#\fB|[\fI+\fB|\fI-\fB]\fImm:ss.ss\fB}\fR
82 Stop at the given sample number for each input file.
83 This works for both encoding and decoding, but not testing.
84 The given sample number is not included in the decoded
85 output.  The alternative form mm:ss.ss can be used to
86 specify minutes, seconds, and fractions of a second.  If a
87 `+' (plus) sign is at the beginning, the --until point is
88 relative to the --skip point.  If a `-' (minus) sign is at
89 the beginning, the --until point is relative to end of the
90 audio.
91 .TP
92 \fB--ogg\fR
93 When encoding, generate Ogg-FLAC output instead
94 of native-FLAC.  Ogg-FLAC streams are FLAC streams
95 wrapped in an Ogg transport layer.  The resulting
96 file should have an '.ogg' extension and will still
97 be decodable by flac.
98
99 When decoding, force the input to be treated as
100 Ogg-FLAC.  This is useful when piping input from
101 stdin or when the filename does not end in '.ogg'.
102 .TP
103 \fB--serial-number=\fI#\fB\fR
104 When used with --ogg, specifies the serial
105 number to use for the FLAC stream.  When encoding and
106 no serial number is given, flac uses '0'.  When
107 decoding and no number is given, flac uses the serial
108 number of the first page.
109 .SS "ANALYSIS OPTIONS"
110 .TP
111 \fB--residual-text \fR
112 Includes the residual signal in the analysis
113 file.  This will make the file very big, much
114 larger than even the decoded file.
115 .TP
116 \fB--residual-gnuplot \fR
117 Generates a gnuplot file for every subframe;
118 each file will contain the residual distribution
119 of the subframe.  This will create a lot of
120 files.
121 .SS "DECODING OPTIONS"
122 .TP
123 \fB-F, --decode-through-errors \fR
124 By default flac stops decoding with an error
125 and removes the partially decoded file if it
126 encounters a bitstream error.  With -F, errors are
127 still printed but flac will continue decoding to
128 completion.  Note that errors may cause the decoded
129 audio to be missing some samples or have silent
130 sections.
131 .SS "ENCODING OPTIONS"
132 .TP
133 \fB-V, --verify\fR
134 Verify a correct encoding by decoding the
135 output in parallel and comparing to the
136 original
137 .TP
138 \fB--lax\fR
139 Allow encoder to generate non-Subset
140 files.
141 .TP
142 \fB--replay-gain\fR
143 Calculate ReplayGain values and store in
144 Vorbis comments, similar to vorbisgain.  Title
145 gains/peaks will be computed for each input
146 file, and an album gain/peak will be computed
147 for all files.  All input files must have the
148 same resolution, sample rate, and number of
149 channels.  Only mono and stereo files are
150 allowed, and the sample rate must be one of
151 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48
152 kHz.  Also note that this option may leave a
153 few extra bytes in a PADDING block as the exact
154 size of the tags is not known until all files
155 are processed.  Note that this option cannot be
156 used when encoding to standard output (stdout).
157 .TP
158 \fB--cuesheet=\fIfilename\fB\fR
159 Import the given cuesheet file and store it in a
160 CUESHEET metadata block.  This option may only be used
161 when encoding a single file.  A seekpoint will be added
162 for each index point in the cuesheet to the SEEKTABLE
163 unless --no-cued-seekpoints is specified.
164 .TP
165 \fB--sector-align\fR
166 Align encoding of multiple CD format WAVE
167 files on sector boundaries.  See the HTML
168 documentation for more information.
169 .TP
170 \fB-S {\fI#\fB|\fIX\fB|\fI#x\fB|\fI#s\fB}, --seekpoint={\fI#\fB|\fIX\fB|\fI#x\fB|\fI#s\fB}\fR
171 Include a point or points in a SEEKTABLE.  Using #,
172 a seek point at that sample number is added.  Using
173 X, a placeholder point is added at the end of a the
174 table.  Using #x, # evenly spaced seek points will
175 be added, the first being at sample 0.  Using #s, a
176 seekpoint will be added every # seconds (# does not
177 have to be a whole number; it can be, for example, 9.5,
178 meaning a seekpoint every 9.5 seconds).  You may use
179 many -S options; the resulting SEEKTABLE will be the
180 unique-ified union of all such values.  With no -S
181 options, flac defaults to '-S 10s'.  Use --no-seektable
182 for no SEEKTABLE.  Note: '-S #x' and '-S #s' will not
183 work if the encoder can't determine the input size before
184 starting.  Note: if you use '-S #' and # is >=
185 samples in the input, there will be either no seek
186 point entered (if the input size is determinable
187 before encoding starts) or a placeholder point (if
188 input size is not determinable).
189 .TP
190 \fB-P \fI#\fB, --padding=\fI#\fB\fR
191 Tell the encoder to write a PADDING metadata
192 block of the given length (in bytes) after the
193 STREAMINFO block.  This is useful if you plan to
194 tag the file later with an APPLICATION block;
195 instead of having to rewrite the entire file later
196 just to insert your block, you can write directly
197 over the PADDING block.  Note that the total length
198 of the PADDING block will be 4 bytes longer than
199 the length given because of the 4 metadata block
200 header bytes.  You can force no PADDING block at
201 all to be written with --no-padding.  The encoder
202 writes a PADDING block of 4096 bytes by default.
203 .TP
204 \fB-T \fIFIELD=VALUE\fB, --tag=\fIFIELD=VALUE\fB\fR
205 Add a Vorbis comment.  The comment must adhere
206 to the Vorbis comment spec; i.e. the FIELD must
207 contain only legal characters, terminated by an
208 \&'equals' sign.  Make sure to quote the comment if
209 necessary.  This option may appear more than once
210 to add several comments.  NOTE: all tags will be
211 added to all encoded files.
212 .TP
213 \fB-b \fI#\fB, --blocksize=\fI#\fB\fR
214 Specify the block size in samples.  The
215 default is 1152 for -l 0, else 4608; must be one of
216 192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
217 4096, 8192, 16384, or 32768 (unless --lax is used)
218 .TP
219 \fB-m, --mid-side\fR
220 Try mid-side coding for each frame (stereo
221 input only)
222 .TP
223 \fB-M, --adaptive-mid-side\fR
224 Adaptive mid-side coding for all frames (stereo
225 input only)
226 .TP
227 \fB-0..-8, --compression-level-0..--compression-level-8\fR
228 Fastest compression..highest compression
229 (default is -5).  These are synonyms for other
230 options:
231 .RS
232 .TP
233 \fB-0, --compression-level-0\fR
234 Synonymous with -l 0 -b 1152 -r 2,2
235 .TP
236 \fB-1, --compression-level-1\fR
237 Synonymous with -l 0 -b 1152 -M -r 2,2
238 .TP
239 \fB-2, --compression-level-2\fR
240 Synonymous with -l 0 -b 1152 -m -r 3
241 .TP
242 \fB-3, --compression-level-3\fR
243 Synonymous with -l 6 -b 4608 -r 3,3
244 .TP
245 \fB-4, --compression-level-4\fR
246 Synonymous with -l 8 -b 4608 -M -r 3,3
247 .TP
248 \fB-5, --compression-level-5\fR
249 Synonymous with -l 8 -b 4608 -m -r 3,3
250 .TP
251 \fB-6, --compression-level-6\fR
252 Synonymous with -l 8 -b 4608 -m -r 4
253 .TP
254 \fB-7, --compression-level-7\fR
255 Synonymous with -l 8 -b 4608 -m -e -r 6
256 .TP
257 \fB-8, --compression-level-8\fR
258 Synonymous with -l 12 -b 4608 -m -e -r 6
259 .RE
260 .TP
261 \fB--fast\fR
262 Fastest compression.  Currently
263 synonymous with -0.
264 .TP
265 \fB--best\fR
266 Highest compression.  Currently
267 synonymous with -8.
268 .TP
269 \fB-e, --exhaustive-model-search\fR
270 Do exhaustive model search
271 (expensive!)
272 .TP
273 \fB-l \fI#\fB, --max-lpc-order=\fI#\fB\fR
274 Set the maximum LPC order; 0 means use only the fixed predictors
275 .TP
276 \fB-p, --qlp-coeff-precision-search\fR
277 Do exhaustive search of LP coefficient
278 quantization (expensive!).  Overrides -q;
279 does nothing if using -l 0
280 .TP
281 \fB-q \fI#\fB, --qlp-coeff-precision=\fI#\fB\fR
282 Precision of the quantized linear-predictor
283 coefficients, 0 => let encoder decide (min is 5,
284 default is 0)
285 .TP
286 \fB-r [\fI#\fB,]\fI#\fB, --rice-partition-order=[\fI#\fB,]\fI#\fB\fR
287 Set the [min,]max residual partition order
288 (0..16). min defaults to 0 if unspecified.  Default
289 is -r 3,3.
290 .SS "FORMAT OPTIONS"
291 .TP
292 \fB--endian={\fIbig\fB|\fIlittle\fB}\fR
293 Set the byte order for samples
294 .TP
295 \fB--channels=\fI#\fB\fR
296 Set number of channels.
297 .TP
298 \fB--bps=\fI#\fB\fR
299 Set bits per sample.
300 .TP
301 \fB--sample-rate=\fI#\fB\fR
302 Set sample rate (in Hz).
303 .TP
304 \fB--sign={\fIsigned\fB|\fIunsigned\fB}\fR
305 Set the sign of samples (the default is signed).
306 .TP
307 \fB--force-aiff-format\fR
308 Force the decoder to output AIFF format.  This option
309 is not needed if the output filename (as set by -o) ends
310 with \fI.aiff\fR.  Also, this option has no
311 effect when encoding since input AIFF is auto-detected.
312 .TP
313 \fB--force-raw-format\fR
314 Force input (when encoding) or output (when decoding)
315 to be treated as raw samples (even if filename ends
316 in \fI.wav\fR).
317 .SS "NEGATIVE OPTIONS"
318 .TP
319 \fB--no-adaptive-mid-side\fR
320 .TP
321 \fB--no-decode-through-errors\fR
322 .TP
323 \fB--no-delete-input-file\fR
324 .TP
325 \fB--no-exhaustive-model-search\fR
326 .TP
327 \fB--no-lax\fR
328 .TP
329 \fB--no-mid-side\fR
330 .TP
331 \fB--no-ogg\fR
332 .TP
333 \fB--no-padding\fR
334 .TP
335 \fB--no-qlp-coeff-precision-search\fR
336 .TP
337 \fB--no-residual-gnuplot\fR
338 .TP
339 \fB--no-residual-text\fR
340 .TP
341 \fB--no-sector-align\fR
342 .TP
343 \fB--no-seektable\fR
344 .TP
345 \fB--no-silent\fR
346 .TP
347 \fB--no-verify\fR
348 These flags can be used to invert the sense
349 of the corresponding normal option.
350 .SH "SEE ALSO"
351 .PP
352 metaflac(1).
353 .PP
354 The programs are documented fully by HTML format
355 documentation, available in
356 \fI/usr/share/doc/flac/html\fR on
357 Debian GNU/Linux systems.
358 .SH "AUTHOR"
359 .PP
360 This manual page was written by Matt Zimmerman <mdz@debian.org> for
361 the Debian GNU/Linux system (but may be used by others).