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