JAVE manual

• Installation and requirements
• Audio/video encoding
• Encoding attributes
• Audio encoding attributes
• Video encoding attributes
• Monitoring the transcoding operation
• Transcoding failures
• Getting informations about a multimedia file
• Using an alternative ffmpeg executable
• Supported container formats
• Built-in decoders and encoders
• Examples

Installation and requirements

In order to use JAVE in your Java application, you have to add the file jave-1.0.jar in your application CLASSPATH.

JAVE runs on a Java Runtime Environment J2SE v.1.4 or later.

JAVE includes and uses a ffmpeg executable built for Windows and Linux operating systems on i386/32 bit hardware platforms. In order to run JAVE on other platforms you have to replace the built-in ffmpeg executable with another one suitable for your needs. This is very simple, once you have built your own ffmpeg binaries. The operation is described in the "Using an alternative ffmpeg executable" section.

Audio/video encoding

The most important JAVE class is it.sauronsoftware.jave.Encoder. Encoder objects expose many methods for multimedia transcoding. In order to use JAVE, you always have to create an Encoder istance:

Encoder encoder = new Encoder();

Once the instance has been created, you can start transcoding calling the encode() method:

public void encode(java.io.File source,
                   java.io.File target,
                   it.sauronsoftware.jave.EncodingAttributes attributes)
            throws java.lang.IllegalArgumentException,
                   it.sauronsoftware.jave.InputFormatException,
                   it.sauronsoftware.jave.EncoderException

The first parameter, source, represents the source file to decode.

The second parameter, target, is the target file that will be created and encoded.

The attributes parameter, whose type is it.sauronsoftware.jave.EncodingAttributes, is a data structure containing any information needed by the encoder.

Please note that a call to encode() is a blocking one: the method will return only once the transcoding operation has been completed (or failed). If you are interested in monitoring the transcoding operation take a look to the "Monitoring the transcoding operation" section.

Encoding attributes

To specify your preferences about the transcoding operation you have to supply an it.sauronsoftware.jave.EncodingAttributes instance to the encode() call. You can create your own EncodingAttributes instance, and you can populate it with the following methods:

• public void setAudioAttributes(it.sauronsoftware.jave.AudioAttributes audioAttributes)
  It sets the audio encoding attributes. If never called on a new EncodingAttributes instance, or if the given parameter is null, no audio stream will be included in the encoded file. See also "Audio encoding attributes".
• public void setVideoAttributes(it.sauronsoftware.jave.AudioAttributes videoAttributes)
  It sets the video encoding attributes. If never called on a new EncodingAttributes instance, or if the given parameter is null, no video stream will be included in the encoded file. See also "Video encoding attributes".
• public void setFormat(java.lang.String format)
  It sets the format of the streams container that will be used for the new encoded file. The given parameter represents the format name. An encoding format name is valid and supported only if it appears in the list returned by the getSupportedEncodingFormats() method of the Encoder instance in use.
• public void setOffset(java.lang.Float offset)
  It sets an offset for the transcoding operation. The source file will be re-encoded starting at offset seconds since its beginning. In example if you'd like to cut the first five seconds of the source file, you should call setOffset(5) on the EncodingAttributes object passed to the encoder.
• public void setDuration(java.lang.Float duration)
  It sets a duration for the transcoding operation. Only duration seconds of the source will be re-encoded in the target file. In example if you'd like to extract and transcode a portion of thirty seconds from the source, you should call setDuration(30) on the EncodingAttributes object passed to the encoder.

Audio encoding attributes

Audio encoding attributes are represented by the instances of the it.sauronsoftware.jave.AudioAttributes class. The available methods on this kind of objects are:

• public void setCodec(java.lang.String codec)
  It sets the name of the codec that will be used for the transcoding of the audio stream. You have to choose a value from the list returned by the getAudioEncoders() method of the current Encoder instance. Otherwise you can pass the AudioAttributes.DIRECT_STREAM_COPY special value, that requires the copy of the original audio stream from the source file.
