Sauron Software Projects Repository
JAVE
Overview Documentation Download

JAVE manual

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:

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:

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:

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:

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:

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

FormatoDescrizione
4xm4X Technologies format
MTVMTV format
RoQId RoQ format
aacADTS AAC
ac3raw ac3
aiffAudio IFF
alawpcm A law format
amr3gpp amr file format
apcCRYO APC format
apeMonkey's Audio
asfasf format
auSUN AU Format
aviavi format
avsAVISynth
bethsoftvidBethesda Softworks 'Daggerfall' VID format
c93Interplay C93
daudD-Cinema audio format
dsicinDelphine Software International CIN format
dtsraw dts
dvDV video format
dxadxa
eaElectronic Arts Multimedia Format
ea_cdataElectronic Arts cdata
ffmffm format
film_cpkSega FILM/CPK format
flacraw flac
flicFLI/FLC/FLX animation format
flvflv format
gifGIF Animation
gxfGXF format
h261raw h261
h263raw h263
h264raw H264 video format
idcinId CIN format
image2image2 sequence
image2pipepiped image2 sequence
ingenientIngenient MJPEG
ipmovieInterplay MVE format
libnutnut format
m4vraw MPEG4 video format
matroskaMatroska File Format
mjpegMJPEG video
mmAmerican Laser Games MM format
mmfmmf format
mov,mp4,m4a,3gp,3g2,mj2QuickTime/MPEG4/Motion JPEG 2000 format
mp3MPEG audio layer 3
mpcmusepack
mpc8musepack8
mpegMPEG1 System format
mpegtsMPEG2 transport stream format
mpegtsrawMPEG2 raw transport stream format
mpegvideoMPEG video
mulawpcm mu law format
mxfMXF format
nsvNullSoft Video format
nutnut format
nuvNuppelVideo format
oggOgg format
psxstrSony Playstation STR format
rawvideoraw video format
redirRedirector format
rmrm format
rtspRTSP input format
s16bepcm signed 16 bit big endian format
s16lepcm signed 16 bit little endian format
s8pcm signed 8 bit format
sdpSDP
shnraw shorten
siffBeam Software SIFF
smkSmacker Video
solSierra SOL Format
swfFlash format
thpTHP
tiertexseqTiertex Limited SEQ format
ttatrue-audio
txdtxd format
u16bepcm unsigned 16 bit big endian format
u16lepcm unsigned 16 bit little endian format
u8pcm unsigned 8 bit format
vc1raw vc1
vmdSierra VMD format
vocCreative Voice File format
wavwav format
wc3movieWing Commander III movie format
wsaudWestwood Studios audio format
wsvqaWestwood Studios VQA format
wvWavPack
yuv4mpegpipeYUV4MPEG pipe format

Encoding

FormatoDescrizione
3g23gp2 format
3gp3gp format
RoQId RoQ format
ac3raw ac3
adtsADTS AAC
aiffAudio IFF
alawpcm A law format
amr3gpp amr file format
asfasf format
asf_streamasf format
auSUN AU Format
aviavi format
crccrc testing format
dvDV video format
dvdMPEG2 PS format (DVD VOB)
ffmffm format
flacraw flac
flvflv format
framecrcframecrc testing format
gifGIF Animation
gxfGXF format
h261raw h261
h263raw h263
h264raw H264 video format
image2image2 sequence
image2pipepiped image2 sequence
libnutnut format
m4vraw MPEG4 video format
matroskaMatroska File Format
mjpegMJPEG video
mmfmmf format
movmov format
mp2MPEG audio layer 2
mp3MPEG audio layer 3
mp4mp4 format
mpegMPEG1 System format
mpeg1videoMPEG video
mpeg2videoMPEG2 video
mpegtsMPEG2 transport stream format
mpjpegMime multipart JPEG format
mulawpcm mu law format
nullnull video format
nutnut format
oggOgg format
psppsp mp4 format
rawvideoraw video format
rmrm format
rtpRTP output format
s16bepcm signed 16 bit big endian format
s16lepcm signed 16 bit little endian format
s8pcm signed 8 bit format
svcdMPEG2 PS format (VOB)
swfFlash format
u16bepcm unsigned 16 bit big endian format
u16lepcm unsigned 16 bit little endian format
u8pcm unsigned 8 bit format
vcdMPEG1 System format (VCD)
vobMPEG2 PS format (VOB)
vocCreative Voice File format
wavwav format
yuv4mpegpipeYUV4MPEG pipe format

