man/flac.sgml

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