• public void setBitRate(java.lang.Integer bitRate)
  It sets the bitrate value for the new re-encoded audio stream. If no bitrate value is set, a default one will be picked by the encoder. The value should be expressed in bits per second. In example if you want a 128 kb/s bitrate you should call setBitRate(new Integer(128000)).
• public void setSamplingRate(java.lang.Integer bitRate)
  It sets the sampling rate for the new re-encoded audio stream. If no sampling-rate value is set, a default one will be picked by the encoder. The value should be expressed in hertz. In example if you want a CD-like 44100 Hz sampling-rate, you should call setSamplingRate(new Integer(44100)).
• public void setChannels(java.lang.Integer channels)
  It sets the number of the audio channels that will be used in the re-encoded audio stream (1 = mono, 2 = stereo). If no channels value is set, a default one will be picked by the encoder.
• public void setVolume(java.lang.Integer volume)
  This method can be called to alter the volume of the audio stream. A value of 256 means no volume change. So a value less than 256 is a volume decrease, while a value greater than 256 will increase the volume of the audio stream.

Video encoding attributes

Video encoding attributes are represented by the instances of the it.sauronsoftware.jave.VideoAttributes class. The available methods on this kind of objects are:

• public void setCodec(java.lang.String codec)
  It sets the name of the codec that will be used for the transcoding of the video stream. You have to choose a value from the list returned by the getVideoEncoders() method of the current Encoder instance. Otherwise you can pass the VideoAttributes.DIRECT_STREAM_COPY special value, that requires the copy of the original video stream from the source file.
• public void setTag(java.lang.String tag)
  It sets the tag/fourcc value associated to the re-encoded video stream. If no value is set a default one will be picked by the encoder. The tag value is often used by multimedia players to choose which video decoder run on the stream. In example a MPEG 4 video stream with a "DIVX" tag value will be decoded with the default DivX decoder used by the player. And, by the way, this is exactly what a DivX is: a MPEG 4 video stream with an attached "DIVX" tag/fourcc value!
• public void setBitRate(java.lang.Integer bitRate)
  It sets the bitrate value for the new re-encoded video stream. If no bitrate value is set, a default one will be picked by the encoder. The value should be expressed in bits per second. In example if you want a 360 kb/s bitrate you should call setBitRate(new Integer(360000)).
• public void setFrameRate(java.lang.Integer bitRate)
  It sets the frame rate value for the new re-encoded audio stream. If no bitrate frame-rate is set, a default one will be picked by the encoder. The value should be expressed in frames per second. In example if you want a 30 f/s frame-rate you should call setFrameRate(new Integer(30)).
• public void setSize(it.sauronsoftware.jave.VideoSize size)
  It sets the size and the proportion of the images in the video stream. If no value is set, the encoder will preserve the original size and proportion. Otherwise you can pass a it.sauronsoftware.java.VideoSize instance, with your preferred size. You can set the width and the height of the new encoded video, with pixel values, scaling the original one. In example if you want to scale the video to 512 px in width and 384px in height you should call setSize(new VideoSize(512, 384)).

Monitoring the transcoding operation

You can monitor a transcoding operation with a listener. JAVE defines the it.sauronsoftware.jave.EncoderProgressListener interface. This interface could be implemented by your application, and concrete EncoderProgressListener instances can be passed to the encoder. The encoder will call your listener methods every time a significant event occurs. To pass an EncoderProgressListener to the encoder you should use this definition of the encode() method:

public void encode(java.io.File source,
                   java.io.File target,
                   it.sauronsoftware.jave.EncodingAttributes attributes,
                   it.sauronsoftware.jave.EncoderProgressListener listener)
            throws java.lang.IllegalArgumentException,
                   it.sauronsoftware.jave.InputFormatException,
                   it.sauronsoftware.jave.EncoderException

To implemen the EncoderProgressListener interface you have to define all of the following methods:

• public void sourceInfo(it.sauronsoftware.jave.MultimediaInfo info)
  The encoder calls this method after the source file has been analized. The info parameter is an instance of the it.sauronsoftware.jave.MultimediaInfo class and it represents informations about the source audio and video streams and their container.
