org.monte.media.quicktime
Class QuickTimeOutputStream

java.lang.Object
  org.monte.media.quicktime.AbstractQuickTimeStream
      org.monte.media.quicktime.QuickTimeOutputStream

Direct Known Subclasses:

QuickTimeWriter

public class QuickTimeOutputStream
extends AbstractQuickTimeStream

This class provides low-level support for writing already encoded audio and video samples into a QuickTime file.

Version:

1.0 2011-08-19 Created.

Author:

Werner Randelshofer

Nested Class Summary

Nested classes/interfaces inherited from class org.monte.media.quicktime.AbstractQuickTimeStream

AbstractQuickTimeStream.Atom, AbstractQuickTimeStream.AudioTrack, AbstractQuickTimeStream.Chunk, AbstractQuickTimeStream.CompositeAtom, AbstractQuickTimeStream.DataAtom, AbstractQuickTimeStream.Edit, AbstractQuickTimeStream.Group, AbstractQuickTimeStream.Sample, AbstractQuickTimeStream.SampleSizeGroup, AbstractQuickTimeStream.States, AbstractQuickTimeStream.TimeToSampleGroup, AbstractQuickTimeStream.Track, AbstractQuickTimeStream.VideoTrack, AbstractQuickTimeStream.WideDataAtom

Field Summary

Fields inherited from class org.monte.media.quicktime.AbstractQuickTimeStream

creationTime, mdatAtom, mdatOffset, modificationTime, moovAtom, movieMatrix, movieTimeScale, out, state, streamOffset, tracks

Constructor Summary

QuickTimeOutputStream(java.io.File file)
Creates a new instance.

QuickTimeOutputStream(javax.imageio.stream.ImageOutputStream out)
Creates a new instance.

Method Summary

int	addAudioTrack(java.lang.String compressionType, long timeScale, double sampleRate, int numberOfChannels, int sampleSizeInBits, boolean isCompressed, int frameDuration, int frameSize, boolean signed, java.nio.ByteOrder byteOrder) Adds an audio track.
int	addVideoTrack(java.lang.String compressionType, java.lang.String compressorName, long timeScale, int width, int height, int depth, int syncInterval) Adds a video track.
void	close() Closes the movie file as well as the stream being filtered.
protected void	ensureOpen() Check to make sure that this stream has not been closed
protected void	ensureStarted() Sets the state of the QuickTimeWriter to started.
void	finish() Finishes writing the contents of the QuickTime output stream without closing the underlying stream.
float	getCompressionQuality(int track) Returns the compression quality of a track.
long	getMediaDuration(int track) Returns the media duration of a track in the media's time scale.
long	getMediaTimeScale(int track) Returns the time scale of the media in a track.
long	getMovieDuration() Returns the total duration of the movie in the movie's time scale.
long	getMovieTimeScale() Returns the time scale of the movie.
int	getSyncInterval(int track) Gets the sync interval from the specified video track.
long	getTrackDuration(int track) Returns the track duration in the movie's time scale.
double[]	getTransformationMatrix(int track) Gets the transformation matrix of the specified track.
long	getUneditedTrackDuration(int track) Returns the track duration in the movie's time scale without taking the edit list into account.
java.awt.image.IndexColorModel	getVideoColorTable(int track) Gets the preferred color table for displaying the movie on devices that support only 256 colors.
boolean	isDataLimitReached() Returns true if the limit for media samples has been reached.
void	setCompressionQuality(int track, float newValue) Sets the compression quality of a track.
void	setCreationTime(java.util.Date creationTime) Sets the creation time of the movie.
void	setEditList(int track, AbstractQuickTimeStream.Edit[] editList) Sets the edit list for the specified track.
void	setModificationTime(java.util.Date modificationTime) Sets the modification time of the movie.
void	setMovieTimeScale(long timeScale) Sets the time scale for this movie, that is, the number of time units that pass per second in its time coordinate system.
void	setSyncInterval(int track, int i) Sets the sync interval for the specified video track.
void	setTransformationMatrix(int track, double[] matrix) Sets the transformation matrix of the specified track.
void	setVideoColorTable(int track, java.awt.image.IndexColorModel icm) Sets the color table for videos with indexed color models.
void	toWebOptimizedMovie(java.io.File outputFile, boolean compressHeader) Writes a version of the movie which is optimized for the web into the specified output file.
void	writeSample(int track, byte[] data, int off, int len, long duration, boolean isSync) Writes an already encoded sample from a byte array into a track.
void	writeSample(int track, byte[] data, long duration, boolean isSync) Writes an already encoded sample from a byte array into a track.
void	writeSample(int track, java.io.File file, long duration, boolean isSync) Writes an already encoded sample from a file into a track.
void	writeSample(int track, java.io.InputStream in, long duration, boolean isSync) Writes an already encoded sample from an input stream into a track.
void	writeSamples(int track, int sampleCount, byte[] data, int off, int len, long sampleDuration) Writes multiple sync samples from a byte array into a track.
void	writeSamples(int track, int sampleCount, byte[] data, int off, int len, long sampleDuration, boolean isSync) Writes multiple samples from a byte array into a track.
void	writeSamples(int track, int sampleCount, byte[] data, long sampleDuration, boolean isSync) Writes multiple sync samples from a byte array into a track.

