flac.sgml 14.9 KB
Newer Older
Josh Coalson's avatar
Josh Coalson committed
1
2
3
4
5
6
<!doctype refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Matt</firstname>">
  <!ENTITY dhsurname   "<surname>Zimmerman</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
Josh Coalson's avatar
Josh Coalson committed
7
  <!ENTITY dhdate      "<date>June 26, 2001</date>">
Josh Coalson's avatar
Josh Coalson committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>mdz@debian.org</email>">
  <!ENTITY dhusername  "Matt Zimmerman">
  <!ENTITY dhucpackage "<refentrytitle>FLAC</refentrytitle>">
  <!ENTITY dhpackage   "flac">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <docinfo>
    <address>
	&dhemail;
    </address>
    <author>
	&dhfirstname;
	&dhsurname;
      </author>
	<copyright>
Josh Coalson's avatar
Josh Coalson committed
30
		    <year>2001</year>
Josh Coalson's avatar
Josh Coalson committed
31
32
33
34
35
36
37
38
39
40
41
42
		    <holder>&dhusername;</holder>
	</copyright>
	    &dhdate;
	</docinfo>
  <refmeta>
      &dhucpackage;

      &dhsection;
    </refmeta>
      <refnamediv>
		   <refname>&dhpackage;</refname>

43
	<refpurpose>Free Lossless Audio Codec</refpurpose>
Josh Coalson's avatar
Josh Coalson committed
44
45
46
47
48
49
50
      </refnamediv>
	<refsynopsisdiv>
	  <cmdsynopsis>
	    <command>flac</command>

	    <arg><option><replaceable>OPTION</replaceable></option></arg>
	    <arg choice=plain><replaceable>infile</replaceable></arg>
51
	    <arg choice=plain><replaceable>...</replaceable></arg>
Josh Coalson's avatar
Josh Coalson committed
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
	  </cmdsynopsis>
	</refsynopsisdiv>
	<refsect1>
	  <title>DESCRIPTION</title>

	  <para>This manual page documents briefly the
	    <command>flac</command> command.</para>

	  <para>This manual page was written for the &debian;
	    distribution because the original program does not have a
	    manual page.  Instead, it has documentation in HTML
	    format; see below.</para>

	</refsect1>
	<refsect1>
	  <title>OPTIONS</title>

	  <para>A summary of options is included below.  For a complete
	  description, see the HTML documentation.</para>

	  <refsect2>
	    <title>Generic Options</title>

	    <variablelist>
	      <varlistentry>
		<term><option>-d</option>
		</term>
		<listitem>
		  <para>Decode (default behavior is encode)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-t</option>
		</term>
		<listitem>
		  <para>Test a flac encoded file (same as -d
		    except no decoded file is written)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-a</option>
		</term>
		<listitem>
		  <para>Analyze a flac encoded file (same as -d
		    except an analysis file is written)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-s</option>
		</term>
		<listitem>
		  <para>Silent mode (do not write runtime
		    encode/decode statistics to stdout)</para>
		</listitem>
	      </varlistentry>

