b23d2df0c2496bd5ed22c943dffeefb62feb5405
[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>August 13, 2002</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>2002</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>-h</option>, <option>--help</option>
78                 </term>
79                 <listitem>
80                   <para>Show basic usage and a list of all options</para>
81                 </listitem>
82               </varlistentry>
83
84               <varlistentry>
85                 <term><option>-H</option>, <option>--explain</option>
86                 </term>
87                 <listitem>
88                   <para>Show detailed explanation of usage and all options</para>
89                 </listitem>
90               </varlistentry>
91
92               <varlistentry>
93                 <term><option>-d</option>, <option>--decode</option>
94                 </term>
95                 <listitem>
96                   <para>Decode (the default behavior is to encode)</para>
97                 </listitem>
98               </varlistentry>
99
100               <varlistentry>
101                 <term><option>-t</option>, <option>--test</option>
102                 </term>
103                 <listitem>
104                   <para>Test a flac encoded file (same as -d
105                     except no decoded file is written)</para>
106                 </listitem>
107               </varlistentry>
108
109               <varlistentry>
110                 <term><option>-a</option>, <option>--analyze</option>
111                 </term>
112                 <listitem>
113                   <para>Analyze a flac encoded file (same as -d
114                     except an analysis file is written)</para>
115                 </listitem>
116               </varlistentry>
117
118               <varlistentry>
119                 <term><option>-c</option>, <option>--stdout</option>
120                 </term>
121                 <listitem>
122                   <para>Write output to stdout</para>
123                 </listitem>
124               </varlistentry>
125
126               <varlistentry>
127                 <term><option>-s</option>, <option>--silent</option>
128                 </term>
129                 <listitem>
130                   <para>Silent mode (do not write runtime
131                     encode/decode statistics to stderr)</para>
132                 </listitem>
133               </varlistentry>
134
135               <varlistentry>
136                 <term><option>-o</option> <replaceable>filename</replaceable>, <option>--output-name</option>=<replaceable>filename</replaceable></term>
137                 <listitem>
138                   <para>Force the output file name (usually flac just
139                     changes the extension).  May only be used when
140                     encoding a single file.  May not be used in
141                     conjunction with --output-prefix.</para>
142                 </listitem>
143               </varlistentry>
144
145               <varlistentry>
146                 <term><option>--output-prefix</option>=<replaceable>string</replaceable></term>
147                 <listitem>
148                   <para>Prefix each output file name with the given
149                     string.  This can be useful for encoding or decoding
150                     files to a different directory.  Make sure if your
151                     string is a path name that it ends with a trailing
152                     `/' (slash).</para>
153                 </listitem>
154               </varlistentry>
155
156               <varlistentry>
157                 <term><option>--delete-input-file</option>
158                 </term>
159                 <listitem>
160                   <para>Automatically delete the input file after a
161                     successful encode or decode.  If there was an
162                     error (including a verify error) the input file
163                     is left intact.</para>
164                 </listitem>
165               </varlistentry>
166
167               <varlistentry>
168                 <term><option>--skip</option>=<replaceable>#</replaceable></term>
169                 <listitem>
170                   <para>Skip the specified number of samples at the
171                     beginning of the input file (can be used for both
172                     encoding and decoding)</para>
173                 </listitem>
174               </varlistentry>
175
176             </variablelist>
177           </refsect2>
178
179           <refsect2>
180             <title>Analysis Options</title>
181
182             <variablelist>
183               <varlistentry>
184                 <term><option>--residual-text</option>
185                 </term>
186                 <listitem>
187                   <para>Includes the residual signal in the analysis
188                     file.  This will make the file very big, much
189                     larger than even the decoded file.</para>
190                 </listitem>
191               </varlistentry>
192
193               <varlistentry>
194                 <term><option>--residual-gnuplot</option>
195                 </term>
196                 <listitem>
197                   <para>Generates a gnuplot file for every subframe;
198                     each file will contain the residual distribution
199                     of the subframe.  This will create a lot of
200                     files.</para>
201                 </listitem>
202               </varlistentry>
203
204             </variablelist>
205           </refsect2>
206
207           <refsect2>
208             <title>Decoding Options</title>
209
210             <variablelist>
211               <varlistentry>
212                 <term><option>-F</option>, <option>--decode-through-errors</option>
213                 </term>
214                 <listitem>
215                   <para>By default flac stops decoding with an error
216                     and removes the partially decoded file if it
217                     encounters a bitstream error.  With -F, errors are
218                     still printed but flac will continue decoding to
219                     completion.  Note that errors may cause the decoded
220                     audio to be missing some samples or have silent
221                     sections.</para>
222                 </listitem>
223               </varlistentry>
224
225             </variablelist>
226           </refsect2>
227
228           <refsect2>
229             <title>Encoding Options</title>
230
231             <variablelist>
232               <varlistentry>
233                 <term><option>-V</option>, <option>--verify</option></term>
234
235                 <listitem>
236                   <para>Verify a correct encoding by decoding the
237                     output in parallel and comparing to the
238                     original</para>
239                 </listitem>
240               </varlistentry>
241
242               <varlistentry>
243                 <term><option>--ogg</option></term>
244
245                 <listitem>
246                   <para>When encoding, generate Ogg-FLAC output instead
247                     of native-FLAC.  Ogg-FLAC streams are FLAC streams
248                     wrapped in an Ogg transport layer.  The resulting
249                     file should have an '.ogg' extension and will still
250                     be decodable by flac.</para>
251                   <para>When decoding, force the input to be treated as
252                     Ogg-FLAC.  This is useful when piping input from
253                     stdin or when the filename does not end in '.ogg'.</para>
254                 </listitem>
255               </varlistentry>
256
257               <varlistentry>
258                 <term><option>--lax</option></term>
259
260                 <listitem>
261                   <para>Allow encoder to generate non-Subset
262                     files.</para>
263                 </listitem>
264               </varlistentry>
265
266               <varlistentry>
267                 <term><option>--sector-align</option></term>
268
269                 <listitem>
270                   <para>Align encoding of multiple CD format WAVE
271                     files on sector boundaries.  See the HTML
272                     documentation for more information.</para>
273                 </listitem>
274               </varlistentry>
275
276               <varlistentry>
277                 <term><option>-S</option> {<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}, <option>--seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}</term>
278
279                 <listitem>
280                   <para>
281                     Include a point or points in a SEEKTABLE.  Using #,
282                     a seek point at that sample number is added.  Using
283                     X, a placeholder point is added at the end of a the
284                     table.  Using #x, # evenly spaced seek points will
285                     be added, the first being at sample 0.  You may use
286                     many -S options; the resulting SEEKTABLE will be the
287                     unique-ified union of all such values.  With no -S
288                     options, flac defaults to '-S 100x'.  Use -S- for
289                     no SEEKTABLE.  Note: '-S #x' will not work if the
290                     encoder can't determine the input size before
291                     starting.  Note: if you use '-S #' and # is >=
292                     samples in the input, there will be either no seek
293                     point entered (if the input size is determinable
294                     before encoding starts) or a placeholder point (if
295                     input size is not determinable).</para>
296                 </listitem>
297               </varlistentry>
298
299               <varlistentry>
300                 <term><option>-P</option> <replaceable>#</replaceable>, <option>--padding</option>=<replaceable>#</replaceable></term>
301
302                 <listitem>
303                   <para>Tell the encoder to write a PADDING metadata
304                     block of the given length (in bytes) after the
305                     STREAMINFO block.  This is useful if you plan to
306                     tag the file later with an APPLICATION block;
307                     instead of having to rewrite the entire file later
308                     just to insert your block, you can write directly
309                     over the PADDING block.  Note that the total length
310                     of the PADDING block will be 4 bytes longer than
311                     the length given because of the 4 metadata block
312                     header bytes.  You can force no PADDING block at
313                     all to be written with -P-, which is the default.
314                     </para>
315                 </listitem>
316               </varlistentry>
317
318               <varlistentry>
319                 <term><option>-b</option> <replaceable>#</replaceable>, <option>--blocksize</option>=<replaceable>#</replaceable></term>
320
321                 <listitem>
322                   <para>Specify the block size in samples.  The
323                     default is 1152 for -l 0, else 4608; must be one of
324                     192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
325                     4096, 8192, 16384, or 32768 (unless --lax is used)</para>
326                 </listitem>
327               </varlistentry>
328
329               <varlistentry>
330                 <term><option>-m</option>, <option>--mid-side</option></term>
331
332                 <listitem>
333                   <para>Try mid-side coding for each frame (stereo
334                     input only)</para>
335                 </listitem>
336               </varlistentry>
337
338               <varlistentry>
339                 <term><option>-M</option>, <option>--adaptive-mid-side</option></term>
340
341                 <listitem>
342                   <para>Adaptive mid-side coding for all frames (stereo
343                     input only)</para>
344                 </listitem>
345               </varlistentry>
346
347               <varlistentry>
348                 <term><option>-0</option>..<option>-8</option>, <option>--compression-level-0</option>..<option>--compression-level-8</option></term>
349
350                 <listitem>
351                   <para>Fastest compression..highest compression
352                     (default is -5).  These are synonyms for other
353                     options:</para>
354
355                   <variablelist>
356                     <varlistentry>
357                       <term><option>-0</option>, <option>--compression-level-0</option></term>
358
359                       <listitem>
360                         <para>Synonymous with -l 0 -b 1152 -r 2,2
361                           </para>
362                       </listitem>
363                     </varlistentry>
364
365                     <varlistentry>
366                       <term><option>-1</option>, <option>--compression-level-1</option></term>
367
368                       <listitem>
369                         <para>Synonymous with -l 0 -b 1152 -M -r 2,2
370                           </para>
371                       </listitem>
372                     </varlistentry>
373
374                     <varlistentry>
375                       <term><option>-2</option>, <option>--compression-level-2</option></term>
376
377                       <listitem>
378                         <para>Synonymous with -l 0 -b 1152 -m -r 3
379                           </para>
380                       </listitem>
381                     </varlistentry>
382
383                     <varlistentry>
384                       <term><option>-3</option>, <option>--compression-level-3</option></term>
385
386                       <listitem>
387                         <para>Synonymous with -l 6 -b 4608 -r 3,3
388                           </para>
389                       </listitem>
390                     </varlistentry>
391
392                     <varlistentry>
393                       <term><option>-4</option>, <option>--compression-level-4</option></term>
394
395                       <listitem>
396                         <para>Synonymous with -l 8 -b 4608 -M -r 3,3
397                           </para>
398                       </listitem>
399                     </varlistentry>
400
401                     <varlistentry>
402                       <term><option>-5</option>, <option>--compression-level-5</option></term>
403
404                       <listitem>
405                         <para>Synonymous with -l 8 -b 4608 -m -r 3,3
406                           </para>
407                       </listitem>
408                     </varlistentry>
409
410                     <varlistentry>
411                       <term><option>-6</option>, <option>--compression-level-6</option></term>
412
413                       <listitem>
414                         <para>Synonymous with -l 8 -b 4608 -m -r 4
415                           </para>
416                       </listitem>
417                     </varlistentry>
418
419                     <varlistentry>
420                       <term><option>-7</option>, <option>--compression-level-7</option></term>
421
422                       <listitem>
423                         <para>Synonymous with -l 8 -b 4608 -m -e -r 6
424                           </para>
425                       </listitem>
426                     </varlistentry>
427
428                     <varlistentry>
429                       <term><option>-8</option>, <option>--compression-level-8</option></term>
430
431                       <listitem>
432                         <para>Synonymous with -l 12 -b 4608 -m -e -r 6
433                           </para>
434                       </listitem>
435                     </varlistentry>
436                   </variablelist>
437
438                 </listitem>
439
440               </varlistentry>
441
442               <varlistentry>
443                 <term><option>--fast</option></term>
444
445                 <listitem>
446                   <para>Fastest compression.  Currently
447                     synonymous with -0.</para>
448                 </listitem>
449               </varlistentry>
450
451               <varlistentry>
452                 <term><option>--best</option></term>
453
454                 <listitem>
455                   <para>Highest compression.  Currently
456                     synonymous with -8.</para>
457                 </listitem>
458               </varlistentry>
459
460               <varlistentry>
461                 <term><option>-e</option>, <option>--exhaustive-model-search</option></term>
462
463                 <listitem>
464                   <para>Do exhaustive model search
465                     (expensive!)</para>
466                 </listitem>
467               </varlistentry>
468
469               <varlistentry>
470                 <term><option>-E</option>, <option>--escape-coding</option></term>
471
472                 <listitem>
473                   <para>Do escape coding in the entropy coder.  This
474                     causes the encoder to use an unencoded representation
475                     of the residual in a partition if it is smaller.  It
476                     increases the runtime and usually results in an
477                     improvement of less than 1%.</para>
478                 </listitem>
479               </varlistentry>
480
481               <varlistentry>
482                 <term><option>-l</option> <replaceable>#</replaceable>, <option>--max-lpc-order</option>=<replaceable>#</replaceable></term>
483
484                 <listitem>
485                   <para>Set the maximum LPC order; 0 means use only the fixed predictors</para>
486                 </listitem>
487               </varlistentry>
488
489               <varlistentry>
490                 <term><option>-p</option>, <option>--qlp-coeff-precision-search</option></term>
491
492                 <listitem>
493                   <para>Do exhaustive search of LP coefficient
494                     quantization (expensive!).  Overrides -q;
495                     does nothing if using -l 0</para>
496                 </listitem>
497               </varlistentry>
498
499               <varlistentry>
500                 <term><option>-q</option> <replaceable>#</replaceable>, <option>--qlp-coeff-precision</option>=<replaceable>#</replaceable></term>
501
502                 <listitem>
503                   <para>Precision of the quantized linear-predictor
504                     coefficients, 0 => let encoder decide (min is 5,
505                     default is 0)</para>
506                 </listitem>
507               </varlistentry>
508
509               <varlistentry>
510                 <term><option>-r</option> [<replaceable>#</replaceable>,]<replaceable>#</replaceable>, <option>--rice-partition-order</option>=[<replaceable>#</replaceable>,]<replaceable>#</replaceable></term>
511
512                 <listitem>
513                   <para>Set the [min,]max residual partition order
514                     (0..16). min defaults to 0 if unspecified.  Default
515                     is -r 3,3.</para>
516                 </listitem>
517               </varlistentry>
518
519             </variablelist>
520
521           </refsect2>
522           <refsect2>
523             <title>Format Options</title>
524
525             <variablelist>
526               <varlistentry>
527                 <term><option>--endian</option>={<replaceable>big</replaceable>|<replaceable>little</replaceable>}</term>
528
529                 <listitem>
530                   <para>Set the byte order for samples</para>
531                 </listitem>
532               </varlistentry>
533
534               <varlistentry>
535                 <term><option>--channels</option>=<replaceable>#</replaceable></term>
536
537                 <listitem>
538                   <para>Set number of channels.</para>
539                 </listitem>
540               </varlistentry>
541
542               <varlistentry>
543                 <term><option>--bps</option>=<replaceable>#</replaceable></term>
544
545                 <listitem>
546                   <para>Set bits per sample.</para>
547                 </listitem>
548               </varlistentry>
549
550               <varlistentry>
551                 <term><option>--sample-rate</option>=<replaceable>#</replaceable></term>
552
553                 <listitem>
554                   <para>Set sample rate (in Hz).</para>
555                 </listitem>
556               </varlistentry>
557
558               <varlistentry>
559                 <term><option>--sign</option>={<replaceable>signed</replaceable>|<replaceable>unsigned</replaceable>}</term>
560
561                 <listitem>
562                   <para>Set the sign of samples (the default is signed).</para>
563                 </listitem>
564               </varlistentry>
565
566               <varlistentry>
567                 <term><option>--force-raw-input</option></term>
568
569                 <listitem>
570                   <para>Force input to be treated as raw samples (even if filename ends
571                     in <filename>.wav</filename>).</para>
572                 </listitem>
573               </varlistentry>
574
575             </variablelist>
576           </refsect2>
577
578           <refsect2>
579             <title>Negative Options</title>
580
581             <variablelist>
582               <varlistentry>
583                 <term><option>--no-adaptive-mid-side</option></term>
584                 <term><option>--no-decode-through-errors</option></term>
585                 <term><option>--no-delete-input-file</option></term>
586                 <term><option>--no-escape-coding</option></term>
587                 <term><option>--no-exhaustive-model-search</option></term>
588                 <term><option>--no-lax</option></term>
589                 <term><option>--no-mid-side</option></term>
590                 <term><option>--no-ogg</option></term>
591                 <term><option>--no-padding</option></term>
592                 <term><option>--no-qlp-coeff-precision-search</option></term>
593                 <term><option>--no-residual-gnuplot</option></term>
594                 <term><option>--no-residual-text</option></term>
595                 <term><option>--no-sector-align</option></term>
596                 <term><option>--no-seektable</option></term>
597                 <term><option>--no-silent</option></term>
598                 <term><option>--no-verify</option></term>
599                 <listitem>
600                   <para>These flags can be used to invert the sense
601                     of the corresponding normal option.</para>
602                 </listitem>
603               </varlistentry>
604             </variablelist>
605
606           </refsect2>
607
608         </refsect1>
609           <refsect1>
610             <title>SEE ALSO</title>
611
612             <para>The programs are documented fully by HTML format
613               documentation, available in
614               <filename>/usr/share/doc/flac/html</filename> on
615                 &debian; systems.</para>
616           </refsect1>
617           <refsect1>
618             <title>AUTHOR</title>
619
620             <para>This manual page was written by &dhusername; &dhemail; for
621               the &debian; system (but may be used by others).</para>
622
623             <!-- <para>Permission is granted to copy, distribute and/or modify
624             this document under the terms of the <acronym>GNU</acronym> Free
625             Documentation License, Version 1.1 or any later version
626             published by the Free Software Foundation; with no Invariant
627             Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy
628             of the license can be found under
629           <filename>/usr/share/common-licenses/FDL</filename>.</para> -->
630
631         </refsect1>
632       </refentry>
633
634         <!-- Keep this comment at the end of the file
635               Local variables:
636               mode: sgml
637               sgml-omittag:t
638               sgml-shorttag:t
639               sgml-minimize-attributes:nil
640               sgml-always-quote-attributes:t
641               sgml-indent-step:2
642               sgml-indent-data:t
643               sgml-parent-document:nil
644               sgml-default-dtd-file:nil
645               sgml-exposed-tags:nil
646               sgml-local-catalogs:nil
647               sgml-local-ecat-files:nil
648               End:
649               -->