add docs for -E 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).  May only be used when
116                     encoding a single file.  May not be used in
117                     conjunction with --output-prefix.</para>
118                 </listitem>
119               </varlistentry>
120
121               <varlistentry>
122                 <term><option>--output-prefix</option> <replaceable>string</replaceable></term>
123                 <listitem>
124                   <para>Prefix each output file name with the given
125                     string.  This can be useful for encoding/decoding
126                     files to a different directory.  Make sure if your
127                     string is a path name that it ends with a trailing
128                     `/' (slash).</para>
129                 </listitem>
130               </varlistentry>
131
132               <varlistentry>
133                 <term><option>--delete-input-file</option>
134                 </term>
135                 <listitem>
136                   <para>Automatically delete the input file after a
137                     successful encode or decode.  If there was an
138                     error (including a verify error) the input file
139                     is left intact.</para>
140                 </listitem>
141               </varlistentry>
142
143               <varlistentry>
144                 <term><option>--skip</option> <replaceable>samples</replaceable></term>
145                 <listitem>
146                   <para>Skip the specified number of samples at the
147                     beginning of the input file (can be used for both
148                     encoding and decoding)</para>
149                 </listitem>
150               </varlistentry>
151
152             </variablelist>
153           </refsect2>
154
155           <refsect2>
156             <title>Analysis Options</title>
157
158             <variablelist>
159               <varlistentry>
160                 <term><option>--a-rtext</option>
161                 </term>
162                 <listitem>
163                   <para>Includes the residual signal in the analysis
164                     file.  This will make the file very big, much
165                     larger than even the decoded file.</para>
166                 </listitem>
167               </varlistentry>
168
169               <varlistentry>
170                 <term><option>--a-rgp</option>
171                 </term>
172                 <listitem>
173                   <para>Generates a gnuplot file for every subframe;
174                     each file will contain the residual distribution
175                     of the subframe.  This will create a lot of
176                     files.</para>
177                 </listitem>
178               </varlistentry>
179
180             </variablelist>
181           </refsect2>
182
183           <refsect2>
184             <title>Encoding Options</title>
185
186             <variablelist>
187               <varlistentry>
188                 <term><option>--lax</option></term>
189
190                 <listitem>
191                   <para>Allow encoder to generate non-Subset
192                     files.</para>
193                 </listitem>
194               </varlistentry>
195
196               <varlistentry>
197                 <term><option>--sector-align</option></term>
198
199                 <listitem>
200                   <para>Align encoding of multiple CD format WAVE
201                     files on sector boundaries.  See the HTML
202                     documentation for more information.</para>
203                 </listitem>
204               </varlistentry>
205
206               <varlistentry>
207                 <term><option>-S</option> <replaceable>{ # | X | #x }</replaceable></term>
208
209                 <listitem>
210                   <para>
211                     Include a point or points in a SEEKTABLE.  Using #,
212                     a seek point at that sample number is added.  Using
213                     X, a placeholder point is added at the end of a the
214                     table.  Using #x, # evenly spaced seek points will
215                     be added, the first being at sample 0.  You may use
216                     many -S options; the resulting SEEKTABLE will be the
217                     unique-ified union of all such values.  With no -S
218                     options, flac defaults to '-S 100x'.  Use -S- for
219                     no SEEKTABLE.  Note: '-S #x' will not work if the
220                     encoder can't determine the input size before
221                     starting.  Note: if you use '-S #' and # is >=
222                     samples in the input, there will be either no seek
223                     point entered (if the input size is determinable
224                     before encoding starts) or a placeholder point (if
225                     input size is not determinable).</para>
226                 </listitem>
227               </varlistentry>
228
229               <varlistentry>
230                 <term><option>-P</option> <replaceable>bytes</replaceable></term>
231
232                 <listitem>
233                   <para>Tell the encoder to write a PADDING metadata
234                     block of the given length (in bytes) after the
235                     STREAMINFO block.  -P 0 implies no PADDING block,
236                     which is the default.  This is useful if you plan
237                     to tag the file later with an APPLICATION block;
238                     instead of having to rewrite the entire file later
239                     just to insert your block, you can write directly
240                     over the PADDING block.</para>
241                 </listitem>
242               </varlistentry>
243
244               <varlistentry>
245                 <term><option>-b</option> <replaceable>blocksize</replaceable></term>
246
247                 <listitem>
248                   <para>Default is 1152 for -l 0, else 4608; must be
249                     192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768
250                     (unless --lax is used)</para>
251                 </listitem>
252               </varlistentry>
253
254               <varlistentry>
255                 <term><option>-m</option></term>
256
257                 <listitem>
258                   <para>Try mid-side coding for each frame (stereo
259                     input only)</para>
260                 </listitem>
261               </varlistentry>
262
263               <varlistentry>
264                 <term><option>-m</option></term>
265
266                 <listitem>
267                   <para>Loose mid-side coding for all frames (stereo
268                     input only)</para>
269                 </listitem>
270               </varlistentry>
271
272               <varlistentry>
273                 <term><option>-0</option>..<option>-9</option></term>
274
275                 <listitem>
276                   <para>Fastest compression..highest compression
277                     (default is -5).  These are synonyms for other
278                     options:</para>
279
280                   <variablelist>
281                     <varlistentry>
282                       <term><option>-0</option></term>
283
284                       <listitem>
285                         <para>Synonymous with -l 0 -b 1152 -r 2,2
286                           </para>
287                       </listitem>
288                     </varlistentry>
289
290                     <varlistentry>
291                       <term><option>-1</option></term>
292
293                       <listitem>
294                         <para>Synonymous with -l 0 -b 1152 -M -r 2,2
295                           </para>
296                       </listitem>
297                     </varlistentry>
298
299                     <varlistentry>
300                       <term><option>-2</option></term>
301
302                       <listitem>
303                         <para>Synonymous with -l 0 -b 1152 -m -r 3
304                           </para>
305                       </listitem>
306                     </varlistentry>
307
308                     <varlistentry>
309                       <term><option>-3</option></term>
310
311                       <listitem>
312                         <para>Synonymous with -l 6 -b 4608 -r 3,3
313                           </para>
314                       </listitem>
315                     </varlistentry>
316
317                     <varlistentry>
318                       <term><option>-4</option></term>
319
320                       <listitem>
321                         <para>Synonymous with -l 8 -b 4608 -M -r 3,3
322                           </para>
323                       </listitem>
324                     </varlistentry>
325
326                     <varlistentry>
327                       <term><option>-5</option></term>
328
329                       <listitem>
330                         <para>Synonymous with -l 8 -b 4608 -m -r 3,3
331                           </para>
332                       </listitem>
333                     </varlistentry>
334
335                     <varlistentry>
336                       <term><option>-6</option></term>
337
338                       <listitem>
339                         <para>Synonymous with -l 8 -b 4608 -m -r 4
340                           </para>
341                       </listitem>
342                     </varlistentry>
343
344                     <varlistentry>
345                       <term><option>-7</option></term>
346
347                       <listitem>
348                         <para>Synonymous with -l 8 -b 4608 -m -e -r 6
349                           </para>
350                       </listitem>
351                     </varlistentry>
352
353                     <varlistentry>
354                       <term><option>-8</option></term>
355
356                       <listitem>
357                         <para>Synonymous with -l 12 -b 4608 -m -e -r 6
358                           </para>
359                       </listitem>
360                     </varlistentry>
361
362                     <varlistentry>
363                       <term><option>-9</option></term>
364
365                       <listitem>
366                         <para>Synonymous with -l 32 -b 4608 -m -e -E -r 16 -p
367                           (very slow!)</para>
368                       </listitem>
369                     </varlistentry>
370                   </variablelist>
371
372                 </listitem>
373
374
375               </varlistentry>
376
377               <varlistentry>
378                 <term><option>-e</option></term>
379
380                 <listitem>
381                   <para>Do exhaustive model search
382                     (expensive!)</para>
383                 </listitem>
384               </varlistentry>
385
386               <varlistentry>
387                 <term><option>-E</option></term>
388
389                 <listitem>
390                   <para>Do escape coding in the entropy coder.  This
391                     causes the encoder to use an unencoded representation
392                     of the residual in a partition if it is smaller.  It
393                     increases the runtime and usually results in an
394                     improvement of less than 1%.</para>
395                 </listitem>
396               </varlistentry>
397
398               <varlistentry>
399                 <term><option>-l</option> <replaceable>max_lpc_order</replaceable></term>
400
401                 <listitem>
402                   <para>0 => use only fixed predictors</para>
403                 </listitem>
404               </varlistentry>
405
406               <varlistentry>
407                 <term><option>-p</option></term>
408
409                 <listitem>
410                   <para>Do exhaustive search of LP coefficient
411                     quantization (expensive!).  Overrides -q,
412                     does nothing if using -l 0</para>
413                 </listitem>
414               </varlistentry>
415
416               <varlistentry>
417                 <term><option>-q</option> <replaceable>bits</replaceable></term>
418
419                 <listitem>
420                   <para>Precision of the quantized linear-predictor
421                     coefficients, 0 => let encoder decide (min is 5,
422                     default is 0)</para>
423                 </listitem>
424               </varlistentry>
425
426               <varlistentry>
427                 <term><option>-r</option> <replaceable>[level,]level</replaceable></term>
428
429                 <listitem>
430                   <para>Set the [min,]max residual partition order
431                     (0..16). min defaults to 0 if unspecified.  Default
432                     is -r 3,3.</para>
433                 </listitem>
434               </varlistentry>
435
436               <varlistentry>
437                 <term><option>-R</option> <replaceable>#</replaceable></term>
438
439                 <listitem>
440                   <para>Set the Rice parameter search distance.
441                     Default is 0.</para>
442                 </listitem>
443               </varlistentry>
444
445               <varlistentry>
446                 <term><option>-V</option></term>
447
448                 <listitem>
449                   <para>Verify a correct encoding by decoding the
450                     output in parallel and comparing to the
451                     original</para>
452                 </listitem>
453               </varlistentry>
454
455               <varlistentry>
456                 <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>
457                 </term>
458
459                 <listitem>
460                   <para>These flags can be used to invert the sense
461                     of the corresponding normal option.</para>
462                 </listitem>
463               </varlistentry>
464             </variablelist>
465
466           </refsect2>
467           <refsect2>
468             <title>Format Options</title>
469
470             <variablelist>
471               <varlistentry>
472                 <term><option>-fb</option></term>
473
474                 <listitem>
475                   <para>Big-endian byte order</para>
476                 </listitem>
477               </varlistentry>
478
479               <varlistentry>
480                 <term><option>-fl</option></term>
481
482                 <listitem>
483                   <para>Little-endian byte order</para>
484                 </listitem>
485               </varlistentry>
486
487               <varlistentry>
488                 <term><option>-fc</option>
489                   <replaceable>channels</replaceable></term>
490
491                 <listitem>
492                   <para>Set number of channels.</para>
493                 </listitem>
494               </varlistentry>
495
496               <varlistentry>
497                 <term><option>-fp</option>
498                   <replaceable>bits_per_sample</replaceable></term>
499
500                 <listitem>
501                   <para>Set bits per sample.</para>
502                 </listitem>
503               </varlistentry>
504
505               <varlistentry>
506                 <term><option>-fs</option>
507                   <replaceable>sample_rate</replaceable></term>
508
509                 <listitem>
510                   <para>Set sample rate (in Hz).</para>
511                 </listitem>
512               </varlistentry>
513
514               <varlistentry>
515                 <term><option>-fu</option></term>
516
517                 <listitem>
518                   <para>Unsigned samples (default is signed)</para>
519                 </listitem>
520               </varlistentry>
521
522               <varlistentry>
523                 <term><option>-fr</option></term>
524
525                 <listitem>
526                   <para>Force to raw format (even if filename ends
527                     in <filename>.wav</filename>).</para>
528                 </listitem>
529               </varlistentry>
530
531               <varlistentry>
532                 <term><option>-fw</option></term>
533
534                 <listitem>
535                   <para>Force to RIFF WAVE.</para>
536                 </listitem>
537               </varlistentry>
538
539             </variablelist>
540           </refsect2>
541
542         </refsect1>
543           <refsect1>
544             <title>SEE ALSO</title>
545
546             <para>The programs are documented fully by HTML format
547               documentation, available in
548               <filename>/usr/share/doc/flac/html</filename> on
549                 &debian; systems.</para>
550           </refsect1>
551           <refsect1>
552             <title>AUTHOR</title>
553
554             <para>This manual page was written by &dhusername; &dhemail; for
555               the &debian; system (but may be used by others).</para>
556
557             <!-- <para>Permission is granted to copy, distribute and/or modify
558             this document under the terms of the <acronym>GNU</acronym> Free
559             Documentation License, Version 1.1 or any later version
560             published by the Free Software Foundation; with no Invariant
561             Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy
562             of the license can be found under
563           <filename>/usr/share/common-licenses/FDL</filename>.</para> -->
564
565         </refsect1>
566       </refentry>
567
568         <!-- Keep this comment at the end of the file
569               Local variables:
570               mode: sgml
571               sgml-omittag:t
572               sgml-shorttag:t
573               sgml-minimize-attributes:nil
574               sgml-always-quote-attributes:t
575               sgml-indent-step:2
576               sgml-indent-data:t
577               sgml-parent-document:nil
578               sgml-default-dtd-file:nil
579               sgml-exposed-tags:nil
580               sgml-local-catalogs:nil
581               sgml-local-ecat-files:nil
582               End:
583               -->