Built-in decoders and encoders

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

Audio decoders

adpcm_4xmadpcm_adxadpcm_ctadpcm_eaadpcm_ea_r1
adpcm_ea_r2adpcm_ea_r3adpcm_ea_xasadpcm_ima_amvadpcm_ima_dk3
adpcm_ima_dk4adpcm_ima_ea_eacsadpcm_ima_ea_seadadpcm_ima_qtadpcm_ima_smjpeg
adpcm_ima_wavadpcm_ima_wsadpcm_msadpcm_sbpro_2adpcm_sbpro_3
adpcm_sbpro_4adpcm_swfadpcm_thpadpcm_xaadpcm_yamaha
alacapeatrac 3cookdca
dsicinaudioflacg726imcinterplay_dpcm
liba52libamr_nblibamr_wblibfaadlibgsm
libgsm_msmace3mace6mp2mp3
mp3adump3on4mpc sv7mpc sv8mpeg4aac
nellymoserpcm_alawpcm_mulawpcm_s16bepcm_s16le
pcm_s16le_planarpcm_s24bepcm_s24daudpcm_s24lepcm_s32be
pcm_s32lepcm_s8pcm_u16bepcm_u16lepcm_u24be
pcm_u24lepcm_u32bepcm_u32lepcm_u8pcm_zork
qdm2real_144real_288roq_dpcmshorten
smackaudsol_dpcmsonictruespeechtta
vmdaudiovorbiswavpackwmav1wmav2
ws_snd1xan_dpcm   

Audio encoders

ac3adpcm_adxadpcm_ima_wavadpcm_msadpcm_swf
adpcm_yamahaflacg726libamr_nblibamr_wb
libfaaclibgsmlibgsm_mslibmp3lamelibvorbis
mp2pcm_alawpcm_mulawpcm_s16bepcm_s16le
pcm_s24bepcm_s24daudpcm_s24lepcm_s32bepcm_s32le
pcm_s8pcm_u16bepcm_u16lepcm_u24bepcm_u24le
pcm_u32bepcm_u32lepcm_u8pcm_zorkroq_dpcm
sonicsoniclsvorbiswmav1wmav2

Video decoders

4xm8bpsVMware videoaascamv
asv1asv2avsbethsoftvidbmp
c93camstudiocamtasiacavscinepak
cljrcyuvdnxhddsicinvideodvvideo
dxaffv1ffvhuffflashsvflic
flvfrapsgifh261h263
h263ih264huffyuvidcinvideoindeo2
indeo3interplayvideojpeglskmvcloco
mdecmjpegmjpegbmmvideompeg1video
mpeg2videompeg4mpegvideomsmpeg4msmpeg4v1
msmpeg4v2msrlemsvideo1mszhnuv
pampbmpgmpgmyuvpng
ppmptxqdrawqpegqtrle
rawvideoroqvideorpzarv10rv20
sgismackvidsmcsnowsp5x
svq1svq3targatheorathp
tiertexseqvideotifftruemotion1truemotion2txd
ultimotionvbvc1vcr1vmdvideo
vp3vp5vp6vp6avp6f
vqavideowmv1wmv2wmv3wnv1
xan_wc3xlzlibzmbv 

Video encoders

asv1asv2bmpdnxhddvvideo
ffv1ffvhuffflashsvflvgif
h261h263h263phuffyuvjpegls
libtheoralibx264libxvidljpegmjpeg
mpeg1videompeg2videompeg4msmpeg4msmpeg4v1
msmpeg4v2pampbmpgmpgmyuv
pngppmqtrlerawvideoroqvideo
rv10rv20sgisnowsvq1
targatiffwmv1wmv2zlib
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);
© Sauron Software 2007 - 2012 | Questa pagina in italiano