• public void progress(int permil)
  This method is called by the encoder every time a progress in the encoding operation has been done. The permil parameter is a value representing the point reached by the current operation and its range is from 0 (operation just started) to 1000 (operation completed).
• public void message(java.lang.String message)
  This method is called by the encoder to notify a message regarding the transcoding operation (usually the message is a warning).

Transcoding failures

Of course, a transcoding operation could fail. Then the encode() method will propagate an exception. Depending on what is happened, the exception will be one of the following:

• java.lang.IllegalArgumentException
  The transcoding operation has never started since the encoding attributes passed to the encoder has been recognized as invalid. Usualy this occurs when the EncodingAttributes instance given to the encoder asks the encoding of a container with no audio and no video streams (both AudioAttributes and VideoAttribues attributes are null or not set).
• it.sauronsoftware.jave.InputFormatException
  The source file can't be decoded. It occurs when the source file container, the video stream format or the audio stream format are not supported by the decoder. You can check for supported containers and plugged decoders calling the encoder methods getSupportedDecodingFormats(), getAudioDecoders() and getVideoDecoders().
• it.sauronsoftware.jave.EncoderExpection
  The operation has failed during the trancoding due to an internal error. You should check the exception message, and you can also use an EncoderProgressListener instance to check any message issued by the encoder.

Getting informations about a multimedia file

You can get informations about an existing multimedia file before transcoding it, calling the encoder getInfo() method. The getInfo() method gives you informations about the container used by the file and about its wrapped audio and video streams:

public it.sauronsoftware.jave.MultimediaInfo getInfo(java.io.File source)
                                             throws it.sauronsoftware.jave.InputFormatException,
                                                    it.sauronsoftware.jave.EncoderException

An it.sauronsoftware.jave.MultimediaInfo object encapsulates information on the whole multimedia content and its streams, using instances of it.sauronsoftware.jave.AudioInfo and it.sauronsoftware.jave.VideoInfo to describe the wrapped audio and video. These objects are similar to the EncodingAttributes, AudioAttributes and VideoAttributes ones, but they works in a read-only mode. Check the JAVE API javadoc documentation, bundled with the JAVE distribution, to gain more details about them.

Using an alternative ffmpeg executable

