ca.randelshofer
Class AVIOutputStream

java.lang.Object
  ca.randelshofer.AVIOutputStream

public class AVIOutputStream
extends java.lang.Object

This class supports writing of images into an AVI 1.0 video file.

The images are written as video frames.

Video frames can be encoded with one of the following formats:

• JPEG
• PNG
• RAW
• RLE

All frames must have the same format. When JPG is used each frame can have an individual encoding quality.

All frames in an AVI file must have the same duration. The duration can be set by setting an appropriate pair of values using methods setFrameRate(int) and setTimeScale(int).

The length of an AVI 1.0 file is limited to 1 GB. This class supports lengths of up to 4 GB, but such files may not work on all players.

For detailed information about the AVI RIFF file format see:
msdn.microsoft.com AVI RIFF
www.microsoft.com FOURCC for Video Compression
www.saettler.com RIFF

Version:

1.5.1 2011-01-17 Fixes unintended closing of output stream..
1.5 2011-01-06 Adds support for RLE 8-bit video format.
1.4 2011-01-04 Adds support for RAW 4-bit and 8-bit video format. Fixes offsets in "idx1" chunk.
1.3.2 2010-12-27 File size limit is 1 GB.
1.3.1 2010-07-19 Fixes seeking and calculation of offsets.
1.3 2010-07-08 Adds constructor with ImageOutputStream. Added method getVideoDimension().
1.2 2009-08-29 Adds support for RAW video format.
1.1 2008-08-27 Fixes computation of dwMicroSecPerFrame in avih chunk. Changed the API to reflect that AVI works with frame rates instead of with frame durations.
1.0.1 2008-08-13 Uses FourCC "MJPG" instead of "jpg " for JPG encoded video.
1.0 2008-08-11 Created.

Author:

Werner Randelshofer

Nested Class Summary

static class

AVIOutputStream.VideoFormat Supported video encodings.

Constructor Summary

AVIOutputStream(java.io.File file, AVIOutputStream.VideoFormat format)
Creates a new AVI file with the specified video format and frame rate.

AVIOutputStream(java.io.File file, AVIOutputStream.VideoFormat format, int bitsPerPixel)
Creates a new AVI file with the specified video format and frame rate.

AVIOutputStream(javax.imageio.stream.ImageOutputStream out, AVIOutputStream.VideoFormat format)
Creates a new AVI output stream with the specified video format and framerate.

Method Summary

void	close() Closes the movie file as well as the stream being filtered.
void	finish() Finishes writing the contents of the AVI output stream without closing the underlying stream.
int	getFrameRate() Returns the frame rate of this media.
int	getTimeScale() Returns the time scale of this media.
float	getVideoCompressionQuality() Returns the video compression quality.
java.awt.Dimension	getVideoDimension() Gets the dimension of the video track.
void	setFrameRate(int newValue) Sets the rate of video frames in time scale units.
void	setPalette(java.awt.image.IndexColorModel palette) Sets the global color palette.
void	setTimeScale(int newValue) Used with frameRate to specify the time scale that this stream will use.
void	setVideoCompressionQuality(float newValue) Sets the compression quality of the video track.
void	setVideoDimension(int width, int height) Sets the dimension of the video track.
void	writeFrame(java.awt.image.BufferedImage image) Writes a frame to the video track.
void	writeFrame(java.io.File file) Writes a frame from a file to the video track.
void	writeFrame(java.io.InputStream in) Writes a frame to the video track.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AVIOutputStream

public AVIOutputStream(java.io.File file,
                       AVIOutputStream.VideoFormat format)
                throws java.io.IOException

Creates a new AVI file with the specified video format and frame rate. The video has 24 bits per pixel.

Parameters:

file - the output file

format - Selects an encoder for the video format.

Throws:

java.lang.IllegalArgumentException - if videoFormat is null or if frame rate is <= 0

java.io.IOException

AVIOutputStream

public AVIOutputStream(java.io.File file,
                       AVIOutputStream.VideoFormat format,
                       int bitsPerPixel)
                throws java.io.IOException

Creates a new AVI file with the specified video format and frame rate.

Parameters:

file - the output file

format - Selects an encoder for the video format.

bitsPerPixel - the number of bits per pixel.

Throws:

java.lang.IllegalArgumentException - if videoFormat is null or if frame rate is <= 0

