Update of /cvsroot/audacity/lib-src/twolame/doc
In directory sc8-pr-cvs11.sourceforge.net:/tmp/cvs-serv26676/doc
Added Files:
Makefile.am Makefile.in api.txt doxygen.conf index.txt
psycho.txt twolame.1 twolame.1.txt twolame.1.xml vbr.txt
Log Message:
Add twolame MP2 import library to lib-src
--- NEW FILE: doxygen.conf ---
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
#
PROJECT_NAME = "libtwolame"
OUTPUT_DIRECTORY = .
CREATE_SUBDIRS = No
OUTPUT_LANGUAGE = English
INPUT = ../libtwolame/twolame.h
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_ALL = YES
QUIET = YES
WARNINGS = YES
GENERATE_HTML = YES
HTML_OUTPUT = html
DISABLE_INDEX = YES
SORT_MEMBER_DOCS = NO
SORT_BRIEF_DOCS = NO
ENUM_VALUES_PER_LINE = 1
GENERATE_LATEX = NO
GENERATE_RTF = NO
GENERATE_MAN = NO
GENERATE_XML = NO
--- NEW FILE: twolame.1.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
<refentry>
<refmeta>
<refentrytitle>twolame</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>twolame</refname>
<refpurpose>an optimised MPEG Audio Layer 2 (MP2) encoder</refpurpose>
</refnamediv>
<refsynopsisdiv>
<simpara><emphasis>twolame</emphasis> [options] <infile>
[outfile]</simpara>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<simpara>TwoLAME is an optimised MPEG Audio Layer 2 (MP2) encoder based on
tooLAME by
Mike Cheng, which in turn is based upon the ISO dist10 code and portions of
LAME. Encoding is performed by the libtwolame library backend.</simpara>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<refsect2>
<title>Input File</title>
<simpara>twolame uses libsndfile for reading the input sound file, so
the input file can be in any format supported by libsndfile.
To read raw PCM audio from STDIN, then use - as the input filename.</simpara>
</refsect2>
<refsect2>
<title>Output File</title>
<simpara>If no output filename is specified, then suffix of the input filename
is automatically changed to .mp2. To write the encoded audio to STDOUT
then use - as the output filename.</simpara>
</refsect2>
<refsect2>
<title>Input Options</title>
<variablelist>
<varlistentry>
<term>
-r, --raw-input
</term>
<listitem>
<simpara>
Specifies that input is raw 16-bit signed PCM audio.
If audio is stereo, than audio samples are interleaved
between the two channels.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-x, --byte-swap
</term>
<listitem>
<simpara>
Force byte-swapping of the input. Endian detection is performed
automatically by libsndfile, so this option shouldn't
normally be needed.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-s, --samplerate <int>
</term>
<listitem>
<simpara>
If inputting raw PCM sound, you must specify the sample rate of
the audio in Hz.
Valid sample rates: 16000, 22050, 24000, 32000, 44100, 48000Hz.
Default sample rate is 44100Hz.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-N, --channels <int>
</term>
<listitem>
<simpara>
If inputting raw PCM sound, you must specify the number of channels
in the input audio. Default number of channels is 2.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-g, --swap-channels
</term>
<listitem>
<simpara>
Swap the Left and Right channels of a stereo input file.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--scale <float>
</term>
<listitem>
<simpara>
Scale the input audio prior to encoding.
All of the input audio is multiplied by specified value.
Value between 0 and 1 will reduce the audio gain, and a value
above 1 will increase the gain of the audio.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--scale-l <float>
</term>
<listitem>
<simpara>
Same as --scale, but only affects the left channel.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--scale-r <float>
</term>
<listitem>
<simpara>
Same as --scale, but only affects the right channel.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Output Options</title>
<variablelist>
<varlistentry>
<term>
-m, --mode <char>
</term>
<listitem>
<simpara>
Choose the mode of the resulting audio. Default is auto.
</simpara>
<itemizedlist>
<listitem>
<simpara>
"a" auto - choose mode automatically based on the input
</simpara>
</listitem>
<listitem>
<simpara>
"s" stereo
</simpara>
</listitem>
<listitem>
<simpara>
"d" dual channel
</simpara>
</listitem>
<listitem>
<simpara>
"j" joint stereo
</simpara>
</listitem>
<listitem>
<simpara>
"m" mono
</simpara>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>
-a, --downmix
</term>
<listitem>
<simpara>
If the input file is stereo then, downmix the left and right
input channels into a single mono channel.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-b, --bitrate <int>
</term>
<listitem>
<simpara>
Sets the total bitrate (in kbps) for the output file.
The default bitrate depends on the number of
input channels and samplerate.
</simpara>
<literallayout class="monospaced">------------------------------
Sample Rate Mono Stereo
------------------------------
48000 96 192
44100 96 192
32000 80 160
24000 48 96
22050 48 96
16000 32 64
------------------------------</literallayout>
</listitem>
</varlistentry>
<varlistentry>
<term>
-P, --psyc-mode <int>
</term>
<listitem>
<simpara>
Choose the psycho-acoustic model to use (-1 to 4).
Model number -1 is turns off psycho-acoustic modelling and
uses fixed default values instead.
Please see the file <emphasis>psycho</emphasis> for a full description
of
each of the models available.
Default model is 3.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v, --vbr
</term>
<listitem>
<simpara>
Enable VBR mode. See <emphasis>vbr</emphasis> documentation file for
details.
Default VBR level is 5.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v, --vbr-level <float>
</term>
<listitem>
<simpara>
Enable VBR mode and set quality level.
The higher the number the better the quality.
Maximum range is -50 to 50 but useful range is -10 to 10.
See <emphasis>vbr</emphasis> documentation file for details.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-l, --ath <float>
</term>
<listitem>
<simpara>
Set the ATH level. Default level is 0.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-q, --quick <int>
</term>
<listitem>
<simpara>
Enable quick mode. Only re-calculate psycho-acoustic
model every specified number of frames.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-S, --single-frame
</term>
<listitem>
<simpara>
Enables single frame mode: only a single frame of MPEG audio
is output and then the program terminates.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Miscellaneous Options</title>
<variablelist>
<varlistentry>
<term>
-c, --copyright
</term>
<listitem>
<simpara>
Turn on Copyright flag in output bitstream.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-o, --non-original
</term>
<listitem>
<simpara>
Turn off Original flag in output bitstream.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--original
</term>
<listitem>
<simpara>
Turn on Original flag in output bitstream.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-p, --protect
</term>
<listitem>
<simpara>
Enable CRC error protection in output bitstream.
An extra 16-bit checksum is added to frames.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-d, --padding
</term>
<listitem>
<simpara>
Turn on padding in output bitstream.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-R, --reserve <int>
</term>
<listitem>
<simpara>
Reserve specified number of bits in the each from of the
output bitstream.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-e, --deemphasis <char>
</term>
<listitem>
<simpara>
Set the de-emphasis type (n/c/5). Default is none.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-E, --energy
</term>
<listitem>
<simpara>
Turn on energy level extensions.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Verbosity Options</title>
<variablelist>
<varlistentry>
<term>
-t, --talkativity <int>
</term>
<listitem>
<simpara>
Set the amount of information to be displayed on stderr (0 to 10).
Default is 2.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--quiet
</term>
<listitem>
<simpara>
Don't send any messages to stderr, unless there is an error.
(Same as --talkativity=0)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--brief
</term>
<listitem>
<simpara>
Only display a minimal number of messages while encoding.
This setting is quieter than the default talkativity setting.
(Same as --talkativity=1)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--verbose
</term>
<listitem>
<simpara>
Display an increased number of messages on stderr.
This setting is useful to diagnose problems.
(Same as --talkativity=4)
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Return Codes</title>
<simpara>If encoding completes successfully, then twolame will return 0.
However if encoding is not successful, then it will return one of the following
codes.</simpara>
<itemizedlist>
<listitem>
<simpara>
1 (No encoding performed)
</simpara>
</listitem>
<listitem>
<simpara>
2 (Error opening input file)
</simpara>
</listitem>
<listitem>
<simpara>
4 (Error opening output file)
</simpara>
</listitem>
<listitem>
<simpara>
6 (Error allocating memory)
</simpara>
</listitem>
<listitem>
<simpara>
8 (Error in chosen encoding parameters)
</simpara>
</listitem>
<listitem>
<simpara>
10 (Error reading input audio)
</simpara>
</listitem>
<listitem>
<simpara>
12 (Error occured while encoding)
</simpara>
</listitem>
<listitem>
<simpara>
14 (Error writing output audio)
</simpara>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>EXAMPLES</title>
<simpara>This will encode sound.wav to sound.mp2 using the default constant
bitrate of 192 kbps
and using the default psycho-acoustic model (model 3):</simpara>
<literallayout class="monospaced">twolame sound.wav</literallayout>
<simpara>Constant bitrate of 160kbps and joint stereo encoding, saved to file
sound_160.mp2:</simpara>
<literallayout class="monospaced">twolame -b 160 -m j sound.aiff
sound_160.mp2</literallayout>
<simpara>Encode sound.wav to newfile.mp2 using psycho-acoustic model 2 and
encoding
with variable bitrate:</simpara>
<literallayout class="monospaced">twolame -P 2 -v sound.wav
newfile.mp2</literallayout>
<simpara>Same as example above, except that the negative value of the "-V"
argument
means that the lower bitrates will be favoured over the higher ones:</simpara>
<literallayout class="monospaced">twolame -P 2 -V -5 sound.wav
newfile.mp2</literallayout>
<simpara>Resample audio file using sox and pipe straight through
twolame:</simpara>
<literallayout class="monospaced">sox sound_11025.aiff -t raw -r 16000 |
twolame -r -s 16000 - - > out.mp2</literallayout>
</refsect1>
<refsect1>
<title>AUTHORS</title>
<simpara>The twolame frontend was (re)written by Nicholas J Humfrey.
The libtwolame library is based on toolame by Mike Cheng.
For a full list of authors, please see the AUTHORS file.</simpara>
</refsect1>
<refsect1>
<title>RESOURCES</title>
<simpara>TwoLAME web site: http://www.twolame.org/</simpara>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<simpara>lame(1), mpg123(1), madplay(1), sox(1)</simpara>
</refsect1>
<refsect1>
<title>COPYING</title>
<simpara>Copyright © 2004-2005 The TwoLAME Project. Free use of this
software is
granted under the terms of the GNU Lesser General Public License
(LGPL).</simpara>
</refsect1>
</refentry>
--- NEW FILE: api.txt ---
The libtwolame API
==================
This is the interface for encoding PCM audio to MPEG Audio Layer 2.
It is 'very' similar to the libmp3lame API.
See simplefrontend/simplefrontend.c for a very simple application
using the API.
Steps to encode PCM to MP2
--------------------------
1. Grab a set of default options by calling:
twolame_options *encodeOptions;
encodeOptions = twolame_init();
2. Adjust those options to suit your requirements.
See twolame.h for a full list of options. eg.
twolame_set_out_samplerate(encodeOptions, 32000);
twolame_set_bitrate(encodeOptions, 160);
3. Initialise twolame library with these options by calling:
twolame_init_params(encodeOptions);
NOTE: The return value should be checked to see if the options were valid.
Currently only ever returns 0
4. Encode PCM audio to MP2 by calling:
int twolame_encode_buffer(
twolame_options *glopts, // the set of options you're using
const short int leftpcm[], // the left and right audio channels
const short int rightpcm[],
int num_samples, // the number of samples in each channel
unsigned char *mp2buffer, // a pointer to a buffer for the MP2 audio
data
// NB User must allocate space!
int mp2buffer_size); // The size of the mp2buffer that the user
allocated
int *mp2fill_size);
This function returns the number of bytes written into mp2buffer by the
library MPEG.
Multiple calls can be made to this function.
It is the users responsibility to:
- allocate the mp2buffer
- read the pcmaudio from somewhere with new samples always staring from
the beginning of the buffer
- write the mp2buffer contents to somewhere (it is overwritten with
each call)
5. Flush the encoder by calling:
int twolame_encode_flush(
twolame_options *glopts,
unsigned char *mp2buffer,
int mp2buffer_size);
When encoding is finished, unless there was exactly a multiple of 1152
samples/channel
sent to the encoder, there will be some remaining audio that is not
encoded. This function
encodes this last bit of audio by padding out with zeros until there is
1152 samples per channel
in the PCM audio buffers and then encoding this.
This function returns the number of bytes written into mp2buffer by the
library MPEG.
6. The user must "de-initialise" the encoder at the end by calling:
void twolame_close(twolame_options **glopts);
This function must be called to free all the memory and structures
associated with this set of encoding parameters.
POST: glopts = NULL
--- NEW FILE: Makefile.in ---
# Makefile.in generated by automake 1.7.9 from Makefile.am.
# @configure_input@
# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003
# Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
@SET_MAKE@
srcdir = @srcdir@
top_srcdir = @top_srcdir@
VPATH = @srcdir@
pkgdatadir = $(datadir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
top_builddir = ..
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
INSTALL = @INSTALL@
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
target_triplet = @target@
ACLOCAL = @ACLOCAL@
AMDEP_FALSE = @AMDEP_FALSE@
AMDEP_TRUE = @AMDEP_TRUE@
AMTAR = @AMTAR@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CFLAGS = @CFLAGS@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CXX = @CXX@
CXXCPP = @CXXCPP@
CXXDEPMODE = @CXXDEPMODE@
CXXFLAGS = @CXXFLAGS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
ECHO = @ECHO@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
F77 = @F77@
FFLAGS = @FFLAGS@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
LDFLAGS = @LDFLAGS@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
MAKEINFO = @MAKEINFO@
OBJEXT = @OBJEXT@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
PKG_CONFIG = @PKG_CONFIG@
RANLIB = @RANLIB@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
SNDFILE_CFLAGS = @SNDFILE_CFLAGS@
SNDFILE_LIBS = @SNDFILE_LIBS@
STRIP = @STRIP@
TWOLAME_BIN = @TWOLAME_BIN@
TWOLAME_SO_VERSION = @TWOLAME_SO_VERSION@
VERSION = @VERSION@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_CXX = @ac_ct_CXX@
ac_ct_F77 = @ac_ct_F77@
ac_ct_RANLIB = @ac_ct_RANLIB@
ac_ct_STRIP = @ac_ct_STRIP@
ac_pt_PKG_CONFIG = @ac_pt_PKG_CONFIG@
am__fastdepCC_FALSE = @am__fastdepCC_FALSE@
am__fastdepCC_TRUE = @am__fastdepCC_TRUE@
am__fastdepCXX_FALSE = @am__fastdepCXX_FALSE@
am__fastdepCXX_TRUE = @am__fastdepCXX_TRUE@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
datadir = @datadir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localstatedir = @localstatedir@
mandir = @mandir@
oldincludedir = @oldincludedir@
prefix = @prefix@
program_transform_name = @program_transform_name@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
sysconfdir = @sysconfdir@
target = @target@
target_alias = @target_alias@
target_cpu = @target_cpu@
target_os = @target_os@
target_vendor = @target_vendor@
man_MANS = twolame.1
htmldir = $(srcdir)/html
asciidoc = asciidoc -b xhtml11 \
-a revision="@PACKAGE_VERSION@" \
-a theme=twolame \
-a linkcss \
-a stylesdir=.
doxygen = doxygen doxygen.conf
docdir = $(datadir)/doc
pkgdocdir = $(docdir)/$(PACKAGE)
pkghtmldir = $(pkgdocdir)/html
pkghtml_DATA = \
$(htmldir)/api.html \
$(htmldir)/authors.html \
$(htmldir)/doxygen.css \
$(htmldir)/doxygen.png \
$(htmldir)/index.html \
$(htmldir)/changelog.html \
$(htmldir)/psycho.html \
$(htmldir)/readme.html \
$(htmldir)/todo.html \
$(htmldir)/twolame_8h-source.html \
$(htmldir)/twolame_8h.html \
$(htmldir)/twolame.1.html \
$(htmldir)/twolame.css \
$(htmldir)/twolame-manpage.css \
$(htmldir)/twolame-quirks.css \
$(htmldir)/vbr.html
pkgdoc_DATA = \
$(srcdir)/api.txt \
$(srcdir)/psycho.txt \
$(srcdir)/vbr.txt
EXTRA_DIST = \
$(man_MANS) \
$(pkgdoc_DATA) \
$(pkghtml_DATA) \
dist10-text/*.txt \
doxygen.conf \
index.txt \
twolame.1.txt \
twolame.1.xml
subdir = doc
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
mkinstalldirs = $(SHELL) $(top_srcdir)/build/mkinstalldirs
CONFIG_HEADER = $(top_builddir)/build/config.h
CONFIG_CLEAN_FILES =
DIST_SOURCES =
NROFF = nroff
MANS = $(man_MANS)
DATA = $(pkgdoc_DATA) $(pkghtml_DATA)
DIST_COMMON = $(srcdir)/Makefile.in Makefile.am
all: all-am
.SUFFIXES:
$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.ac $(ACLOCAL_M4)
cd $(top_srcdir) && \
$(AUTOMAKE) --gnu doc/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@
$(am__depfiles_maybe)
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
distclean-libtool:
-rm -f libtool
uninstall-info-am:
man1dir = $(mandir)/man1
install-man1: $(man1_MANS) $(man_MANS)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(man1dir)
@list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
for i in $$l2; do \
case "$$i" in \
*.1*) list="$$list $$i" ;; \
esac; \
done; \
for i in $$list; do \
if test -f $(srcdir)/$$i; then file=$(srcdir)/$$i; \
else file=$$i; fi; \
ext=`echo $$i | sed -e 's/^.*\\.//'`; \
case "$$ext" in \
1*) ;; \
*) ext='1' ;; \
esac; \
inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
inst=`echo $$inst | sed -e 's/^.*\///'`; \
inst=`echo $$inst | sed '$(transform)'`.$$ext; \
echo " $(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst"; \
$(INSTALL_DATA) $$file $(DESTDIR)$(man1dir)/$$inst; \
done
uninstall-man1:
@$(NORMAL_UNINSTALL)
@list='$(man1_MANS) $(dist_man1_MANS) $(nodist_man1_MANS)'; \
l2='$(man_MANS) $(dist_man_MANS) $(nodist_man_MANS)'; \
for i in $$l2; do \
case "$$i" in \
*.1*) list="$$list $$i" ;; \
esac; \
done; \
for i in $$list; do \
ext=`echo $$i | sed -e 's/^.*\\.//'`; \
case "$$ext" in \
1*) ;; \
*) ext='1' ;; \
esac; \
inst=`echo $$i | sed -e 's/\\.[0-9a-z]*$$//'`; \
inst=`echo $$inst | sed -e 's/^.*\///'`; \
inst=`echo $$inst | sed '$(transform)'`.$$ext; \
echo " rm -f $(DESTDIR)$(man1dir)/$$inst"; \
rm -f $(DESTDIR)$(man1dir)/$$inst; \
done
pkgdocDATA_INSTALL = $(INSTALL_DATA)
install-pkgdocDATA: $(pkgdoc_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(pkgdocdir)
@list='$(pkgdoc_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(pkgdocDATA_INSTALL) $$d$$p $(DESTDIR)$(pkgdocdir)/$$f"; \
$(pkgdocDATA_INSTALL) $$d$$p $(DESTDIR)$(pkgdocdir)/$$f; \
done
uninstall-pkgdocDATA:
@$(NORMAL_UNINSTALL)
@list='$(pkgdoc_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(pkgdocdir)/$$f"; \
rm -f $(DESTDIR)$(pkgdocdir)/$$f; \
done
pkghtmlDATA_INSTALL = $(INSTALL_DATA)
install-pkghtmlDATA: $(pkghtml_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(pkghtmldir)
@list='$(pkghtml_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(pkghtmlDATA_INSTALL) $$d$$p $(DESTDIR)$(pkghtmldir)/$$f"; \
$(pkghtmlDATA_INSTALL) $$d$$p $(DESTDIR)$(pkghtmldir)/$$f; \
done
uninstall-pkghtmlDATA:
@$(NORMAL_UNINSTALL)
@list='$(pkghtml_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(pkghtmldir)/$$f"; \
rm -f $(DESTDIR)$(pkghtmldir)/$$f; \
done
tags: TAGS
TAGS:
ctags: CTAGS
CTAGS:
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
top_distdir = ..
distdir = $(top_distdir)/$(PACKAGE)-$(VERSION)
distdir: $(DISTFILES)
$(mkinstalldirs) $(distdir)/$(htmldir) $(distdir)/$(srcdir)
$(distdir)/dist10-text
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's|.|.|g'`; \
list='$(DISTFILES)'; for file in $$list; do \
case $$file in \
$(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
$(top_srcdir)/*) file=`echo "$$file" | sed
"s|^$$topsrcdirstrip/|$(top_builddir)/|"`;; \
esac; \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
if test "$$dir" != "$$file" && test "$$dir" != "."; then \
dir="/$$dir"; \
$(mkinstalldirs) "$(distdir)$$dir"; \
else \
dir=''; \
fi; \
if test -d $$d/$$file; then \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
fi; \
cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
else \
test -f $(distdir)/$$file \
|| cp -p $$d/$$file $(distdir)/$$file \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-am
all-am: Makefile $(MANS) $(DATA)
installdirs:
$(mkinstalldirs) $(DESTDIR)$(man1dir) $(DESTDIR)$(pkgdocdir)
$(DESTDIR)$(pkghtmldir)
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
`test -z '$(STRIP)' || \
echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
mostlyclean-generic:
clean-generic:
distclean-generic:
-rm -f $(CONFIG_CLEAN_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean-am: clean-generic clean-libtool mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic distclean-libtool
dvi: dvi-am
dvi-am:
info: info-am
info-am:
install-data-am: install-man install-pkgdocDATA install-pkghtmlDATA
install-exec-am:
install-info: install-info-am
install-man: install-man1
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-generic mostlyclean-libtool
pdf: pdf-am
pdf-am:
ps: ps-am
ps-am:
uninstall-am: uninstall-info-am uninstall-man uninstall-pkgdocDATA \
uninstall-pkghtmlDATA
uninstall-man: uninstall-man1
.PHONY: all all-am check check-am clean clean-generic clean-libtool \
distclean distclean-generic distclean-libtool distdir dvi \
dvi-am info info-am install install-am install-data \
install-data-am install-exec install-exec-am install-info \
install-info-am install-man install-man1 install-pkgdocDATA \
install-pkghtmlDATA install-strip installcheck installcheck-am \
installdirs maintainer-clean maintainer-clean-generic \
mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \
ps ps-am uninstall uninstall-am uninstall-info-am uninstall-man \
uninstall-man1 uninstall-pkgdocDATA uninstall-pkghtmlDATA
twolame.1.xml: twolame.1.txt
asciidoc -d manpage -b docbook -o twolame.1.xml twolame.1.txt
twolame.1: twolame.1.xml
xmlto man twolame.1.xml
build-html:
rm -f $(htmldir)/*.html
$(doxygen)
rm -f $(htmldir)/index.html $(htmldir)/files.html
$(htmldir)/globals*.html
$(asciidoc) -o $(htmldir)/index.html $(srcdir)/index.txt
$(asciidoc) -o $(htmldir)/readme.html $(top_srcdir)/README
$(asciidoc) -o $(htmldir)/authors.html $(top_srcdir)/AUTHORS
$(asciidoc) -o $(htmldir)/changelog.html $(top_srcdir)/ChangeLog
$(asciidoc) -o $(htmldir)/todo.html $(top_srcdir)/TODO
$(asciidoc) -o $(htmldir)/api.html $(srcdir)/api.txt
$(asciidoc) -o $(htmldir)/psycho.html $(srcdir)/psycho.txt
$(asciidoc) -o $(htmldir)/vbr.html $(srcdir)/vbr.txt
$(asciidoc) -d manpage -o $(htmldir)/twolame.1.html
$(srcdir)/twolame.1.txt
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
--- NEW FILE: index.txt ---
TwoLAME Documentation
=====================
TwoLAME - an optimized MPEG Audio Layer 2 encoder
- link:readme.html[Read Me]
- link:twolame.1.html[TwoLAME(1) Manual Page]
- link:changelog.html[What is New]
- link:todo.html[TODO]
- link:api.html[libtwolame API Overview]
- link:twolame_8h.html[libtwolame API Reference]
- link:psycho.html[Psychoacoustic Models Overview]
- link:vbr.html[VBR Features Overview]
- link:authors.html[The TwoLAME Authors]
twolame homepage: link:http://www.twolame.org[http://www.twolame.org] +
twolame mailing list: link:http://lists.sourceforge.net/lists/listinfo/[EMAIL
PROTECTED]
--- NEW FILE: Makefile.am ---
## Man Page
man_MANS = twolame.1
twolame.1.xml: twolame.1.txt
asciidoc -d manpage -b docbook -o twolame.1.xml twolame.1.txt
twolame.1: twolame.1.xml
xmlto man twolame.1.xml
## Building HTML documentation Requires:
## asciidoc: http://www.methods.co.nz/asciidoc/
## doxygen: http://www.doxygen.org
##
htmldir=$(srcdir)/html
asciidoc=asciidoc -b xhtml11 \
-a revision="@PACKAGE_VERSION@" \
-a theme=twolame \
-a linkcss \
-a stylesdir=.
doxygen=doxygen doxygen.conf
build-html:
rm -f $(htmldir)/*.html
$(doxygen)
rm -f $(htmldir)/index.html $(htmldir)/files.html
$(htmldir)/globals*.html
$(asciidoc) -o $(htmldir)/index.html $(srcdir)/index.txt
$(asciidoc) -o $(htmldir)/readme.html $(top_srcdir)/README
$(asciidoc) -o $(htmldir)/authors.html $(top_srcdir)/AUTHORS
$(asciidoc) -o $(htmldir)/changelog.html $(top_srcdir)/ChangeLog
$(asciidoc) -o $(htmldir)/todo.html $(top_srcdir)/TODO
$(asciidoc) -o $(htmldir)/api.html $(srcdir)/api.txt
$(asciidoc) -o $(htmldir)/psycho.html $(srcdir)/psycho.txt
$(asciidoc) -o $(htmldir)/vbr.html $(srcdir)/vbr.txt
$(asciidoc) -d manpage -o $(htmldir)/twolame.1.html
$(srcdir)/twolame.1.txt
## Install HTML Documention
docdir = $(datadir)/doc
pkgdocdir = $(docdir)/$(PACKAGE)
pkghtmldir = $(pkgdocdir)/html
pkghtml_DATA = \
$(htmldir)/api.html \
$(htmldir)/authors.html \
$(htmldir)/doxygen.css \
$(htmldir)/doxygen.png \
$(htmldir)/index.html \
$(htmldir)/changelog.html \
$(htmldir)/psycho.html \
$(htmldir)/readme.html \
$(htmldir)/todo.html \
$(htmldir)/twolame_8h-source.html \
$(htmldir)/twolame_8h.html \
$(htmldir)/twolame.1.html \
$(htmldir)/twolame.css \
$(htmldir)/twolame-manpage.css \
$(htmldir)/twolame-quirks.css \
$(htmldir)/vbr.html
pkgdoc_DATA = \
$(srcdir)/api.txt \
$(srcdir)/psycho.txt \
$(srcdir)/vbr.txt
EXTRA_DIST = \
$(man_MANS) \
$(pkgdoc_DATA) \
$(pkghtml_DATA) \
dist10-text/*.txt \
doxygen.conf \
index.txt \
twolame.1.txt \
twolame.1.xml
--- NEW FILE: twolame.1 ---
.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "TWOLAME" 1 "" "" ""
.SH NAME
twolame \- an optimised MPEG Audio Layer 2 (MP2) encoder
.SH "SYNOPSIS"
\fItwolame\fR [options] <infile> [outfile]
.SH "DESCRIPTION"
TwoLAME is an optimised MPEG Audio Layer 2 (MP2) encoder based on tooLAME by
Mike Cheng, which in turn is based upon the ISO dist10 code and portions of
LAME\&. Encoding is performed by the libtwolame library backend\&.
.SH "OPTIONS"
.SS "Input File"
twolame uses libsndfile for reading the input sound file, so the input file can
be in any format supported by libsndfile\&. To read raw PCM audio from STDIN,
then use \- as the input filename\&.
.SS "Output File"
If no output filename is specified, then suffix of the input filename is
automatically changed to \&.mp2\&. To write the encoded audio to STDOUT then
use \- as the output filename\&.
.SS "Input Options"
.TP
\-r, \-\-raw\-input
Specifies that input is raw 16\-bit signed PCM audio\&. If audio is stereo,
than audio samples are interleaved between the two channels\&.
.TP
\-x, \-\-byte\-swap
Force byte\-swapping of the input\&. Endian detection is performed
automatically by libsndfile, so this option shouldn't normally be needed\&.
.TP
\-s, \-\-samplerate <int>
If inputting raw PCM sound, you must specify the sample rate of the audio in
Hz\&. Valid sample rates: 16000, 22050, 24000, 32000, 44100, 48000Hz\&. Default
sample rate is 44100Hz\&.
.TP
\-N, \-\-channels <int>
If inputting raw PCM sound, you must specify the number of channels in the
input audio\&. Default number of channels is 2\&.
.TP
\-g, \-\-swap\-channels
Swap the Left and Right channels of a stereo input file\&.
.TP
\-\-scale <float>
Scale the input audio prior to encoding\&. All of the input audio is multiplied
by specified value\&. Value between 0 and 1 will reduce the audio gain, and a
value above 1 will increase the gain of the audio\&.
.TP
\-\-scale\-l <float>
Same as \-\-scale, but only affects the left channel\&.
.TP
\-\-scale\-r <float>
Same as \-\-scale, but only affects the right channel\&.
.SS "Output Options"
.TP
\-m, \-\-mode <char>
Choose the mode of the resulting audio\&. Default is auto\&.
.RS
.TP 3
\(bu
"a" auto \- choose mode automatically based on the input
.TP
\(bu
"s" stereo
.TP
\(bu
"d" dual channel
.TP
\(bu
"j" joint stereo
.TP
\(bu
"m" mono
.LP
.RE
.IP
.TP
\-a, \-\-downmix
If the input file is stereo then, downmix the left and right input channels
into a single mono channel\&.
.TP
\-b, \-\-bitrate <int>
Sets the total bitrate (in kbps) for the output file\&. The default bitrate
depends on the number of input channels and samplerate\&.
.nf
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Sample Rate Mono Stereo
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
48000 96 192
44100 96 192
32000 80 160
24000 48 96
22050 48 96
16000 32 64
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.fi
.TP
\-P, \-\-psyc\-mode <int>
Choose the psycho\-acoustic model to use (\-1 to 4)\&. Model number \-1 is
turns off psycho\-acoustic modelling and uses fixed default values instead\&.
Please see the file \fIpsycho\fR for a full description of each of the models
available\&. Default model is 3\&.
.TP
\-v, \-\-vbr
Enable VBR mode\&. See \fIvbr\fR documentation file for details\&. Default VBR
level is 5\&.0\&.
.TP
\-v, \-\-vbr\-level <float>
Enable VBR mode and set quality level\&. The higher the number the better the
quality\&. Maximum range is \-50 to 50 but useful range is \-10 to 10\&. See
\fIvbr\fR documentation file for details\&.
.TP
\-l, \-\-ath <float>
Set the ATH level\&. Default level is 0\&.0\&.
.TP
\-q, \-\-quick <int>
Enable quick mode\&. Only re\-calculate psycho\-acoustic model every specified
number of frames\&.
.TP
\-S, \-\-single\-frame
Enables single frame mode: only a single frame of MPEG audio is output and then
the program terminates\&.
.SS "Miscellaneous Options"
.TP
\-c, \-\-copyright
Turn on Copyright flag in output bitstream\&.
.TP
\-o, \-\-non\-original
Turn off Original flag in output bitstream\&.
.TP
\-\-original
Turn on Original flag in output bitstream\&.
.TP
\-p, \-\-protect
Enable CRC error protection in output bitstream\&. An extra 16\-bit checksum is
added to frames\&.
.TP
\-d, \-\-padding
Turn on padding in output bitstream\&.
.TP
\-R, \-\-reserve <int>
Reserve specified number of bits in the each from of the output bitstream\&.
.TP
\-e, \-\-deemphasis <char>
Set the de\-emphasis type (n/c/5)\&. Default is none\&.
.TP
\-E, \-\-energy
Turn on energy level extensions\&.
.SS "Verbosity Options"
.TP
\-t, \-\-talkativity <int>
Set the amount of information to be displayed on stderr (0 to 10)\&. Default is
2\&.
.TP
\-\-quiet
Don't send any messages to stderr, unless there is an error\&. (Same as
\-\-talkativity=0)
.TP
\-\-brief
Only display a minimal number of messages while encoding\&. This setting is
quieter than the default talkativity setting\&. (Same as \-\-talkativity=1)
.TP
\-\-verbose
Display an increased number of messages on stderr\&. This setting is useful to
diagnose problems\&. (Same as \-\-talkativity=4)
.SH "RETURN CODES"
If encoding completes successfully, then twolame will return 0\&. However if
encoding is not successful, then it will return one of the following codes\&.
.TP 3
\(bu
1 (No encoding performed)
.TP
\(bu
2 (Error opening input file)
.TP
\(bu
4 (Error opening output file)
.TP
\(bu
6 (Error allocating memory)
.TP
\(bu
8 (Error in chosen encoding parameters)
.TP
\(bu
10 (Error reading input audio)
.TP
\(bu
12 (Error occured while encoding)
.TP
\(bu
14 (Error writing output audio)
.LP
.SH "EXAMPLES"
This will encode sound\&.wav to sound\&.mp2 using the default constant bitrate
of 192 kbps and using the default psycho\-acoustic model (model 3):
.nf
twolame sound\&.wav
.fi
Constant bitrate of 160kbps and joint stereo encoding, saved to file
sound_160\&.mp2:
.nf
twolame \-b 160 \-m j sound\&.aiff sound_160\&.mp2
.fi
Encode sound\&.wav to newfile\&.mp2 using psycho\-acoustic model 2 and encoding
with variable bitrate:
.nf
twolame \-P 2 \-v sound\&.wav newfile\&.mp2
.fi
Same as example above, except that the negative value of the "\-V" argument
means that the lower bitrates will be favoured over the higher ones:
.nf
twolame \-P 2 \-V \-5 sound\&.wav newfile\&.mp2
.fi
Resample audio file using sox and pipe straight through twolame:
.nf
sox sound_11025\&.aiff \-t raw \-r 16000 | twolame \-r \-s 16000 \- \- >
out\&.mp2
.fi
.SH "AUTHORS"
The twolame frontend was (re)written by Nicholas J Humfrey\&. The libtwolame
library is based on toolame by Mike Cheng\&. For a full list of authors, please
see the AUTHORS file\&.
.SH "RESOURCES"
TwoLAME web site: http://www\&.twolame\&.org/
.SH "SEE ALSO"
lame(1), mpg123(1), madplay(1), sox(1)
.SH "COPYING"
Copyright © 2004\-2005 The TwoLAME Project\&. Free use of this software is
granted under the terms of the GNU Lesser General Public License (LGPL)\&.
--- NEW FILE: twolame.1.txt ---
TWOLAME(1)
==========
Nicholas J Humfrey <[EMAIL PROTECTED]>
NAME
----
twolame - an optimised MPEG Audio Layer 2 (MP2) encoder
SYNOPSIS
--------
'twolame' [options] <infile> [outfile]
DESCRIPTION
-----------
TwoLAME is an optimised MPEG Audio Layer 2 (MP2) encoder based on tooLAME by
Mike Cheng, which in turn is based upon the ISO dist10 code and portions of
LAME. Encoding is performed by the libtwolame library backend.
OPTIONS
-------
Input File
~~~~~~~~~~
twolame uses libsndfile for reading the input sound file, so
the input file can be in any format supported by libsndfile.
To read raw PCM audio from STDIN, then use - as the input filename.
Output File
~~~~~~~~~~~
If no output filename is specified, then suffix of the input filename
is automatically changed to .mp2. To write the encoded audio to STDOUT
then use - as the output filename.
Input Options
~~~~~~~~~~~~~
-r, --raw-input::
Specifies that input is raw 16-bit signed PCM audio.
If audio is stereo, than audio samples are interleaved
between the two channels.
-x, --byte-swap::
Force byte-swapping of the input. Endian detection is performed
automatically by libsndfile, so this option shouldn't
normally be needed.
-s, --samplerate <int>::
If inputting raw PCM sound, you must specify the sample rate of
the audio in Hz.
Valid sample rates: 16000, 22050, 24000, 32000, 44100, 48000Hz.
Default sample rate is 44100Hz.
-N, --channels <int>::
If inputting raw PCM sound, you must specify the number of channels
in the input audio. Default number of channels is 2.
-g, --swap-channels::
Swap the Left and Right channels of a stereo input file.
--scale <float>::
Scale the input audio prior to encoding.
All of the input audio is multiplied by specified value.
Value between 0 and 1 will reduce the audio gain, and a value
above 1 will increase the gain of the audio.
--scale-l <float>::
Same as --scale, but only affects the left channel.
--scale-r <float>::
Same as --scale, but only affects the right channel.
Output Options
~~~~~~~~~~~~~~
-m, --mode <char>::
Choose the mode of the resulting audio. Default is auto.
- "a" auto - choose mode automatically based on the input
- "s" stereo
- "d" dual channel
- "j" joint stereo
- "m" mono
-a, --downmix::
If the input file is stereo then, downmix the left and right
input channels into a single mono channel.
-b, --bitrate <int>::
Sets the total bitrate (in kbps) for the output file.
The default bitrate depends on the number of
input channels and samplerate.
------------------------------
Sample Rate Mono Stereo
------------------------------
48000 96 192
44100 96 192
32000 80 160
24000 48 96
22050 48 96
16000 32 64
------------------------------
-P, --psyc-mode <int>::
Choose the psycho-acoustic model to use (-1 to 4).
Model number -1 is turns off psycho-acoustic modelling and
uses fixed default values instead.
Please see the file 'psycho' for a full description of
each of the models available.
Default model is 3.
-v, --vbr::
Enable VBR mode. See 'vbr' documentation file for details.
Default VBR level is 5.0.
-v, --vbr-level <float>::
Enable VBR mode and set quality level.
The higher the number the better the quality.
Maximum range is -50 to 50 but useful range is -10 to 10.
See 'vbr' documentation file for details.
-l, --ath <float>::
Set the ATH level. Default level is 0.0.
-q, --quick <int>::
Enable quick mode. Only re-calculate psycho-acoustic
model every specified number of frames.
-S, --single-frame::
Enables single frame mode: only a single frame of MPEG audio
is output and then the program terminates.
Miscellaneous Options
~~~~~~~~~~~~~~~~~~~~~
-c, --copyright::
Turn on Copyright flag in output bitstream.
-o, --non-original::
Turn off Original flag in output bitstream.
--original::
Turn on Original flag in output bitstream.
-p, --protect::
Enable CRC error protection in output bitstream.
An extra 16-bit checksum is added to frames.
-d, --padding::
Turn on padding in output bitstream.
-R, --reserve <int>::
Reserve specified number of bits in the each from of the
output bitstream.
-e, --deemphasis <char>::
Set the de-emphasis type (n/c/5). Default is none.
-E, --energy::
Turn on energy level extensions.
Verbosity Options
~~~~~~~~~~~~~~~~~
-t, --talkativity <int>::
Set the amount of information to be displayed on stderr (0 to 10).
Default is 2.
--quiet::
Don't send any messages to stderr, unless there is an error.
(Same as --talkativity=0)
--brief::
Only display a minimal number of messages while encoding.
This setting is quieter than the default talkativity setting.
(Same as --talkativity=1)
--verbose::
Display an increased number of messages on stderr.
This setting is useful to diagnose problems.
(Same as --talkativity=4)
Return Codes
------------
If encoding completes successfully, then twolame will return 0.
However if encoding is not successful, then it will return one of the following
codes.
- 1 (No encoding performed)
- 2 (Error opening input file)
- 4 (Error opening output file)
- 6 (Error allocating memory)
- 8 (Error in chosen encoding parameters)
- 10 (Error reading input audio)
- 12 (Error occured while encoding)
- 14 (Error writing output audio)
EXAMPLES
--------
This will encode sound.wav to sound.mp2 using the default constant bitrate of
192 kbps
and using the default psycho-acoustic model (model 3):
twolame sound.wav
Constant bitrate of 160kbps and joint stereo encoding, saved to file
sound_160.mp2:
twolame -b 160 -m j sound.aiff sound_160.mp2
Encode sound.wav to newfile.mp2 using psycho-acoustic model 2 and encoding
with variable bitrate:
twolame -P 2 -v sound.wav newfile.mp2
Same as example above, except that the negative value of the "-V" argument
means that the lower bitrates will be favoured over the higher ones:
twolame -P 2 -V -5 sound.wav newfile.mp2
Resample audio file using sox and pipe straight through twolame:
sox sound_11025.aiff -t raw -r 16000 | twolame -r -s 16000 - - >
out.mp2
AUTHORS
-------
The twolame frontend was (re)written by Nicholas J Humfrey.
The libtwolame library is based on toolame by Mike Cheng.
For a full list of authors, please see the AUTHORS file.
RESOURCES
---------
TwoLAME web site: http://www.twolame.org/
SEE ALSO
--------
lame(1), mpg123(1), madplay(1), sox(1)
COPYING
-------
Copyright (C) 2004-2005 The TwoLAME Project. Free use of this software is
granted under the terms of the GNU Lesser General Public License (LGPL).
--- NEW FILE: psycho.txt ---
Psychoacoustic Models in TwoLAME
================================
Introduction
------------
In MPEG audio encoding, a psychoacoustic model (PAM) is used to determine which
are the sonically important parts of the waveform that is being encoded. The
PAM
looks for loud sounds which may mask soft sounds, noise which may affect the
level
of sounds nearby, sounds which are too soft for us to hear and should be
ignored
and so on. The information from the PAM is used to determine which parts of
the
spectrum should get more bits and thus be encoded at greater quality - and
which
parts are inaudible/unimportant and should thus get fewer bits.
In MPEG Audio LayerII encoding, 1152 sound samples are read in - this
constitutes
a 'frame'. For each frame the PAM outputs just *32* values
(The values are the Signal to Masking Ratio [SMR] in that subband). This is
important!
There are only 32 values to determine how to alloctate bits for 1152 samples -
this
is a pretty coarse technique.
The different PAMs listed below use different techniques to decide on these 32
values. Some models are better than others - meaning that the 32 values chosen
are pretty good at spreading the bits where they should go. Even with a really
bad PAM (e.g. Model -1) you can still get satisfactory results a lot of the
time.
All of these models have strengths and weaknesses. The model 'you' end up
using
will be the one that produces the best sound for your ears, for your audio.
Psychoacoustic Model -1
-----------------------
This PAM doesn't actually look at the samples being encoded to decide upon the
output values. There is simply a set of 32 default values which are used,
regardless of input.
*Pros*: Faaaast. Low complexity. Surprisingly good.
"Surprising" in that the other PAMs go to the effort of calculating FFTs
and subbands and masking, and this one does absolutely *nothing*.
Zip. Nada. Diddly Squat. This model might be the best example of why
it is hard to make a good model - if having no computations sounds OK,
how do you improve on it?
*Cons*: Absolutely no attempt to consider any of the masking effects that
would help the audio sound better.
Psychoacoustic Model 0
----------------------
This PAM looks at the sizes of the 'scalefactors' for the audio and combines
it with the Absolute Threshold of Hearing (ATH) to make the 32 SMR values.
*Pros*: Faaast. Low complexity.
*Cons*: This model has absolutely no mathematical basis and does not use
any perceptual model of hearing. It simply juggles some of the numbers of
the input sound to determine the values. Feel free to hack the daylights out
of this PAM - add multipliers, constants, log-tables *anything*. Tweak it until
you begin to like the sound.
Psychoacoustic Model 1 and 2
----------------------------
These PAMs are from the ISO standard. Just because they are the standard,
doesn't mean that they are any good. Look at LAME which basically threw out
the MP3 standard psycho models and made their own (GPSYCHO).
*Pros*: A reference for future PAMs
*Cons*: Terrible ISO code, buggy tables, poor documentation.
Psychoacoustic Model 3
----------------------
A re-implementation of psychoacoustic model 1. ISO11172 was used as the guide
for re-writing this PAM from the ground up.
*Pros*: No more obscure tables of values from the ISO code. Hopefully a good
base to work upon for tweaking PAMs
*Cons*: At the moment, doesn't really sound any better than PAM1
Psychoacoustic Model 4
----------------------
A cleaned up version of PAM2.
*Pros*: Faster than PAM2. No more obscure tables of values from the ISO
standard. Hopefully a good base to work from for improving the PAMs
*Cons*: Still has the same "warbling"/"Davros" problems as PAM2.
Future psychoacoustic models
----------------------------
There's a heap that could be done. Unfortunately, I've got a set of tin
ears, crappy speakers and a noisy computer room. If you've got the
capability to do proper PAM testing then please feel free to do so.
Otherwise, I'll just keep plodding along with new ideas as they
arise, such as:
- Temporal masking (there's no pre-echo or anything in TwoLAME)
- Left Right Masking
- A PAM that's fully tuneable from the command line?
- Graphical output of SMR values etc. Would allow better debugging of PAMs
- Re-sampling routines
- Low/High pass filtering
--- NEW FILE: vbr.txt ---
TwoLAME: MPEG Audio Layer II VBR
================================
Contents
--------
- Introduction
- Usage
- Bitrate Ranges for various Sampling frequencies
- Why can't the bitrate vary from 32kbps to 384kbps for every file?
- Short Answer
- Long Answer
- Tech Stuff
Introduction
------------
VBR mode works by selecting a different bitrate for each frame. Frames
which are harder to encode will be allocated more bits i.e. a higher bitrate.
LayerII VBR is a complete hack - the ISO standard actually says that decoders
are not
required to support it. As a hack, its implementation is a pain to try and
understand.
If you're mega-keen to get full range VBR working, either (a) send me money (b)
grab the
ISO standard and a C compiler and email me.
Usage
-----
twolame -v [level] inputfile outputfile.
A level of 5 works very well for me.
The level value can is a measurement of quality - the higher
the level the higher the average bitrate of the resultant file.
[See TECH STUFF for a better explanation of what the value does]
The confusing part of my implementation of LayerII VBR is that it's different
from MP3 VBR.
- The range of bitrates used is controlled by the input sampling frequency.
(See below "Bitrate ranges")
- The tendency to use higher bitrates is governed by the <level>.
E.g. Say you have a 44.1kHz Stereo file. In VBR mode, the bitrate can range
from 192 to 384 kbps.
Using "-v -5" will force the encoder to favour the lower bitrate.
Using "-v 5" will force the encoder to favour the upper bitrate.
The value can actually be *any* int. -27, 233, 47. The larger the number, the
greater
the bitrate bias.
Bitrate Ranges
--------------
When making a VBR stream, the bitrate is only allowed to vary within
set limits
48kHz
Stereo: 112-384kbps Mono: 56-192kbps
44.1kHz & 32kHz
Stereo: 192-384kbps Mono: 96-192kbps
24kHz, 22.05kHz & 16kHz
Stereo/Mono: 8-160kbps
Why doesn't the VBR mode work the same as MP3VBR? The Short Answer
------------------------------------------------------------------
*Why can't the bitrate vary from 32kbps to 384kbps for every file?*
According to the standard (ISO/IEC 11172-3:1993) Section 2.4.2.3
"In order to provide the smallest possible delay and complexity, the
decoder is not required to support a continuously variable bitrate when
in layer I or II. Layer III supports variable bitrate by switching the
bitrate index."
and
"For Layer II, not all combinations of total bitrate and mode are
allowed."
Hence, most LayerII coders would not have been written with VBR in mind, and
LayerII VBR is a hack. It works for limited cases. Getting it to work to
the same extent as MP3-style VBR will be a major hack.
(If you *really* want better bitrate ranges, read "The Long Answer" and submit
your mega-patch.)
Why doesn't the VBR mode work the same as MP3VBR? The Long Answer
-----------------------------------------------------------------
*Why can't the bitrate vary from 32kbps to 384kbps for every file?*
Reason 1: The standard limits the range
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As quoted above from the standard for 48/44.1/32kHz:
"For Layer II, not all combinations of total bitrate and mode are
allowed. See
the following table."
Bitrate Allowed Modes
(kbps)
32 mono only
48 mono only
56 mono only
64 all modes
80 mono only
96 all modes
112 all modes
128 all modes
160 all modes
192 all modes
224 stereo only
256 stereo only
320 stereo only
384 stereo only
So based upon this table alone, you *could* have VBR stereo encoding which
varies
smoothly from 96 to 384kbps. Or you could have have VBR mono encoding which
varies from
32 to 192kbps. But since the top and bottom bitrates don't apply to all modes,
it would
be impossible to have a stereo file encoded from 32 to 384 kbps.
But this isn't what is really limiting the allowable bitrate range - the bit
allocation
tables are the major hurdle.
Reason 2: The bit allocation tables don't allow it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>From the standard, Section 2.4.3.3.1 "Bit allocation decoding"
"For different combinations of bitrate and sampling frequency,
different bit
allocation tables exist.
These bit allocation tables are pre-determined tables (in Annex B of the
standard) which
indicate
- how many bits to read for the initial data (2,3 or 4)
- these bits are then used as an index back into the table to
find the number of quantize levels for the samples in this subband
But the table used (and hence the number of bits and the calculated index) are
different
for different combinations of bitrate and sampling frequency.
I will use TableB.2a as an example.
Table B.2a Applies for the following combinations.
Sampling Freq Bitrates in (kbps/channel) [emphasis: this is a
PER CHANNEL bitrate]
48 56, 64, 80, 96, 112, 128, 160, 192
44.1 56, 64, 80
32 56, 64, 80
If we have a STEREO 48kHz input file, and we use this table, then the bitrates
we could calculate from this would be 112, 128, 160, 192, 224, 256, 320 and 384
kbps.
This table contains no information on how to encode stuff at bitrates less than
112kbps
(for a stereo file). You would have to load allocation table B.2c to encode
stereo at
64kbps and 128kbps.
Since it would be a MAJOR piece of hacking to get the different tables shifted
in and out
during the encoding process, once an allocation table is loaded *IT IS NOT
CHANGED*.
Hence, the best table is picked at the start of the encoding process, and the
encoder
is stuck with it for the rest of the encode.
For twolame-02j, I have picked the table it loads for different
sampling frequencies in order to optimize the range of bitrates possible.
48 kHz - Table B.2a
Stereo Bitrate Range: 112 - 384
Mono Bitrate Range : 56 - 192
44.1/32 kHz - Table B.2b
Stereo Bitrate Range: 192 - 384
Mono Bitrate Range: 96 - 192
24/22.05/16 kHz - LSF Table (Standard ISO/IEC 13818.3:1995 Annex B,
Table B.1)
There is only 1 table for the Lower Sampling Frequencies
All modes (mono and stereo) are allowable at all bitrates
So at the Lower Sampling Frequencies you *can* have a
completely variable
bitrate over the entire range.
Tech Stuff
----------
The VBR mode is mainly centered around the main_bit_allocation() and
a_bit_allocation() routines in encode.c.
The limited range of VBR is due to my particular implementation which restricts
ranges to within one alloc table (see tables B.2a, B.2b, B.2c and B.2d in ISO
11172).
The VBR range for 32/44.1khz lies within B.2b, and the 48khz VBR lies within
table B.2a.
I'm not sure whether it is worth extending these ranges down to lower bitrates.
The work required to switch alloc tables *during* the encoding is major.
In the case of silence, it might be worth doing a quick check for very low
signals
and writing a pre-calculated *blank* 32kpbs frame. [probably also a lot of
work].
How CBR works
-------------
- Use the psycho model to determine the MNRs for each subband
[MNR = the ratio of "masking" to "noise"]
(From an encoding perspective, a bigger MNR in a subband means that
it sounds better since the noise is more masked))
- calculate the available data bits (adb) for this bitrate.
- Based upon the MNR (Masking:Noise Ratio) values, allocate bits to each
subband
- Keep increasing the bits to whichever subband currently has the min MNR
value until we have no bits left.
- This mode does not guarentee that all the subbands are without noise
ie there may still be subbands with MNR less than 0.0 (noisy!)
How VBR works
-------------
- pretend we have lots of bits to spare, and work out the bits which would
raise the MNR in each subband to the level given by the argument on
the
command line "-v [int]"
- Pick the bitrate which has more bits than the required_bits we just
calculated
- calculate a_bit_allocation()
- VBR "guarantees" that all subbands have MNR > VBRLEVEL or that we have
reached the maximum bitrate.
FUTURE
------
- with this VBR mode, we know the bits aren't going to run out, so we can
just assign them "greedily".
- VBR_a_bit_allocation() is yet to be written :)
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Audacity-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/audacity-cvs
