flac/man/flac.sgml

<!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. -->
  <!ENTITY dhdate      "<date>November 15, 2001</date>">
  <!-- 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>
		    <year>2001</year>
		    <holder>&dhusername;</holder>
	</copyright>
	    &dhdate;
	</docinfo>
  <refmeta>
      &dhucpackage;

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

	<refpurpose>Free Lossless Audio Codec</refpurpose>
      </refnamediv>
	<refsynopsisdiv>
	  <cmdsynopsis>
	    <command>flac</command>

	    <arg><option><replaceable>OPTION</replaceable></option></arg>
	    <arg choice=plain><replaceable>infile</replaceable></arg>
	    <arg choice=plain><replaceable>...</replaceable></arg>
	  </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>-H</option>
		</term>
		<listitem>
		  <para>Show detailed help screen</para>
		</listitem>
	      </varlistentry>

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

              <varlistentry>
	        <term><option>-c</option>
                </term>
                <listitem>
                  <para>Encode from standard input, or decode to
                  standard output</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>

	      <varlistentry>
		<term><option>-o</option> <replaceable>filename</replaceable></term>
		<listitem>
		  <para>Force the output file name (usually flac just
		    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>
		</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>

	      <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>

	  <refsect2>
	    <title>Analysis Options</title>

	    <variablelist>
	      <varlistentry>
		<term><option>--a-rtext</option>
		</term>
		<listitem>
		  <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>
		</listitem>
	      </varlistentry>

	    </variablelist>
	  </refsect2>

	  <refsect2>
	    <title>Encoding Options</title>

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

		<listitem>
		  <para>When encoding, generate Ogg-FLAC output instead
		    of native-FLAC.  Ogg-FLAC streams are FLAC streams
		    wrapped in an Ogg transport layer.  The resulting
		    file should have an '.ogg' extension and will still
		    be decodable by flac.</para>
		  <para>When decoding, force the input to be treated as
		    Ogg-FLAC.  This is useful when piping input from
		    stdin or when the filename does not end in '.ogg'.</para>
		</listitem>
	      </varlistentry>

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

		<listitem>
		  <para>Allow encoder to generate non-Subset
		    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>
		</listitem>
	      </varlistentry>

	      <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
		    input size is not determinable).</para>
		</listitem>
	      </varlistentry>

	      <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>

	      <varlistentry>
		<term><option>-b</option> <replaceable>blocksize</replaceable></term>

		<listitem>
		  <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>
		</listitem>
	      </varlistentry>

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

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

	      <varlistentry>
		<term><option>-M</option></term>

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

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

		<listitem>
		  <para>Fastest compression..highest compression
		    (default is -5).  These are synonyms for other
		    options:</para>

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

		      <listitem>
			<para>Synonymous with -l 0 -b 1152 -r 2,2
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-1</option></term>

		      <listitem>
			<para>Synonymous with -l 0 -b 1152 -M -r 2,2
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-2</option></term>

		      <listitem>
			<para>Synonymous with -l 0 -b 1152 -m -r 3
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-3</option></term>

		      <listitem>
			<para>Synonymous with -l 6 -b 4608 -r 3,3
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-4</option></term>

		      <listitem>
			<para>Synonymous with -l 8 -b 4608 -M -r 3,3
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-5</option></term>

		      <listitem>
			<para>Synonymous with -l 8 -b 4608 -m -r 3,3
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-6</option></term>

		      <listitem>
			<para>Synonymous with -l 8 -b 4608 -m -r 4
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-7</option></term>

		      <listitem>
			<para>Synonymous with -l 8 -b 4608 -m -e -r 6
			  </para>
		      </listitem>
		    </varlistentry>

		    <varlistentry>
		      <term><option>-8</option></term>

		      <listitem>
			<para>Synonymous with -l 12 -b 4608 -m -e -r 6
			  </para>
		      </listitem>
		    </varlistentry>
		  </variablelist>

		</listitem>


	      </varlistentry>

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

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

	      <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>

	      <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
		    quantization (expensive!).  Overrides -q,
		    does nothing if using -l 0</para>
		</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>
		<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>

		<listitem>
		  <para>Set the Rice parameter search distance.
		    Default is 0.</para>
		</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>
		<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> <option>--ogg-</option>
		</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>

	    </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:
	      -->