java.io.IOException

AVIOutputStream

public AVIOutputStream(javax.imageio.stream.ImageOutputStream out,
                       AVIOutputStream.VideoFormat format)
                throws java.io.IOException

Creates a new AVI output stream with the specified video format and framerate.

Parameters:

out - the underlying output stream

format - Selects an encoder for the video format.

Throws:

java.lang.IllegalArgumentException - if videoFormat is null or if framerate is <= 0

java.io.IOException

Method Detail

setTimeScale

public void setTimeScale(int newValue)

Used with frameRate to specify the time scale that this stream will use. Dividing frameRate by timeScale gives the number of samples per second. For video streams, this is the frame rate. For audio streams, this rate corresponds to the time needed to play nBlockAlign bytes of audio, which for PCM audio is the just the sample rate.

The default value is 1.

Parameters:

newValue -

getTimeScale

public int getTimeScale()

Returns the time scale of this media.

Returns:

time scale

setFrameRate

public void setFrameRate(int newValue)

Sets the rate of video frames in time scale units.

The default value is 30. Together with the default value 1 of timeScale this results in 30 frames pers second.

Parameters:

newValue -

getFrameRate

public int getFrameRate()

Returns the frame rate of this media.

Returns:

frame rate

setPalette

public void setPalette(java.awt.image.IndexColorModel palette)

Sets the global color palette.

setVideoCompressionQuality

public void setVideoCompressionQuality(float newValue)

Sets the compression quality of the video track. A value of 0 stands for "high compression is important" a value of 1 for "high image quality is important".

Changing this value affects frames which are subsequently written to the AVIOutputStream. Frames which have already been written are not changed.

This value has only effect on videos encoded with JPG format.

The default value is 0.9.

Parameters:

newValue -

getVideoCompressionQuality

public float getVideoCompressionQuality()

Returns the video compression quality.

Returns:

video compression quality

setVideoDimension

public void setVideoDimension(int width,
                              int height)

Sets the dimension of the video track.

You need to explicitly set the dimension, if you add all frames from files or input streams.

If you add frames from buffered images, then AVIOutputStream can determine the video dimension from the image width and height.

Parameters:

width - Must be greater than 0.

height - Must be greater than 0.

getVideoDimension

public java.awt.Dimension getVideoDimension()

Gets the dimension of the video track.

Returns null if the dimension is not known.

writeFrame

public void writeFrame(java.awt.image.BufferedImage image)
                throws java.io.IOException

Writes a frame to the video track.

If the dimension of the video track has not been specified yet, it is derived from the first buffered image added to the AVIOutputStream.

Parameters:

image - The frame image.

Throws:

java.lang.IllegalArgumentException - if the duration is less than 1, or if the dimension of the frame does not match the dimension of the video track.

java.io.IOException - if writing the image failed.

writeFrame

public void writeFrame(java.io.File file)
                throws java.io.IOException

Writes a frame from a file to the video track.

This method does not inspect the contents of the file. For example, Its your responsibility to only add JPG files if you have chosen the JPEG video format.

If you add all frames from files or from input streams, then you have to explicitly set the dimension of the video track before you call finish() or close().

Parameters:

file - The file which holds the image data.

Throws:

java.lang.IllegalStateException - if the duration is less than 1.

java.io.IOException - if writing the image failed.

writeFrame

public void writeFrame(java.io.InputStream in)
                throws java.io.IOException

Writes a frame to the video track.

This method does not inspect the contents of the file. For example, its your responsibility to only add JPG files if you have chosen the JPEG video format.

If you add all frames from files or from input streams, then you have to explicitly set the dimension of the video track before you call finish() or close().

Parameters:

in - The input stream which holds the image data.

Throws:

java.lang.IllegalArgumentException - if the duration is less than 1.

java.io.IOException - if writing the image failed.

close

public void close()
           throws java.io.IOException

Closes the movie file as well as the stream being filtered.

Throws:

java.io.IOException - if an I/O error has occurred

finish

public void finish()
            throws java.io.IOException

Finishes writing the contents of the AVI output stream without closing the underlying stream. Use this method when applying multiple filters in succession to the same output stream.

Throws:

java.lang.IllegalStateException - if the dimension of the video track has not been specified or determined yet.

java.io.IOException - if an I/O exception has occurred