Methods inherited from class org.monte.media.quicktime.AbstractQuickTimeStream

getRelativeStreamPosition, intToType, seekRelative, typeToInt

Methods inherited from class java.lang.Object

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

Constructor Detail

QuickTimeOutputStream

public QuickTimeOutputStream(java.io.File file)
                      throws java.io.IOException

Creates a new instance.

Parameters:

file - the output file

Throws:

java.io.IOException

QuickTimeOutputStream

public QuickTimeOutputStream(javax.imageio.stream.ImageOutputStream out)
                      throws java.io.IOException

Creates a new instance.

Parameters:

out - the output stream.

Throws:

java.io.IOException

Method Detail

setMovieTimeScale

public void setMovieTimeScale(long timeScale)

Sets the time scale for this movie, that is, the number of time units that pass per second in its time coordinate system.

The default value is 600.

Parameters:

timeScale -

getMovieTimeScale

public long getMovieTimeScale()

Returns the time scale of the movie.

Returns:

time scale

See Also:

setMovieTimeScale(long)

getMediaTimeScale

public long getMediaTimeScale(int track)

Returns the time scale of the media in a track.

Parameters:

track - Track index.

Returns:

time scale

See Also:

setMovieTimeScale(long)

getMediaDuration

public long getMediaDuration(int track)

Returns the media duration of a track in the media's time scale.

Parameters:

track - Track index.

Returns:

media duration

getUneditedTrackDuration

public long getUneditedTrackDuration(int track)

Returns the track duration in the movie's time scale without taking the edit list into account.

The returned value is the media duration of the track in the movies's time scale.

Parameters:

track - Track index.

Returns:

unedited track duration

getTrackDuration

public long getTrackDuration(int track)

Returns the track duration in the movie's time scale.

If the track has an edit-list, the track duration is the sum of all edit durations.

If the track does not have an edit-list, then this method returns the media duration of the track in the movie's time scale.

Parameters:

track - Track index.

Returns:

track duration

getMovieDuration

public long getMovieDuration()

Returns the total duration of the movie in the movie's time scale.

Returns:

media duration

setVideoColorTable

public void setVideoColorTable(int track,
                               java.awt.image.IndexColorModel icm)

Sets the color table for videos with indexed color models.

Parameters:

track - The track number.

icm - IndexColorModel. Specify null to use the standard Macintosh color table.

getVideoColorTable

public java.awt.image.IndexColorModel getVideoColorTable(int track)

Gets the preferred color table for displaying the movie on devices that support only 256 colors.

Parameters:

track - The track number.

Returns:

The color table or null, if the video uses the standard Macintosh color table.

setEditList

public void setEditList(int track,
                        AbstractQuickTimeStream.Edit[] editList)

Sets the edit list for the specified track.

In the absence of an edit list, the presentation of the track starts immediately. An empty edit is used to offset the start time of a track.

Throws:

java.lang.IllegalArgumentException - If the edit list ends with an empty edit.

addVideoTrack

public int addVideoTrack(java.lang.String compressionType,
                         java.lang.String compressorName,
                         long timeScale,
                         int width,
                         int height,
                         int depth,
                         int syncInterval)
                  throws java.io.IOException

Adds a video track.

Parameters:

