mirrors
/
flac
mirror of https://github.com/xiph/flac
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Convert docbook to markdown 

Currently, the man pages are converted from a docbook document, but
the conversion doesn't seem very reliable. Also, the man page is
more-or-less duplicated by the html documentation.

This commit moves all tool documentation to a markdown document which
is readable by itself and can be converted by pandoc to a man page
and can be used by Jekyll to populate the website.
This commit is contained in:
Martijn van Beurden 2022-08-09 21:26:19 +02:00 committed by GitHub
parent 4f40fa8433
commit 80d064e15d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 1026 additions and 3873 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/distcheck.yml vendored
View File

@ -16,7 +16,7 @@ jobs:
- name: Install Linux dependencies
run: |
sudo apt-get update
sudo apt-get install -y libtool-bin libogg-dev doxygen libxml2-utils w3c-sgml-lib
sudo apt-get install -y libtool-bin libogg-dev doxygen libxml2-utils w3c-sgml-lib pandoc
- name: Build with Autotools
run: |

4
.gitignore vendored
View File

@ -39,8 +39,8 @@ m4/ltoptions.m4
m4/ltsugar.m4
m4/ltversion.m4
m4/lt~obsolete.m4
man/manpage.links
man/manpage.refs
man/flac.1
man/metaflac.1
missing
objs/debug
objs/release

10
configure.ac
View File

