TarsosTranscoder

TarsosTranscoder is a Java library that enables you to quickly play and process audio encoded as MP3, Flac, Vorbis or about any other audio format from a Java environment. It also provides support for http and other streams. Under the hood it uses platform dependent libraries which are provided automatically for Windows, Mac OS X and Linux.

Downloads can be found on the release repository. Some information can also be found here.

Getting Started

If you want to use the an mp3 from within Java you need to call Transcoder. The following code converts foo.mp3 to a stereo wave file with 16 bits per sample (little endian) and 44.1kHz sampling rate. The resulting wav file is stored in foo.wav. A number of default formats are provided all transcoding operations supported by the ffmpeg binary (see below) are supported. This means you can trancode e.g. an Ogg Vorbis stereo file to flac mono. Transcoding is only supported on files and not on streams.

Transcoder.transcode("foo.mp3","foo.wav",DefaultAttributes.WAV_PCM_S16LE_STEREO_44KHZ);

To stream, decode, resample and downmix audio from about any source (streams and files) can be done with the following code. The code decodes a stereo MP3 http stream on the fly to a single channel PCM wav. The AudioInputStream in the requested AudioFormat can be used for any purpose, but here the result is played to the speakers.

//The source http stream
String source = "http://mp3.streampower.be/stubru-high.mp3";

//Set the transcoding to WAV PCM, 16bits LE, 16789Hz (or any other sample rate). 
Attributes attributes = DefaultAttributes.WAV_PCM_S16LE_MONO_44KHZ.getAttributes();
attributes.setSamplingRate(16789);
		
//Stream the same file with on the fly decoding:		
AudioInputStream streamedAudioInputStream = Streamer.stream(source, attributes);
AudioFormat audioFormat = Streamer.streamAudioFormat(attributes);
		
byte[] streamBuffer = new byte[1024];
		
DataLine.Info info = new DataLine.Info(SourceDataLine.class, audioFormat);
SourceDataLine line = (SourceDataLine) AudioSystem.getLine(info);
line.open(audioFormat);
line.start();
				
while (streamedAudioInputStream.available() > streamBuffer.length){
	int bytesRead = streamedAudioInputStream.read(streamBuffer);
	int bytesWrote = line.write(streamBuffer, 0, streamBuffer.length);
	assert bytesRead == bytesWrote;
}
line.close();
streamedAudioInputStream.close();

To build TarsosTrancoder yourself, you need to have Apache Ant and git installed on your system. The following commands build and test library:

git clone https://JorenSix@github.com/JorenSix/TarsosTranscoder.git
cd TarsosTranscoder/build
#Compile and build the core TarsosTranscoder library
ant 
#Create the javadoc documentation in TarsosTranscoder/doc
ant javadoc 
#Run some unit tests
ant test
#Test wav to flac transcoding command line interface
java -jar TarsosTranscoder-1.2.jar ../audio/input/tone/tone_10s.wav test.flac FLAC_MONO_44KHZ
#Play the transcoded flac file (a sine wave) 
java -jar TarsosTranscoder-1.2.jar play test.flac 

Inner workings

Tarsos Transcoder tries to find an FFmpeg binary in the path of the system. If it does not find one it tries to copy a binary for the current platform. Tarsos Transcoder contains three binaries: one for MAC OS X, one for Linux (x86) and one for windows. Tarsos Transcoder has been tested on:

It will probably work most of the time.

It is a heavily modified fork of JAVE (Java Audio and Video Encoder) by Carlo Pelliccia (www.sauronsoftware.it). The main differences are that Tarsos Transcoder focuses only on audio and it is compatible with more, and more recent FFmpeg binaries and it less dependent on text output of the different binaries. The interface is also simplified. It falls back to use the ffmpeg binary in the system path, if one is present, therefore it supports platforms for which no binary is provided within the release.

Alternative Binaries

If the TarsosTranscoder does not include binaries for you platform, install ffmpeg and add the ffmpeg executable to your systems path. It will be found and used by TarsosTranscoder automatically.

Alternatively, providing binaries for your (unsupported) platform can be done by implementing FFMPEGLocator. The PickMe() method should yield true on your platform and copy e.g. an FFmpeg binary to a temporary directory.

Why TarsosTranscoder?

Although the Java audio system has a nice plug-in system (service provider interface) to add support for various audio formats, the state of pure Java audio decoders that are available could be improved. There are pure Java implementations to decode Flac, Ogg Vorbis and MP3. Together with the Tritonus libraries these can decode audio in the respective formats.

Unfortunately the Java libraries are not (well) maintained. The Tritonus libraries for example have not seen an update in the last decade. The implementation of the decoders are also incomplete. The MP3 library has problems with files longer than half an hour and is not able to handle corrupted MP3’s. Jorbis does not support 48kHz files with 32bit floating point samples (Q5). Jflac has troubles with multi-channel (3 or more) files, although the flac specification supports up to 8 channels. Support for http-streaming and decoding also varies for each library. Downmixing and resampling in PCM audio can be done with the Tritonus libraries but is again of limited use, since it can only be used for Jorbis and the MP3 decoder.

Ideally a system should be able to decode audio in about any format, from any source (also video container formats like avi) to PCM. A system should also be able to resample and downmix on the fly to any sampling rate. Preferably the system should be robust to with corrupted audio samples. When leaving the Java-ecosystem the actively developed ffmpeg project seems to offer these capabilities. TarsosTranscoder in turn offers an easy way to call and use this library from within Java without having to worry about installing ffmpeg.

An alternative to TarsosTranscoder is JLibav. The main difference is that the user needs to install libav, an ffmpeg fork, before using Jlibav. With TarsosTranscoder binaries are provided automatically for the main platforms.

License

This software is licensed under GPL, TarsosTranscoder is based on JAVE (GPL).

Credits

JAVE (Java Audio and Video Encoder) by Carlo Pelliccia – www.sauronsoftware.it

FFmpeg: this uses libraries from the FFmpeg project under the LGPLv2.1

This product includes software developed by The Apache Software Foundation. It uses the Apache Commons Exec library, licensed under the Apache License Version 2.0

TarsosTranscoder is used by Tarsos, Tarsos is developed at University College Ghent and the Faculty of Music and University Ghent, IPEM