Manuale di JAVE

• Prima di cominciare
• Codificare i flussi audio/video
• Attributi di codifica
• Attributi di codifica audio
• Attributi di codifica video
• Monitorare l'operazione di codifica
• Fallimento dell'operazione di codifica
• Ottenere informazioni su un file multimediale
• Cambiare l'eseguibile di ffmpeg in uso
• Formati supportati
• Codec e decoder compresi
• Esempi

Prima di cominciare

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".

Codificare i flussi audio/video

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).

Attributi di codifica

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)
  Permette di impostare gli attributi specifici per la ricodifica del flusso audio. Se il metodo non viene richiamato su una nuova istanza di EncodingAttributes e, di conseguenza, nessun attributo di ricodifica audio viene specificato, allora l'encoder non effettuerà codifica audio. Il file di destinazione, di conseguenza, non conterrà alcuna traccia audio, anche se quello di origine ne ha una. Vedi paragrafo "Attributi di codifica audio".
• public void setVideoAttributes(it.sauronsoftware.jave.AudioAttributes videoAttributes)
  Permette di impostare gli attributi specifici per la ricodifica del flusso video. Se il metodo non viene richiamato su una nuova istanza di EncodingAttributes e, di conseguenza, nessun attributo di ricodifica video viene specificato, allora l'encoder non effettuerà codifica video. Il file di destinazione, di conseguenza, non conterrà alcuna traccia video, anche se quello di origine ne ha una. Vedi paragrafo "Attributi di codifica video".
• public void setFormat(java.lang.String formatHandle)
  Questo metodo serve per specificare il formato del contenitore dei flussi audio e video. Il formato va espresso mediante una stringa che ne rappresenta il nome. La lista dei nomi dei formati supportati può essere ricavata chiamando il metodo getSupportedEncodingFormats() su un oggetto di tipo Encoder.
• public void setOffset(java.lang.Float offset)
  Questo metodo può essere richiamato per specificare un offset di ricodifica, cioè un taglio iniziale del flusso multimediale sorgente. Il valore del taglio è espresso in secondi, con la possibilità di utilizzare valori decimali. Ad esempio se si vuole iniziare la ricodifica un flusso multimediale tagliandone i primi cinque secondi è sufficiente fornire all'encoder un'oggetto EncodingAttributes sul quale sia stato precedentemente richiamato il metodo setOffset(5).
• public void setDuration(java.lang.Float duration)
  Questo metodo può essere richiamato per impostare la durata della ricodifica. Il valore è espresso in secondi, con la possibilità di utilizzare valori decimali. Ad esempio se si vogliono ricodificare soltanto trenta secondi di un flusso multimediale è sufficiente fornire all'encoder un'oggetto EncodingAttributes sul quale sia stato precedentemente richiamato il metodo setDuration(30).

Attributi di codifica audio

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)
  Questo metodo imposta il codec per la ricodifica del flusso audio. Può essere specificato lo speciale valore espresso dalla costante AudioAttributes.DIRECT_STREAM_COPY per ottenere una copia del flusso audio contenuto nel file multimediale sorgente, altrimenti è necessario specificare il nome del codec che si intende utilizzare. La lista dei codec audio disponibili può essere recuperata chiamando il metodo getAudioEncoders() su un oggetto di tipo Encoder.
• public void setBitRate(java.lang.Integer bitRate)
  Questo metodo può essere richiamato per specificare esplicitamente il bitrate di codifica audio. Se nessun valore viene impostato, l'encoder ne sceglierà uno di default. Nel caso si intenda specificare manualmente il bitrate si faccia attenzione al fatto che il valore deve essere espresso come bit al secondo e non kbit al secondo. Ad esempio nella codifica di un flusso audio con bitrate pari a 128 kb/s la chiamata giusta da utilizzare è setBitRate(new Integer(128000)).
• public void setSamplingRate(java.lang.Integer bitRate)
  Questo metodo può essere richiamato per specificare esplicitamente una frequenza di campionamento per la codifica audio. Se nessun valore viene impostato, l'encoder ne sceglierà uno di default. Il valore va espresso in hertz. Ad esempio, per una frequenza di campionamento uguale a quella di un audio CD, si deve eseguire la chiamata setSamplingRate(new Integer(44100)).
• public void setChannels(java.lang.Integer channels)
  Questo metodo può essere richiamato per specificare esplicitamente il numero dei canali da utilizzare nella codifica audio (1 = mono, 2 = stereo). Se nessun valore viene impostato, l'encoder ne sceglierà uno di default.
• public void setVolume(java.lang.Integer volume)
  Questo metodo può essere richiamato per alterare il volume del flusso audio durante la sua ricodicia. Un valore pari a 256 implica nessun cambio di volume. Pertanto valori più grandi di 256 aumenteranno il volume rispetto al flusso audio originario, mentre valori minori lo abbasseranno.

