man/flac.sgml

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