add --sector-align option
[flac.git] / man / flac.sgml
1 <!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
2
3   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
4   <!ENTITY dhfirstname "<firstname>Matt</firstname>">
5   <!ENTITY dhsurname   "<surname>Zimmerman</surname>">
6   <!-- Please adjust the date whenever revising the manpage. -->
7   <!ENTITY dhdate      "<date>June 26, 2001</date>">
8   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
9        allowed: see man(7), man(1). -->
10   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
11   <!ENTITY dhemail     "<email>mdz@debian.org</email>">
12   <!ENTITY dhusername  "Matt Zimmerman">
13   <!ENTITY dhucpackage "<refentrytitle>FLAC</refentrytitle>">
14   <!ENTITY dhpackage   "flac">
15
16   <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
17   <!ENTITY gnu         "<acronym>GNU</acronym>">
18 ]>
19
20 <refentry>
21   <docinfo>
22     <address>
23         &dhemail;
24     </address>
25     <author>
26         &dhfirstname;
27         &dhsurname;
28       </author>
29         <copyright>
30                     <year>2001</year>
31                     <holder>&dhusername;</holder>
32         </copyright>
33             &dhdate;
34         </docinfo>
35   <refmeta>
36       &dhucpackage;
37
38       &dhsection;
39     </refmeta>
40       <refnamediv>
41                    <refname>&dhpackage;</refname>
42
43         <refpurpose>Free Lossless Audio Codec</refpurpose>
44       </refnamediv>
45         <refsynopsisdiv>
46           <cmdsynopsis>
47             <command>flac</command>
48
49             <arg><option><replaceable>OPTION</replaceable></option></arg>
50             <arg choice=plain><replaceable>infile</replaceable></arg>
51             <arg choice=plain><replaceable>...</replaceable></arg>
52           </cmdsynopsis>
53         </refsynopsisdiv>
54         <refsect1>
55           <title>DESCRIPTION</title>
56
57           <para>This manual page documents briefly the
58             <command>flac</command> command.</para>
59
60           <para>This manual page was written for the &debian;
61             distribution because the original program does not have a
62             manual page.  Instead, it has documentation in HTML
63             format; see below.</para>
64
65         </refsect1>
66         <refsect1>
67           <title>OPTIONS</title>
68
69           <para>A summary of options is included below.  For a complete
70           description, see the HTML documentation.</para>
71
72           <refsect2>
73             <title>Generic Options</title>
74
75             <variablelist>
76               <varlistentry>
77                 <term><option>-d</option>
78                 </term>
79                 <listitem>
80                   <para>Decode (default behavior is encode)</para>
81                 </listitem>
82               </varlistentry>
83
84               <varlistentry>
85                 <term><option>-t</option>
86                 </term>
87                 <listitem>
88                   <para>Test a flac encoded file (same as -d
89                     except no decoded file is written)</para>
90                 </listitem>
91               </varlistentry>
92
93               <varlistentry>
94                 <term><option>-a</option>
95                 </term>
96                 <listitem>
97                   <para>Analyze a flac encoded file (same as -d
98                     except an analysis file is written)</para>
99                 </listitem>
100               </varlistentry>
101
102               <varlistentry>
103                 <term><option>-s</option>
104                 </term>
105                 <listitem>
106                   <para>Silent mode (do not write runtime
107                     encode/decode statistics to stdout)</para>
108                 </listitem>
109               </varlistentry>
110
111               <varlistentry>
112                 <term><option>-o</option> <replaceable>filename</replaceable></term>
113                 <listitem>
114                   <para>Force the output file name (usually flac just
115                     changes the extension).</para>
116                 </listitem>
117               </varlistentry>
118
119               <varlistentry>
120                 <term><option>--delete-input-file</option>
121                 </term>
122                 <listitem>
123                   <para>Automatically delete the input file after a
124                     successful encode or decode.  If there was an
125                     error (including a verify error) the input file
126                     is left intact.</para>
127                 </listitem>
128               </varlistentry>
129
130               <varlistentry>
131                 <term><option>--skip</option> <replaceable>samples</replaceable></term>
132                 <listitem>
133                   <para>Skip the specified number of samples at the
134                     beginning of the input file (can be used for both
135                     encoding and decoding)</para>
136                 </listitem>
137               </varlistentry>
138
139             </variablelist>
140           </refsect2>
141
142           <refsect2>
143             <title>Analysis Options</title>
144
145             <variablelist>
146               <varlistentry>
147                 <term><option>--a-rtext</option>
148                 </term>
149                 <listitem>
150                   <para>Includes the residual signal in the analysis
151                     file.  This will make the file very big, much
152                     larger than even the decoded file.</para>
153                 </listitem>
154               </varlistentry>
155
156               <varlistentry>
157                 <term><option>--a-rgp</option>
158                 </term>
159                 <listitem>
160                   <para>Generates a gnuplot file for every subframe;
161                     each file will contain the residual distribution
162                     of the subframe.  This will create a lot of
163                     files.</para>
164                 </listitem>
165               </varlistentry>
166
167             </variablelist>
168           </refsect2>
169
170           <refsect2>
171             <title>Encoding Options</title>
172
173             <variablelist>
174               <varlistentry>
175                 <term><option>--lax</option></term>
176
177                 <listitem>
178                   <para>Allow encoder to generate non-Subset
179                     files.</para>
180                 </listitem>
181               </varlistentry>
182
183               <varlistentry>
184                 <term><option>--sector-align</option></term>
185
186                 <listitem>
187                   <para>Align encoding of multiple CD format WAVE
188                     files on sector boundaries.  See the HTML
189                     documentation for more information.</para>
190                 </listitem>
191               </varlistentry>
192
193               <varlistentry>
194                 <term><option>-S</option> <replaceable>{ # | X | #x }</replaceable></term>
195
196                 <listitem>
197                   <para>
198                     Include a point or points in a SEEKTABLE.  Using #,
199                     a seek point at that sample number is added.  Using
200                     X, a placeholder point is added at the end of a the
201                     table.  Using #x, # evenly spaced seek points will
202                     be added, the first being at sample 0.  You may use
203                     many -S options; the resulting SEEKTABLE will be the
204                     unique-ified union of all such values.  With no -S
205                     options, flac defaults to '-S 100x'.  Use -S- for
206                     no SEEKTABLE.  Note: '-S #x' will not work if the
207                     encoder can't determine the input size before
208                     starting.  Note: if you use '-S #' and # is >=
209                     samples in the input, there will be either no seek
210                     point entered (if the input size is determinable
211                     before encoding starts) or a placeholder point (if
212                     input size is not determinable).</para>
213                 </listitem>
214               </varlistentry>
215
216               <varlistentry>
217                 <term><option>-P</option> <replaceable>bytes</replaceable></term>
218
219                 <listitem>
220                   <para>Tell the encoder to write a PADDING metadata
221                     block of the given length (in bytes) after the
222                     STREAMINFO block.  -P 0 implies no PADDING block,
223                     which is the default.  This is useful if you plan
224                     to tag the file later with an APPLICATION block;
225                     instead of having to rewrite the entire file later
226                     just to insert your block, you can write directly
227                     over the PADDING block.</para>
228                 </listitem>
229               </varlistentry>
230
231               <varlistentry>
232                 <term><option>-b</option> <replaceable>blocksize</replaceable></term>
233
234                 <listitem>
235                   <para>Default is 1152 for -l 0, else 4608; must be
236                     192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768
237                     (unless --lax is used)</para>
238                 </listitem>
239               </varlistentry>
240
241               <varlistentry>
242                 <term><option>-m</option></term>
243
244                 <listitem>
245                   <para>Try mid-side coding for each frame (stereo
246                     input only)</para>
247                 </listitem>
248               </varlistentry>
249
250               <varlistentry>
251                 <term><option>-m</option></term>
252
253                 <listitem>
254                   <para>Loose mid-side coding for all frames (stereo
255                     input only)</para>
256                 </listitem>
257               </varlistentry>
258
259               <varlistentry>
260                 <term><option>-0</option>..<option>-9</option></term>
261
262                 <listitem>
263                   <para>Fastest compression..highest compression
264                     (default is -5).  These are synonyms for other
265                     options:</para>
266
267                   <variablelist>
268                     <varlistentry>
269                       <term><option>-0</option></term>
270
271                       <listitem>
272                         <para>Synonymous with -l 0 -b 1152 -r 2,2
273                           </para>
274                       </listitem>
275                     </varlistentry>
276
277                     <varlistentry>
278                       <term><option>-1</option></term>
279
280                       <listitem>
281                         <para>Synonymous with -l 0 -b 1152 -M -r 2,2
282                           </para>
283                       </listitem>
284                     </varlistentry>
285
286                     <varlistentry>
287                       <term><option>-2</option></term>
288
289                       <listitem>
290                         <para>Synonymous with -l 0 -b 1152 -m -r 3
291                           </para>
292                       </listitem>
293                     </varlistentry>
294
295                     <varlistentry>
296                       <term><option>-3</option></term>
297
298                       <listitem>
299                         <para>Synonymous with -l 6 -b 4608 -r 3,3
300                           </para>
301                       </listitem>
302                     </varlistentry>
303
304                     <varlistentry>
305                       <term><option>-4</option></term>
306
307                       <listitem>
308                         <para>Synonymous with -l 8 -b 4608 -M -r 3,3
309                           </para>
310                       </listitem>
311                     </varlistentry>
312
313                     <varlistentry>
314                       <term><option>-5</option></term>
315
316                       <listitem>
317                         <para>Synonymous with -l 8 -b 4608 -m -r 3,3
318                           </para>
319                       </listitem>
320                     </varlistentry>
321
322                     <varlistentry>
323                       <term><option>-6</option></term>
324
325                       <listitem>
326                         <para>Synonymous with -l 8 -b 4608 -m -r 4
327                           </para>
328                       </listitem>
329                     </varlistentry>
330
331                     <varlistentry>
332                       <term><option>-7</option></term>
333
334                       <listitem>
335                         <para>Synonymous with -l 8 -b 4608 -m -e -r 6
336                           </para>
337                       </listitem>
338                     </varlistentry>
339
340                     <varlistentry>
341                       <term><option>-8</option></term>
342
343                       <listitem>
344                         <para>Synonymous with -l 12 -b 4608 -m -e -r 6
345                           </para>
346                       </listitem>
347                     </varlistentry>
348
349                     <varlistentry>
350                       <term><option>-9</option></term>
351
352                       <listitem>
353                         <para>Synonymous with -l 32 -b 4608 -m -e -r 16 -p
354                           (very slow!)</para>
355                       </listitem>
356                     </varlistentry>
357                   </variablelist>
358
359                 </listitem>
360
361
362               </varlistentry>
363
364               <varlistentry>
365                 <term><option>-e</option></term>
366
367                 <listitem>
368                   <para>Do exhaustive model search
369                     (expensive!)</para>
370                 </listitem>
371               </varlistentry>
372
373               <varlistentry>
374                 <term><option>-l</option> <replaceable>max_lpc_order</replaceable></term>
375
376                 <listitem>
377                   <para>0 => use only fixed predictors</para>
378                 </listitem>
379               </varlistentry>
380
381               <varlistentry>
382                 <term><option>-p</option></term>
383
384                 <listitem>
385                   <para>Do exhaustive search of LP coefficient
386                     quantization (expensive!).  Overrides -q,
387                     does nothing if using -l 0</para>
388                 </listitem>
389               </varlistentry>
390
391               <varlistentry>
392                 <term><option>-q</option> <replaceable>bits</replaceable></term>
393
394                 <listitem>
395                   <para>Precision of the quantized linear-predictor
396                     coefficients, 0 => let encoder decide (min is 5,
397                     default is 0)</para>
398                 </listitem>
399               </varlistentry>
400
401               <varlistentry>
402                 <term><option>-r</option> <replaceable>[level,]level</replaceable></term>
403
404                 <listitem>
405                   <para>Set the [min,]max residual partition order
406                     (0..16). min defaults to 0 if unspecified.  Default
407                     is -r 3,3.</para>
408                 </listitem>
409               </varlistentry>
410
411               <varlistentry>
412                 <term><option>-R</option> <replaceable>#</replaceable></term>
413
414                 <listitem>
415                   <para>Set the Rice parameter search distance.
416                     Default is 0.</para>
417                 </listitem>
418               </varlistentry>
419
420               <varlistentry>
421                 <term><option>-V</option></term>
422
423                 <listitem>
424                   <para>Verify a correct encoding by decoding the
425                     output in parallel and comparing to the
426                     original</para>
427                 </listitem>
428               </varlistentry>
429
430               <varlistentry>
431                 <term><option>-S-</option> <option>-m-</option> <option>-M-</option> <option>-e-</option> <option>-p-</option> <option>-V-</option> <option>--delete-input-file-</option> <option>--lax-</option>
432                 </term>
433
434                 <listitem>
435                   <para>These flags can be used to invert the sense
436                     of the corresponding normal option.</para>
437                 </listitem>
438               </varlistentry>
439             </variablelist>
440
441           </refsect2>
442           <refsect2>
443             <title>Format Options</title>
444
445             <variablelist>
446               <varlistentry>
447                 <term><option>-fb</option></term>
448
449                 <listitem>
450                   <para>Big-endian byte order</para>
451                 </listitem>
452               </varlistentry>
453
454               <varlistentry>
455                 <term><option>-fl</option></term>
456
457                 <listitem>
458                   <para>Little-endian byte order</para>
459                 </listitem>
460               </varlistentry>
461
462               <varlistentry>
463                 <term><option>-fc</option>
464                   <replaceable>channels</replaceable></term>
465
466                 <listitem>
467                   <para>Set number of channels.</para>
468                 </listitem>
469               </varlistentry>
470
471               <varlistentry>
472                 <term><option>-fp</option>
473                   <replaceable>bits_per_sample</replaceable></term>
474
475                 <listitem>
476                   <para>Set bits per sample.</para>
477                 </listitem>
478               </varlistentry>
479
480               <varlistentry>
481                 <term><option>-fs</option>
482                   <replaceable>sample_rate</replaceable></term>
483
484                 <listitem>
485                   <para>Set sample rate (in Hz).</para>
486                 </listitem>
487               </varlistentry>
488
489               <varlistentry>
490                 <term><option>-fu</option></term>
491
492                 <listitem>
493                   <para>Unsigned samples (default is signed)</para>
494                 </listitem>
495               </varlistentry>
496
497               <varlistentry>
498                 <term><option>-fr</option></term>
499
500                 <listitem>
501                   <para>Force to raw format (even if filename ends
502                     in <filename>.wav</filename>).</para>
503                 </listitem>
504               </varlistentry>
505
506               <varlistentry>
507                 <term><option>-fw</option></term>
508
509                 <listitem>
510                   <para>Force to RIFF WAVE.</para>
511                 </listitem>
512               </varlistentry>
513
514             </variablelist>
515           </refsect2>
516
517         </refsect1>
518           <refsect1>
519             <title>SEE ALSO</title>
520
521             <para>The programs are documented fully by HTML format
522               documentation, available in
523               <filename>/usr/share/doc/flac/html</filename> on
524                 &debian; systems.</para>
525           </refsect1>
526           <refsect1>
527             <title>AUTHOR</title>
528
529             <para>This manual page was written by &dhusername; &dhemail; for
530               the &debian; system (but may be used by others).</para>
531
532             <!-- <para>Permission is granted to copy, distribute and/or modify
533             this document under the terms of the <acronym>GNU</acronym> Free
534             Documentation License, Version 1.1 or any later version
535             published by the Free Software Foundation; with no Invariant
536             Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy
537             of the license can be found under
538           <filename>/usr/share/common-licenses/FDL</filename>.</para> -->
539
540         </refsect1>
541       </refentry>
542
543         <!-- Keep this comment at the end of the file
544               Local variables:
545               mode: sgml
546               sgml-omittag:t
547               sgml-shorttag:t
548               sgml-minimize-attributes:nil
549               sgml-always-quote-attributes:t
550               sgml-indent-step:2
551               sgml-indent-data:t
552               sgml-parent-document:nil
553               sgml-default-dtd-file:nil
554               sgml-exposed-tags:nil
555               sgml-local-catalogs:nil
556               sgml-local-ecat-files:nil
557               End:
558               -->