tooLAME - an optimized mpeg 1/2 layer 2 audio encoder with ODR-DabMux compatible ZeroMQ output and JACK input

Copyright (C) 2002, 2003 Michael Cheng [mikecheng at NOT planckenergy.com] remove the NOT http://www.planckenergy.com/

Copyright (C) 2014, 2015 Matthias P. Braendli [matthias.braendli@mpb.li] http://opendigitalradio.org/

All changes to the ISO source are licensed under the LGPL (see LGPL.txt for details)

tooLAME is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

tooLAME is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with tooLAME; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

INTRODUCTION

tooLAME is an optimized Mpeg Audio 1/2 Layer 2 encoder. It is based heavily on - the ISO dist10 code - improvement to algorithms as part of the LAME project (www.sulaco.org/mp3) - work by Mike Cheng and other contributors (see CONTRIBUTORS)

It can encode to a file, and also to a zeromq socket that can connect to ODR-DabMux See http://opendigitalradio.org

INSTALLATION

0. install zeromq 4.0.3 or newer, install cmake. optional: install JACK and/or libvlc
1. mkdir build
2. cd build
3. cmake ..
4. 'make'

USAGE

     ./toolame [options] <input> <output>

Input tooLAME parses AIFF and WAV files for file info raw PCM is assumed if no header is found for stdin use a - for JACK input, use -j option, and specify the name of the JACK port with for the libvlc based input, use -V, and specify the URL with

Output file is automatically renamed from . to *.mp2 for stdout use a - for zeromq use tcp://: pointing to a ODR-DabMux. You can put more than one endpoint, separated by a semicolon. Mind that the shell might interpret the semicolon: use quotes around the list of endpoints to avoid this.

Input Options -s [int] if inputting raw PCM sound, you must specify the sample rate default sample rate is 44.1khz.

-a
    downmix from stereo to mono
    if the incoming file is stereo, combine the audio into
    a single channel

-x
    force byte-swapping of the input.  (current endian detection is dodgy,
    so if toolame produces only noise, use -x )

-g
    swap the LR channels of a stereo file

Output Options -m [char] the encoding mode (default 'j') 's' stereo 'd' dual channel 'j' joint stereo 'm' mono

-p [int]
    which psy model to use (default '1')
    Different models for the psychoacoustics
    Models: -1 to 4

-b [int]
    the total bitrate
    For 48/44.1/32kHz default = 192
    For 24/22.05/16kHz default = 96

-v [int]
    Switch on VBR mode.
    The higher the number the better the quality.
    Useful range -10 to 10.
    See README.VBR for details.
    Don't use that for DAB encoding.

Operation -f fast mode turns off calculation of the psychoacoustic model. Instead a set of default values are assumed

-q [int]
    quick mode calculates the psy model every 'num' frames.

Misc -d emp de-emphasis (default 'n') -c mark as copyright -o mark as original -e add error protection -r force padding bits off -D add DAB extensions -t [int] 'talkativity' setting. 0 = no message. 3 = too much information

EXAMPLES

1. toolame sound.wav

   This will encode sound.wav to sound.mp2 using the default bitrate of 192 kbps and using the default psychoacoustic model (model 1)

2. toolame -p 2 -v 5 sound.wav newfile.mp2

   Encode sound.wav to newfile.mp2 using psychoacoustic model 2 and encoding with variable bitrate. The high value of the "-v" argument means that the encoding will tend to favour higher bitrates.

3. toolame -p 2 -v -5 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.

4. cat sound.pcm | toolame -s 22050 -f -b 96 - newfile.mp2

   Toolame is encoding from stdin at a bitrate of 96kbps and is using the 'fast' mode which means that no psychoacoustic modelling is done.The input file is raw pcm so the sample rate needs to be specified (22050Hz)

5. toolame -V -s 48 -L -b 128 http://your_stream_url tcp://localhost:9002

   Use libvlc to read and decode the stream at the given url, and encode it at 48000Hz sample rate to the ZeroMQ input of ODR-DabMux running on localhost:9002

CONTRIBUTORS

Dist10 code writers LAME specific contributions fht routines from Ron Mayer fht tweaking by Mathew Hendry window_subband & filter_subband from LAME circa v3.30 (multiple LAME authors) (before Takehiro's window/filter/mdct combination)

Oliver Lietz Tables now included in the exe! (yay! :)

Patrick de Smet scale_factor calc speedup. subband_quantization speedup

Federico Grau Bill Eldridge option for "no padding"

Nick Burch WAV file reading os/2 Makefile mods.

Phillipe Jouguet <philippe.jouguet at vdldiffusion.com> DAB extensions spelling, LSF using psyII, WAVE reading

Henrik Herranen - leopold at vlsi.fi (WAVE reading)

Andreas Neukoetter - anti at webhome.de (verbosity patch '-t' switch for transcode plugin)

Sami Sallinen - sami.sallinen at g-cluster.com (filter_subband loop unroll psycho_i fix for "% 1408" calcs)

Mike Cheng (remove the NOT) Most of the rest

Matthias P. Braendli matthias@mpb.li ZeroMQ output for ODR-DabMux PAD insertion for DLS and slides JACK and libVLC input

REFERENCE PAPERS

(Specifically LayerII Papers)

Kumar, M & Zubair, M., A high performance software implementation of mpeg audio encoder, 1996, ICASSP Conf Proceedings (I think)

Fischer, K.A., Calculation of the psychoacoustic simultaneous masked threshold based on MPEG/Audio Encoder Model One, ICSI Technical Report, 1997 ftp://ftp.icsi.berkeley.edu/pub/real/kyrill/PsychoMpegOne.tar.Z

Hyen-O et al, New Implementation techniques of a real-time mpeg-2 audio encoding system. p2287, ICASSP 99.

Imai, T., et al, MPEG-1 Audio real-time encoding system, IEEE Trans on Consumer Electronics, v44, n3 1998. p888

Teh, D., et al, Efficient bit allocation algorithm for ISO/MPEG audio encoder, Electronics Letters, v34, n8, p721

Murphy, C & Anandakumar, K, Real-time MPEG-1 audio coding and decoding on a DSP Chip, IEEE Trans on Consumer Electronics, v43, n1, 1997 p40

Hans, M & Bhaskaran, V., A compliant MPEG-1 layer II audio decoder with 16-B arithmetic operations, IEEE Signal Proc Letters v4 n5 1997 p121

[mikecheng at NOT planckenergy.com] remove the NOT and [matthias.braendli@mpb.li]