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