JAVE is not pure Java: it acts as a wrapper around an ffmpeg (http://ffmpeg.mplayerhq.hu/) executable. ffmpeg is an open source and free software project entirely written in C, so its executables cannot be easily ported from a machine to another. You need a pre-compiled version of ffmpeg in order to run JAVE on your target machine. The JAVE distribution includes two pre-compiled executables of ffmpeg: a Windows one and a Linux one, both compiled for i386/32 bit hardware achitectures. This should be enough in most cases. If it is not enough for your specific situation, you can still run JAVE, but you need to obtain a platform specific ffmpeg executable. Check the Internet for it. You can even build it by yourself getting the code (and the documentation to build it) on the official ffmpeg site. Once you have obtained a ffmpeg executable suitable for your needs, you have to hook it in the JAVE library. That's a plain operation. JAVE gives you an abstract class called it.sauronsoftware.jave.FFMPEGLocator. Extend it. All you have to do is to define the following method:

public java.lang.String getFFMPEGExecutablePath()

This method should return a file system based path to your custom ffmpeg executable.

Once your class is ready, suppose you have called it MyFFMPEGExecutableLocator, you have to create an alternate encoder that uses it instead of the default locator:

Encoder encoder = new Encoder(new MyFFMPEGExecutableLocator())

You can use the same procedure also to switch to other versions of ffmpeg, even if you are on a platform covered by the executables bundled in the JAVE distribution.

Anyway be careful and test ever your application: JAVE it's not guaranteed to work properly with custom ffmpeg executables different from the bundled ones.

Supported container formats

The JAVE built-in ffmpeg executable gives support for the following multimedia container formats:

Decoding

Formato Descrizione

4xm	4X Technologies format
MTV	MTV format
RoQ	Id RoQ format
aac	ADTS AAC
ac3	raw ac3
aiff	Audio IFF
alaw	pcm A law format
amr	3gpp amr file format
apc	CRYO APC format
ape	Monkey's Audio
asf	asf format
au	SUN AU Format
avi	avi format
avs	AVISynth
bethsoftvid	Bethesda Softworks 'Daggerfall' VID format
c93	Interplay C93
daud	D-Cinema audio format
dsicin	Delphine Software International CIN format
dts	raw dts
dv	DV video format
dxa	dxa
ea	Electronic Arts Multimedia Format
ea_cdata	Electronic Arts cdata
ffm	ffm format
film_cpk	Sega FILM/CPK format
flac	raw flac
flic	FLI/FLC/FLX animation format
flv	flv format
gif	GIF Animation
gxf	GXF format
h261	raw h261
h263	raw h263
h264	raw H264 video format
idcin	Id CIN format
image2	image2 sequence
image2pipe	piped image2 sequence
ingenient	Ingenient MJPEG
ipmovie	Interplay MVE format
libnut	nut format
m4v	raw MPEG4 video format
matroska	Matroska File Format
mjpeg	MJPEG video
mm	American Laser Games MM format
mmf	mmf format
mov,mp4,m4a,3gp,3g2,mj2	QuickTime/MPEG4/Motion JPEG 2000 format
mp3	MPEG audio layer 3
mpc	musepack
mpc8	musepack8
mpeg	MPEG1 System format
mpegts	MPEG2 transport stream format
mpegtsraw	MPEG2 raw transport stream format
mpegvideo	MPEG video
mulaw	pcm mu law format
mxf	MXF format
nsv	NullSoft Video format
nut	nut format
nuv	NuppelVideo format
ogg	Ogg format
psxstr	Sony Playstation STR format
rawvideo	raw video format
redir	Redirector format
rm	rm format
rtsp	RTSP input format
s16be	pcm signed 16 bit big endian format
s16le	pcm signed 16 bit little endian format
s8	pcm signed 8 bit format
sdp	SDP
shn	raw shorten
siff	Beam Software SIFF
smk	Smacker Video
sol	Sierra SOL Format
swf	Flash format
thp	THP
tiertexseq	Tiertex Limited SEQ format
tta	true-audio
txd	txd format
u16be	pcm unsigned 16 bit big endian format
u16le	pcm unsigned 16 bit little endian format
u8	pcm unsigned 8 bit format
vc1	raw vc1
vmd	Sierra VMD format
voc	Creative Voice File format
wav	wav format
wc3movie	Wing Commander III movie format
wsaud	Westwood Studios audio format
wsvqa	Westwood Studios VQA format
wv	WavPack
yuv4mpegpipe	YUV4MPEG pipe format

Encoding

Formato Descrizione

3g2	3gp2 format
3gp	3gp format
RoQ	Id RoQ format
ac3	raw ac3
adts	ADTS AAC
aiff	Audio IFF
alaw	pcm A law format
amr	3gpp amr file format
asf	asf format
asf_stream	asf format
au	SUN AU Format
avi	avi format
crc	crc testing format
dv	DV video format
dvd	MPEG2 PS format (DVD VOB)
ffm	ffm format
flac	raw flac
flv	flv format
framecrc	framecrc testing format
gif	GIF Animation
gxf	GXF format
h261	raw h261
h263	raw h263
h264	raw H264 video format
image2	image2 sequence
image2pipe	piped image2 sequence
libnut	nut format
m4v	raw MPEG4 video format
matroska	Matroska File Format
mjpeg	MJPEG video
mmf	mmf format
mov	mov format
mp2	MPEG audio layer 2
mp3	MPEG audio layer 3
mp4	mp4 format
mpeg	MPEG1 System format
mpeg1video	MPEG video
mpeg2video	MPEG2 video
mpegts	MPEG2 transport stream format
mpjpeg	Mime multipart JPEG format
mulaw	pcm mu law format
null	null video format
nut	nut format
ogg	Ogg format
psp	psp mp4 format
rawvideo	raw video format
rm	rm format
rtp	RTP output format
s16be	pcm signed 16 bit big endian format
s16le	pcm signed 16 bit little endian format
s8	pcm signed 8 bit format
svcd	MPEG2 PS format (VOB)
swf	Flash format
u16be	pcm unsigned 16 bit big endian format
u16le	pcm unsigned 16 bit little endian format
u8	pcm unsigned 8 bit format
vcd	MPEG1 System format (VCD)
vob	MPEG2 PS format (VOB)
voc	Creative Voice File format
wav	wav format
yuv4mpegpipe	YUV4MPEG pipe format

Built-in decoders and encoders

The JAVE built-in ffmpeg executable contains the following decoders and encoders:

Audio decoders

adpcm_4xm	adpcm_adx	adpcm_ct	adpcm_ea	adpcm_ea_r1
adpcm_ea_r2	adpcm_ea_r3	adpcm_ea_xas	adpcm_ima_amv	adpcm_ima_dk3
adpcm_ima_dk4	adpcm_ima_ea_eacs	adpcm_ima_ea_sead	adpcm_ima_qt	adpcm_ima_smjpeg
adpcm_ima_wav	adpcm_ima_ws	adpcm_ms	adpcm_sbpro_2	adpcm_sbpro_3
adpcm_sbpro_4	adpcm_swf	adpcm_thp	adpcm_xa	adpcm_yamaha
alac	ape	atrac 3	cook	dca
dsicinaudio	flac	g726	imc	interplay_dpcm
liba52	libamr_nb	libamr_wb	libfaad	libgsm
libgsm_ms	mace3	mace6	mp2	mp3
mp3adu	mp3on4	mpc sv7	mpc sv8	mpeg4aac
nellymoser	pcm_alaw	pcm_mulaw	pcm_s16be	pcm_s16le
pcm_s16le_planar	pcm_s24be	pcm_s24daud	pcm_s24le	pcm_s32be
pcm_s32le	pcm_s8	pcm_u16be	pcm_u16le	pcm_u24be
pcm_u24le	pcm_u32be	pcm_u32le	pcm_u8	pcm_zork
qdm2	real_144	real_288	roq_dpcm	shorten
smackaud	sol_dpcm	sonic	truespeech	tta
vmdaudio	vorbis	wavpack	wmav1	wmav2
ws_snd1	xan_dpcm

Audio encoders

ac3	adpcm_adx	adpcm_ima_wav	adpcm_ms	adpcm_swf
adpcm_yamaha	flac	g726	libamr_nb	libamr_wb
libfaac	libgsm	libgsm_ms	libmp3lame	libvorbis
mp2	pcm_alaw	pcm_mulaw	pcm_s16be	pcm_s16le
pcm_s24be	pcm_s24daud	pcm_s24le	pcm_s32be	pcm_s32le
pcm_s8	pcm_u16be	pcm_u16le	pcm_u24be	pcm_u24le
pcm_u32be	pcm_u32le	pcm_u8	pcm_zork	roq_dpcm
sonic	sonicls	vorbis	wmav1	wmav2

Video decoders

4xm	8bps	VMware video	aasc	amv
asv1	asv2	avs	bethsoftvid	bmp
c93	camstudio	camtasia	cavs	cinepak
cljr	cyuv	dnxhd	dsicinvideo	dvvideo
dxa	ffv1	ffvhuff	flashsv	flic
flv	fraps	gif	h261	h263
h263i	h264	huffyuv	idcinvideo	indeo2
indeo3	interplayvideo	jpegls	kmvc	loco
mdec	mjpeg	mjpegb	mmvideo	mpeg1video
mpeg2video	mpeg4	mpegvideo	msmpeg4	msmpeg4v1
msmpeg4v2	msrle	msvideo1	mszh	nuv
pam	pbm	pgm	pgmyuv	png
ppm	ptx	qdraw	qpeg	qtrle
rawvideo	roqvideo	rpza	rv10	rv20
sgi	smackvid	smc	snow	sp5x
svq1	svq3	targa	theora	thp
tiertexseqvideo	tiff	truemotion1	truemotion2	txd
ultimotion	vb	vc1	vcr1	vmdvideo
vp3	vp5	vp6	vp6a	vp6f
vqavideo	wmv1	wmv2	wmv3	wnv1
xan_wc3	xl	zlib	zmbv

Video encoders

asv1	asv2	bmp	dnxhd	dvvideo
ffv1	ffvhuff	flashsv	flv	gif
h261	h263	h263p	huffyuv	jpegls
libtheora	libx264	libxvid	ljpeg	mjpeg
mpeg1video	mpeg2video	mpeg4	msmpeg4	msmpeg4v1
msmpeg4v2	pam	pbm	pgm	pgmyuv
png	ppm	qtrle	rawvideo	roqvideo
rv10	rv20	sgi	snow	svq1
targa	tiff	wmv1	wmv2	zlib
zmbv

Examples

From a generic AVI to a youtube-like FLV movie, with an embedded MP3 audio stream:

File source = new File("source.avi");
File target = new File("target.flv");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("libmp3lame");
audio.setBitRate(new Integer(64000));
audio.setChannels(new Integer(1));
audio.setSamplingRate(new Integer(22050));
VideoAttributes video = new VideoAttributes();
video.setCodec("flv");
video.setBitRate(new Integer(160000));
video.setFrameRate(new Integer(15));
video.setSize(new VideoSize(400, 300));
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("flv");
attrs.setAudioAttributes(audio);
attrs.setVideoAttributes(video);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);