compressionType - The QuickTime "image compression format" 4-Character code. A list of supported 4-Character codes is given in qtff, table 3-1, page 96.

compressorName - The QuickTime compressor name. Can be up to 32 characters long.

timeScale - The media time scale between 1 and 2^32.

width - The width of a video frame.

height - The height of a video frame.

depth - The number of bits per pixel.

syncInterval - Interval for sync-samples. 0=automatic. 1=all frames are keyframes. Values larger than 1 specify that for every n-th frame is a keyframe. Apple's QuickTime will not work properly if there is not at least one keyframe every second.

Returns:

Returns the track index.

Throws:

java.lang.IllegalArgumentException - if width or height is smaller than 1, if the length of compressionType is not equal to 4, if the length of the compressorName is not between 1 and 32, if the tiimeScale is not between 1 and 2^32.

java.io.IOException

addAudioTrack

public int addAudioTrack(java.lang.String compressionType,
                         long timeScale,
                         double sampleRate,
                         int numberOfChannels,
                         int sampleSizeInBits,
                         boolean isCompressed,
                         int frameDuration,
                         int frameSize,
                         boolean signed,
                         java.nio.ByteOrder byteOrder)
                  throws java.io.IOException

Adds an audio track.

Parameters:

compressionType - The QuickTime 4-character code. A list of supported 4-Character codes is given in qtff, table 3-7, page 113.

timeScale - The media time scale between 1 and 2^32.

sampleRate - The sample rate. The integer portion must match the timeScale.

numberOfChannels - The number of channels: 1 for mono, 2 for stereo.

sampleSizeInBits - The number of bits in a sample: 8 or 16.

isCompressed - Whether the sound is compressed.

frameDuration - The frame duration, expressed in the media’s timescale, where the timescale is equal to the sample rate. For uncompressed formats, this field is always 1.

frameSize - For uncompressed audio, the number of bytes in a sample for a single channel (sampleSize divided by 8). For compressed audio, the number of bytes in a frame.

Returns:

Returns the track index.

Throws:

java.lang.IllegalArgumentException - if the audioFormat is not 4 characters long, if the time scale is not between 1 and 2^32, if the integer portion of the sampleRate is not equal to the timeScale, if numberOfChannels is not 1 or 2.

java.io.IOException

setCompressionQuality

public void setCompressionQuality(int track,
                                  float newValue)

Sets the compression quality of a 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 the encoding of video frames which are subsequently written into the track. Frames which have already been written are not changed.

This value has no effect on videos encoded with lossless encoders such as the PNG format.

The default value is 0.97.

Parameters:

newValue -

getCompressionQuality

public float getCompressionQuality(int track)

Returns the compression quality of a track.

Returns:

compression quality

setSyncInterval

public void setSyncInterval(int track,
                            int i)

Sets the sync interval for the specified video track.

Parameters:

track - The track number.

i - Interval between sync samples (keyframes). 0 = automatic. 1 = write all samples as sync samples. n = sync every n-th sample.

getSyncInterval

public int getSyncInterval(int track)

Gets the sync interval from the specified video track.

setCreationTime

public void setCreationTime(java.util.Date creationTime)

Sets the creation time of the movie.

setModificationTime

public void setModificationTime(java.util.Date modificationTime)

Sets the modification time of the movie.

setTransformationMatrix

public void setTransformationMatrix(int track,
                                    double[] matrix)

Sets the transformation matrix of the specified track.

 {a, b, u,
  c, d, v,
  tx,ty,w} // X- and Y-Translation
 
           [ a  b  u
 [x y 1] *   c  d  v   = [x' y' 1]
 

tx ty w ]

Parameters:

track - The track number.

matrix - The transformation matrix.

getTransformationMatrix

public double[] getTransformationMatrix(int track)

Gets the transformation matrix of the specified track.

Parameters:

track - The track number.

Returns:

The transformation matrix.

ensureStarted

protected void ensureStarted()
                      throws java.io.IOException

Sets the state of the QuickTimeWriter to started.

If the state is changed by this method, the prolog is written.

Throws:

java.io.IOException

writeSample

public void writeSample(int track,
                        java.io.File file,
                        long duration,
                        boolean isSync)
                 throws java.io.IOException

Writes an already encoded sample from a file into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

