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