Next lines extracts audio informations from an AVI and store them in a plain WAV file:

File source = new File("source.avi");
File target = new File("target.wav");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("pcm_s16le");
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("wav");
attrs.setAudioAttributes(audio);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);

Next example takes an audio WAV file and generates a 128 kbit/s, stereo, 44100 Hz MP3 file:

File source = new File("source.wav");
File target = new File("target.mp3");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("libmp3lame");
audio.setBitRate(new Integer(128000));
audio.setChannels(new Integer(2));
audio.setSamplingRate(new Integer(44100));
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("mp3");
attrs.setAudioAttributes(audio);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);

Next one decodes a generic AVI file and creates another one with the same video stream of the source and a re-encoded low quality MP3 audio stream:

File source = new File("source.avi");
File target = new File("target.avi");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("libmp3lame");
audio.setBitRate(new Integer(56000));
audio.setChannels(new Integer(1));
audio.setSamplingRate(new Integer(22050));
VideoAttributes video = new VideoAttributes();
video.setCodec(VideoAttributes.DIRECT_STREAM_COPY);
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("avi");
attrs.setAudioAttributes(audio);
attrs.setVideoAttributes(video);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);

Next one generates an AVI with MPEG 4/DivX video and OGG Vorbis audio:

File source = new File("source.avi");
File target = new File("target.avi");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("libvorbis");
VideoAttributes video = new VideoAttributes();
video.setCodec("mpeg4");
video.setTag("DIVX");
video.setBitRate(new Integer(160000));
video.setFrameRate(new Integer(30));
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("mpegvideo");
attrs.setAudioAttributes(audio);
attrs.setVideoAttributes(video);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);

A smartphone suitable video:

File source = new File("source.avi");
File target = new File("target.3gp");
AudioAttributes audio = new AudioAttributes();
audio.setCodec("libfaac");
audio.setBitRate(new Integer(128000));
audio.setSamplingRate(new Integer(44100));
audio.setChannels(new Integer(2));
VideoAttributes video = new VideoAttributes();
video.setCodec("mpeg4");
video.setBitRate(new Integer(160000));
video.setFrameRate(new Integer(15));
video.setSize(new VideoSize(176, 144));
EncodingAttributes attrs = new EncodingAttributes();
attrs.setFormat("3gp");
attrs.setAudioAttributes(audio);
attrs.setVideoAttributes(video);
Encoder encoder = new Encoder();
encoder.encode(source, target, attrs);