Class QuickTimeOutputStream

java.lang.Object
org.monte.media.quicktime.AbstractQuickTimeStream
org.monte.media.quicktime.QuickTimeOutputStream
public class QuickTimeOutputStream extends AbstractQuickTimeStream
This class provides low-level support for writing already encoded audio and video samples into a QuickTime file.
Author:
Werner Randelshofer

  • Constructor Details

    • QuickTimeOutputStream

      public QuickTimeOutputStream(File file) throws IOException
      Creates a new instance.
      Parameters:
      file - the output file
      Throws:
      IOException

    • QuickTimeOutputStream

      public QuickTimeOutputStream(ImageOutputStream out) throws IOException
      Creates a new instance.
      Parameters:
      out - the output stream.
      Throws:
      IOException

  • Method Details

    • 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:

    • 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:

    • 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, ColorModel 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 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:
      IllegalArgumentException - If the edit list ends with an empty edit.

    • addVideoTrack

      public int addVideoTrack(String compressionType, String compressorName, long timeScale, int width, int height, int depth, int syncInterval) throws 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:
      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.
      IOException

    • addAudioTrack

      public int addAudioTrack(String compressionType, long timeScale, double sampleRate, int numberOfChannels, int sampleSizeInBits, boolean isCompressed, int frameDuration, int frameSize, boolean signed, ByteOrder byteOrder) throws 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:
      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.
      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 - the new value

    • 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(Date creationTime)
      Sets the creation time of the movie.

    • getCreationTime

      public Date getCreationTime()
      Gets the creation time of the movie.

    • setModificationTime

      public void setModificationTime(Date modificationTime)
      Sets the modification time of the movie.

    • getModificationTime

      public Date getModificationTime()
      Gets the modification time of the movie.

    • getPreferredRate

      public double getPreferredRate()
      Gets the preferred rate at which to play this movie. A value of 1.0 indicates normal rate.

    • setPreferredRate

      public void setPreferredRate(double preferredRate)
      Sets the preferred rate at which to play this movie. A value of 1.0 indicates normal rate.

    • getPreferredVolume

      public double getPreferredVolume()
      Gets the preferred volume of this movie’s sound. A value of 1.0 indicates full volume.

    • setPreferredVolume

      public void setPreferredVolume(double preferredVolume)
      Sets the preferred volume of this movie’s sound. A value of 1.0 indicates full volume.

    • getCurrentTime

      public long getCurrentTime()
      Gets the time value for current time position within the movie.

    • setCurrentTime

      public void setCurrentTime(long currentTime)
      Sets the time value for current time position within the movie.

    • getPosterTime

      public long getPosterTime()
      Gets the time value of the time of the movie poster.

    • setPosterTime

      public void setPosterTime(long posterTime)
      Sets the time value of the time of the movie poster.

    • getPreviewDuration

      public long getPreviewDuration()
      Gets the duration of the movie preview in movie time scale units.

    • setPreviewDuration

      public void setPreviewDuration(long previewDuration)
      Gets the duration of the movie preview in movie time scale units.

    • getPreviewTime

      public long getPreviewTime()
      Gets the time value in the movie at which the preview begins.

    • setPreviewTime

      public void setPreviewTime(long previewTime)
      The time value in the movie at which the preview begins.

    • getSelectionDuration

      public long getSelectionDuration()
      The duration of the current selection in movie time scale units.

    • setSelectionDuration

      public void setSelectionDuration(long selectionDuration)
      The duration of the current selection in movie time scale units.

    • getSelectionTime

      public long getSelectionTime()
      The time value for the start time of the current selection.

    • setSelectionTime

      public void setSelectionTime(long selectionTime)
      The time value for the start time of the current selection.

    • setMovieTransformationMatrix

      public void setMovieTransformationMatrix(double[] matrix)
      Sets the transformation matrix of the entire movie. 
       {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:
      matrix - The transformation matrix.

    • getMovieTransformationMatrix

      public double[] getMovieTransformationMatrix()
      Gets the transformation matrix of the entire movie.
      Returns:
      The transformation matrix.

    • 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 IOException
      Sets the state of the QuickTimeWriter to started.

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

      Throws:
      IOException

    • writeSample

      public void writeSample(int track, File file, long duration, boolean isSync) throws 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:
      IOException - if writing the sample data failed.

    • writeSample

      public void writeSample(int track, InputStream in, long duration, boolean isSync) throws 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:
      IllegalArgumentException - if the duration is less than 1.
      IOException - if writing the sample data failed.

    • writeSample

      public void writeSample(int track, byte[] data, long duration, boolean isSync) throws 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:
      IllegalArgumentException - if the duration is less than 1.
      IOException - if writing the sample data failed.

    • writeSample

      public void writeSample(int track, byte[] data, int off, int len, long duration, boolean isSync) throws 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:
      IllegalArgumentException - if the duration is less than 1.
      IOException - if writing the sample data failed.

    • writeSamples

      public void writeSamples(int track, int sampleCount, byte[] data, long sampleDuration, boolean isSync) throws 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:
      IllegalArgumentException - if sampleDuration is less than 1 or if the length of data is not dividable by sampleCount.
      IOException - if writing the chunk failed.

    • writeSamples

      public void writeSamples(int track, int sampleCount, byte[] data, int off, int len, long sampleDuration) throws 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:
      IllegalArgumentException - if the duration is less than 1.
      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 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:
      IllegalArgumentException - if the duration is less than 1.
      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 IOException
      Closes the movie file as well as the stream being filtered.
      Throws:
      IOException - if an I/O error has occurred

    • finish

      public void finish() throws 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:
      IllegalStateException - if the dimension of the video track has not been specified or determined yet.
      IOException - if an I/O exception has occurred

    • ensureOpen

      protected void ensureOpen() throws IOException
      Check to make sure that this stream has not been closed
      Throws:
      IOException

    • writeTrackAtoms

      protected void writeTrackAtoms(int trackIndex, AbstractQuickTimeStream.CompositeAtom moovAtom, Date modificationTime) throws IOException
      Throws:
      IOException

    • writeMediaInformationAtoms

      protected void writeMediaInformationAtoms(int trackIndex, AbstractQuickTimeStream.CompositeAtom mdiaAtom) throws IOException
      Throws:
      IOException

    • writeVideoMediaInformationHeaderAtom

      protected void writeVideoMediaInformationHeaderAtom(int trackIndex, AbstractQuickTimeStream.CompositeAtom minfAtom) throws IOException
      Throws:
      IOException

    • writeSoundMediaInformationHeaderAtom

      protected void writeSoundMediaInformationHeaderAtom(int trackIndex, AbstractQuickTimeStream.CompositeAtom minfAtom) throws IOException
      Throws:
      IOException

    • writeSampleTableAtoms

      protected void writeSampleTableAtoms(int trackIndex, AbstractQuickTimeStream.CompositeAtom minfAtom) throws IOException
      Throws:
      IOException

    • toWebOptimizedMovie

      public void toWebOptimizedMovie(File outputFile, boolean compressHeader) throws 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:
      IOException