file - The file which holds the encoded data sample.

duration - The duration of the sample in media time scale units.

isSync - whether the sample is a sync sample (key frame).

Throws:

IndexOutofBoundsException - if the track index is out of bounds.

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

java.io.IOException - if writing the sample data failed.

writeSample

public void writeSample(int track,
                        java.io.InputStream in,
                        long duration,
                        boolean isSync)
                 throws java.io.IOException

Writes an already encoded sample from an input stream into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

in - The input stream which holds the encoded sample data.

duration - The duration of the video frame in media time scale units.

isSync - Whether the sample is a sync sample (keyframe).

Throws:

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

java.io.IOException - if writing the sample data failed.

writeSample

public void writeSample(int track,
                        byte[] data,
                        long duration,
                        boolean isSync)
                 throws java.io.IOException

Writes an already encoded sample from a byte array into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

data - The encoded sample data.

duration - The duration of the sample in media time scale units.

isSync - Whether the sample is a sync sample.

Throws:

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

java.io.IOException - if writing the sample data failed.

writeSample

public void writeSample(int track,
                        byte[] data,
                        int off,
                        int len,
                        long duration,
                        boolean isSync)
                 throws java.io.IOException

Writes an already encoded sample from a byte array into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

data - The encoded sample data.

off - The start offset in the data.

len - The number of bytes to write.

duration - The duration of the sample in media time scale units.

isSync - Whether the sample is a sync sample (keyframe).

Throws:

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

java.io.IOException - if writing the sample data failed.

writeSamples

public void writeSamples(int track,
                         int sampleCount,
                         byte[] data,
                         long sampleDuration,
                         boolean isSync)
                  throws java.io.IOException

Writes multiple sync samples from a byte array into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

sampleCount - The number of samples.

data - The encoded sample data. The length of data must be dividable by sampleCount.

sampleDuration - The duration of a sample. All samples must have the same duration.

Throws:

java.lang.IllegalArgumentException - if sampleDuration is less than 1 or if the length of data is not dividable by sampleCount.

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

writeSamples

public void writeSamples(int track,
                         int sampleCount,
                         byte[] data,
                         int off,
                         int len,
                         long sampleDuration)
                  throws java.io.IOException

Writes multiple sync samples from a byte array into a track.

This method does not inspect the contents of the samples. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

sampleCount - The number of samples.

data - The encoded sample data.

off - The start offset in the data.

len - The number of bytes to write. Must be dividable by sampleCount.

sampleDuration - The duration of a sample. All samples must have the same duration.

Throws:

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

java.io.IOException - if writing the sample data failed.

writeSamples

public void writeSamples(int track,
                         int sampleCount,
                         byte[] data,
                         int off,
                         int len,
                         long sampleDuration,
                         boolean isSync)
                  throws java.io.IOException

Writes multiple samples from a byte array into a track.

This method does not inspect the contents of the data. The contents has to match the format and dimensions of the media in this track.

Parameters:

track - The track index.

sampleCount - The number of samples.

data - The encoded sample data.

off - The start offset in the data.

len - The number of bytes to write. Must be dividable by sampleCount.

sampleDuration - The duration of a sample. All samples must have the same duration.

isSync - Whether the samples are sync samples. All samples must either be sync samples or non-sync samples.

Throws:

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

java.io.IOException - if writing the sample data failed.

isDataLimitReached

public boolean isDataLimitReached()

Returns true if the limit for media samples has been reached. If this limit is reached, no more samples should be added to the movie.

QuickTime files can be up to 64 TB long, but there are other values that may overflow before this size is reached. This method returns true when the files size exceeds 2^60 or when the media duration value of a track exceeds 2^61.

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 QuickTime 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

ensureOpen

protected void ensureOpen()
                   throws java.io.IOException

Check to make sure that this stream has not been closed

Throws:

java.io.IOException

toWebOptimizedMovie

public void toWebOptimizedMovie(java.io.File outputFile,
                                boolean compressHeader)
                         throws java.io.IOException

Writes a version of the movie which is optimized for the web into the specified output file.

This method finishes the movie and then copies its content into the specified file. The web-optimized file starts with the movie header.

Parameters:

outputFile - The output file

compressHeader - Whether the movie header shall be compressed.

Throws:

java.io.IOException