Attributi di codifica video

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)
  Questo metodo imposta il codec per la ricodifica del flusso video. Può essere specificato lo speciale valore espresso dalla costante VideoAttributes.DIRECT_STREAM_COPY per ottenere una copia del flusso video contenuto nel file multimediale sorgente, altrimenti è necessario specificare il nome del codec che si intende utilizzare. La lista dei codec video disponibili può essere recuperata chiamando il metodo getVideoEncoders() su un oggetto di tipo Encoder.
• public void setTag(java.lang.String tag)
  Questo metodo imposta il tag del flusso video che sarà generato. Il tag è utilizzato dai player per decidere esattamente con quale componente decodificare il flusso. Ad esempio un DivX è un flusso video MPEG4 il cui tag associato ha valore "DIVX", per forzarne la decodifica con il decoder DivX installato nel sistema.
• public void setBitRate(java.lang.Integer bitRate)
  Questo metodo può essere richiamato per specificare esplicitamente il bitrate di codifica video. Se nessun valore viene impostato, l'encoder ne sceglierà uno di default. Nel caso si intenda specificare manualmente il bitrate si faccia attenzione al fatto che il valore deve essere espresso come bit al secondo e non kbit al secondo. Ad esempio nella codifica di un flusso video con bitrate pari a 360 kb/s la chiamata giusta da utilizzare è setBitRate(new Integer(360000)).
• public void setFrameRate(java.lang.Integer bitRate)
  Questo metodo può essere richiamato per specificare esplicitamente il framerate per la codifica audio. Se nessun valore viene impostato, l'encoder ne sceglierà uno di default. Il valore va espresso come fotogrammi al secondo. Ad esempio, per ottenere un flusso video con 30 fotogrammi al secondo, si deve eseguire la chiamata setFrameRate(new Integer(30)).
• public void setSize(it.sauronsoftware.jave.VideoSize size)
  Questo metodo può essere richiamato per alterare la dimensione del video. Se nessun valore viene impostato, l'encoder manterrà le dimensioni presenti nel flusso video sorgente. Le dimensioni sono espresse mediante un oggetto it.sauronsoftware.java.VideoSize, che permette di specificare la larghezza e l'altezza, in pixel, per la ricodifica video. Ad esempio per generare un flusso video con larghezza 512 px e altezza 384 px si deve eseguire la chiamata setSize(new VideoSize(512, 384)).

Monitorare l'operazione di codifica

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)
  Questo metodo viene richiamato dall'encoder non appena viene terminata l'analisi del file multimediale sorgente e appena prima che l'operazione di transcodifica abbia inizio. Il parametro fornito, di tipo it.sauronsoftware.jave.MultimediaInfo, contiene informazioni sul formato e sui flussi del file multimediale di origine.
• public void progress(int permil)
  Questo metodo viene richiamato dall'encoder per notificare un avvenuto progresso durante l'operazione di ricodifica. Il parametro fornito è un valore permille: fatto 1000 il punto in cui l'operazione è completata, il parametro fornisce il valore corrispondente al punto raggiunto dall'operazione.
• public void message(java.lang.String message)
  Questo metodo viene richiamato dall'encoder per segnalare un messaggio, generalmente un avviso o un errore.

Fallimento dell'operazione di codifica

L'operazione di codifica può fallire. In tal caso in metodo encode() propaga un'eccezione. A seconda di quel che è accaduto, l'eccezione è differente:

• java.lang.IllegalArgumentException
  L'operazione di codifica non è stata avviata in quanto gli attributi di ricodifica forniti all'encoder non sono validi. Generalmente questo accade quando si passa un oggetto EncodingAttributes che richiede la creazione di un file multimediale senza flussi né audio né video.
• it.sauronsoftware.jave.InputFormatException
  L'operazione di codifica non è stata avviata in quanto il file sorgente non può essere decodificato. Accertarsi che si tratti effettivamente di un file multimediale e, in tal caso, accertarsi che il formato del contenitore, del flusso audio e del flusso video siano decodificabili. Le liste dei formati supportati e dei decoder audio e video installati possono essere recuperate, rispettivamente, con i metodi getSupportedDecodingFormats(), getAudioDecoders() e getVideoDecoders() di un oggetto di tipo Encoder.
• it.sauronsoftware.jave.EncoderExpection
  L'operazione è fallita durante la ricodifica a causa di un errore non prevedibile a priori. Controllare il messaggio dell'eccezione ed eventualmente verificare gli avvisi propagati dall'encoder attraverso un EncoderProgressListener.

Ottenere informazioni su un file multimediale

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.

Cambiare l'eseguibile di ffmpeg in uso

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.

Formati supportati

Le versioni di ffmpeg precompilate e distribuite insieme a JAVE supportato i seguenti formati.

In lettura

In scrittura

Codec e decoder compresi

Le versioni di ffmpeg precompilate e distribuite insieme a JAVE comprendono i seguenti codec e decoder.

Decoder audio

Codec audio

Decoder video

Codec video

Esempi

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);