111
112
113
114
	      <varlistentry>
		<term><option>-o</option> <replaceable>filename</replaceable></term>
		<listitem>
		  <para>Force the output file name (usually flac just
Josh Coalson's avatar
Josh Coalson committed
115
116
117
118
119
120
121
122
123
124
125
126
127
128
		    changes the extension).  May only be used when
		    encoding a single file.  May not be used in
		    conjunction with --output-prefix.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>--output-prefix</option> <replaceable>string</replaceable></term>
		<listitem>
		  <para>Prefix each output file name with the given
		    string.  This can be useful for encoding/decoding
		    files to a different directory.  Make sure if your
		    string is a path name that it ends with a trailing
		    `/' (slash).</para>
129
130
131
132
133
134
135
136
137
138
139
140
141
142
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>--delete-input-file</option>
		</term>
		<listitem>
		  <para>Automatically delete the input file after a
		    successful encode or decode.  If there was an
		    error (including a verify error) the input file
		    is left intact.</para>
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
143
144
145
146
147
148
149
150
151
152
153
154
	      <varlistentry>
		<term><option>--skip</option> <replaceable>samples</replaceable></term>
		<listitem>
		  <para>Skip the specified number of samples at the
		    beginning of the input file (can be used for both
		    encoding and decoding)</para>
		</listitem>
	      </varlistentry>

	    </variablelist>
	  </refsect2>

Josh Coalson's avatar
Josh Coalson committed
155
156
157
158
159
	  <refsect2>
	    <title>Analysis Options</title>

	    <variablelist>
	      <varlistentry>
Josh Coalson's avatar
Josh Coalson committed
160
		<term><option>--a-rtext</option>
Josh Coalson's avatar
Josh Coalson committed
161
162
		</term>
		<listitem>
Josh Coalson's avatar
Josh Coalson committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
		  <para>Includes the residual signal in the analysis
		    file.  This will make the file very big, much
		    larger than even the decoded file.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>--a-rgp</option>
		</term>
		<listitem>
		  <para>Generates a gnuplot file for every subframe;
		    each file will contain the residual distribution
		    of the subframe.  This will create a lot of
		    files.</para>
Josh Coalson's avatar
Josh Coalson committed
177
178
179
180
181
182
		</listitem>
	      </varlistentry>

	    </variablelist>
	  </refsect2>

Josh Coalson's avatar
Josh Coalson committed
183
184
185
186
187
188
189
190
191
	  <refsect2>
	    <title>Encoding Options</title>

	    <variablelist>
	      <varlistentry>
		<term><option>--lax</option></term>

		<listitem>
		  <para>Allow encoder to generate non-Subset
Josh Coalson's avatar
Josh Coalson committed
192
193
194
195
196
197
198
199
200
201
202
		    files.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>--sector-align</option></term>

		<listitem>
		  <para>Align encoding of multiple CD format WAVE
		    files on sector boundaries.  See the HTML
		    documentation for more information.</para>
Josh Coalson's avatar
Josh Coalson committed
203
204
205
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
	      <varlistentry>
		<term><option>-S</option> <replaceable>{ # | X | #x }</replaceable></term>

		<listitem>
		  <para>
		    Include a point or points in a SEEKTABLE.  Using #,
		    a seek point at that sample number is added.  Using
		    X, a placeholder point is added at the end of a the
		    table.  Using #x, # evenly spaced seek points will
		    be added, the first being at sample 0.  You may use
		    many -S options; the resulting SEEKTABLE will be the
		    unique-ified union of all such values.  With no -S
		    options, flac defaults to '-S 100x'.  Use -S- for
		    no SEEKTABLE.  Note: '-S #x' will not work if the
		    encoder can't determine the input size before
		    starting.  Note: if you use '-S #' and # is >=
		    samples in the input, there will be either no seek
		    point entered (if the input size is determinable
		    before encoding starts) or a placeholder point (if
Josh Coalson's avatar
Josh Coalson committed
225
		    input size is not determinable).</para>
Josh Coalson's avatar
Josh Coalson committed
226
227
228
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
	      <varlistentry>
		<term><option>-P</option> <replaceable>bytes</replaceable></term>

		<listitem>
		  <para>Tell the encoder to write a PADDING metadata
		    block of the given length (in bytes) after the
		    STREAMINFO block.  -P 0 implies no PADDING block,
		    which is the default.  This is useful if you plan
		    to tag the file later with an APPLICATION block;
		    instead of having to rewrite the entire file later
		    just to insert your block, you can write directly
		    over the PADDING block.</para>
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
244
245
246
247
	      <varlistentry>
		<term><option>-b</option> <replaceable>blocksize</replaceable></term>

		<listitem>
Josh Coalson's avatar
Josh Coalson committed
248
249
250
		  <para>Default is 1152 for -l 0, else 4608; must be
		    192/576/1152/2304/4608/256/512/1024/2048/4096/8192/16384/32768
		    (unless --lax is used)</para>
Josh Coalson's avatar
Josh Coalson committed
251
252
253
254
255
256
257
258
259
260
261
262
263
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-m</option></term>

		<listitem>
		  <para>Try mid-side coding for each frame (stereo
		    input only)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
264
		<term><option>-M</option></term>
Josh Coalson's avatar
Josh Coalson committed
265
266
267
268
269
270
271
272
273
274
275
276

		<listitem>
		  <para>Loose mid-side coding for all frames (stereo
		    input only)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-0</option>..<option>-9</option></term>

		<listitem>
		  <para>Fastest compression..highest compression
Josh Coalson's avatar
Josh Coalson committed
277
		    (default is -5).  These are synonyms for other
Josh Coalson's avatar
Josh Coalson committed
278
279
280
281
282
		    options:</para>

		  <variablelist>
		    <varlistentry>
		      <term><option>-0</option></term>
Josh Coalson's avatar
Josh Coalson committed
283

Josh Coalson's avatar
Josh Coalson committed
284
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
285
286
			<para>Synonymous with -l 0 -b 1152 -r 2,2
			  </para>
Josh Coalson's avatar
Josh Coalson committed
287
288
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
289

Josh Coalson's avatar
Josh Coalson committed
290
291
		    <varlistentry>
		      <term><option>-1</option></term>
Josh Coalson's avatar
Josh Coalson committed
292

Josh Coalson's avatar
Josh Coalson committed
293
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
294
295
			<para>Synonymous with -l 0 -b 1152 -M -r 2,2
			  </para>
Josh Coalson's avatar
Josh Coalson committed
296
297
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
298

Josh Coalson's avatar
Josh Coalson committed
299
300
		    <varlistentry>
		      <term><option>-2</option></term>
Josh Coalson's avatar
Josh Coalson committed
301

Josh Coalson's avatar
Josh Coalson committed
302
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
303
304
			<para>Synonymous with -l 0 -b 1152 -m -r 3
			  </para>
Josh Coalson's avatar
Josh Coalson committed
305
306
307
308
309
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-3</option></term>
Josh Coalson's avatar
Josh Coalson committed
310

Josh Coalson's avatar
Josh Coalson committed
311
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
312
313
			<para>Synonymous with -l 6 -b 4608 -r 3,3
			  </para>
Josh Coalson's avatar
Josh Coalson committed
314
315
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
316

Josh Coalson's avatar
Josh Coalson committed
317
318
		    <varlistentry>
		      <term><option>-4</option></term>
Josh Coalson's avatar
Josh Coalson committed
319

Josh Coalson's avatar
Josh Coalson committed
320
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
321
322
			<para>Synonymous with -l 8 -b 4608 -M -r 3,3
			  </para>
Josh Coalson's avatar
Josh Coalson committed
323
324
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
325

Josh Coalson's avatar
Josh Coalson committed
326
327
		    <varlistentry>
		      <term><option>-5</option></term>
Josh Coalson's avatar
Josh Coalson committed
328

Josh Coalson's avatar
Josh Coalson committed
329
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
330
331
			<para>Synonymous with -l 8 -b 4608 -m -r 3,3
			  </para>
Josh Coalson's avatar
Josh Coalson committed
332
333
334
335
336
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-6</option></term>
Josh Coalson's avatar
Josh Coalson committed
337

Josh Coalson's avatar
Josh Coalson committed
338
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
339
340
			<para>Synonymous with -l 8 -b 4608 -m -r 4
			  </para>
Josh Coalson's avatar
Josh Coalson committed
341
342
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
343

Josh Coalson's avatar
Josh Coalson committed
344
345
		    <varlistentry>
		      <term><option>-7</option></term>
Josh Coalson's avatar
Josh Coalson committed
346

Josh Coalson's avatar
Josh Coalson committed
347
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
348
349
			<para>Synonymous with -l 8 -b 4608 -m -e -r 6
			  </para>
Josh Coalson's avatar
Josh Coalson committed
350
351
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
352

Josh Coalson's avatar
Josh Coalson committed
353
354
		    <varlistentry>
		      <term><option>-8</option></term>
Josh Coalson's avatar
Josh Coalson committed
355

Josh Coalson's avatar
Josh Coalson committed
356
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
357
358
			<para>Synonymous with -l 12 -b 4608 -m -e -r 6
			  </para>
Josh Coalson's avatar
Josh Coalson committed
359
360
		      </listitem>
		    </varlistentry>
Josh Coalson's avatar
Josh Coalson committed
361

Josh Coalson's avatar
Josh Coalson committed
362
363
		    <varlistentry>
		      <term><option>-9</option></term>
Josh Coalson's avatar
Josh Coalson committed
364

Josh Coalson's avatar
Josh Coalson committed
365
		      <listitem>
Josh Coalson's avatar
Josh Coalson committed
366
			<para>Synonymous with -l 32 -b 4608 -m -e -E -r 16 -p
Josh Coalson's avatar
Josh Coalson committed
367
368
369
370
			  (very slow!)</para>
		      </listitem>
		    </varlistentry>
		  </variablelist>
Josh Coalson's avatar
Josh Coalson committed
371

Josh Coalson's avatar
Josh Coalson committed
372
373
374
375
376
377
378
379
380
381
382
383
384
385
		</listitem>


	      </varlistentry>

	      <varlistentry>
		<term><option>-e</option></term>

		<listitem>
		  <para>Do exhaustive model search
		    (expensive!)</para>
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
386
387
388
389
390
391
392
393
394
395
396
397
	      <varlistentry>
		<term><option>-E</option></term>

		<listitem>
		  <para>Do escape coding in the entropy coder.  This
		    causes the encoder to use an unencoded representation
		    of the residual in a partition if it is smaller.  It
		    increases the runtime and usually results in an
		    improvement of less than 1%.</para>
		</listitem>
	      </varlistentry>

Josh Coalson's avatar
Josh Coalson committed
398
399
400
401
402
403
404
405
406
407
408
409
410
	      <varlistentry>
		<term><option>-l</option> <replaceable>max_lpc_order</replaceable></term>

		<listitem>
		  <para>0 => use only fixed predictors</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-p</option></term>

		<listitem>
		  <para>Do exhaustive search of LP coefficient
Josh Coalson's avatar
Josh Coalson committed
411
412
		    quantization (expensive!).  Overrides -q,
		    does nothing if using -l 0</para>
Josh Coalson's avatar
Josh Coalson committed
413
414
415
416
417
418
419
420
421
422
423
424
425
426
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-q</option> <replaceable>bits</replaceable></term>

		<listitem>
		  <para>Precision of the quantized linear-predictor
		    coefficients, 0 => let encoder decide (min is 5,
		    default is 0)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
Josh Coalson's avatar
Josh Coalson committed
427
428
429
430
431
432
433
434
435
436
437
		<term><option>-r</option> <replaceable>[level,]level</replaceable></term>

		<listitem>
		  <para>Set the [min,]max residual partition order
		    (0..16). min defaults to 0 if unspecified.  Default
		    is -r 3,3.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-R</option> <replaceable>#</replaceable></term>
Josh Coalson's avatar
Josh Coalson committed
438
439

		<listitem>
Josh Coalson's avatar
Josh Coalson committed
440
441
		  <para>Set the Rice parameter search distance.
		    Default is 0.</para>
Josh Coalson's avatar
Josh Coalson committed
442
443
444
445
446
447
448
449
450
451
452
453
454
455
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-V</option></term>

		<listitem>
		  <para>Verify a correct encoding by decoding the
		    output in parallel and comparing to the
		    original</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
Josh Coalson's avatar
Josh Coalson committed
456
		<term><option>-S-</option> <option>-m-</option> <option>-M-</option> <option>-e-</option> <option>-E-</option> <option>-p-</option> <option>-V-</option> <option>--delete-input-file-</option> <option>--lax-</option>
Josh Coalson's avatar
Josh Coalson committed
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
		</term>

		<listitem>
		  <para>These flags can be used to invert the sense
		    of the corresponding normal option.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>

	  </refsect2>
	  <refsect2>
	    <title>Format Options</title>

	    <variablelist>
	      <varlistentry>
		<term><option>-fb</option></term>

		<listitem>
		  <para>Big-endian byte order</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fl</option></term>

		<listitem>
		  <para>Little-endian byte order</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fc</option>
		  <replaceable>channels</replaceable></term>

		<listitem>
		  <para>Set number of channels.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fp</option>
		  <replaceable>bits_per_sample</replaceable></term>

		<listitem>
		  <para>Set bits per sample.</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fs</option>
		  <replaceable>sample_rate</replaceable></term>

		<listitem>
		  <para>Set sample rate (in Hz).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fu</option></term>

		<listitem>
		  <para>Unsigned samples (default is signed)</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fr</option></term>

		<listitem>
		  <para>Force to raw format (even if filename ends
		    in <filename>.wav</filename>).</para>
		</listitem>
	      </varlistentry>

	      <varlistentry>
		<term><option>-fw</option></term>

		<listitem>
		  <para>Force to RIFF WAVE.</para>
		</listitem>
	      </varlistentry>

	    </variablelist>
	  </refsect2>

	</refsect1>
	  <refsect1>
	    <title>SEE ALSO</title>

	    <para>The programs are documented fully by HTML format
	      documentation, available in
	      <filename>/usr/share/doc/flac/html</filename> on
		&debian; systems.</para>
	  </refsect1>
	  <refsect1>
	    <title>AUTHOR</title>

	    <para>This manual page was written by &dhusername; &dhemail; for
	      the &debian; system (but may be used by others).</para>

	    <!-- <para>Permission is granted to copy, distribute and/or modify
	    this document under the terms of the <acronym>GNU</acronym> Free
	    Documentation License, Version 1.1 or any later version
	    published by the Free Software Foundation; with no Invariant
	    Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy
	    of the license can be found under
	  <filename>/usr/share/common-licenses/FDL</filename>.</para> -->

	</refsect1>
      </refentry>

	<!-- Keep this comment at the end of the file
	      Local variables:
	      mode: sgml
	      sgml-omittag:t
	      sgml-shorttag:t
	      sgml-minimize-attributes:nil
	      sgml-always-quote-attributes:t
	      sgml-indent-step:2
	      sgml-indent-data:t
	      sgml-parent-document:nil
	      sgml-default-dtd-file:nil
	      sgml-exposed-tags:nil
	      sgml-local-catalogs:nil
	      sgml-local-ecat-files:nil
	      End:
	      -->