官网地址:http://www.sauronsoftware.it/projects/jave/manual.php

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:

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

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 video format

dxa

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

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 format

rtsp

RTSP input format

s16be

pcm signed 16 bit big endian format

s16le

pcm signed 16 bit little endian format

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

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

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

SUN AU Format

avi

avi format

crc

crc testing format

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 format

rtp

RTP output format

s16be

pcm signed 16 bit big endian format

s16le

pcm signed 16 bit little endian format

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

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

vc1

vcr1

vmdvideo

vp3

vp5

vp6

vp6a

vp6f

vqavideo

wmv1

wmv2

wmv3

wnv1

xan_wc3

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