Per utilizzare JAVE nella tua applicazione Java, devi aggiungere il file jave-1.0.jar al CLASSPATH.
JAVE richiede un ambiente di esecuzione Java J2SE versione 1.4 o successiva.
JAVE, inoltre, utilizza una versione di ffmpeg precompilata per Windows e Linux su piattaforma hardware i386 a 32 bit. Questo non significa che JAVE non possa funzionare su altre combinazioni, ma per farlo è nessario fornire un compilato di ffmpeg alternativo a quello incluso nella distribuzione. Maggiori dettagli sono riportati nel paragrafo "Cambiare l'eseguibile di ffmpeg in uso".
La principale classe di JAVE è it.sauronsoftware.jave.Encoder. Gli oggetti di tipo Encoder contengono una serie di metodi utili per avere informazioni e per effettuare le operazioni di transcodifica dei flussi multimediali. Prima di ogni altra cosa, pertanto, è necessario istanziare la classe Encoder, con una chiamata del tipo:
Encoder encoder = new Encoder();
Una volta creata l'istanza, il metodo per effettuare l'operazione di transcodifica è encode(). La firma del metodo è:
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
Il primo argomento, source, è il file sorgente da decodificare. Il secondo argomento, target, costituisce il nuovo file da creare, con il flusso multimediale ricodificato secondo richiesta. L'argomento attributes, di tipo it.sauronsoftware.jave.EncodingAttributes, è una struttura dati che incapsula tutti gli argomenti necessari per la ricodifica del flusso.
Si osservi che la chiamata al metodo è bloccante: il metodo ritorna solo al termine dell'operazione di codifica (o dopo un eventuale fallimento della stessa).
L'encoder di JAVE accetta gli attributi di codifica dei flussi multimediali attraverso un'istanza della classe it.sauronsoftware.jave.EncodingAttributes. La classe mette a disposizione i seguenti metodi:
public void setAudioAttributes(it.sauronsoftware.jave.AudioAttributes audioAttributes)
public void setVideoAttributes(it.sauronsoftware.jave.AudioAttributes videoAttributes)
public void setFormat(java.lang.String format)
public void setOffset(java.lang.Float offset)
public void setDuration(java.lang.Float duration)
Gli attributi di codifica audio devono essere espressi attraverso un oggetto di tipo it.sauronsoftware.jave.AudioAttributes. Gli oggetti di questo tipo permotto di impostare gli attributi di ricodifica audio mediante i seguenti metodi:
public void setCodec(java.lang.String codec)
public void setBitRate(java.lang.Integer bitRate)
public void setSamplingRate(java.lang.Integer bitRate)
public void setChannels(java.lang.Integer channels)
public void setVolume(java.lang.Integer volume)
Gli attributi di codifica video devono essere espressi attraverso un oggetto di tipo it.sauronsoftware.jave.VideoAttributes. Gli oggetti di questo tipo permotto di impostare gli attributi di ricodifica video mediante i seguenti metodi:
public void setCodec(java.lang.String codec)
public void setTag(java.lang.String tag)
public void setBitRate(java.lang.Integer bitRate)
public void setFrameRate(java.lang.Integer bitRate)
public void setSize(it.sauronsoftware.jave.VideoSize size)
Le operazioni di codifica possono essere monitorate durante il loro svolgimento mediante un meccanismo ad eventi basato sul paradigma dei listener. JAVE definisce l'interfaccia it.sauronsoftware.jave.EncoderProgressListener che può essere implementata per generare degli oggetti listener da fornire poi all'encoder, attraverso la variante del metodo encode così formulata:
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
L'inrefaccia EncoderProgressListener richiede la definizione dei seguenti metodi:
public void sourceInfo(it.sauronsoftware.jave.MultimediaInfo info)
public void progress(int permil)
public void message(java.lang.String message)
L'operazione di codifica può fallire. In tal caso in metodo encode() propaga un'eccezione. A seconda di quel che è accaduto, l'eccezione è differente:
JAVE permette di avere informazioni su un file multimediale esistente prima ancora di ricodificarlo, attraverso il metodo getInfo() degli oggetti Encoder, così definito:
public it.sauronsoftware.jave.MultimediaInfo getInfo(java.io.File source) throws it.sauronsoftware.jave.InputFormatException, it.sauronsoftware.jave.EncoderException
Gli oggetti it.sauronsoftware.jave.MultimediaInfo, che a loro volta contengono oggetti it.sauronsoftware.jave.AudioInfo e it.sauronsoftware.jave.VideoInfo, sono speculari rispetto agli oggetti di tipo EncodingAttributes, AudioAttributes e VideoAttributes, e dispongono di metodi per il recupero di informazioni quali il formato del contenitore multimediale, i decoder in grado di decodificare i flussi, informazioni su bitrate, samplerate, framerate ecc. Questi metodi possono essere facilmente consultati nella documentazione javadoc delle API di JAVE, fornita nella distribuzione stessa della libreria.
JAVE non è una libreria pure Java, ma un wrapper su un progetto libero chiamato ffmpeg (http://ffmpeg.mplayerhq.hu/). Il codice di ffmpeg è in C, pertanto non ha la portabilità di Java ed è necessario disporre di una versione compilata del tool per ogni combinazione hardware/software sulla quale si vuole impiegare JAVE. La distribuzione di JAVE comprende due versioni precompilate di ffmpeg, una per Windows e una per Linux, entrambe per piattaforme hardware di tipo i386 con architettura a 32 bit. Ciò copre la maggior parte delle esigenze. In piattaforme differenti da quelle elencate è necessario generare un compilato di ffmpeg. I sorgenti e le istruzioni per farlo sono disponibili nel sito Web del progetto. Una volta ottenuto il compilato è necessario agganciarlo all'encoder di JAVE. E' possibile farlo fornendo al costruttore di Encoder un'istanza della classe astratta it.sauronsoftware.jave.FFMPEGLocator. Per far ciò è necessario estendere FFMPEGLocator andando a definire il metodo con firma:
public java.lang.String getFFMPEGExecutablePath()
Il metodo deve restituire un percorso sul file system locale che conduce all'eseguibile di ffmpeg che si intende utilizzare.
Successivamente l'encoder di JAVE può essere istanziato con una chiamata del tipo:
Encoder encoder = new Encoder(new MyFFMPEGExecutableLocator())
La stessa tecnica può essere utilizzata anche sulle piattaforme già supportate dai precompilati presenti in JAVE, al solo scopo di modificare la versione di ffmpeg in uso.
Le versioni di ffmpeg precompilate e distribuite insieme a JAVE supportato i seguenti formati.
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 |
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 |
Le versioni di ffmpeg precompilate e distribuite insieme a JAVE comprendono i seguenti codec e decoder.
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 |
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 |
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 |
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 |
Il seguente codice prende un generico AVI come fonte e genera un filmato FLV a la youtube, con audio in MP3:
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);
Il prossimo esempio estrae l'audio da un filmato di origine e lo salva come file WAV:
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);
Il prossimo esempio prende un file WAV e genera un MP3 128 kbit/s, stereo, 44100 Hz:
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);
Il prossimo esempio prende in ingresso un file AVI e ne genera un altro dove il flusso video è esattamente lo stesso della sorgente, mentre l'audio viene compresso in MP3 di bassa qualità:
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);
Genera un AVI con video MPEG 4/DivX e audio OGG Vorbis:
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);
Un video per cellulari:
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);