@ -467,11 +467,11 @@ dnl check for i18n(internationalization); these are from libiconv/gettext
AM_ICONV
AM_LANGINFO_CODESET
AC_CHECK_PROGS(DOCBOOK_TO_MAN, docbook-to-man docbook2man)
AM_CONDITIONAL(FLaC__HAS_DOCBOOK_TO_MAN, test -n "$DOCBOOK_TO_MAN")
if test -n "$DOCBOOK_TO_MAN" ; then
AC_DEFINE(FLAC__HAS_DOCBOOK_TO_MAN)
AH_TEMPLATE(FLAC__HAS_DOCBOOK_TO_MAN, [define if you have docbook-to-man or docbook2man])
AC_CHECK_PROGS(PANDOC, pandoc)
AM_CONDITIONAL(FLaC__HAS_PANDOC, test -n "$PANDOC")
if test -n "$PANDOC" ; then
AC_DEFINE(FLAC__HAS_PANDOC)
AH_TEMPLATE(FLAC__HAS_PANDOC, [define if you have pandoc])
fi
AC_CHECK_LIB(rt, clock_gettime,

2
doc/html/Makefile.am
View File

@ -25,8 +25,6 @@ html_DATA = \
documentation_example_code.html \
documentation_format_overview.html \
documentation_tools.html \
documentation_tools_flac.html \
documentation_tools_metaflac.html \
faq.html \
favicon.ico \
features.html \

1189
doc/html/documentation_tools_flac.html
View File

File diff suppressed because it is too large Load Diff

566
doc/html/documentation_tools_metaflac.html
View File

@ -1,566 +0,0 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Copyright (c) 2000-2009 Josh Coalson -->
<!-- Copyright (c) 2011-2022 Xiph.Org Foundation -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.1 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no invariant sections. -->
<!-- A copy of the license can be found at http://www.gnu.org/copyleft/fdl.html -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<meta name="author" content="Josh Coalson" />
<meta name="description" content="A free, open source codec for lossless audio compression and decompression" />
<meta name="keywords" content="free,lossless,audio,codec,encoder,decoder,compression,compressor,archival,archive,archiving,backup,music" />
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico" />
<link rel="stylesheet" type="text/css" href="flac.css" />
<title>FLAC - documentation</title>
</head>
<body>
<div class="logo">
<a href="index.html"><img src="images/logo130.gif" alt="FLAC Logo" align="middle" border="0" hspace="0" /></a>
</div>
<div class="above_nav"></div>
<div class="navbar">
&nbsp;<a href="index.html">home</a>&nbsp;&nbsp;|
&nbsp;<a href="faq.html">faq</a>&nbsp;&nbsp;|
&nbsp;<a href="documentation.html">documentation</a>&nbsp;&nbsp;|
&nbsp;<a href="developers.html">developers</a>&nbsp;&nbsp;|
&nbsp;<a href="changelog.html">changelog</a>&nbsp;&nbsp;|
&nbsp;<a href="http://xiph.org/flac">more</a>
</div>
<div class="below_nav"></div>
<div class="box">
<div class="box_title">
<a name="metaflac">metaflac</a>
</div>
<div class="box_header"></div>
<div class="box_body">
<a name="toc"><font size="+1"><b><u>Table of Contents</u></b></font></a>
<ul>
<li><a href="#usage">General Usage</a></li>
<li><a href="#global_options">Global Options</a></li>
<li><a href="#shorthand_operations">Shorthand Operations</a></li>
<li><a href="#major_operations">Major Operations</a></li>
<li><a href="#option_index">Option Index</a></li>
</ul>
<a name="usage"><font size="+1"><b><u>General Usage</u></b></font></a><br />
<br />
<span class="commandname">metaflac</span> is the command-line <span class="code">.flac</span> file metadata editor. You can use it to list the contents of metadata blocks, edit, delete or insert blocks, and manage padding.<br />
<br />
<span class="commandname">metaflac</span> takes a set of "options" (though some are not optional) and a set of FLAC files to operate on. There are three kinds of "options":
<ul>
<li>
Major operations, which specify a mode of operation like listing blocks, removing blocks, etc. These will have sub-operations describing exactly what is to be done.
</li>
<li>
Shorthand operations, which are convenient synonyms for major operations. For example, there is a shorthand operation <span class="argument">--show-sample-rate</span> that shows just the sample rate field from the <span class="code">STREAMINFO</span> metadata block.
</li>
<li>
Global options, which affect all the operations.
</li>
</ul>
All of these are described in the tables below. At least one shorthand or major operation must be supplied. You can use multiple shorthand operations to do more than one thing to a file or set of files. Most of the common things to do to metadata have shorthand operations. As an example, here is how to show the MD5 signatures for a set of three FLAC files:<br />
<br />
<span class="code">metaflac --show-md5sum file1.flac file2.flac file3.flac</span><br />
<br />
Another example; this removes all DESCRIPTION and COMMENT tags in a set of FLAC files, and uses the <span class="argument">--preserve-modtime</span> global option to keep the FLAC file modification times the same (usually when files are edited the modification time is set to the current time):<br />
<br />
<span class="code">metaflac --preserve-modtime --remove-tag=DESCRIPTION --remove-tag=COMMENT file1.flac file2.flac file3.flac</span><br />
<br />
<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td>
<table width="100%" border="1" bgcolor="#EEEED4">
<tr>
<td colspan="2" bgcolor="#D3D4C5">
<a name="global_options"><font size="+1"><b>Global Options</b></font></a>
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_options_preserve_modtime" />
<span class="argument">--preserve-modtime</span>
</td>
<td>
Preserve the original modification time in spite of edits.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_options_with_filename" />
<span class="argument">--with-filename</span>
</td>
<td>
Prefix each output line with the FLAC file name (the default if more than one FLAC file is specified).
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_options_no_filename" />
<span class="argument">--no-filename</span>
</td>
<td>
Do not prefix each output line with the FLAC file name (the default if only one FLAC file is specified)
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_options_no_utf8_convert" />
<span class="argument">--no-utf8-convert</span>
</td>
<td>
Do not convert tags from UTF-8 to local charset, or vice versa. This is useful for scripts, and setting tags in situations where the locale is wrong.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_options_dont_use_padding" />
<span class="argument">--dont-use-padding</span>
</td>
<td>
By default <span class="commandname">metaflac</span> tries to use padding where possible to avoid rewriting the entire file if the metadata size changes. Use this option to tell metaflac to not take advantage of padding this way.
</td>
</tr>
</table>
</td></tr></table>
<br />
<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td>
<table width="100%" border="1" bgcolor="#EEEED4">
<tr>
<td colspan="2" bgcolor="#D3D4C5">
<a name="shorthand_operations"><font size="+1"><b>Shorthand Operations</b></font></a>
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_md5sum" />
<span class="argument">--show-md5sum</span>
</td>
<td>
Show the MD5 signature from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_min_blocksize" />
<span class="argument">--show-min-blocksize</span>
</td>
<td>
Show the minimum block size from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_max_blocksize" />
<span class="argument">--show-max-blocksize</span>
</td>
<td>
Show the maximum block size from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_min_framesize" />
<span class="argument">--show-min-framesize</span>
</td>
<td>
Show the minimum frame size from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_max_framesize" />
<span class="argument">--show-max-framesize</span>
</td>
<td>
Show the maximum frame size from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_sample_rate" />
<span class="argument">--show-sample-rate</span>
</td>
<td>
Show the sample rate from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_channels" />
<span class="argument">--show-channels</span>
</td>
<td>
Show the number of channels from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_bps" />
<span class="argument">--show-bps</span>
</td>
<td>
Show the # of bits per sample from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_total_samples" />
<span class="argument">--show-total-samples</span>
</td>
<td>
Show the total # of samples from the <span class="code">STREAMINFO</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_vendor_tag" />
<span class="argument">--show-vendor-tag</span>
</td>
<td>
Show the vendor string from the <span class="code">VORBIS_COMMENT</span> block.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_show_tag" />
<span class="argument">--show-tag=NAME</span>
</td>
<td>
Show all tags where the field name matches <span class="argument">NAME</span>.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_remove_tag" />
<span class="argument">--remove-tag=NAME</span>
</td>
<td>
Remove all tags whose field name is <span class="argument">NAME</span>.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_remove_first_tag" />
<span class="argument">--remove-first-tag=NAME</span>
</td>
<td>
Remove first tag whose field name is <span class="argument">NAME</span>.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_remove_all_tags" />
<span class="argument">--remove-all-tags</span>
</td>
<td>
Remove all tags, leaving only the vendor string.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_set_tag" />
<span class="argument">--set-tag=FIELD</span>
</td>
<td>
Add a tag. The <span class="argument">FIELD</span> must comply with the Vorbis comment spec, of the form <span class="argument">NAME=VALUE</span>. If there is currently no tag block, one will be created.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_set_tag_from_file" />
<span class="argument">--set-tag-from-file=FIELD</span>
</td>
<td>
Like <a href="#metaflac_shorthand_set_tag"><span class="argument">--set-tag</span></a>, except the VALUE is a filename whose contents will be read verbatim to set the tag value. Unless <a href="#metaflac_options_no_utf8_convert"><span class="argument">--no-utf8-convert</span></a> is specified, the contents will be converted to UTF-8 from the local charset. This can be used to store a cuesheet in a tag (e.g. <span class="argument">--set-tag-from-file="CUESHEET=image.cue"</span>). Do not try to store binary data in tag fields! Use APPLICATION blocks for that.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_import_tags_from" />
<span class="argument">--import-tags-from=FILE</span>
</td>
<td>
Import tags from a file. Use <span class="argument">-</span> for stdin. Each line should be of the form <span class="argument">NAME=VALUE</span>. Multi-line comments are currently not supported. Specify <span class="argument">--remove-all-tags</span> and/or <a href="#metaflac_options_no_utf8_convert"><span class="argument">--no-utf8-convert</span></a> before <span class="argument">--import-tags-from</span> if necessary. If <span class="argument">FILE</span> is <span class="argument">-</span> (stdin), only one FLAC file may be specified.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_export_tags_to" />
<span class="argument">--export-tags-to=FILE</span>
</td>
<td>
Export tags to a file. Use <span class="argument">-</span> for stdin. Each line will be of the form <span class="argument">NAME=VALUE</span>. Specify <a href="#metaflac_options_no_utf8_convert"><span class="argument">--no-utf8-convert</span></a> if necessary.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_import_cuesheet_from" />
<span class="argument">--import-cuesheet-from=FILE</span>
</td>
<td>
Import a cuesheet from a file. Use <span class="argument">-</span> for stdin. Only one FLAC file may be specified. A seekpoint will be added for each index point in the cuesheet to the <span class="code">SEEKTABLE</span> unless <span class="argument">--no-cued-seekpoints</span> is specified.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_export_cuesheet_to" />
<span class="argument">--export-cuesheet-to=FILE</span>
</td>
<td>
Export <span class="code">CUESHEET</span> block to a cuesheet file, suitable for use by CD authoring software. Use <span class="argument">-</span> for stdout. Only one FLAC file may be specified on the command line.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_import_picture_from" />
<span class="argument">--import-picture-from={FILENAME|SPECIFICATION}</span>
</td>
<td>
Import a picture and store it in a <a href="format.html#def_PICTURE"><span class="code">PICTURE</span></a> metadata block. See the <span class="commandname">flac</span> option <span class="argument"><a href="documentation_tools_flac.html#flac_options_picture">--picture</a></span> for an explanation of the <span class="argument">SPECIFICATION</span> syntax.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_export_picture_to" />
<span class="argument">--export-picture-to=FILE</span>
</td>
<td>
Export <span class="code">PICTURE</span> block to a file. Use <span class="argument">-</span> for stdout. Only one FLAC file may be specified on the command line. The first <span class="code">PICTURE</span> block will be exported unless <span class="argument">--export-picture-to</span> is preceded by a <span class="argument">--block-number=#</span> option to specify the exact metadata block to extract. Note that the block number is the one shown by --list.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_add_replay_gain" />
<span class="argument">--add-replay-gain</span>
</td>
<td>
Calculates the title and album gains/peaks of the given FLAC files as if all the files were part of one album, then stores them as FLAC tags. The tags are the same as those used by <span class="commandname">vorbisgain</span>. Existing ReplayGain tags will be replaced. If only one FLAC file is given, the album and title gains will be the same. Since this operation requires two passes, it is always executed last, after all other operations have been completed and written to disk. All FLAC files specified must have the same resolution, sample rate, and number of channels. The sample rate must be one of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48 kHz.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_add_replay_gain_scan" />
<span class="argument">--scan-replay-gain</span>
</td>
<td>
Like <span class="argument">--add-replay-gain</span>, but only analyzes the files rather than writing them to the tags.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_remove_replay_gain" />
<span class="argument">--remove-replay-gain</span>
</td>
<td>
Removes the ReplayGain tags.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_add_seekpoint" />
<span class="argument">--add-seekpoint={#|X|#x|#s}</span>
</td>
<td>
Add seek points to a <span class="code">SEEKTABLE</span> block:<br />
<ul>
<li>
<span class="argument">#&nbsp;</span> : a specific sample number for a seek point
</li>
<li>
<span class="argument">X&nbsp;</span> : a placeholder point (always goes at the end of the <span class="code">SEEKTABLE</span>)
</li>
<li>
<span class="argument">#x</span> : # evenly spaced seekpoints, the first being at sample 0
</li>
<li>
<span class="argument">#s</span> : a seekpoint every # seconds; # does not have to be a whole number, it can be, for example, <span class="argument">9.5</span>, meaning a seekpoint every 9.5 seconds
</li>
</ul>
If no <span class="code">SEEKTABLE</span> block exists, one will be created. If one already exists, points will be added to the existing table, and any duplicates will be turned into placeholder points.<br />
You may use many <span class="argument">--add-seekpoint</span> options; the resulting <span class="code">SEEKTABLE</span> will be the unique-ified union of all such values. Example: <span class="argument">--add-seekpoint=100x --add-seekpoint=3.5s</span> will add 100 evenly spaced seekpoints and a seekpoint every 3.5 seconds.<br />
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_shorthand_add_padding" />
<span class="argument">--add-padding=#</span>
</td>
<td>
Add a padding block of the given length (in bytes). The overall length of the new block will be 4 + length; the extra 4 bytes is for the metadata block header.
</td>
</tr>
</table>
</td></tr></table>
<br />
<table width="100%" border="0" cellspacing="0" cellpadding="0" bgcolor="#EEEED4"><tr><td>
<table width="100%" border="1" bgcolor="#EEEED4">
<tr>
<td colspan="2" bgcolor="#D3D4C5">
<a name="major_operations"><font size="+1"><b>Major Operations</b></font></a>
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_version" />
<span class="argument">--version</span>
</td>
<td>
Show the metaflac version number.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_list" />
<span class="argument">--list</span>
</td>
<td>
List the contents of one or more metadata blocks to stdout. By default, all metadata blocks are listed in text format. Use the following options to change this behavior:<br />
<br />
<span class="argument">--block-number=#[,#[...]]</span><br />
An optional comma-separated list of block numbers to display. The first block, the <span class="code">STREAMINFO</span> block, is block 0.<br />
<br />
<span class="argument">--block-type=type[,type[...]]</span><br />
<span class="argument">--except-block-type=type[,type[...]]</span><br />
An optional comma-separated list of block types to be included or ignored with this option. Use only one of <span class="argument">--block-type</span> or <span class="argument">--except-block-type</span>. The valid block types are: <span class="code">STREAMINFO</span>, <span class="code">PADDING</span>, <span class="code">APPLICATION</span>, <span class="code">SEEKTABLE</span>, <span class="code">VORBIS_COMMENT</span>. You may narrow down the types of <span class="code">APPLICATION</span> blocks displayed as follows:<br />
<table border="1">
<tr>
<td><span class="argument">APPLICATION:abcd</span></td>
<td>The <span class="code">APPLICATION</span> block(s) whose textual representation of the 4-byte ID is "abcd"</td>
</tr>
<tr>
<td><span class="argument">APPLICATION:0xXXXXXXXX</span></td>
<td>The <span class="code">APPLICATION</span> block(s) whose hexadecimal big- endian representation of the 4-byte ID is "0xXXXXXXXX". For the example "abcd" above the hexadecimal equivalalent is 0x61626364</td>
</tr>
</table>
<br />
NOTE: if both <span class="argument">--block-number</span> and <span class="argument">--[except-]block-type</span> are specified, the result is the logical AND of both arguments.<br />
<br />
<span class="argument">--application-data-format=hexdump|text</span><br />
If the application block you are displaying contains binary data but your <span class="argument">--data-format=text</span>, you can display a hex dump of the application data contents instead using <span class="argument">--application-data-format=hexdump</span>.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_remove" />
<span class="argument">--remove</span>
</td>
<td>
Remove one or more metadata blocks from the metadata. Unless <span class="argument">--dont-use-padding</span> is specified, the blocks will be replaced with padding. You may not remove the <span class="code">STREAMINFO</span> block.<br />
<br />
<span class="argument">--block-number=#[,#[...]]</span><br />
<span class="argument">--block-type=type[,type[...]]</span><br />
<span class="argument">--except-block-type=type[,type[...]]</span><br />
See <a href="#metaflac_operations_list"><span class="argument">--list</span></a> above for usage.<br />
<br />
NOTE: if both <span class="argument">--block-number</span> and <span class="argument">--[except-]block-type</span> are specified, the result is the logical AND of both arguments.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_remove_all" />
<span class="argument">--remove-all</span>
</td>
<td>
Remove all metadata blocks (except the <span class="code">STREAMINFO</span> block) from the metadata. Unless <span class="argument">--dont-use-padding</span> is specified, the blocks will be replaced with padding.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_merge_padding" />
<span class="argument">--merge-padding</span>
</td>
<td>
Merge adjacent <span class="code">PADDING</span> blocks into single blocks.
</td>
</tr>
<tr>
<td nowrap="nowrap" align="right" valign="top" bgcolor="#F4F4CC">
<a name="metaflac_operations_sort_padding" />
<span class="argument">--sort-padding</span>
</td>
<td>
Move all <span class="code">PADDING</span> blocks to the end of the metadata and merge them into a single block.
</td>
</tr>
</table>
</td></tr></table>
<br />
<a name="option_index"><font size="+1"><b><u>Option Index</u></b></font></a><br />
<br />
<a href="#metaflac_shorthand_add_padding"><span class="argument">--add-padding</span></a><br />
<a href="#metaflac_shorthand_add_replay_gain"><span class="argument">--add-replay-gain</span></a><br />
<a href="#metaflac_shorthand_add_seekpoint"><span class="argument">--add-seekpoint</span></a><br />
<a href="#metaflac_options_dont_use_padding"><span class="argument">--dont-use-padding</span></a><br />
<a href="#metaflac_shorthand_export_cuesheet_to"><span class="argument">--export-cuesheet-to</span></a><br />
<a href="#metaflac_shorthand_export_picture_to"><span class="argument">--export-picture-to</span></a><br />
<a href="#metaflac_shorthand_export_tags_to"><span class="argument">--export-tags-to</span></a><br />
<a href="#metaflac_shorthand_import_cuesheet_from"><span class="argument">--import-cuesheet-from</span></a><br />
<a href="#metaflac_shorthand_import_picture_from"><span class="argument">--import-picture-from</span></a><br />
<a href="#metaflac_shorthand_import_tags_from"><span class="argument">--import-tags-from</span></a><br />
<a href="#metaflac_operations_list"><span class="argument">--list</span></a><br />
<a href="#metaflac_operations_merge_padding"><span class="argument">--merge-padding</span></a><br />
<a href="#metaflac_options_no_filename"><span class="argument">--no-filename</span></a><br />
<a href="#metaflac_options_no_utf8_convert"><span class="argument">--no-utf8-convert</span></a><br />
<a href="#metaflac_options_preserve_modtime"><span class="argument">--preserve-modtime</span></a><br />
<a href="#metaflac_shorthand_remove_all_tags"><span class="argument">--remove-all-tags</span></a><br />
<a href="#metaflac_operations_remove_all"><span class="argument">--remove-all</span></a><br />
<a href="#metaflac_shorthand_remove_first_tag"><span class="argument">--remove-first-tag</span></a><br />
<a href="#metaflac_shorthand_remove_replay_gain"><span class="argument">--remove-replay-gain</span></a><br />
<a href="#metaflac_shorthand_remove_tag"><span class="argument">--remove-tag</span></a><br />
<a href="#metaflac_operations_remove"><span class="argument">--remove</span></a><br />
<a href="#metaflac_shorthand_scan_replay_gain"><span class="argument">--scan-replay-gain</span></a><br />
<a href="#metaflac_shorthand_set_tag_from_file"><span class="argument">--set-tag-from-file</span></a><br />
<a href="#metaflac_shorthand_set_tag"><span class="argument">--set-tag</span></a><br />
<a href="#metaflac_shorthand_show_bps"><span class="argument">--show-bps</span></a><br />
<a href="#metaflac_shorthand_show_channels"><span class="argument">--show-channels</span></a><br />
<a href="#metaflac_shorthand_show_max_blocksize"><span class="argument">--show-max-blocksize</span></a><br />
<a href="#metaflac_shorthand_show_max_framesize"><span class="argument">--show-max-framesize</span></a><br />
<a href="#metaflac_shorthand_show_md5sum"><span class="argument">--show-md5sum</span></a><br />
<a href="#metaflac_shorthand_show_min_blocksize"><span class="argument">--show-min-blocksize</span></a><br />
<a href="#metaflac_shorthand_show_min_framesize"><span class="argument">--show-min-framesize</span></a><br />
<a href="#metaflac_shorthand_show_sample_rate"><span class="argument">--show-sample-rate</span></a><br />
<a href="#metaflac_shorthand_show_tag"><span class="argument">--show-tag</span></a><br />
<a href="#metaflac_shorthand_show_total_samples"><span class="argument">--show-total-samples</span></a><br />
<a href="#metaflac_shorthand_show_vendor_tag"><span class="argument">--show-vendor-tag</span></a><br />
<a href="#metaflac_operations_sort_padding"><span class="argument">--sort-padding</span></a><br />
<a href="#metaflac_operations_version"><span class="argument">--version</span></a><br />
<a href="#metaflac_options_with_filename"><span class="argument">--with-filename</span></a><br />
</div>
<div class="box_footer"></div>
</div>
<div class="copyright">
<!-- @@@ oh so hacky -->
<table>
<tr>
<td align="left">
Copyright (c) 2000-2009 Josh Coalson
<br/>
Copyright (c) 2011-2022 Xiph.Org Foundation
</td>
</tr>
</table>
</div>
</body>
</html>

15
man/Makefile.am
View File

@ -16,14 +16,13 @@
# with this program; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
if FLaC__HAS_DOCBOOK_TO_MAN
flac.1: flac.sgml
docbook-to-man $? > $@
(docbook2man $? && mv FLAC.1 $@)
if FLaC__HAS_PANDOC
flac.1: flac.md
pandoc --standalone --to man $? > $@
metaflac.1: metaflac.sgml
docbook-to-man $? > $@
(docbook2man $? && mv METAFLAC.1 $@)
metaflac.1: metaflac.md
pandoc --standalone --to man $? > $@
else
flac.1:
echo "*** Warning: docbook-to-man not found; man pages will not be built."
@ -35,4 +34,4 @@ endif
man_MANS = flac.1 metaflac.1
EXTRA_DIST = $(man_MANS) flac.sgml metaflac.sgml
EXTRA_DIST = $(man_MANS) flac.md metaflac.md

393
man/flac.1
View File

@ -1,393 +0,0 @@
.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "FLAC" "1" "2021/08/31" "" ""
.SH NAME
flac \- Free Lossless Audio Codec
.SH SYNOPSIS
\fBflac\fR [ \fB\fIOPTIONS\fB\fR ] [ \fB\fIinfile.wav\fB\fR | \fB\fIinfile.rf64\fB\fR | \fB\fIinfile.aiff\fB\fR | \fB\fIinfile.raw\fB\fR | \fB\fIinfile.flac\fB\fR | \fB\fIinfile.oga\fB\fR | \fB\fIinfile.ogg\fB\fR | \fB-\fR\fI ...\fR ]
\fBflac\fR [ \fB-d\fR | \fB--decode\fR | \fB-t\fR | \fB--test\fR | \fB-a\fR | \fB--analyze\fR ] [ \fB\fIOPTIONS\fB\fR ] [ \fB\fIinfile.flac\fB\fR | \fB\fIinfile.oga\fB\fR | \fB\fIinfile.ogg\fB\fR | \fB-\fR\fI ...\fR ]
.SH "DESCRIPTION"
.PP
\fBflac\fR is a command-line tool for encoding, decoding, testing and analyzing FLAC streams.
.SH "OPTIONS"
.PP
A summary of options is included below. For a complete
description, see the HTML documentation.
.SS "GENERAL OPTIONS"
.TP
\fB-v, --version\fR
Show the flac version number
.TP
\fB-h, --help \fR
Show basic usage and a list of all options
.TP
\fB-H, --explain \fR
Show detailed explanation of usage and all options
.TP
\fB-d, --decode \fR
Decode (the default behavior is to encode)
.TP
\fB-t, --test \fR
Test a flac encoded file (same as -d except no decoded file is written)
.TP
\fB-a, --analyze \fR
Analyze a FLAC encoded file (same as -d except an analysis file is written)
.TP
\fB-c, --stdout \fR
Write output to stdout
.TP
\fB-s, --silent \fR
Silent mode (do not write runtime encode/decode statistics to stderr)
.TP
\fB--totally-silent \fR
Do not print anything of any kind, including warnings or errors. The exit code will be the only way to determine successful completion.
.TP
\fB--no-utf8-convert \fR
Do not convert tags from local charset to UTF-8. This is useful for scripts, and setting tags in situations where the locale is wrong. This option must appear before any tag options!
.TP
\fB-w, --warnings-as-errors \fR
Treat all warnings as errors (which cause flac to terminate with a non-zero exit code).
.TP
\fB-f, --force \fR
Force overwriting of output files. By default, flac warns that the output file already exists and continues to the next file.
.TP
\fB-o \fIfilename\fB, --output-name=\fIfilename\fB\fR
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.
.TP
\fB--output-prefix=\fIstring\fB\fR
Prefix each output file name with the given string. This can be useful for encoding or decoding files to a different directory. Make sure if your string is a path name that it ends with a trailing `/' (slash).
.TP
\fB--delete-input-file \fR
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.
.TP
\fB--preserve-modtime \fR
Output files have their timestamps/permissions set to match those of their inputs (this is default). Use --no-preserve-modtime to make output files have the current time and default permissions.
.TP
\fB--keep-foreign-metadata \fR
If encoding, save WAVE, RF64, or AIFF non-audio chunks in FLAC metadata. If decoding, restore any saved non-audio chunks from FLAC metadata when writing the decoded file. Foreign metadata cannot be transcoded, e.g. WAVE chunks saved in a FLAC file cannot be restored when decoding to AIFF. Input and output must be regular files (not stdin or stdout).
.TP
\fB--keep-foreign-metadata-if-present \fR
Like --keep-foreign-metadata, but without throwing an error if foreign metadata cannot be found or restored, instead printing a warning.
.TP
\fB--skip={\fI#\fB|\fImm:ss.ss\fB}\fR
Skip over the first number of samples of the input. This works for both encoding and decoding, but not testing. The alternative form mm:ss.ss can be used to specify minutes, seconds, and fractions of a second.
.TP
\fB--until={\fI#\fB|[\fI+\fB|\fI-\fB]\fImm:ss.ss\fB}\fR
Stop at the given sample number for each input file. This works for both encoding and decoding, but not testing. The given sample number is not included in the decoded output. The alternative form mm:ss.ss can be used to specify minutes, seconds, and fractions of a second. If a `+' (plus) sign is at the beginning, the --until point is relative to the --skip point. If a `-' (minus) sign is at the beginning, the --until point is relative to end of the audio.
.TP
\fB--ogg\fR
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 '.oga' extension and will still be decodable by flac.
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 '.oga' or '.ogg'.
.TP
\fB--serial-number=\fI#\fB\fR
When used with --ogg, specifies the serial number to use for the first Ogg FLAC stream, which is then incremented for each additional stream. When encoding and no serial number is given, flac uses a random number for the first stream, then increments it for each additional stream. When decoding and no number is given, flac uses the serial number of the first page.
.SS "ANALYSIS OPTIONS"
.TP
\fB--residual-text \fR
Includes the residual signal in the analysis file. This will make the file very big, much larger than even the decoded file.
.TP
\fB--residual-gnuplot \fR
Generates a gnuplot file for every subframe; each file will contain the residual distribution of the subframe. This will create a lot of files.
.SS "DECODING OPTIONS"
.TP
\fB--cue=[\fI#.#\fB][-[\fI#.#\fB]]\fR
Set the beginning and ending cuepoints to decode. The optional first #.# is the track and index point at which decoding will start; the default is the beginning of the stream. The optional second #.# is the track and index point at which decoding will end; the default is the end of the stream. If the cuepoint does not exist, the closest one before it (for the start point) or after it (for the end point) will be used. If those don't exist, the start of the stream (for the start point) or end of the stream (for the end point) will be used. The cuepoints are merely translated into sample numbers then used as --skip and --until. A CD track can always be cued by, for example, --cue=9.1-10.1 for track 9, even if the CD has no 10th track.
.TP
\fB-F, --decode-through-errors \fR
By default flac stops decoding with an error and removes the partially decoded file if it encounters a bitstream error. With -F, errors are still printed but flac will continue decoding to completion. Note that errors may cause the decoded audio to be missing some samples or have silent sections.
.TP
\fB--apply-replaygain-which-is-not-lossless[=<specification>] \fR
Applies ReplayGain values while decoding.
WARNING: THIS IS NOT LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH THIS OPTION.
The equals sign and <specification> is optional. If omitted, the default is 0aLn1.
The <specification> is a shorthand notation for describing how to apply ReplayGain. All components are optional but order is important. '[]' means 'optional'. '|' means 'or'. '{}' means required. The format is:
[<preamp>][a|t][l|L][n{0|1|2|3}]
.RS
.TP
\fBpreamp\fR
A floating point number in dB. This is added to the existing gain value.
.TP
\fBa|t\fR
Specify 'a' to use the album gain, or 't' to use the track gain. If tags for the preferred kind (album/track) do not exist but tags for the other (track/album) do, those will be used instead.
.TP
\fBl|L\fR
Specify 'l' to peak-limit the output, so that the ReplayGain peak value is full-scale. Specify 'L' to use a 6dB hard limiter that kicks in when the signal approaches full-scale.
.TP
\fBn{0|1|2|3}\fR
Specify the amount of noise shaping. ReplayGain synthesis happens in floating point; the result is dithered before converting back to integer. This quantization adds noise. Noise shaping tries to move the noise where you won't hear it as much. 0 means no noise shaping, 1 means 'low', 2 means 'medium', 3 means 'high'.
.RE
For example, the default of 0aLn1 means 0dB preamp, use album gain, 6dB hard limit, low noise shaping.
--apply-replaygain-which-is-not-lossless=3 means 3dB preamp, use album gain, no limiting, no noise shaping.
flac uses the ReplayGain tags for the calculation. If a stream does not have the required tags or they can't be parsed, decoding will continue with a warning, and no ReplayGain is applied to that stream.
.SS "ENCODING OPTIONS"
.TP
\fB-V, --verify\fR
Verify a correct encoding by decoding the output in parallel and comparing to the original
.TP
\fB--lax\fR
Allow encoder to generate non-Subset files. The resulting FLAC file may not be streamable or might have trouble being played in all players (especially hardware devices), so you should only use this option in combination with custom encoding options meant for archival.
.TP
\fB--replay-gain\fR
Calculate ReplayGain values and store them as FLAC tags, similar to vorbisgain. Title gains/peaks will be computed for each input file, and an album gain/peak will be computed for all files. All input files must have the same resolution, sample rate, and number of channels. Only mono and stereo files are allowed, and the sample rate must be one of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48 kHz. Also note that this option may leave a few extra bytes in a PADDING block as the exact size of the tags is not known until all files are processed. Note that this option cannot be used when encoding to standard output (stdout).
.TP
\fB--cuesheet=\fIfilename\fB\fR
Import the given cuesheet file and store it in a CUESHEET metadata block. This option may only be used when encoding a single file. A seekpoint will be added for each index point in the cuesheet to the SEEKTABLE unless --no-cued-seekpoints is specified.
.TP
\fB--picture={\fIFILENAME\fB|\fISPECIFICATION\fB}\fR
Import a picture and store it in a PICTURE metadata block. More than one --picture command can be specified. Either a filename for the picture file or a more complete specification form can be used. The SPECIFICATION is a string whose parts are separated by | (pipe) characters. Some parts may be left empty to invoke default values. FILENAME is just shorthand for "||||FILENAME". The format of SPECIFICATION is
[TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE
TYPE is optional; it is a number from one of:
0: Other
1: 32x32 pixels 'file icon' (PNG only)
2: Other file icon
3: Cover (front)
4: Cover (back)
5: Leaflet page
6: Media (e.g. label side of CD)
7: Lead artist/lead performer/soloist
8: Artist/performer
9: Conductor
10: Band/Orchestra
11: Composer
12: Lyricist/text writer
13: Recording Location
14: During recording
15: During performance
16: Movie/video screen capture
17: A bright coloured fish
18: Illustration
19: Band/artist logotype
20: Publisher/Studio logotype
The default is 3 (front cover). There may only be one picture each of type 1 and 2 in a file.
MIME-TYPE is optional; if left blank, it will be detected from the file. For best compatibility with players, use pictures with MIME type image/jpeg or image/png. The MIME type can also be --> to mean that FILE is actually a URL to an image, though this use is discouraged.
DESCRIPTION is optional; the default is an empty string.
The next part specifies the resolution and color information. If the MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave this empty and they can be detected from the file. Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel. If the image has indexed colors you should also specify the number of colors used. When manually specified, it is not checked against the file for accuracy.
FILE is the path to the picture file to be imported, or the URL if MIME type is -->
For example, "|image/jpeg|||../cover.jpg" will embed the JPEG file at ../cover.jpg, defaulting to type 3 (front cover) and an empty description. The resolution and color info will be retrieved from the file itself.
The specification "4|-->|CD|320x300x24/173|http://blah.blah/backcover.tiff" will embed the given URL, with type 4 (back cover), description "CD", and a manually specified resolution of 320x300, 24 bits-per-pixel, and 173 colors. The file at the URL will not be fetched; the URL itself is stored in the PICTURE metadata block.
.TP
\fB--sector-align\fR
Align encoding of multiple CD format files on sector boundaries. See the HTML documentation for more information. This option is DEPRECATED and may not exist in future versions of flac.
.TP
\fB--ignore-chunk-sizes\fR
When encoding to flac, ignore the file size headers in WAV and AIFF files to attempt to work around problems with over-sized or malformed files.
WAV and AIFF files both have an unsigned 32 bit numbers in the file header which specifes the length of audio data. Since this number is unsigned 32 bits, that limits the size of a valid file to being just over 4 Gigabytes. Files larger than this are mal-formed, but should be read correctly using this option.
.TP
\fB-S {\fI#\fB|\fIX\fB|\fI#x\fB|\fI#s\fB}, --seekpoint={\fI#\fB|\fIX\fB|\fI#x\fB|\fI#s\fB}\fR
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. Using #s, a seekpoint will be added every # seconds (# does not have to be a whole number; it can be, for example, 9.5, meaning a seekpoint every 9.5 seconds). 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 10s'. Use --no-seektable for no SEEKTABLE. Note: '-S #x' and '-S #s' 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).
.TP
\fB-P \fI#\fB, --padding=\fI#\fB\fR
Tell the encoder to write a PADDING metadata block of the given length (in bytes) after the STREAMINFO block. 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. Note that the total length of the PADDING block will be 4 bytes longer than the length given because of the 4 metadata block header bytes. You can force no PADDING block at all to be written with --no-padding. The encoder writes a PADDING block of 8192 bytes by default (or 65536 bytes if the input audio stream is more that 20 minutes long).
.TP
\fB-T \fIFIELD=VALUE\fB, --tag=\fIFIELD=VALUE\fB\fR
Add a FLAC tag. The comment must adhere to the Vorbis comment spec; i.e. the FIELD must contain only legal characters, terminated by an 'equals' sign. Make sure to quote the comment if necessary. This option may appear more than once to add several comments. NOTE: all tags will be added to all encoded files.
.TP
\fB--tag-from-file=\fIFIELD=FILENAME\fB\fR
Like --tag, except FILENAME is a file whose contents will be read verbatim to set the tag value. The contents will be converted to UTF-8 from the local charset. This can be used to store a cuesheet in a tag (e.g. --tag-from-file="CUESHEET=image.cue"). Do not try to store binary data in tag fields! Use APPLICATION blocks for that.
.TP
\fB-b \fI#\fB, --blocksize=\fI#\fB\fR
Specify the blocksize in samples. The default is 1152 for -l 0, else 4096. For subset streams this must be <= 4608 if the samplerate <= 48kHz, for subset streams with higher samplerates it must be <= 16384.
.TP
\fB-m, --mid-side\fR
Try mid-side coding for each frame (stereo input only)
.TP
\fB-M, --adaptive-mid-side\fR
Adaptive mid-side coding for all frames (stereo input only)
.TP
\fB-0\&..-8, --compression-level-0\&..--compression-level-8\fR
Fastest compression..highest compression (default is -5). These are synonyms for other options:
.RS
.TP
\fB-0, --compression-level-0\fR
Synonymous with -l 0 -b 1152 -r 3 --no-mid-side
.TP
\fB-1, --compression-level-1\fR
Synonymous with -l 0 -b 1152 -M -r 3
.TP
\fB-2, --compression-level-2\fR
Synonymous with -l 0 -b 1152 -m -r 3
.TP
\fB-3, --compression-level-3\fR
Synonymous with -l 6 -b 4096 -r 4 --no-mid-side
.TP
\fB-4, --compression-level-4\fR
Synonymous with -l 8 -b 4096 -M -r 4
.TP
\fB-5, --compression-level-5\fR
Synonymous with -l 8 -b 4096 -m -r 5
.TP
\fB-6, --compression-level-6\fR
Synonymous with -l 8 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)
.TP
\fB-7, --compression-level-7\fR
Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)
.TP
\fB-8, --compression-level-8\fR
Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)
.RE
.TP
\fB--fast\fR
Fastest compression. Currently synonymous with -0.
.TP
\fB--best\fR
Highest compression. Currently synonymous with -8.
.TP
\fB-e, --exhaustive-model-search\fR
Do exhaustive model search (expensive!)
.TP
\fB-A \fIfunction\fB, --apodization=\fIfunction\fB\fR
Window audio data with given the apodization function. The functions are: bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), partial_tukey(n[/ov[/P]]), punchout_tukey(n[/ov[/P]]), welch.
For gauss(STDDEV), STDDEV is the standard deviation (0<STDDEV<=0.5).
For tukey(P), P specifies the fraction of the window that is tapered (0<=P<=1; P=0 corresponds to "rectangle" and P=1 corresponds to "hann").
For partial_tukey(n) and punchout_tukey(n), n apodization functions are added that span different parts of each block. Values of 2 to 6 seem to yield sane results. If necessary, an overlap can be specified, as can be the taper parameter, for example partial_tukey(2/0.2) or partial_tukey(2/0.2/0.5). ov should be smaller than 1 and can be negative.
Please note that P, STDDEV and ov are locale specific, so a comma as decimal separator might be required instead of a dot.
More than one -A option (up to 32) may be used. Any function that is specified erroneously is silently dropped. The encoder chooses suitable defaults in the absence of any -A options; any -A option specified replaces the default(s).
When more than one function is specified, then for every subframe the encoder will try each of them separately and choose the window that results in the smallest compressed subframe. Multiple functions can greatly increase the encoding time.
.TP
\fB-l \fI#\fB, --max-lpc-order=\fI#\fB\fR
Specifies the maximum LPC order. This number must be <= 32. For Subset streams, it must be <=12 if the sample rate is <=48kHz. If 0, the encoder will not attempt generic linear prediction, and use only fixed predictors. Using fixed predictors is faster but usually results in files being 5-10% larger.
.TP
\fB-p, --qlp-coeff-precision-search\fR
Do exhaustive search of LP coefficient quantization (expensive!). Overrides -q; does nothing if using -l 0
.TP
\fB-q \fI#\fB, --qlp-coeff-precision=\fI#\fB\fR
Precision of the quantized linear-predictor coefficients, 0 => let encoder decide (min is 5, default is 0)
.TP
\fB-r [\fI#\fB,]\fI#\fB, --rice-partition-order=[\fI#\fB,]\fI#\fB\fR
Set the [min,]max residual partition order (0..15). min defaults to 0 if unspecified. Default is -r 5.
.SS "FORMAT OPTIONS"
.TP
\fB--endian={\fIbig\fB|\fIlittle\fB}\fR
Set the byte order for samples
.TP
\fB--channels=\fI#\fB\fR
Set number of channels.
.TP
\fB--bps=\fI#\fB\fR
Set bits per sample.
.TP
\fB--sample-rate=\fI#\fB\fR
Set sample rate (in Hz).
.TP
\fB--sign={\fIsigned\fB|\fIunsigned\fB}\fR
Set the sign of samples (the default is signed).
.TP
\fB--input-size=\fI#\fB\fR
Specify the size of the raw input in bytes. If you are encoding raw samples from stdin, you must set this option in order to be able to use --skip, --until, --cuesheet, or other options that need to know the size of the input beforehand. If the size given is greater than what is found in the input stream, the encoder will complain about an unexpected end-of-file. If the size given is less, samples will be truncated.
.TP
\fB--force-raw-format\fR
Force input (when encoding) or output (when decoding) to be treated as raw samples (even if filename ends in \fI\&.wav\fR).
.TP
\fB--force-aiff-format\fR
Force the decoder to output AIFF format. This option is not needed if the output filename (as set by -o) ends with \fI\&.aif\fR or \fI\&.aiff\fR\&. Also, this option has no effect when encoding since input AIFF is auto-detected.
.TP
\fB--force-rf64-format\fR
Force the decoder to output RF64 format. This option is not needed if the output filename (as set by -o) ends with \fI\&.rf64\fR\&. Also, this option has no effect when encoding since input RF64 is auto-detected.
.TP
\fB--force-wave64-format\fR
Force the decoder to output Wave64 format. This option is not needed if the output filename (as set by -o) ends with \fI\&.w64\fR\&. Also, this option has no effect when encoding since input Wave64 is auto-detected.
.SS "NEGATIVE OPTIONS"
.TP
\fB--no-adaptive-mid-side\fR
.TP
\fB--no-cued-seekpoints\fR
.TP
\fB--no-decode-through-errors\fR
.TP
\fB--no-delete-input-file\fR
.TP
\fB--no-preserve-modtime\fR
.TP
\fB--no-keep-foreign-metadata\fR
.TP
\fB--no-exhaustive-model-search\fR
.TP
\fB--no-force\fR
.TP
\fB--no-lax\fR
.TP
\fB--no-mid-side\fR
.TP
\fB--no-ogg\fR
.TP
\fB--no-padding\fR
.TP
\fB--no-qlp-coeff-prec-search\fR
.TP
\fB--no-replay-gain\fR
.TP
\fB--no-residual-gnuplot\fR
.TP
\fB--no-residual-text\fR
.TP
\fB--no-sector-align\fR
.TP
\fB--no-seektable\fR
.TP
\fB--no-silent\fR
.TP
\fB--no-verify\fR
.TP
\fB--no-warnings-as-errors\fR
These flags can be used to invert the sense of the corresponding normal option.
.SH "SEE ALSO"
.PP
metaflac(1)
.PP
The programs are documented fully by HTML format documentation, available in \fI/usr/share/doc/libflac-doc/html\fR on Debian GNU/Linux systems.
.SH "AUTHOR"
.PP
This manual page was initially written by Matt Zimmerman <mdz@debian.org> for the Debian GNU/Linux system (but may be used by others). It has been kept up-to-date by the Xiph.org Foundation.

741
man/flac.md Normal file
View File

@ -0,0 +1,741 @@
% flac(1) Version 1.3.4 | Free Lossless Audio Codec conversion tool
# NAME
flac - Free Lossless Audio Codec
# SYNOPSIS
**flac** \[ *OPTIONS* \] \[ *infile.wav* \| *infile.rf64* \|
*infile.aiff* \| *infile.raw* \| *infile.flac* \| *infile.oga* \|
*infile.ogg* \| **-** *...* \]
**flac** \[ **-d** \| **\--decode** \| **-t** \| **\--test** \| **-a** \|
**\--analyze** \] \[ *OPTIONS* \] \[ *infile.flac* \| *infile.oga* \|
*infile.ogg* \| **-** *...* \]
# DESCRIPTION
**flac** is a command-line tool for encoding, decoding, testing and
analyzing FLAC streams.
# GENERAL USAGE
**flac** supports as input RIFF WAVE, Wave64, RF64, AIFF, FLAC or Ogg
FLAC format, or raw interleaved samples. The decoder currently can output
to RIFF WAVE, Wave64, RF64, or AIFF format, or raw interleaved samples.
flac only supports linear PCM samples (in other words, no A-LAW, uLAW,
etc.), and the input must be between 4 and 32 bits per sample.
flac assumes that files ending in ".wav" or that have the RIFF WAVE
header present are WAVE files, files ending in ".w64" or have the Wave64
header present are Wave64 files, files ending in ".rf64" or have the
RF64 header present are RF64 files, files ending in ".aif" or ".aiff" or
have the AIFF header present are AIFF files, files ending in ".flac"
or have the FLAC header present are FLAC files and files ending in ".oga"
or ".ogg" or have the Ogg FLAC header present are Ogg FLAC files.
Other than this, flac makes no assumptions about file extensions, though
the convention is that FLAC files have the extension ".flac"
(or ".fla" on ancient "8.3" file systems like FAT-16).
Before going into the full command-line description, a few other things
help to sort it out:
1. flac encodes by default, so you must use -d to decode
2. the options -0 .. -8 (or --fast and --best) that control the
compression level actually are just synonyms for different groups of
specific encoding options (described later) and you can get the same
effect by using the same options. When specific options are specified
they take priority over the compression level no matter the order
3. flac behaves similarly to gzip in the way it handles input and output
files
4. the order in which options are specified is generally not important
Skip to the examples below for examples of some common tasks.
flac will be invoked one of four ways, depending on whether you are
encoding, decoding, testing, or analyzing. Encoding is the default
invocation, but can be switch to decoding with **-d**, analysis with
**-a** or testing with **-t**. Depending on which way is chosen,
encoding, decoding, analysis or testing options can be used, see section
OPTIONS for details. General options can be used for all.
If only one inputfile is specified, it may be "-" for stdin. When stdin
is used as input, flac will write to stdout. Otherwise flac will perform
the desired operation on each input file to similarly named output files
(meaning for encoding, the extension will be replaced with ".flac", or
appended with ".flac" if the input file has no extension, and for
decoding, the extension will be ".wav" for WAVE output and ".raw" for raw
output). The original file is not deleted unless --delete-input-file is
specified.
If you are encoding/decoding from stdin to a file, you should use the -o
option like so:
flac [options] -o outputfile
flac -d [options] -o outputfile
which are better than:
flac [options] > outputfile
flac -d [options] > outputfile
since the former allows flac to seek backwards to write the STREAMINFO or
RIFF WAVE header contents when necessary.
Also, you can force output data to go to stdout using -c.
To encode or decode files that start with a dash, use -- to signal the
end of options, to keep the filenames themselves from being treated as
options:
flac -V -- -01-filename.wav
The encoding options affect the compression ratio and encoding speed. The
format options are used to tell flac the arrangement of samples if the
input file (or output file when decoding) is a raw file. If it is a RIFF
WAVE, Wave64, RF64, or AIFF file the format options are not needed since
they are read from the file's header.
In test mode, flac acts just like in decode mode, except no output file
is written. Both decode and test modes detect errors in the stream, but
they also detect when the MD5 signature of the decoded audio does not
match the stored MD5 signature, even when the bitstream is valid.
flac can also re-encode FLAC files. In other words, you can specify a
FLAC or Ogg FLAC file as an input to the encoder and it will decoder it
and re-encode it according to the options you specify. It will also
preserve all the metadata unless you override it with other options (e.g.
specifying new tags, seekpoints, cuesheet, padding, etc.).
flac has been tuned so that the default settings yield a good speed vs.
compression tradeoff for many kinds of input. However, if you are looking
to maximize the compression rate or speed, or want to use the full power
of FLAC's metadata system, see the page titled 'About the FLAC Format' on
the FLAC website.
# EXAMPLES
Some common **encoding** tasks using flac:
`flac abc.wav`
: Encode abc.wav to abc.flac using the default compression setting. abc.wav is not deleted.
`flac --delete-input-file abc.wav`
: Like above, except abc.wav is deleted if there were no errors.
`flac --delete-input-file -w abc.wav`
: Like above, except abc.wav is deleted if there were no errors or warnings.
`flac --best abc.wav`
: Encode abc.wav to abc.flac using the highest compression setting.
`flac --verify abc.wav`
: Encode abc.wav to abc.flac and internally decode abc.flac to make sure it matches abc.wav.
`flac -o my.flac abc.wav`
: Encode abc.wav to my.flac.
`flac -T "TITLE=Bohemian Rhapsody" -T "ARTIST=Queen" abc.wav`
: Encode abc.wav and add some tags at the same time to abc.flac.
`flac *.wav`
: Encode all .wav files in the current directory.
`flac abc.aiff`
: Encode abc.aiff to abc.flac.
`flac abc.rf64`
: Encode abc.rf64 to abc.flac.
`flac abc.w64`
: Encode abc.w64 to abc.flac.
`flac abc.flac --force`
: This one's a little tricky: notice that flac is in encode mode by
default (you have to specify -d to decode) so this command actually
recompresses abc.flac back to abc.flac. --force is needed to make
sure you really want to overwrite abc.flac with a new version. Why
would you want to do this? It allows you to recompress an existing
FLAC file with (usually) higher compression options or a newer
version of FLAC and preserve all the metadata like tags too.
Some common **decoding** tasks using flac:
`flac -d abc.flac`
: Decode abc.flac to abc.wav. abc.flac is not deleted. NOTE: Without
-d it means re-encode abc.flac to abc.flac (see above).
`flac -d --force-aiff-format abc.flac`
`flac -d -o abc.aiff abc.flac`
: Two different ways of decoding abc.flac to abc.aiff (AIFF format).
abc.flac is not deleted.
`flac -d --force-rf64-format abc.flac`
`flac -d -o abc.rf64 abc.flac`
: Two different ways of decoding abc.flac to abc.rf64 (RF64 format).
abc.flac is not deleted.
`flac -d --force-wave64-format abc.flac`
`flac -d -o abc.w64 abc.flac`
: Two different ways of decoding abc.flac to abc.w64 (Wave64 format).
abc.flac is not deleted.
`flac -d -F abc.flac`
: Decode abc.flac to abc.wav and don't abort if errors are found
(useful for recovering as much as possible from corrupted files).
# OPTIONS
A summary of options is included below. For a complete description, see
the HTML documentation.
## GENERAL OPTIONS
**-v, \--version**
: Show the flac version number
**-h, \--help**
: Show basic usage and a list of all options
**-H, \--explain**
: Show detailed explanation of usage and all options
**-d, \--decode**
: Decode (the default behavior is to encode)
**-t, \--test**
: Test a flac encoded file (same as -d except no decoded file is written)
**-a, \--analyze**
: Analyze a FLAC encoded file (same as -d except an analysis file is
written)
**-c, \--stdout**
: Write output to stdout
**-s, \--silent**
: Silent mode (do not write runtime encode/decode statistics to stderr)
**\--totally-silent**
: Do not print anything of any kind, including warnings or errors. The
exit code will be the only way to determine successful completion.
**\--no-utf8-convert**
: Do not convert tags from local charset to UTF-8. This is useful for
scripts, and setting tags in situations where the locale is wrong.
This option must appear before any tag options!
**-w, \--warnings-as-errors**
: Treat all warnings as errors (which cause flac to terminate with a
non-zero exit code).
**-f, \--force**
: Force overwriting of output files. By default, flac warns that the
output file already exists and continues to the next file.
**-o** *filename***, \--output-name=***filename*
: 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.
**\--output-prefix=***string*
: Prefix each output file name with the given string. This can be
useful for encoding or decoding files to a different directory. Make
sure if your string is a path name that it ends with a trailing \`/'
(slash).
**\--delete-input-file**
: 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.
**\--preserve-modtime**
: Output files have their timestamps/permissions set to match those of
their inputs (this is default). Use \--no-preserve-modtime to make
output files have the current time and default permissions.
**\--keep-foreign-metadata**
: If encoding, save WAVE, RF64, or AIFF non-audio chunks in FLAC
metadata. If decoding, restore any saved non-audio chunks from FLAC
metadata when writing the decoded file. Foreign metadata cannot be
transcoded, e.g. WAVE chunks saved in a FLAC file cannot be restored
when decoding to AIFF. Input and output must be regular files (not
stdin or stdout).
**\--keep-foreign-metadata-if-present**
: Like \--keep-foreign-metadata, but without throwing an error if
foreign metadata cannot be found or restored, instead printing a
warning.
**\--skip={***\#***\|***mm:ss.ss***}**
: Skip over the first number of samples of the input. This works for
both encoding and decoding, but not testing. The alternative form
mm:ss.ss can be used to specify minutes, seconds, and fractions of a
second.
**\--until={***\#***\|\[***+***\|***-***\]***mm:ss.ss***}**
: Stop at the given sample number for each input file. This works for
both encoding and decoding, but not testing. The given sample number
is not included in the decoded output. The alternative form mm:ss.ss
can be used to specify minutes, seconds, and fractions of a second.
If a \`+' (plus) sign is at the beginning, the \--until point is
relative to the \--skip point. If a \`-' (minus) sign is at the
beginning, the \--until point is relative to end of the audio.
**\--ogg**
: 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 '.oga' extension and will still be
decodable by flac. 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 '.oga' or '.ogg'.
**\--serial-number=***\#*
: When used with \--ogg, specifies the serial number to use for the
first Ogg FLAC stream, which is then incremented for each additional
stream. When encoding and no serial number is given, flac uses a
random number for the first stream, then increments it for each
additional stream. When decoding and no number is given, flac uses
the serial number of the first page.
## ANALYSIS OPTIONS
**\--residual-text**
: Includes the residual signal in the analysis file. This will make the
file very big, much larger than even the decoded file.
**\--residual-gnuplot**
: Generates a gnuplot file for every subframe; each file will contain
the residual distribution of the subframe. This will create a lot of
files.
## DECODING OPTIONS
**\--cue=\[***\#.#***\]\[-\[***\#.#***\]\]**
: Set the beginning and ending cuepoints to decode. The optional first
\#.# is the track and index point at which decoding will start; the
default is the beginning of the stream. The optional second \#.# is
the track and index point at which decoding will end; the default is
the end of the stream. If the cuepoint does not exist, the closest
one before it (for the start point) or after it (for the end point)
will be used. If those don't exist, the start of the stream (for the
start point) or end of the stream (for the end point) will be used.
The cuepoints are merely translated into sample numbers then used as
\--skip and \--until. A CD track can always be cued by, for example,
\--cue=9.1-10.1 for track 9, even if the CD has no 10th track.
**-F, \--decode-through-errors**
: By default flac stops decoding with an error and removes the
partially decoded file if it encounters a bitstream error. With -F,
errors are still printed but flac will continue decoding to
completion. Note that errors may cause the decoded audio to be
missing some samples or have silent sections.
**\--apply-replaygain-which-is-not-lossless\[=\<specification\>\]**
: Applies ReplayGain values while decoding. **WARNING: THIS IS NOT
LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH
THIS OPTION.** This option is useful for example in transcoding
media servers, where the client does not support ReplayGain. For
details on the use of this option, see the section **ReplayGain
application specification**.
## ENCODING OPTIONS
**-V, \--verify**
: Verify a correct encoding by decoding the output in parallel and
comparing to the original
**\--lax**
: Allow encoder to generate non-Subset files. The resulting FLAC file
may not be streamable or might have trouble being played in all
players (especially hardware devices), so you should only use this
option in combination with custom encoding options meant for
archival.
**\--replay-gain**
: Calculate ReplayGain values and store them as FLAC tags, similar to
vorbisgain. Title gains/peaks will be computed for each input file,
and an album gain/peak will be computed for all files. All input
files must have the same resolution, sample rate, and number of
channels. Only mono and stereo files are allowed, and the sample
rate must be one of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48
kHz. Also note that this option may leave a few extra bytes in a
PADDING block as the exact size of the tags is not known until all
files are processed. Note that this option cannot be used when
encoding to standard output (stdout).
**\--cuesheet=***filename*
: Import the given cuesheet file and store it in a CUESHEET metadata
block. This option may only be used when encoding a single file. A
seekpoint will be added for each index point in the cuesheet to the
SEEKTABLE unless \--no-cued-seekpoints is specified.
**\--picture={***FILENAME***\|***SPECIFICATION***}**
: Import a picture and store it in a PICTURE metadata block. More than
one \--picture option can be specified. Either a filename for the
picture file or a more complete specification form can be used. The
SPECIFICATION is a string whose parts are separated by \| (pipe)
characters. Some parts may be left empty to invoke default values.
FILENAME is just shorthand for "\|\|\|\|FILENAME". For the format of
SPECIFICATION, see the section **picture specification**.
**\--sector-align**
: Align encoding of multiple CD format files on sector boundaries. See the
HTML documentation for more information. This option is DEPRECATED and
may not exist in future versions of flac.
**\--ignore-chunk-sizes**
: When encoding to flac, ignore the file size headers in WAV and AIFF
files to attempt to work around problems with over-sized or malformed
files. WAV and AIFF files both have an unsigned 32 bit numbers in
the file header which specifes the length of audio data. Since this
number is unsigned 32 bits, that limits the size of a valid file to
being just over 4 Gigabytes. Files larger than this are mal-formed,
but should be read correctly using this option.
**-S {***\#***\|***X***\|***\#x***\|***\#s***}, \--seekpoint={***\#***\|***X***\|***\#x***\|***\#s***}**
: 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. Using \#s, a seekpoint will be
added every \# seconds (# does not have to be a whole number; it can
be, for example, 9.5, meaning a seekpoint every 9.5 seconds). 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 10s'. Use \--no-seektable for no SEEKTABLE. Note: '-S \#x' and
'-S \#s' 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).
**-P** *\#***, \--padding=***\#*
: Tell the encoder to write a PADDING metadata block of the given
length (in bytes) after the STREAMINFO block. 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. Note that the total
length of the PADDING block will be 4 bytes longer than the length
given because of the 4 metadata block header bytes. You can force no
PADDING block at all to be written with \--no-padding. The encoder
writes a PADDING block of 8192 bytes by default (or 65536 bytes if
the input audio stream is more that 20 minutes long).
**-T** *FIELD=VALUE***, \--tag=***FIELD=VALUE*
: Add a FLAC tag. The comment must adhere to the Vorbis comment spec;
i.e. the FIELD must contain only legal characters, terminated by an
'equals' sign. Make sure to quote the comment if necessary. This
option may appear more than once to add several comments. NOTE: all
tags will be added to all encoded files.
**\--tag-from-file=***FIELD=FILENAME*
: Like \--tag, except FILENAME is a file whose contents will be read
verbatim to set the tag value. The contents will be converted to
UTF-8 from the local charset. This can be used to store a cuesheet
in a tag (e.g. \--tag-from-file="CUESHEET=image.cue"). Do not try to
store binary data in tag fields! Use APPLICATION blocks for that.
**-b** *\#***, \--blocksize=***\#*
: Specify the blocksize in samples. The default is 1152 for -l 0,
else 4096. For subset streams this must be \<= 4608 if the samplerate
\<= 48kHz, for subset streams with higher samplerates it must be \<=
16384.
**-m, \--mid-side**
: Try mid-side coding for each frame (stereo input only)
**-M, \--adaptive-mid-side**
: Adaptive mid-side coding for all frames (stereo input only)
**-0..-8, \--compression-level-0..\--compression-level-8**
: Fastest compression..highest compression (default is -5). These are
synonyms for other options:
**-0, \--compression-level-0**
: Synonymous with -l 0 -b 1152 -r 3 \--no-mid-side
**-1, \--compression-level-1**
: Synonymous with -l 0 -b 1152 -M -r 3
**-2, \--compression-level-2**
: Synonymous with -l 0 -b 1152 -m -r 3
**-3, \--compression-level-3**
: Synonymous with -l 6 -b 4096 -r 4 \--no-mid-side
**-4, \--compression-level-4**
: Synonymous with -l 8 -b 4096 -M -r 4
**-5, \--compression-level-5**
: Synonymous with -l 8 -b 4096 -m -r 5
**-6, \--compression-level-6**
: Synonymous with -l 8 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)
**-7, \--compression-level-7**
: Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)
**-8, \--compression-level-8**
: Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)
-A punchout_tukey(3)
**\--fast**
: Fastest compression. Currently synonymous with -0.
**\--best**
: Highest compression. Currently synonymous with -8.
**-e, \--exhaustive-model-search**
: Do exhaustive model search (expensive!)
**-A** *function***, \--apodization=***function*
: Window audio data with given the apodization function. See section
**Apodization functions** for details.
**-l** *\#***, \--max-lpc-order=***\#*
: Specifies the maximum LPC order. This number must be \<= 32. For
subset streams, it must be \<=12 if the sample rate is \<=48kHz. If
0, the encoder will not attempt generic linear prediction, and use
only fixed predictors. Using fixed predictors is faster but usually
results in files being 5-10% larger.
**-p, \--qlp-coeff-precision-search**
: Do exhaustive search of LP coefficient quantization (expensive!).
Overrides -q; does nothing if using -l 0
**-q** *\#***, \--qlp-coeff-precision=***\#*
: Precision of the quantized linear-predictor coefficients, 0 =\> let
encoder decide (min is 5, default is 0)
**-r \[***\#***,\]***\#***, \--rice-partition-order=\[***\#***,\]***\#*
: Set the \[min,\]max residual partition order (0..15). min defaults to
0 if unspecified. Default is -r 5.
## FORMAT OPTIONS
**\--endian={***big***\|***little***}**
: Set the byte order for samples
**\--channels=***\#*
: Set number of channels.
**\--bps=***\#*
: Set bits per sample.
**\--sample-rate=***\#*
: Set sample rate (in Hz).
**\--sign={***signed***\|***unsigned***}**
: Set the sign of samples (the default is signed).
**\--input-size=***\#*
: Specify the size of the raw input in bytes. If you are encoding raw
samples from stdin, you must set this option in order to be able to
use \--skip, \--until, \--cuesheet, or other options that need to
know the size of the input beforehand. If the size given is greater
than what is found in the input stream, the encoder will complain
about an unexpected end-of-file. If the size given is less, samples
will be truncated.
**\--force-raw-format**
: Force input (when encoding) or output (when decoding) to be treated
as raw samples (even if filename ends in *.wav*).
**\--force-aiff-format**
: Force the decoder to output AIFF format. This option is not needed if
the output filename (as set by -o) ends with *.aif* or *.aiff*. Also,
this option has no effect when encoding since input AIFF is
auto-detected.
**\--force-rf64-format**
: Force the decoder to output RF64 format. This option is not needed if
the output filename (as set by -o) ends with *.rf64*. Also, this
option has no effect when encoding since input RF64 is auto-detected.
**\--force-wave64-format**
: Force the decoder to output Wave64 format. This option is not needed
if the output filename (as set by -o) ends with *.w64*. Also, this
option has no effect when encoding since input Wave64 is
auto-detected.
## NEGATIVE OPTIONS
**\--no-adaptive-mid-side**
**\--no-cued-seekpoints**
**\--no-decode-through-errors**
**\--no-delete-input-file**
**\--no-preserve-modtime**
**\--no-keep-foreign-metadata**
**\--no-exhaustive-model-search**
**\--no-force**
**\--no-lax**
**\--no-mid-side**
**\--no-ogg**
**\--no-padding**
**\--no-qlp-coeff-prec-search**
**\--no-replay-gain**
**\--no-residual-gnuplot**
**\--no-residual-text**
**\--no-sector-align**
**\--no-seektable**
**\--no-silent**
**\--no-verify**
**\--no-warnings-as-errors**
These flags can be used to invert the sense of the corresponding normal
option.
## ReplayGain application specification
The option \--apply-replaygain-which-is-not-lossless\[=\<specification\>\]**
applies ReplayGain values while decoding. **WARNING: THIS IS NOT
LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH THIS
OPTION.** This option is useful for example in transcoding media servers,
where the client does not support ReplayGain.
The equals sign and \<specification\> is optional. If omitted, the
default specification is 0aLn1.
The \<specification\> is a shorthand notation for describing how to apply
ReplayGain. All components are optional but order is important. '\[\]'
means 'optional'. '\|' means 'or'. '{}' means required. The format is:
\[\<preamp\>\]\[a\|t\]\[l\|L\]\[n{0\|1\|2\|3}\]
In which the following parameters are used:
- **preamp**: A floating point number in dB. This is added to the
existing gain value.
- **a\|t**: Specify 'a' to use the album gain, or 't' to use the track
gain. If tags for the preferred kind (album/track) do not exist but
tags for the other (track/album) do, those will be used instead.
- **l\|L**: Specify 'l' to peak-limit the output, so that the
ReplayGain peak value is full-scale. Specify 'L' to use a 6dB hard
limiter that kicks in when the signal approaches full-scale.
- **n{0\|1\|2\|3}**: Specify the amount of noise shaping. ReplayGain
synthesis happens in floating point; the result is dithered before
converting back to integer. This quantization adds noise. Noise
shaping tries to move the noise where you won't hear it as much.
0 means no noise shaping, 1 means 'low', 2 means 'medium', 3 means
'high'.
For example, the default of 0aLn1 means 0dB preamp, use album gain, 6dB
hard limit, low noise shaping. \--apply-replaygain-which-is-not-lossless=3
means 3dB preamp, use album gain, no limiting, no noise shaping.
flac uses the ReplayGain tags for the calculation. If a stream does
not have the required tags or they can't be parsed, decoding will
continue with a warning, and no ReplayGain is applied to that stream.
## Picture specification
This described the specification used for the **\--picture** option.
\[TYPE\]\|\[MIME-TYPE\]\|\[DESCRIPTION\]\|\[WIDTHxHEIGHTxDEPTH\[/COLORS\]\]\|FILE
TYPE is optional; it is a number from one of:
0. Other
1. 32x32 pixels 'file icon' (PNG only)
2. Other file icon
3. Cover (front)
4. Cover (back)
5. Leaflet page
6. Media (e.g. label side of CD)
7. Lead artist/lead performer/soloist
8. Artist/performer
9. Conductor
10. Band/Orchestra
11. Composer
12. Lyricist/text writer
13. Recording Location
14. During recording
15. During performance
16. Movie/video screen capture
17. A bright coloured fish
18. Illustration
19. Band/artist logotype
20. Publisher/Studio logotype
The default is 3 (front cover). There may only be one picture each of
type 1 and 2 in a file.
MIME-TYPE is optional; if left blank, it will be detected from the file.
For best compatibility with players, use pictures with MIME type
image/jpeg or image/png. The MIME type can also be \--\> to mean that
FILE is actually a URL to an image, though this use is discouraged.
DESCRIPTION is optional; the default is an empty string.
The next part specifies the resolution and color information. If the
MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave
this empty and they can be detected from the file. Otherwise, you must
specify the width in pixels, height in pixels, and color depth in
bits-per-pixel. If the image has indexed colors you should also specify
the number of colors used. When manually specified, it is not checked
against the file for accuracy.
FILE is the path to the picture file to be imported, or the URL if MIME
type is \--\>
For example, "\|image/jpeg\|\|\|../cover.jpg" will embed the JPEG file
at ../cover.jpg, defaulting to type 3 (front cover) and an empty
description. The resolution and color info will be retrieved from the
file itself.
The specification
"4\|\--\>\|CD\|320x300x24/173\|http://blah.blah/backcover.tiff" will
embed the given URL, with type 4 (back cover), description "CD", and a
manually specified resolution of 320x300, 24 bits-per-pixel, and 173
colors. The file at the URL will not be fetched; the URL itself is
stored in the PICTURE metadata block.
## Apodization functions
To improve LPC analysis, audio data is windowed . The window can be
selected with one or more **-A** options. Possible functions are:
bartlett, bartlett_hann, blackman, blackman_harris_4term_92db,
connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall,
rectangle, triangle, tukey(P), partial_tukey(n\[/ov\[/P\]\]),
punchout_tukey(n\[/ov\[/P\]\]), welch.
- For gauss(STDDEV), STDDEV is the standard deviation (0\<STDDEV\<=0.5).
- For tukey(P), P specifies the fraction of the window that is tapered
(0\<=P\<=1; P=0 corresponds to "rectangle" and P=1 corresponds to
"hann").
- For partial_tukey(n) and punchout_tukey(n), n apodization functions are
added that span different parts of each block. Values of 2 to 6 seem to
yield sane results. If necessary, an overlap can be specified, as can be
the taper parameter, for example partial_tukey(2/0.2) or
partial_tukey(2/0.2/0.5). ov should be smaller than 1 and can be
negative. The use of this is that different parts of a block are ignored
as the might contain transients which are hard to predict anyway. The
encoder will try each different added apodization (each covering a
different part of the block) to see which resulting predictor results in
the smallest representation.
Note that P, STDDEV and ov are locale specific, so a comma as
decimal separator might be required instead of a dot.
More than one -A option (up to 32) may be used. Any function that is
specified erroneously is silently dropped. The encoder chooses suitable
defaults in the absence of any -A options; any -A option specified
replaces the default(s).
When more than one function is specified, then for every subframe the
encoder will try each of them separately and choose the window that
results in the smallest compressed subframe. Multiple functions can
greatly increase the encoding time.
# SEE ALSO
**metaflac(1)**
# AUTHOR
This manual page was initially written by Matt Zimmerman
\<mdz@debian.org\> for the Debian GNU/Linux system (but may be used by
others). It has been kept up-to-date by the Xiph.org Foundation.

822
man/flac.sgml
View File

@ -1,822 +0,0 @@
<!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>2021/08/31</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>2002-2005, 2011-2021</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 choice=opt><replaceable>OPTIONS</replaceable></arg>
<group rep=repeat>
<arg><replaceable>infile.wav</replaceable></arg>
<arg><replaceable>infile.rf64</replaceable></arg>
<arg><replaceable>infile.aiff</replaceable></arg>
<arg><replaceable>infile.raw</replaceable></arg>
<arg><replaceable>infile.flac</replaceable></arg>
<arg><replaceable>infile.oga</replaceable></arg>
<arg><replaceable>infile.ogg</replaceable></arg>
<arg>-</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>flac</command>
<group>
<arg>-d</arg> <arg>--decode</arg>
<arg>-t</arg> <arg>--test</arg>
<arg>-a</arg> <arg>--analyze</arg>
</group>
<arg choice=opt><replaceable>OPTIONS</replaceable></arg>
<group rep=repeat>
<arg><replaceable>infile.flac</replaceable></arg>
<arg><replaceable>infile.oga</replaceable></arg>
<arg><replaceable>infile.ogg</replaceable></arg>
<arg>-</arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para><command>flac</command> is a command-line tool for encoding, decoding, testing and analyzing FLAC streams.</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>General Options</title>
<variablelist>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem>
<para>Show the flac version number</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--help</option>
</term>
<listitem>
<para>Show basic usage and a list of all options</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-H</option>, <option>--explain</option>
</term>
<listitem>
<para>Show detailed explanation of usage and all options</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--decode</option>
</term>
<listitem>
<para>Decode (the default behavior is to encode)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>, <option>--test</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>, <option>--analyze</option>
</term>
<listitem>
<para>Analyze a FLAC encoded file (same as -d except an analysis file is written)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--stdout</option>
</term>
<listitem>
<para>Write output to stdout</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--silent</option>
</term>
<listitem>
<para>Silent mode (do not write runtime encode/decode statistics to stderr)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--totally-silent</option>
</term>
<listitem>
<para>Do not print anything of any kind, including warnings or errors. The exit code will be the only way to determine successful completion.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-utf8-convert</option>
</term>
<listitem>
<para>Do not convert tags from local charset to UTF-8. This is useful for scripts, and setting tags in situations where the locale is wrong. This option must appear before any tag options!</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</option>, <option>--warnings-as-errors</option>
</term>
<listitem>
<para>Treat all warnings as errors (which cause flac to terminate with a non-zero exit code).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option>
</term>
<listitem>
<para>Force overwriting of output files. By default, flac warns that the output file already exists and continues to the next file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option> <replaceable>filename</replaceable>, <option>--output-name</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 or 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>--preserve-modtime</option>
</term>
<listitem>
<para>Output files have their timestamps/permissions set to match those of their inputs (this is default). Use --no-preserve-modtime to make output files have the current time and default permissions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--keep-foreign-metadata</option>
</term>
<listitem>
<para>If encoding, save WAVE, RF64, or AIFF non-audio chunks in FLAC metadata. If decoding, restore any saved non-audio chunks from FLAC metadata when writing the decoded file. Foreign metadata cannot be transcoded, e.g. WAVE chunks saved in a FLAC file cannot be restored when decoding to AIFF. Input and output must be regular files (not stdin or stdout).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--keep-foreign-metadata-if-present</option>
</term>
<listitem>
<para>Like --keep-foreign-metadata, but without throwing an error if foreign metadata cannot be found or restored, instead printing a warning.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--skip</option>={<replaceable>#</replaceable>|<replaceable>mm:ss.ss</replaceable>}</term>
<listitem>
<para>Skip over the first number of samples of the input. This works for both encoding and decoding, but not testing. The alternative form mm:ss.ss can be used to specify minutes, seconds, and fractions of a second.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--until</option>={<replaceable>#</replaceable>|[<replaceable>+</replaceable>|<replaceable>-</replaceable>]<replaceable>mm:ss.ss</replaceable>}</term>
<listitem>
<para>Stop at the given sample number for each input file. This works for both encoding and decoding, but not testing. The given sample number is not included in the decoded output. The alternative form mm:ss.ss can be used to specify minutes, seconds, and fractions of a second. If a `+' (plus) sign is at the beginning, the --until point is relative to the --skip point. If a `-' (minus) sign is at the beginning, the --until point is relative to end of the audio.</para>
</listitem>
</varlistentry>
<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 '.oga' 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 '.oga' or '.ogg'.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--serial-number</option>=<replaceable>#</replaceable></term>
<listitem>
<para>When used with --ogg, specifies the serial number to use for the first Ogg FLAC stream, which is then incremented for each additional stream. When encoding and no serial number is given, flac uses a random number for the first stream, then increments it for each additional stream. When decoding and no number is given, flac uses the serial number of the first page.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Analysis Options</title>
<variablelist>
<varlistentry>
<term><option>--residual-text</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>--residual-gnuplot</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>Decoding Options</title>
<variablelist>
<varlistentry>
<term><option>--cue=[<replaceable>#.#</replaceable>][-[<replaceable>#.#</replaceable>]]</option></term>
<listitem>
<para>Set the beginning and ending cuepoints to decode. The optional first #.# is the track and index point at which decoding will start; the default is the beginning of the stream. The optional second #.# is the track and index point at which decoding will end; the default is the end of the stream. If the cuepoint does not exist, the closest one before it (for the start point) or after it (for the end point) will be used. If those don't exist, the start of the stream (for the start point) or end of the stream (for the end point) will be used. The cuepoints are merely translated into sample numbers then used as --skip and --until. A CD track can always be cued by, for example, --cue=9.1-10.1 for track 9, even if the CD has no 10th track.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-F</option>, <option>--decode-through-errors</option>
</term>
<listitem>
<para>By default flac stops decoding with an error and removes the partially decoded file if it encounters a bitstream error. With -F, errors are still printed but flac will continue decoding to completion. Note that errors may cause the decoded audio to be missing some samples or have silent sections.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--apply-replaygain-which-is-not-lossless[=&lt;specification&gt;]</option>
</term>
<listitem>
<para>Applies ReplayGain values while decoding.</para>
<para>WARNING: THIS IS NOT LOSSLESS. DECODED AUDIO WILL NOT BE IDENTICAL TO THE ORIGINAL WITH THIS OPTION.</para>
<para>The equals sign and &lt;specification&gt; is optional. If omitted, the default is 0aLn1.</para>
<para>The &lt;specification&gt; is a shorthand notation for describing how to apply ReplayGain. All components are optional but order is important. '[]' means 'optional'. '|' means 'or'. '{}' means required. The format is:</para>
<para>[&lt;preamp&gt;][a|t][l|L][n{0|1|2|3}]</para>
<variablelist>
<varlistentry>
<term><option>preamp</option></term>
<listitem>
<para>A floating point number in dB. This is added to the existing gain value.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>a|t</option></term>
<listitem>
<para>Specify 'a' to use the album gain, or 't' to use the track gain. If tags for the preferred kind (album/track) do not exist but tags for the other (track/album) do, those will be used instead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>l|L</option></term>
<listitem>
<para>Specify 'l' to peak-limit the output, so that the ReplayGain peak value is full-scale. Specify 'L' to use a 6dB hard limiter that kicks in when the signal approaches full-scale.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>n{0|1|2|3}</option></term>
<listitem>
<para>Specify the amount of noise shaping. ReplayGain synthesis happens in floating point; the result is dithered before converting back to integer. This quantization adds noise. Noise shaping tries to move the noise where you won't hear it as much. 0 means no noise shaping, 1 means 'low', 2 means 'medium', 3 means 'high'.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For example, the default of 0aLn1 means 0dB preamp, use album gain, 6dB hard limit, low noise shaping.</para>
<para>--apply-replaygain-which-is-not-lossless=3 means 3dB preamp, use album gain, no limiting, no noise shaping.</para>
<para>flac uses the ReplayGain tags for the calculation. If a stream does not have the required tags or they can't be parsed, decoding will continue with a warning, and no ReplayGain is applied to that stream.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Encoding Options</title>
<variablelist>
<varlistentry>
<term><option>-V</option>, <option>--verify</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>--lax</option></term>
<listitem>
<para>Allow encoder to generate non-Subset files. The resulting FLAC file may not be streamable or might have trouble being played in all players (especially hardware devices), so you should only use this option in combination with custom encoding options meant for archival.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--replay-gain</option></term>
<listitem>
<para>Calculate ReplayGain values and store them as FLAC tags, similar to vorbisgain. Title gains/peaks will be computed for each input file, and an album gain/peak will be computed for all files. All input files must have the same resolution, sample rate, and number of channels. Only mono and stereo files are allowed, and the sample rate must be one of 8, 11.025, 12, 16, 22.05, 24, 32, 44.1, or 48 kHz. Also note that this option may leave a few extra bytes in a PADDING block as the exact size of the tags is not known until all files are processed. Note that this option cannot be used when encoding to standard output (stdout).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--cuesheet</option>=<replaceable>filename</replaceable></term>
<listitem>
<para>Import the given cuesheet file and store it in a CUESHEET metadata block. This option may only be used when encoding a single file. A seekpoint will be added for each index point in the cuesheet to the SEEKTABLE unless --no-cued-seekpoints is specified.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--picture</option>={<replaceable>FILENAME</replaceable>|<replaceable>SPECIFICATION</replaceable>}</term>
<listitem>
<para>Import a picture and store it in a PICTURE metadata block. More than one --picture command can be specified. Either a filename for the picture file or a more complete specification form can be used. The SPECIFICATION is a string whose parts are separated by | (pipe) characters. Some parts may be left empty to invoke default values. FILENAME is just shorthand for "||||FILENAME". The format of SPECIFICATION is</para>
<para>[TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE</para>
<para>TYPE is optional; it is a number from one of:</para>
<para>0: Other</para>
<para>1: 32x32 pixels 'file icon' (PNG only)</para>
<para>2: Other file icon</para>
<para>3: Cover (front)</para>
<para>4: Cover (back)</para>
<para>5: Leaflet page</para>
<para>6: Media (e.g. label side of CD)</para>
<para>7: Lead artist/lead performer/soloist</para>
<para>8: Artist/performer</para>
<para>9: Conductor</para>
<para>10: Band/Orchestra</para>
<para>11: Composer</para>
<para>12: Lyricist/text writer</para>
<para>13: Recording Location</para>
<para>14: During recording</para>
<para>15: During performance</para>
<para>16: Movie/video screen capture</para>
<para>17: A bright coloured fish</para>
<para>18: Illustration</para>
<para>19: Band/artist logotype</para>
<para>20: Publisher/Studio logotype</para>
<para>The default is 3 (front cover). There may only be one picture each of type 1 and 2 in a file.</para>
<para>MIME-TYPE is optional; if left blank, it will be detected from the file. For best compatibility with players, use pictures with MIME type image/jpeg or image/png. The MIME type can also be --&gt; to mean that FILE is actually a URL to an image, though this use is discouraged.</para>
<para>DESCRIPTION is optional; the default is an empty string.</para>
<para>The next part specifies the resolution and color information. If the MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave this empty and they can be detected from the file. Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel. If the image has indexed colors you should also specify the number of colors used. When manually specified, it is not checked against the file for accuracy.</para>
<para>FILE is the path to the picture file to be imported, or the URL if MIME type is --&gt;</para>
<para>For example, "|image/jpeg|||../cover.jpg" will embed the JPEG file at ../cover.jpg, defaulting to type 3 (front cover) and an empty description. The resolution and color info will be retrieved from the file itself.</para>
<para>The specification "4|-->|CD|320x300x24/173|http://blah.blah/backcover.tiff" will embed the given URL, with type 4 (back cover), description "CD", and a manually specified resolution of 320x300, 24 bits-per-pixel, and 173 colors. The file at the URL will not be fetched; the URL itself is stored in the PICTURE metadata block.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sector-align</option></term>
<listitem>
<para>Align encoding of multiple CD format files on sector boundaries. See the HTML documentation for more information. This option is DEPRECATED and may not exist in future versions of flac.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--ignore-chunk-sizes</option></term>
<listitem>
<para>When encoding to flac, ignore the file size headers in WAV and AIFF files to attempt to work around problems with over-sized or malformed files.</para>
<para>WAV and AIFF files both have an unsigned 32 bit numbers in the file header which specifes the length of audio data. Since this number is unsigned 32 bits, that limits the size of a valid file to being just over 4 Gigabytes. Files larger than this are mal-formed, but should be read correctly using this option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option> {<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>|<replaceable>#s</replaceable>}, <option>--seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>|<replaceable>#s</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. Using #s, a seekpoint will be added every # seconds (# does not have to be a whole number; it can be, for example, 9.5, meaning a seekpoint every 9.5 seconds). 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 10s'. Use --no-seektable for no SEEKTABLE. Note: '-S #x' and '-S #s' 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>#</replaceable>, <option>--padding</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Tell the encoder to write a PADDING metadata block of the given length (in bytes) after the STREAMINFO block. 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. Note that the total length of the PADDING block will be 4 bytes longer than the length given because of the 4 metadata block header bytes. You can force no PADDING block at all to be written with --no-padding. The encoder writes a PADDING block of 8192 bytes by default (or 65536 bytes if the input audio stream is more that 20 minutes long).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-T</option> <replaceable>FIELD=VALUE</replaceable>, <option>--tag</option>=<replaceable>FIELD=VALUE</replaceable></term>
<listitem>
<para>Add a FLAC tag. The comment must adhere to the Vorbis comment spec; i.e. the FIELD must contain only legal characters, terminated by an 'equals' sign. Make sure to quote the comment if necessary. This option may appear more than once to add several comments. NOTE: all tags will be added to all encoded files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tag-from-file</option>=<replaceable>FIELD=FILENAME</replaceable></term>
<listitem>
<para>Like --tag, except FILENAME is a file whose contents will be read verbatim to set the tag value. The contents will be converted to UTF-8 from the local charset. This can be used to store a cuesheet in a tag (e.g. --tag-from-file="CUESHEET=image.cue"). Do not try to store binary data in tag fields! Use APPLICATION blocks for that.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option> <replaceable>#</replaceable>, <option>--blocksize</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Specify the blocksize in samples. The default is 1152 for -l 0, else 4096. For subset streams this must be &lt;= 4608 if the samplerate &lt;= 48kHz, for subset streams with higher samplerates it must be &lt;= 16384.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option>, <option>--mid-side</option></term>
<listitem>
<para>Try mid-side coding for each frame (stereo input only)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-M</option>, <option>--adaptive-mid-side</option></term>
<listitem>
<para>Adaptive mid-side coding for all frames (stereo input only)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-0</option>..<option>-8</option>, <option>--compression-level-0</option>..<option>--compression-level-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>, <option>--compression-level-0</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -r 3 --no-mid-side</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-1</option>, <option>--compression-level-1</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -M -r 3</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-2</option>, <option>--compression-level-2</option></term>
<listitem>
<para>Synonymous with -l 0 -b 1152 -m -r 3</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-3</option>, <option>--compression-level-3</option></term>
<listitem>
<para>Synonymous with -l 6 -b 4096 -r 4 --no-mid-side</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-4</option>, <option>--compression-level-4</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4096 -M -r 4</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-5</option>, <option>--compression-level-5</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4096 -m -r 5</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-6</option>, <option>--compression-level-6</option></term>
<listitem>
<para>Synonymous with -l 8 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-7</option>, <option>--compression-level-7</option></term>
<listitem>
<para>Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-8</option>, <option>--compression-level-8</option></term>
<listitem>
<para>Synonymous with -l 12 -b 4096 -m -r 6 -A tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--fast</option></term>
<listitem>
<para>Fastest compression. Currently synonymous with -0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--best</option></term>
<listitem>
<para>Highest compression. Currently synonymous with -8.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--exhaustive-model-search</option></term>
<listitem>
<para>Do exhaustive model search (expensive!)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-A</option> <replaceable>function</replaceable>, <option>--apodization</option>=<replaceable>function</replaceable></term>
<listitem>
<para>Window audio data with given the apodization function. The functions are: bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), partial_tukey(n[/ov[/P]]), punchout_tukey(n[/ov[/P]]), welch.</para>
<para>For gauss(STDDEV), STDDEV is the standard deviation (0&lt;STDDEV&lt;=0.5).</para>
<para>For tukey(P), P specifies the fraction of the window that is tapered (0&lt;=P&lt;=1; P=0 corresponds to "rectangle" and P=1 corresponds to "hann").</para>
<para>For partial_tukey(n) and punchout_tukey(n), n apodization functions are added that span different parts of each block. Values of 2 to 6 seem to yield sane results. If necessary, an overlap can be specified, as can be the taper parameter, for example partial_tukey(2/0.2) or partial_tukey(2/0.2/0.5). ov should be smaller than 1 and can be negative.</para>
<para>Please note that P, STDDEV and ov are locale specific, so a comma as decimal separator might be required instead of a dot.</para>
<para>More than one -A option (up to 32) may be used. Any function that is specified erroneously is silently dropped. The encoder chooses suitable defaults in the absence of any -A options; any -A option specified replaces the default(s).</para>
<para>When more than one function is specified, then for every subframe the encoder will try each of them separately and choose the window that results in the smallest compressed subframe. Multiple functions can greatly increase the encoding time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option> <replaceable>#</replaceable>, <option>--max-lpc-order</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Specifies the maximum LPC order. This number must be &lt;= 32. For Subset streams, it must be &lt;=12 if the sample rate is &lt;=48kHz. If 0, the encoder will not attempt generic linear prediction, and use only fixed predictors. Using fixed predictors is faster but usually results in files being 5-10% larger.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--qlp-coeff-precision-search</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>#</replaceable>, <option>--qlp-coeff-precision</option>=<replaceable>#</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>#</replaceable>,]<replaceable>#</replaceable>, <option>--rice-partition-order</option>=[<replaceable>#</replaceable>,]<replaceable>#</replaceable></term>
<listitem>
<para>Set the [min,]max residual partition order (0..15). min defaults to 0 if unspecified. Default is -r 5.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Format Options</title>
<variablelist>
<varlistentry>
<term><option>--endian</option>={<replaceable>big</replaceable>|<replaceable>little</replaceable>}</term>
<listitem>
<para>Set the byte order for samples</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--channels</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Set number of channels.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--bps</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Set bits per sample.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sample-rate</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Set sample rate (in Hz).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sign</option>={<replaceable>signed</replaceable>|<replaceable>unsigned</replaceable>}</term>
<listitem>
<para>Set the sign of samples (the default is signed).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--input-size</option>=<replaceable>#</replaceable></term>
<listitem>
<para>Specify the size of the raw input in bytes. If you are encoding raw samples from stdin, you must set this option in order to be able to use --skip, --until, --cuesheet, or other options that need to know the size of the input beforehand. If the size given is greater than what is found in the input stream, the encoder will complain about an unexpected end-of-file. If the size given is less, samples will be truncated.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force-raw-format</option></term>
<listitem>
<para>Force input (when encoding) or output (when decoding) to be treated as raw samples (even if filename ends in <filename>.wav</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force-aiff-format</option></term>
<listitem>
<para>Force the decoder to output AIFF format. This option is not needed if the output filename (as set by -o) ends with <filename>.aif</filename> or <filename>.aiff</filename>. Also, this option has no effect when encoding since input AIFF is auto-detected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force-rf64-format</option></term>
<listitem>
<para>Force the decoder to output RF64 format. This option is not needed if the output filename (as set by -o) ends with <filename>.rf64</filename>. Also, this option has no effect when encoding since input RF64 is auto-detected.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--force-wave64-format</option></term>
<listitem>
<para>Force the decoder to output Wave64 format. This option is not needed if the output filename (as set by -o) ends with <filename>.w64</filename>. Also, this option has no effect when encoding since input Wave64 is auto-detected.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Negative Options</title>
<variablelist>
<varlistentry>
<term><option>--no-adaptive-mid-side</option></term>
<term><option>--no-cued-seekpoints</option></term>
<term><option>--no-decode-through-errors</option></term>
<term><option>--no-delete-input-file</option></term>
<term><option>--no-preserve-modtime</option></term>
<term><option>--no-keep-foreign-metadata</option></term>
<term><option>--no-exhaustive-model-search</option></term>
<term><option>--no-force</option></term>
<term><option>--no-lax</option></term>
<term><option>--no-mid-side</option></term>
<term><option>--no-ogg</option></term>
<term><option>--no-padding</option></term>
<term><option>--no-qlp-coeff-prec-search</option></term>
<term><option>--no-replay-gain</option></term>
<term><option>--no-residual-gnuplot</option></term>
<term><option>--no-residual-text</option></term>
<term><option>--no-sector-align</option></term>
<term><option>--no-seektable</option></term>
<term><option>--no-silent</option></term>
<term><option>--no-verify</option></term>
<term><option>--no-warnings-as-errors</option></term>
<listitem>
<para>These flags can be used to invert the sense of the corresponding normal option.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>metaflac(1)</para>
<para>The programs are documented fully by HTML format documentation, available in <filename>/usr/share/doc/libflac-doc/html</filename> on &debian; systems.</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>This manual page was initially written by &dhusername; &dhemail; for the &debian; system (but may be used by others). It has been kept up-to-date by the Xiph.org Foundation.</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:
-->

304
man/metaflac.1
View File

@ -1,304 +0,0 @@
.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "METAFLAC" "1" "2013/04/30" "" ""
.SH NAME
metaflac \- program to list, add, remove, or edit metadata in one or more FLAC files.
.SH SYNOPSIS
\fBmetaflac\fR [ \fB\fIoptions\fB\fR ] [ \fB\fIoperations\fB\fR ] \fB\fIFLACfile\fB\fR\fI ...\fR
.SH "DESCRIPTION"
.PP
Use \fBmetaflac\fR to list, add, remove, or edit
metadata in one or more FLAC files. You may perform one major operation,
or many shorthand operations at a time.
.SH "OPTIONS"
.TP
\fB--preserve-modtime\fR
Preserve the original modification time in spite of edits.
.TP
\fB--with-filename\fR
Prefix each output line with the FLAC file name (the default if
more than one FLAC file is specified).
.TP
\fB--no-filename\fR
Do not prefix each output line with the FLAC file name (the default
if only one FLAC file is specified).
.TP
\fB--no-utf8-convert\fR
Do not convert tags from UTF-8 to local charset, or vice versa. This is
useful for scripts, and setting tags in situations where the locale is wrong.
.TP
\fB--dont-use-padding\fR
By default metaflac tries to use padding where possible to avoid
rewriting the entire file if the metadata size changes. Use this
option to tell metaflac to not take advantage of padding this way.
.SH "SHORTHAND OPERATIONS"
.TP
\fB--show-md5sum\fR
Show the MD5 signature from the STREAMINFO block.
.TP
\fB--show-min-blocksize\fR
Show the minimum block size from the STREAMINFO block.
.TP
\fB--show-max-blocksize\fR
Show the maximum block size from the STREAMINFO block.
.TP
\fB--show-min-framesize\fR
Show the minimum frame size from the STREAMINFO block.
.TP
\fB--show-max-framesize\fR
Show the maximum frame size from the STREAMINFO block.
.TP
\fB--show-sample-rate\fR
Show the sample rate from the STREAMINFO block.
.TP
\fB--show-channels\fR
Show the number of channels from the STREAMINFO block.
.TP
\fB--show-bps\fR
Show the # of bits per sample from the STREAMINFO block.
.TP
\fB--show-total-samples\fR
Show the total # of samples from the STREAMINFO block.
.TP
\fB--show-vendor-tag\fR
Show the vendor string from the VORBIS_COMMENT block.
.TP
\fB--show-tag=name\fR
Show all tags where the field name matches 'name'.
.TP
\fB--remove-tag=name\fR
Remove all tags whose field name is 'name'.
.TP
\fB--remove-first-tag=name\fR
Remove first tag whose field name is 'name'.
.TP
\fB--remove-all-tags\fR
Remove all tags, leaving only the vendor string.
.TP
\fB--set-tag=field\fR
Add a tag. The field must comply with the
Vorbis comment spec, of the form "NAME=VALUE". If there is
currently no tag block, one will be created.
.TP
\fB--set-tag-from-file=field\fR
Like --set-tag, except the VALUE is a filename whose
contents will be read verbatim to set the tag value.
Unless --no-utf8-convert is specified, the contents will be
converted to UTF-8 from the local charset. This can be used
to store a cuesheet in a tag (e.g.
--set-tag-from-file="CUESHEET=image.cue"). Do not try to
store binary data in tag fields! Use APPLICATION blocks for
that.
.TP
\fB--import-tags-from=file\fR
Import tags from a file. Use '-' for stdin. Each
line should be of the form NAME=VALUE. Multi-line comments
are currently not supported. Specify --remove-all-tags and/or
--no-utf8-convert before --import-tags-from if necessary. If
FILE is '-' (stdin), only one FLAC file may be specified.
.TP
\fB--export-tags-to=file\fR
Export tags to a file. Use '-' for stdout. Each
line will be of the form NAME=VALUE. Specify
--no-utf8-convert if necessary.
.TP
\fB--import-cuesheet-from=file\fR
Import a cuesheet from a file. Use '-' for stdin. Only one
FLAC file may be specified. A seekpoint will be added for each
index point in the cuesheet to the SEEKTABLE unless
--no-cued-seekpoints is specified.
.TP
\fB--export-cuesheet-to=file\fR
Export CUESHEET block to a cuesheet file, suitable for use by
CD authoring software. Use '-' for stdout. Only one FLAC file
may be specified on the command line.
.TP
\fB--import-picture-from={\fIFILENAME\fB|\fISPECIFICATION\fB}\fR
Import a picture and store it in a PICTURE metadata block. More than one --import-picture-from command can be specified. Either a filename for the picture file or a more complete specification form can be used. The SPECIFICATION is a string whose parts are separated by | (pipe) characters. Some parts may be left empty to invoke default values. FILENAME is just shorthand for "||||FILENAME". The format of SPECIFICATION is
[TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE
TYPE is optional; it is a number from one of:
0: Other
1: 32x32 pixels 'file icon' (PNG only)
2: Other file icon
3: Cover (front)
4: Cover (back)
5: Leaflet page
6: Media (e.g. label side of CD)
7: Lead artist/lead performer/soloist
8: Artist/performer
9: Conductor
10: Band/Orchestra
11: Composer
12: Lyricist/text writer
13: Recording Location
14: During recording
15: During performance
16: Movie/video screen capture
17: A bright coloured fish
18: Illustration
19: Band/artist logotype
20: Publisher/Studio logotype
The default is 3 (front cover). There may only be one picture each of type 1 and 2 in a file.
MIME-TYPE is optional; if left blank, it will be detected from the file. For best compatibility with players, use pictures with MIME type image/jpeg or image/png. The MIME type can also be --> to mean that FILE is actually a URL to an image, though this use is discouraged.
DESCRIPTION is optional; the default is an empty string.
The next part specifies the resolution and color information. If the MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave this empty and they can be detected from the file. Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel. If the image has indexed colors you should also specify the number of colors used. When manually specified, it is not checked against the file for accuracy.
FILE is the path to the picture file to be imported, or the URL if MIME type is -->
For example, "|image/jpeg|||../cover.jpg" will embed the JPEG file at ../cover.jpg, defaulting to type 3 (front cover) and an empty description. The resolution and color info will be retrieved from the file itself.
The specification "4|-->|CD|320x300x24/173|http://blah.blah/backcover.tiff" will embed the given URL, with type 4 (back cover), description "CD", and a manually specified resolution of 320x300, 24 bits-per-pixel, and 173 colors. The file at the URL will not be fetched; the URL itself is stored in the PICTURE metadata block.
.TP
\fB--export-picture-to=file\fR
Export PICTURE block to a file. Use '-' for stdout. Only one FLAC file may be specified on the command line. The first PICTURE block will be exported unless --export-picture-to is preceded by a --block-number=# option to specify the exact metadata block to extract. Note that the block number is the one shown by --list.
.TP
\fB--add-replay-gain\fR
Calculates the title and album gains/peaks of the given FLAC
files as if all the files were part of one album, then stores
them as FLAC tags. The tags are the same as
those used by vorbisgain. Existing ReplayGain tags will be
replaced. If only one FLAC file is given, the album and title
gains will be the same. Since this operation requires two
passes, it is always executed last, after all other operations
have been completed and written to disk. All FLAC files
specified must have the same resolution, sample rate, and
number of channels. The sample rate must be one of 8, 11.025,
12, 16, 18.9, 22.05, 24, 28, 32, 37.8, 44.1, 48, 56, 64, 88.2,
96, 112, 128, 144, 176.4, or 192kHz.
.TP
\fB--scan-replay-gain\fR
Like --add-replay-gain, but only analyzes the files rather
than writing them to the tags.
.TP
\fB--remove-replay-gain\fR
Removes the ReplayGain tags.
.TP
\fB--add-seekpoint={\fI#\fB|\fIX\fB|\fI#x\fB|\fI#s\fB}\fR
Add seek points to a SEEKTABLE block. 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. Using #s, a
seekpoint will be added every # seconds (# does not have to be a
whole number; it can be, for example, 9.5, meaning a seekpoint
every 9.5 seconds). If no SEEKTABLE block exists, one will be
created. If one already exists, points will be added to the
existing table, and any duplicates will be turned into placeholder
points. You may use many --add-seekpoint options; the resulting
SEEKTABLE will be the unique-ified union of all such values.
Example: --add-seekpoint=100x --add-seekpoint=3.5s will add 100
evenly spaced seekpoints and a seekpoint every 3.5 seconds.
.TP
\fB--add-padding=length\fR
Add a padding block of the given length (in bytes). The overall
length of the new block will be 4 + length; the extra 4 bytes is
for the metadata block header.
.SH "MAJOR OPERATIONS"
.TP
\fB--list\fR
List the contents of one or more metadata blocks to stdout. By
default, all metadata blocks are listed in text format. Use the
following options to change this behavior:
.RS
.TP
\fB--block-number=#[,#[...]]\fR
An optional comma-separated list of block numbers to display.
The first block, the STREAMINFO block, is block 0.
.TP
\fB--block-type=type[,type[...]]\fR
.TP
\fB--except-block-type=type[,type[...]]\fR
An optional comma-separated list of block types to be included
or ignored with this option. Use only one of --block-type or
--except-block-type. The valid block types are: STREAMINFO,
PADDING, APPLICATION, SEEKTABLE, VORBIS_COMMENT, PICTURE. You
may narrow down the types of APPLICATION blocks displayed as
follows:
APPLICATION:abcd The APPLICATION block(s) whose textual repre-
sentation of the 4-byte ID is "abcd"
APPLICATION:0xXXXXXXXX The APPLICATION block(s) whose hexadecimal big-
endian representation of the 4-byte ID is
"0xXXXXXXXX". For the example "abcd" above the
hexadecimal equivalalent is 0x61626364
.sp
.RS
.B "Note:"
if both --block-number and --[except-]block-type are
specified, the result is the logical AND of both
arguments.
.RE
.TP
\fB--application-data-format=hexdump|text\fR
If the application block you are displaying contains binary
data but your --data-format=text, you can display a hex dump
of the application data contents instead using
--application-data-format=hexdump.
.RE
.TP
\fB--remove\fR
Remove one or more metadata blocks from the metadata. Unless
--dont-use-padding is specified, the blocks will be replaced with
padding. You may not remove the STREAMINFO block.
.RS
.TP
\fB--block-number=#[,#[...]]\fR
.TP
\fB--block-type=type[,type[...]]\fR
.TP
\fB--except-block-type=type[,type[...]]\fR
See --list above for usage.
.sp
.RS
.B "Note:"
if both --block-number and --[except-]block-type are
specified, the result is the logical AND of both arguments.
.RE
.RE
.TP
\fB--remove-all\fR
Remove all metadata blocks (except the STREAMINFO block) from the
metadata. Unless --dont-use-padding is specified, the blocks will
be replaced with padding.
.TP
\fB--merge-padding\fR
Merge adjacent PADDING blocks into single blocks.
.TP
\fB--sort-padding\fR
Move all PADDING blocks to the end of the metadata and merge them
into a single block.
.SH "SEE ALSO"
.PP
flac(1).

270
man/metaflac.md Normal file
View File

@ -0,0 +1,270 @@
% metaflac(1) Version 1.3.4 | Free Lossless Audio Codec metadata tool
# NAME
metaflac - program to list, add, remove, or edit metadata in one or more
FLAC files.
# SYNOPSIS
**metaflac** \[ *options* \] \[ *operations* \] *FLACfile ...*
# DESCRIPTION
Use **metaflac** to list, add, remove, or edit metadata in one or more
FLAC files. You may perform one major operation, or many shorthand
operations at a time.
# GENERAL USAGE
metaflac is the command-line .flac file metadata editor. You can use it
to list the contents of metadata blocks, edit, delete or insert blocks,
and manage padding.
metaflac takes a set of "options" (though some are not optional) and a
set of FLAC files to operate on. There are three kinds of "options":
- Major operations, which specify a mode of operation like listing
blocks, removing blocks, etc. These will have sub-operations describing
exactly what is to be done.
- Shorthand operations, which are convenient synonyms for major
operations. For example, there is a shorthand operation
--show-sample-rate that shows just the sample rate field from the
STREAMINFO metadata block.
- Global options, which affect all the operations.
All of these are described in the tables below. At least one shorthand
or major operation must be supplied. You can use multiple shorthand
operations to do more than one thing to a file or set of files. Most of
the common things to do to metadata have shorthand operations. As an
example, here is how to show the MD5 signatures for a set of three FLAC
files:
`metaflac --show-md5sum file1.flac file2.flac file3.flac`
Another example; this removes all DESCRIPTION and COMMENT tags in a set
of FLAC files, and uses the --preserve-modtime global option to keep the
FLAC file modification times the same (usually when files are edited the
modification time is set to the current time):
`metaflac --preserve-modtime --remove-tag=DESCRIPTION --remove-tag=COMMENT file1.flac file2.flac file3.flac`
# OPTIONS
**\--preserve-modtime**
: Preserve the original modification time in spite of edits.
**\--with-filename**
: Prefix each output line with the FLAC file name (the default if more
than one FLAC file is specified).
**\--no-filename**
: Do not prefix each output line with the FLAC file name (the default
if only one FLAC file is specified).
**\--no-utf8-convert**
: Do not convert tags from UTF-8 to local charset, or vice versa. This
is useful for scripts, and setting tags in situations where the
locale is wrong.
**\--dont-use-padding**
: By default metaflac tries to use padding where possible to avoid
rewriting the entire file if the metadata size changes. Use this
option to tell metaflac to not take advantage of padding this way.
# SHORTHAND OPERATIONS
**\--show-md5sum**
: Show the MD5 signature from the STREAMINFO block.
**\--show-min-blocksize**
: Show the minimum block size from the STREAMINFO block.
**\--show-max-blocksize**
: Show the maximum block size from the STREAMINFO block.
**\--show-min-framesize**
: Show the minimum frame size from the STREAMINFO block.
**\--show-max-framesize**
: Show the maximum frame size from the STREAMINFO block.
**\--show-sample-rate**
: Show the sample rate from the STREAMINFO block.
**\--show-channels**
: Show the number of channels from the STREAMINFO block.
**\--show-bps**
: Show the \# of bits per sample from the STREAMINFO block.
**\--show-total-samples**
: Show the total \# of samples from the STREAMINFO block.
**\--show-vendor-tag**
: Show the vendor string from the VORBIS_COMMENT block.
**\--show-tag=name**
: Show all tags where the field name matches 'name'.
**\--remove-tag=name**
: Remove all tags whose field name is 'name'.
**\--remove-first-tag=name**
: Remove first tag whose field name is 'name'.
**\--remove-all-tags**
: Remove all tags, leaving only the vendor string.
**\--set-tag=field**
: Add a tag. The field must comply with the Vorbis comment spec, of the
form "NAME=VALUE". If there is currently no tag block, one will be
created.
**\--set-tag-from-file=field**
: Like \--set-tag, except the VALUE is a filename whose contents will
be read verbatim to set the tag value. Unless \--no-utf8-convert is
specified, the contents will be converted to UTF-8 from the local
charset. This can be used to store a cuesheet in a tag (e.g.
\--set-tag-from-file="CUESHEET=image.cue"). Do not try to store
binary data in tag fields! Use APPLICATION blocks for that.
**\--import-tags-from=file**
: Import tags from a file. Use '-' for stdin. Each line should be of
the form NAME=VALUE. Multi-line comments are currently not supported.
Specify \--remove-all-tags and/or \--no-utf8-convert before
\--import-tags-from if necessary. If FILE is '-' (stdin), only one
FLAC file may be specified.
**\--export-tags-to=file**
: Export tags to a file. Use '-' for stdout. Each line will be of the
form NAME=VALUE. Specify \--no-utf8-convert if necessary.
**\--import-cuesheet-from=file**
: Import a cuesheet from a file. Use '-' for stdin. Only one FLAC file
may be specified. A seekpoint will be added for each index point in
the cuesheet to the SEEKTABLE unless \--no-cued-seekpoints is
specified.
**\--export-cuesheet-to=file**
: Export CUESHEET block to a cuesheet file, suitable for use by CD
authoring software. Use '-' for stdout. Only one FLAC file may be
specified on the command line.
**\--import-picture-from={***FILENAME***\|***SPECIFICATION***}**
: Import a picture and store it in a PICTURE metadata block. More than
one \--import-picture-from command can be specified. Either a filename
for the picture file or a more complete specification form can be
used. The SPECIFICATION is a string whose parts are separated by \|
(pipe) characters. Some parts may be left empty to invoke default
values. FILENAME is just shorthand for "\|\|\|\|FILENAME". For
details on the specification, see the section **Picture
specification** in the **flac(1)** man page.
**\--export-picture-to=file**
: Export PICTURE block to a file. Use '-' for stdout. Only one FLAC
file may be specified on the command line. The first PICTURE block
will be exported unless \--export-picture-to is preceded by a
\--block-number=# option to specify the exact metadata block to
extract. Note that the block number is the one shown by \--list.
**\--add-replay-gain**
: Calculates the title and album gains/peaks of the given FLAC files as
if all the files were part of one album, then stores them as FLAC
tags. The tags are the same as those used by vorbisgain. Existing
ReplayGain tags will be replaced. If only one FLAC file is given,
the album and title gains will be the same. Since this operation
requires two passes, it is always executed last, after all other
operations have been completed and written to disk. All FLAC files
specified must have the same resolution, sample rate, and number of
channels. The sample rate must be one of 8, 11.025, 12, 16, 18.9,
22.05, 24, 28, 32, 37.8, 44.1, 48, 56, 64, 88.2, 96, 112, 128, 144,
176.4, or 192kHz.
**\--scan-replay-gain**
: Like \--add-replay-gain, but only analyzes the files rather than
writing them to the tags.
**\--remove-replay-gain**
: Removes the ReplayGain tags.
**\--add-seekpoint={***\#***\|***X***\|***\#x***\|***\#s***}**
: Add seek points to a SEEKTABLE block. 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. Using \#s, a seekpoint will be
added every \# seconds (# does not have to be a whole number; it can
be, for example, 9.5, meaning a seekpoint every 9.5 seconds). If no
SEEKTABLE block exists, one will be created. If one already exists,
points will be added to the existing table, and any duplicates will
be turned into placeholder points. You may use many \--add-seekpoint
options; the resulting SEEKTABLE will be the unique-ified union of
all such values. Example: \--add-seekpoint=100x \--add-seekpoint=3.5s
will add 100 evenly spaced seekpoints and a seekpoint every 3.5
seconds.
**\--add-padding=length**
: Add a padding block of the given length (in bytes). The overall
length of the new block will be 4 + length; the extra 4 bytes is for
the metadata block header.
# MAJOR OPERATIONS
**\--list**
: List the contents of one or more metadata blocks to stdout. By
default, all metadata blocks are listed in text format. Use the
options **\--block-number**, **\--block-type** or
**\--except-block-type** to change this behavior.
**\--remove**
: Remove one or more metadata blocks from the metadata. Use the options
**\--block-number**, **\--block-type** or **\--except-block-type**
to specify which blocks should be removed. Note that if both
\--block-number and \--[except-]block-type are specified, the result
is the logical AND of both arguments. Unless \--dont-use-padding
is specified, the blocks will be replaced with padding. You may not
remove the STREAMINFO block.
**\--block-number=#\[,#\[...\]\]**
: An optional comma-separated list of block numbers to display. The
first block, the STREAMINFO block, is block 0.
**\--block-type=type\[,type\[...\]\]**
**\--except-block-type=type\[,type\[...\]\]**
: An optional comma-separated list of block types to be included or
ignored with this option. Use only one of \--block-type or
\--except-block-type. The valid block types are: STREAMINFO, PADDING,
APPLICATION, SEEKTABLE, VORBIS_COMMENT, PICTURE. You may narrow down
the types of APPLICATION blocks selected by appending APPLICATION
with a colon and the ID of the APPLICATION block in either ASCII
or hexadecimal representation. E.g. APPLICATION:abcd for the
APPLICATION block(s) whose textual representation of the 4-byte ID
is "abcd" or APPLICATION:0xXXXXXXXX for the APPLICATION block(s)
whose hexadecimal big- endian representation of the 4-byte ID
is "0xXXXXXXXX". For the example "abcd" above the hexadecimal
equivalalent is 0x61626364
**\--application-data-format=hexdump\|text**
: If the application block you are displaying contains binary data but
your \--data-format=text, you can display a hex dump of the
application data contents instead using
\--application-data-format=hexdump.
**\--remove-all**
: Remove all metadata blocks (except the STREAMINFO block) from the
metadata. Unless \--dont-use-padding is specified, the blocks will be
replaced with padding.
**\--merge-padding**
: Merge adjacent PADDING blocks into single blocks.
**\--sort-padding**
: Move all PADDING blocks to the end of the metadata and merge them
into a single block.
# SEE ALSO
**flac(1)**

581
man/metaflac.sgml
View File

@ -1,581 +0,0 @@
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Process this file with docbook-to-man to generate an nroff manual
page: `docbook-to-man manpage.sgml > manpage.1'. You may view
the manual page with: `docbook-to-man manpage.sgml | nroff -man |
less'. A typical entry in a Makefile or Makefile.am is:
manpage.1: manpage.sgml
docbook-to-man $< > $@
-->
<!-- This is based on an example constructed by Colin Watson
<email>cjwatson@debian.org</email>, based on a man page template
provided by Tom Christiansen <email>tchrist@jhereg.perl.com</email>
and a DocBook man page example by Craig Small
<email>csmall@debian.org</email>.
-->
<!-- Fill in the various UPPER CASE things here. -->
<!ENTITY manfirstname "<firstname>dann</firstname>">
<!ENTITY mansurname "<surname>frazier</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY mandate "<date>2013/04/30</date>">
<!-- SECTION should be 1-8, maybe with subsection. Other parameters are
allowed: see man(7), man(1). -->
<!ENTITY mansection "<manvolnum>1</manvolnum>">
<!ENTITY manemail "<email>dannf@debian.org</email>">
<!ENTITY manusername "dannf">
<!ENTITY manucpackage "<refentrytitle>METAFLAC</refentrytitle>">
<!ENTITY manpackage "metaflac">
]>
<refentry>
<refentryinfo>
<address>
&manemail;
</address>
<author>
&manfirstname;
&mansurname;
</author>
<copyright>
<year>2002-2005, 2011-2013</year>
<holder>&manusername;</holder>
</copyright>
&mandate;
</refentryinfo>
<refmeta>
&manucpackage;
&mansection;
</refmeta>
<refnamediv>
<refname>&manpackage;</refname>
<refpurpose>
program to list, add, remove, or edit metadata in one or more FLAC files.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&manpackage;</command>
<group choice="opt"><arg><replaceable>options</replaceable></arg></group>
<group choice="opt">
<arg><replaceable>operations</replaceable></arg></group>
<arg rep="repeat" choice="req"><replaceable>FLACfile</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>Use <command>&manpackage;</command> to list, add, remove, or edit
metadata in one or more FLAC files. You may perform one major operation,
or many shorthand operations at a time.</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term><option>--preserve-modtime</option></term>
<listitem>
<para>
Preserve the original modification time in spite of edits.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--with-filename</option></term>
<listitem>
<para>
Prefix each output line with the FLAC file name (the default if
more than one FLAC file is specified).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-filename</option></term>
<listitem>
<para>
Do not prefix each output line with the FLAC file name (the default
if only one FLAC file is specified).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-utf8-convert</option></term>
<listitem>
<para>
Do not convert tags from UTF-8 to local charset, or vice versa. This is
useful for scripts, and setting tags in situations where the locale is wrong.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--dont-use-padding</option></term>
<listitem>
<para>
By default metaflac tries to use padding where possible to avoid
rewriting the entire file if the metadata size changes. Use this
option to tell metaflac to not take advantage of padding this way.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SHORTHAND OPERATIONS</title>
<variablelist>
<varlistentry>
<term><option>--show-md5sum</option></term>
<listitem>
<para>
Show the MD5 signature from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-min-blocksize</option></term>
<listitem>
<para>
Show the minimum block size from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-max-blocksize</option></term>
<listitem>
<para>
Show the maximum block size from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-min-framesize</option></term>
<listitem>
<para>
Show the minimum frame size from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-max-framesize</option></term>
<listitem>
<para>
Show the maximum frame size from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-sample-rate</option></term>
<listitem>
<para>
Show the sample rate from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-channels</option></term>
<listitem>
<para>
Show the number of channels from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-bps</option></term>
<listitem>
<para>
Show the # of bits per sample from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-total-samples</option></term>
<listitem>
<para>
Show the total # of samples from the STREAMINFO block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-vendor-tag</option></term>
<listitem>
<para>
Show the vendor string from the VORBIS_COMMENT block.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--show-tag=name</option></term>
<listitem>
<para>
Show all tags where the field name matches 'name'.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-tag=name</option></term>
<listitem>
<para>
Remove all tags whose field name is 'name'.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-first-tag=name</option></term>
<listitem>
<para>
Remove first tag whose field name is 'name'.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-all-tags</option></term>
<listitem>
<para>
Remove all tags, leaving only the vendor string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--set-tag=field</option></term>
<listitem>
<para>
Add a tag. The field must comply with the
Vorbis comment spec, of the form "NAME=VALUE". If there is
currently no tag block, one will be created.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--set-tag-from-file=field</option></term>
<listitem>
<para>
Like --set-tag, except the VALUE is a filename whose
contents will be read verbatim to set the tag value.
Unless --no-utf8-convert is specified, the contents will be
converted to UTF-8 from the local charset. This can be used
to store a cuesheet in a tag (e.g.
--set-tag-from-file="CUESHEET=image.cue"). Do not try to
store binary data in tag fields! Use APPLICATION blocks for
that.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--import-tags-from=file</option></term>
<listitem>
<para>
Import tags from a file. Use '-' for stdin. Each
line should be of the form NAME=VALUE. Multi-line comments
are currently not supported. Specify --remove-all-tags and/or
--no-utf8-convert before --import-tags-from if necessary. If
FILE is '-' (stdin), only one FLAC file may be specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--export-tags-to=file</option></term>
<listitem>
<para>
Export tags to a file. Use '-' for stdout. Each
line will be of the form NAME=VALUE. Specify
--no-utf8-convert if necessary.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--import-cuesheet-from=file</option></term>
<listitem>
<para>
Import a cuesheet from a file. Use '-' for stdin. Only one
FLAC file may be specified. A seekpoint will be added for each
index point in the cuesheet to the SEEKTABLE unless
--no-cued-seekpoints is specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--export-cuesheet-to=file</option></term>
<listitem>
<para>
Export CUESHEET block to a cuesheet file, suitable for use by
CD authoring software. Use '-' for stdout. Only one FLAC file
may be specified on the command line.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--import-picture-from</option>={<replaceable>FILENAME</replaceable>|<replaceable>SPECIFICATION</replaceable>}</term>
<listitem>
<para>Import a picture and store it in a PICTURE metadata block. More than one --import-picture-from command can be specified. Either a filename for the picture file or a more complete specification form can be used. The SPECIFICATION is a string whose parts are separated by | (pipe) characters. Some parts may be left empty to invoke default values. FILENAME is just shorthand for "||||FILENAME". The format of SPECIFICATION is</para>
<para>[TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE</para>
<para>TYPE is optional; it is a number from one of:</para>
<para>0: Other</para>
<para>1: 32x32 pixels 'file icon' (PNG only)</para>
<para>2: Other file icon</para>
<para>3: Cover (front)</para>
<para>4: Cover (back)</para>
<para>5: Leaflet page</para>
<para>6: Media (e.g. label side of CD)</para>
<para>7: Lead artist/lead performer/soloist</para>
<para>8: Artist/performer</para>
<para>9: Conductor</para>
<para>10: Band/Orchestra</para>
<para>11: Composer</para>
<para>12: Lyricist/text writer</para>
<para>13: Recording Location</para>
<para>14: During recording</para>
<para>15: During performance</para>
<para>16: Movie/video screen capture</para>
<para>17: A bright coloured fish</para>
<para>18: Illustration</para>
<para>19: Band/artist logotype</para>
<para>20: Publisher/Studio logotype</para>
<para>The default is 3 (front cover). There may only be one picture each of type 1 and 2 in a file.</para>
<para>MIME-TYPE is optional; if left blank, it will be detected from the file. For best compatibility with players, use pictures with MIME type image/jpeg or image/png. The MIME type can also be --&gt; to mean that FILE is actually a URL to an image, though this use is discouraged.</para>
<para>DESCRIPTION is optional; the default is an empty string.</para>
<para>The next part specifies the resolution and color information. If the MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave this empty and they can be detected from the file. Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel. If the image has indexed colors you should also specify the number of colors used. When manually specified, it is not checked against the file for accuracy.</para>
<para>FILE is the path to the picture file to be imported, or the URL if MIME type is --&gt;</para>
<para>For example, "|image/jpeg|||../cover.jpg" will embed the JPEG file at ../cover.jpg, defaulting to type 3 (front cover) and an empty description. The resolution and color info will be retrieved from the file itself.</para>
<para>The specification "4|-->|CD|320x300x24/173|http://blah.blah/backcover.tiff" will embed the given URL, with type 4 (back cover), description "CD", and a manually specified resolution of 320x300, 24 bits-per-pixel, and 173 colors. The file at the URL will not be fetched; the URL itself is stored in the PICTURE metadata block.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--export-picture-to=file</option></term>
<listitem>
<para>
Export PICTURE block to a file. Use '-' for stdout. Only one FLAC file may be specified on the command line. The first PICTURE block will be exported unless --export-picture-to is preceded by a --block-number=# option to specify the exact metadata block to extract. Note that the block number is the one shown by --list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--add-replay-gain</option></term>
<listitem>
<para>
Calculates the title and album gains/peaks of the given FLAC
files as if all the files were part of one album, then stores
them as FLAC tags. The tags are the same as
those used by vorbisgain. Existing ReplayGain tags will be
replaced. If only one FLAC file is given, the album and title
gains will be the same. Since this operation requires two
passes, it is always executed last, after all other operations
have been completed and written to disk. All FLAC files
specified must have the same resolution, sample rate, and
number of channels. The sample rate must be one of 8, 11.025,
12, 16, 18.9, 22.05, 24, 28, 32, 37.8, 44.1, 48, 56, 64, 88.2,
96, 112, 128, 144, 176.4, or 192kHz.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--scan-replay-gain</option></term>
<listitem>
<para>
Like --add-replay-gain, but only analyzes the files rather
than writing them to the tags.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-replay-gain</option></term>
<listitem>
<para>
Removes the ReplayGain tags.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--add-seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>|<replaceable>#s</replaceable>}</term>
<listitem>
<para>
Add seek points to a SEEKTABLE block. 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. Using #s, a
seekpoint will be added every # seconds (# does not have to be a
whole number; it can be, for example, 9.5, meaning a seekpoint
every 9.5 seconds). If no SEEKTABLE block exists, one will be
created. If one already exists, points will be added to the
existing table, and any duplicates will be turned into placeholder
points. You may use many --add-seekpoint options; the resulting
SEEKTABLE will be the unique-ified union of all such values.
Example: --add-seekpoint=100x --add-seekpoint=3.5s will add 100
evenly spaced seekpoints and a seekpoint every 3.5 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--add-padding=length</option></term>
<listitem>
<para>
Add a padding block of the given length (in bytes). The overall
length of the new block will be 4 + length; the extra 4 bytes is
for the metadata block header.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>MAJOR OPERATIONS</title>
<variablelist>
<varlistentry>
<term><option>--list</option></term>
<listitem>
<para>
List the contents of one or more metadata blocks to stdout. By
default, all metadata blocks are listed in text format. Use the
following options to change this behavior:
</para>
<variablelist>
<varlistentry>
<term><option>--block-number=#[,#[...]]</option></term>
<listitem>
<para>
An optional comma-separated list of block numbers to display.
The first block, the STREAMINFO block, is block 0.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--block-type=type[,type[...]]</option></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--except-block-type=type[,type[...]]</option></term>
<listitem>
<para>
An optional comma-separated list of block types to be included
or ignored with this option. Use only one of --block-type or
--except-block-type. The valid block types are: STREAMINFO,
PADDING, APPLICATION, SEEKTABLE, VORBIS_COMMENT, PICTURE. You
may narrow down the types of APPLICATION blocks displayed as
follows:
</para>
<para>
APPLICATION:abcd The APPLICATION block(s) whose textual repre-
sentation of the 4-byte ID is "abcd"
APPLICATION:0xXXXXXXXX The APPLICATION block(s) whose hexadecimal big-
endian representation of the 4-byte ID is
"0xXXXXXXXX". For the example "abcd" above the
hexadecimal equivalalent is 0x61626364
</para>
<note>
<para>
if both --block-number and --[except-]block-type are
specified, the result is the logical AND of both
arguments.</para></note>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--application-data-format=hexdump|text</option></term>
<listitem>
<para>
If the application block you are displaying contains binary
data but your --data-format=text, you can display a hex dump
of the application data contents instead using
--application-data-format=hexdump.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove</option></term>
<listitem>
<para>
Remove one or more metadata blocks from the metadata. Unless
--dont-use-padding is specified, the blocks will be replaced with
padding. You may not remove the STREAMINFO block.
</para>
<variablelist>
<varlistentry>
<term><option>--block-number=#[,#[...]]</option></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--block-type=type[,type[...]]</option></term>
<listitem><para></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--except-block-type=type[,type[...]]</option></term>
<listitem>
<para>See --list above for usage.</para>
<note>
<para>
if both --block-number and --[except-]block-type are
specified, the result is the logical AND of both arguments.
</para></note>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--remove-all</option></term>
<listitem>
<para>
Remove all metadata blocks (except the STREAMINFO block) from the
metadata. Unless --dont-use-padding is specified, the blocks will
be replaced with padding.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--merge-padding</option></term>
<listitem>
<para>
Merge adjacent PADDING blocks into single blocks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--sort-padding</option></term>
<listitem>
<para>
Move all PADDING blocks to the end of the metadata and merge them
into a single block.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>flac(1).</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:
-->