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>--sector-align</option></term>
 288
 289                 <listitem>
 290                   <para>Align encoding of multiple CD format WAVE
 291                     files on sector boundaries.  See the HTML
 292                     documentation for more information.</para>
 293                 </listitem>
 294               </varlistentry>
 295
 296               <varlistentry>
 297                 <term><option>-S</option> {<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}, <option>--seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>}</term>
 298
 299                 <listitem>
 300                   <para>
 301                     Include a point or points in a SEEKTABLE.  Using #,
 302                     a seek point at that sample number is added.  Using
 303                     X, a placeholder point is added at the end of a the
 304                     table.  Using #x, # evenly spaced seek points will
 305                     be added, the first being at sample 0.  You may use
 306                     many -S options; the resulting SEEKTABLE will be the
 307                     unique-ified union of all such values.  With no -S
 308                     options, flac defaults to '-S 100x'.  Use --no-seektable
 309                     for no SEEKTABLE.  Note: '-S #x' will not work if the
 310                     encoder can't determine the input size before
 311                     starting.  Note: if you use '-S #' and # is >=
 312                     samples in the input, there will be either no seek
 313                     point entered (if the input size is determinable
 314                     before encoding starts) or a placeholder point (if
 315                     input size is not determinable).</para>
 316                 </listitem>
 317               </varlistentry>
 318
 319               <varlistentry>
 320                 <term><option>-P</option> <replaceable>#</replaceable>, <option>--padding</option>=<replaceable>#</replaceable></term>
 321
 322                 <listitem>
 323                   <para>Tell the encoder to write a PADDING metadata
 324                     block of the given length (in bytes) after the
 325                     STREAMINFO block.  This is useful if you plan to
 326                     tag the file later with an APPLICATION block;
 327                     instead of having to rewrite the entire file later
 328                     just to insert your block, you can write directly
 329                     over the PADDING block.  Note that the total length
 330                     of the PADDING block will be 4 bytes longer than
 331                     the length given because of the 4 metadata block
 332                     header bytes.  You can force no PADDING block at
 333                     all to be written with --no-padding, which is the
 334                     default.</para>
 335                 </listitem>
 336               </varlistentry>
 337
 338               <varlistentry>
 339                 <term><option>-T</option> <replaceable>FIELD=VALUE</replaceable>, <option>--tag</option>=<replaceable>FIELD=VALUE</replaceable></term>
 340
 341                 <listitem>
 342                   <para>Add a Vorbis comment.  The comment must adhere
 343                     to the Vorbis comment spec; i.e. the FIELD must
 344                     contain only legal characters, terminated by an
 345                     'equals' sign.  Make sure to quote the comment if
 346                     necessary.  This option may appear more than once
 347                     to add several comments.  NOTE: all tags will be
 348                     added to all encoded files.</para>
 349                 </listitem>
 350               </varlistentry>
 351
 352               <varlistentry>
 353                 <term><option>-b</option> <replaceable>#</replaceable>, <option>--blocksize</option>=<replaceable>#</replaceable></term>
 354
 355                 <listitem>
 356                   <para>Specify the block size in samples.  The
 357                     default is 1152 for -l 0, else 4608; must be one of
 358                     192, 576, 1152, 2304, 4608, 256, 512, 1024, 2048,
 359                     4096, 8192, 16384, or 32768 (unless --lax is used)</para>
 360                 </listitem>
 361               </varlistentry>
 362
 363               <varlistentry>
 364                 <term><option>-m</option>, <option>--mid-side</option></term>
 365
 366                 <listitem>
 367                   <para>Try mid-side coding for each frame (stereo
 368                     input only)</para>
 369                 </listitem>
 370               </varlistentry>
 371
 372               <varlistentry>
 373                 <term><option>-M</option>, <option>--adaptive-mid-side</option></term>
 374
 375                 <listitem>
 376                   <para>Adaptive mid-side coding for all frames (stereo
 377                     input only)</para>
 378                 </listitem>
 379               </varlistentry>
 380
 381               <varlistentry>
 382                 <term><option>-0</option>..<option>-8</option>, <option>--compression-level-0</option>..<option>--compression-level-8</option></term>
 383
 384                 <listitem>
 385                   <para>Fastest compression..highest compression
 386                     (default is -5).  These are synonyms for other
 387                     options:</para>
 388
 389                   <variablelist>
 390                     <varlistentry>
 391                       <term><option>-0</option>, <option>--compression-level-0</option></term>
 392
 393                       <listitem>
 394                         <para>Synonymous with -l 0 -b 1152 -r 2,2
 395                           </para>
 396                       </listitem>
 397                     </varlistentry>
 398
 399                     <varlistentry>
 400                       <term><option>-1</option>, <option>--compression-level-1</option></term>
 401
 402                       <listitem>
 403                         <para>Synonymous with -l 0 -b 1152 -M -r 2,2
 404                           </para>
 405                       </listitem>
 406                     </varlistentry>
 407
 408                     <varlistentry>
 409                       <term><option>-2</option>, <option>--compression-level-2</option></term>
 410
 411                       <listitem>
 412                         <para>Synonymous with -l 0 -b 1152 -m -r 3
 413                           </para>
 414                       </listitem>
 415                     </varlistentry>
 416
 417                     <varlistentry>
 418                       <term><option>-3</option>, <option>--compression-level-3</option></term>
 419
 420                       <listitem>
 421                         <para>Synonymous with -l 6 -b 4608 -r 3,3
 422                           </para>
 423                       </listitem>
 424                     </varlistentry>
 425
 426                     <varlistentry>
 427                       <term><option>-4</option>, <option>--compression-level-4</option></term>
 428
 429                       <listitem>
 430                         <para>Synonymous with -l 8 -b 4608 -M -r 3,3
 431                           </para>
 432                       </listitem>
 433                     </varlistentry>
 434
 435                     <varlistentry>
 436                       <term><option>-5</option>, <option>--compression-level-5</option></term>
 437
 438                       <listitem>
 439                         <para>Synonymous with -l 8 -b 4608 -m -r 3,3
 440                           </para>
 441                       </listitem>
 442                     </varlistentry>
 443
 444                     <varlistentry>
 445                       <term><option>-6</option>, <option>--compression-level-6</option></term>
 446
 447                       <listitem>
 448                         <para>Synonymous with -l 8 -b 4608 -m -r 4
 449                           </para>
 450                       </listitem>
 451                     </varlistentry>
 452
 453                     <varlistentry>
 454                       <term><option>-7</option>, <option>--compression-level-7</option></term>
 455
 456                       <listitem>
 457                         <para>Synonymous with -l 8 -b 4608 -m -e -r 6
 458                           </para>
 459                       </listitem>
 460                     </varlistentry>
 461
 462                     <varlistentry>
 463                       <term><option>-8</option>, <option>--compression-level-8</option></term>
 464
 465                       <listitem>
 466                         <para>Synonymous with -l 12 -b 4608 -m -e -r 6
 467                           </para>
 468                       </listitem>
 469                     </varlistentry>
 470                   </variablelist>
 471
 472                 </listitem>
 473
 474               </varlistentry>
 475
 476               <varlistentry>
 477                 <term><option>--fast</option></term>
 478
 479                 <listitem>
 480                   <para>Fastest compression.  Currently
 481                     synonymous with -0.</para>
 482                 </listitem>
 483               </varlistentry>
 484
 485               <varlistentry>
 486                 <term><option>--best</option></term>
 487
 488                 <listitem>
 489                   <para>Highest compression.  Currently
 490                     synonymous with -8.</para>
 491                 </listitem>
 492               </varlistentry>
 493
 494               <varlistentry>
 495                 <term><option>-e</option>, <option>--exhaustive-model-search</option></term>
 496
 497                 <listitem>
 498                   <para>Do exhaustive model search
 499                     (expensive!)</para>
 500                 </listitem>
 501               </varlistentry>
 502
 503               <varlistentry>
 504                 <term><option>-l</option> <replaceable>#</replaceable>, <option>--max-lpc-order</option>=<replaceable>#</replaceable></term>
 505
 506                 <listitem>
 507                   <para>Set the maximum LPC order; 0 means use only the fixed predictors</para>
 508                 </listitem>
 509               </varlistentry>
 510
 511               <varlistentry>
 512                 <term><option>-p</option>, <option>--qlp-coeff-precision-search</option></term>
 513
 514                 <listitem>
 515                   <para>Do exhaustive search of LP coefficient
 516                     quantization (expensive!).  Overrides -q;
 517                     does nothing if using -l 0</para>
 518                 </listitem>
 519               </varlistentry>
 520
 521               <varlistentry>
 522                 <term><option>-q</option> <replaceable>#</replaceable>, <option>--qlp-coeff-precision</option>=<replaceable>#</replaceable></term>
 523
 524                 <listitem>
 525                   <para>Precision of the quantized linear-predictor
 526                     coefficients, 0 => let encoder decide (min is 5,
 527                     default is 0)</para>
 528                 </listitem>
 529               </varlistentry>
 530
 531               <varlistentry>
 532                 <term><option>-r</option> [<replaceable>#</replaceable>,]<replaceable>#</replaceable>, <option>--rice-partition-order</option>=[<replaceable>#</replaceable>,]<replaceable>#</replaceable></term>
 533
 534                 <listitem>
 535                   <para>Set the [min,]max residual partition order
 536                     (0..16). min defaults to 0 if unspecified.  Default
 537                     is -r 3,3.</para>
 538                 </listitem>
 539               </varlistentry>
 540
 541             </variablelist>
 542
 543           </refsect2>
 544           <refsect2>
 545             <title>Format Options</title>
 546
 547             <variablelist>
 548               <varlistentry>
 549                 <term><option>--endian</option>={<replaceable>big</replaceable>|<replaceable>little</replaceable>}</term>
 550
 551                 <listitem>
 552                   <para>Set the byte order for samples</para>
 553                 </listitem>
 554               </varlistentry>
 555
 556               <varlistentry>
 557                 <term><option>--channels</option>=<replaceable>#</replaceable></term>
 558
 559                 <listitem>
 560                   <para>Set number of channels.</para>
 561                 </listitem>
 562               </varlistentry>
 563
 564               <varlistentry>
 565                 <term><option>--bps</option>=<replaceable>#</replaceable></term>
 566
 567                 <listitem>
 568                   <para>Set bits per sample.</para>
 569                 </listitem>
 570               </varlistentry>
 571
 572               <varlistentry>
 573                 <term><option>--sample-rate</option>=<replaceable>#</replaceable></term>
 574
 575                 <listitem>
 576                   <para>Set sample rate (in Hz).</para>
 577                 </listitem>
 578               </varlistentry>
 579
 580               <varlistentry>
 581                 <term><option>--sign</option>={<replaceable>signed</replaceable>|<replaceable>unsigned</replaceable>}</term>
 582
 583                 <listitem>
 584                   <para>Set the sign of samples (the default is signed).</para>
 585                 </listitem>
 586               </varlistentry>
 587
 588               <varlistentry>
 589                 <term><option>--force-raw-format</option></term>
 590
 591                 <listitem>
 592                   <para>Force input (when encoding) or output (when decoding)
 593                     to be treated as raw samples (even if filename ends
 594                     in <filename>.wav</filename>).</para>
 595                 </listitem>
 596               </varlistentry>
 597
 598             </variablelist>
 599           </refsect2>
 600
 601           <refsect2>
 602             <title>Negative Options</title>
 603
 604             <variablelist>
 605               <varlistentry>
 606                 <term><option>--no-adaptive-mid-side</option></term>
 607                 <term><option>--no-decode-through-errors</option></term>
 608                 <term><option>--no-delete-input-file</option></term>
 609                 <term><option>--no-escape-coding</option></term>
 610                 <term><option>--no-exhaustive-model-search</option></term>
 611                 <term><option>--no-lax</option></term>
 612                 <term><option>--no-mid-side</option></term>
 613                 <term><option>--no-ogg</option></term>
 614                 <term><option>--no-padding</option></term>
 615                 <term><option>--no-qlp-coeff-precision-search</option></term>
 616                 <term><option>--no-residual-gnuplot</option></term>
 617                 <term><option>--no-residual-text</option></term>
 618                 <term><option>--no-sector-align</option></term>
 619                 <term><option>--no-seektable</option></term>
 620                 <term><option>--no-silent</option></term>
 621                 <term><option>--no-verify</option></term>
 622                 <listitem>
 623                   <para>These flags can be used to invert the sense
 624                     of the corresponding normal option.</para>
 625                 </listitem>
 626               </varlistentry>
 627             </variablelist>
 628
 629           </refsect2>
 630
 631         </refsect1>
 632           <refsect1>
 633             <title>SEE ALSO</title>
 634
 635             <para>The programs are documented fully by HTML format
 636               documentation, available in
 637               <filename>/usr/share/doc/flac/html</filename> on
 638                 &debian; systems.</para>
 639           </refsect1>
 640           <refsect1>
 641             <title>AUTHOR</title>
 642
 643             <para>This manual page was written by &dhusername; &dhemail; for
 644               the &debian; system (but may be used by others).</para>
 645
 646             <!-- <para>Permission is granted to copy, distribute and/or modify
 647             this document under the terms of the <acronym>GNU</acronym> Free
 648             Documentation License, Version 1.1 or any later version
 649             published by the Free Software Foundation; with no Invariant
 650             Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy
 651             of the license can be found under
 652           <filename>/usr/share/common-licenses/FDL</filename>.</para> -->
 653
 654         </refsect1>
 655       </refentry>
 656
 657         <!-- Keep this comment at the end of the file
 658               Local variables:
 659               mode: sgml
 660               sgml-omittag:t
 661               sgml-shorttag:t
 662               sgml-minimize-attributes:nil
 663               sgml-always-quote-attributes:t
 664               sgml-indent-step:2
 665               sgml-indent-data:t
 666               sgml-parent-document:nil
 667               sgml-default-dtd-file:nil
 668               sgml-exposed-tags:nil
 669               sgml-local-catalogs:nil
 670               sgml-local-ecat-files:nil
 671               End:
 672               -->