com.xuggle.mediatool
Interface IMediaWriter

Package class diagram package IMediaWriter
All Superinterfaces:
IMediaCoder, IMediaGenerator, IMediaListener, IMediaTool

public interface IMediaWriter
extends IMediaCoder, IMediaTool

An IMediaCoder that encodes and decodes media to an IContainer, and can optionally read data for encoding from other IMediaGenerator objects.

Here's some pseudo code that shows how to encode an audio file:

 IMediaWriter writer = ToolFactory.makeWriter("output.mp3");
 int sampleRate = 22050;
 int channels = 1;
 writer.addAudioStream(0, 0, sampleRate, channels);
 
 while(haveMoreAudio())
 {
   short[] samples = getSourceSamples();
   writer.encodeAudio(0, samples);
 }
 writer.close();
 

And here's some pseudo code that shows how to encode a video image every 1 second:

 IMediaWriter writer = ToolFactory.makeWriter("output.mp4");
 writer.addVideoStream(0, 0, sampleRate, channels);
 
 long startTime = System.nanoTime(); 
 while(haveMoreVideo())
 {
   BufferedImage image = getImage();
   writer.encodeAudio(0, image,
    System.nanoTime()-startTime, TimeUnit.NANOSECONDS);
   Thread.sleep(1000);
 }
 writer.close();
 

An IMediaWriter is a simplified interface to the Xuggler library that opens up a media container, and allows media data to be written into it.

The IMediaWriter class implements IMediaListener, and so it can be attached to any IMediaGenerator that generates raw media events (e.g. IMediaReader). If will query the input pipe for all of it's streams, and create the right output streams (and mappings) in the new file.

Calls to encodeAudio(int, IAudioSamples) and encodeVideo(int, IVideoPicture) encode media into packets and write those packets to the specified container.

If you are generating video from Java BufferedImage but you don't have an IVideoPicture object handy, don't sweat. You can use encodeVideo(int, BufferedImage, long, TimeUnit) for that.

If you are generating audio from in Java short arrays (16-bit audio) but don't have an IAudioSamples object handy, don't sweat. You can use encodeAudio(int, short[], long, TimeUnit) for that.


Method Summary
 int addAudioStream(int inputIndex, int streamId, ICodec.ID codecId, int channelCount, int sampleRate)
          Add an audio stream that will later have data encoded with encodeAudio(int, IAudioSamples).
 int addAudioStream(int inputIndex, int streamId, ICodec codec, int channelCount, int sampleRate)
          Add an audio stream that will later have data encoded with encodeAudio(int, IAudioSamples).
 int addAudioStream(int inputIndex, int streamId, int channelCount, int sampleRate)
          Add an audio stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.
 int addVideoStream(int inputIndex, int streamId, ICodec.ID codecId, int width, int height)
          Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).
 int addVideoStream(int inputIndex, int streamId, ICodec.ID codecId, IRational frameRate, int width, int height)
          Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).
 int addVideoStream(int inputIndex, int streamId, ICodec codec, int width, int height)
          Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).
 int addVideoStream(int inputIndex, int streamId, ICodec codec, IRational frameRate, int width, int height)
          Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).
 int addVideoStream(int inputIndex, int streamId, int width, int height)
          Add a video stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.
 int addVideoStream(int inputIndex, int streamId, IRational frameRate, int width, int height)
          Add a video stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.
 void encodeAudio(int streamIndex, IAudioSamples samples)
          Encodes audio from samples into the stream with the specified index.
 void encodeAudio(int streamIndex, short[] samples)
          Encoded audio from samples into the stream with the specified index.
 void encodeAudio(int streamIndex, short[] samples, long timeStamp, TimeUnit timeUnit)
          Encoded audio from samples into the stream with the specified index.
 void encodeVideo(int streamIndex, BufferedImage image, long timeStamp, TimeUnit timeUnit)
          Encodes video from the given picture into the stream with the specified index.
 void encodeVideo(int streamIndex, IVideoPicture picture)
          Encodes video from the given picture into the stream with the specified index.
 void flush()
          Flushes all encoders and writes their contents.
 IPixelFormat.Type getDefaultPixelType()
          Get the default pixel type
 IAudioSamples.Format getDefaultSampleFormat()
          Get the default audio sample format
 IRational getDefaultTimebase()
          Get the default time base we'll use on our encoders if one is not specified by the codec.
 Integer getOutputStreamIndex(int inputStreamIndex)
          Map an input stream index to an output stream index.
 boolean isSupportedCodecType(ICodec.Type type)
          Test if this IMediaWriter can write streams of this type.
 void setForceInterleave(boolean forceInterleave)
          Set the force interleave option.
 void setMaskLateStreamExceptions(boolean maskLateStreamExceptions)
          Set late stream exception policy.
 boolean willForceInterleave()
          Test if the IMediaWriter will forcibly interleave media data.
 boolean willMaskLateStreamExceptions()
          Get the late stream exception policy.
 
Methods inherited from interface com.xuggle.mediatool.IMediaCoder
close, getContainer, getUrl, isOpen, open
 
Methods inherited from interface com.xuggle.mediatool.IMediaGenerator
addListener, getListeners, removeListener
 
Methods inherited from interface com.xuggle.mediatool.IMediaGenerator
addListener, getListeners, removeListener
 
Methods inherited from interface com.xuggle.mediatool.IMediaListener
onAddStream, onAudioSamples, onClose, onCloseCoder, onFlush, onOpen, onOpenCoder, onReadPacket, onVideoPicture, onWriteHeader, onWritePacket, onWriteTrailer
 

Method Detail

setMaskLateStreamExceptions

void setMaskLateStreamExceptions(boolean maskLateStreamExceptions)
Set late stream exception policy. When encodeAudio(int, IAudioSamples) or encodeVideo(int, IVideoPicture) is passed an unrecognized stream index after the the header has been written, either an exception is raised, or the media data is silently ignored. By default exceptions are raised, not masked.

Parameters:
maskLateStreamExceptions - true if late med
See Also:
willMaskLateStreamExceptions()

willMaskLateStreamExceptions

boolean willMaskLateStreamExceptions()
Get the late stream exception policy. When encodeVideo(int, IVideoPicture) or encodeAudio(int, IAudioSamples)is passed an unrecognized stream index after the the header has been written, either an exception is raised, or the media data is silently ignored. By default exceptions are raised, not masked.

Returns:
true if late stream data raises exceptions
See Also:
setMaskLateStreamExceptions(boolean)

setForceInterleave

void setForceInterleave(boolean forceInterleave)
Set the force interleave option.

If false the media data will be left in the order in which it is presented to the IMediaWriter.

If true IMediaWriter will buffer media data in time stamp order, and only write out data when it has at least one same time or later packet from all streams.

Parameters:
forceInterleave - true if the IMediaWriter should force interleaving of media data
See Also:
willForceInterleave()

willForceInterleave

boolean willForceInterleave()
Test if the IMediaWriter will forcibly interleave media data. The default value for this value is true.

Returns:
true if IMediaWriter interleaves media data.
See Also:
setForceInterleave(boolean)

isSupportedCodecType

boolean isSupportedCodecType(ICodec.Type type)
Test if this IMediaWriter can write streams of this type.

Parameters:
type - the type of codec to be tested
Returns:
true if codec type is supported type

getDefaultPixelType

IPixelFormat.Type getDefaultPixelType()
Get the default pixel type

Returns:
the default pixel type

getDefaultSampleFormat

IAudioSamples.Format getDefaultSampleFormat()
Get the default audio sample format

Returns:
the format

getDefaultTimebase

IRational getDefaultTimebase()
Get the default time base we'll use on our encoders if one is not specified by the codec.

Returns:
the default time base

addAudioStream

int addAudioStream(int inputIndex,
                   int streamId,
                   int channelCount,
                   int sampleRate)
Add an audio stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.

The time base defaults to getDefaultTimebase() and the audio format defaults to getDefaultSampleFormat().

Parameters:
inputIndex - the index that will be passed to encodeAudio(int, IAudioSamples) for this stream
streamId - a format-dependent id for this stream
channelCount - the number of audio channels for the stream
sampleRate - sample rate in Hz (samples per seconds), common values are 44100, 22050, 11025, etc.
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
IContainer, IStream, IStreamCoder, ICodec, ICodec.guessEncodingCodec(com.xuggle.xuggler.IContainerFormat, String, String, String, com.xuggle.xuggler.ICodec.Type)

addAudioStream

int addAudioStream(int inputIndex,
                   int streamId,
                   ICodec.ID codecId,
                   int channelCount,
                   int sampleRate)
Add an audio stream that will later have data encoded with encodeAudio(int, IAudioSamples).

The time base defaults to getDefaultTimebase() and the audio format defaults to getDefaultSampleFormat().

Parameters:
inputIndex - the index that will be passed to encodeAudio(int, IAudioSamples) for this stream
streamId - a format-dependent id for this stream
codecId - the codec id to used to encode data, to establish the codec see ICodec
channelCount - the number of audio channels for the stream
sampleRate - sample rate in Hz (samples per seconds), common values are 44100, 22050, 11025, etc.
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
IContainer, IStream, IStreamCoder, ICodec

addAudioStream

int addAudioStream(int inputIndex,
                   int streamId,
                   ICodec codec,
                   int channelCount,
                   int sampleRate)
Add an audio stream that will later have data encoded with encodeAudio(int, IAudioSamples).

The time base defaults to getDefaultTimebase() and the audio format defaults to getDefaultSampleFormat().

Parameters:
inputIndex - the index that will be passed to encodeAudio(int, IAudioSamples) for this stream
streamId - a format-dependent id for this stream
codec - the codec to used to encode data, to establish the codec see ICodec
channelCount - the number of audio channels for the stream
sampleRate - sample rate in Hz (samples per seconds), common values are 44100, 22050, 11025, etc.
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
See Also:
IContainer, IStream, IStreamCoder, ICodec

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   int width,
                   int height)
Add a video stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
IContainer, IStream, IStreamCoder, ICodec, ICodec.guessEncodingCodec(com.xuggle.xuggler.IContainerFormat, String, String, String, com.xuggle.xuggler.ICodec.Type)

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   ICodec.ID codecId,
                   int width,
                   int height)
Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
codecId - the codec to used to encode data, to establish the codec see ICodec
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
IContainer, IStream, IStreamCoder, ICodec

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   ICodec codec,
                   int width,
                   int height)
Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
codec - the codec to used to encode data, to establish the codec see ICodec
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
See Also:
IContainer, IStream, IStreamCoder, ICodec

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   IRational frameRate,
                   int width,
                   int height)
Add a video stream with a codec guessed based on IMediaCoder.getUrl() of this IMediaWriter.

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
frameRate - The frame rate if known or required by the output codec. See addVideoStream(int, int, com.xuggle.xuggler.ICodec.ID, IRational, int, int) .
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
addVideoStream(int, int, com.xuggle.xuggler.ICodec.ID, IRational, int, int), IContainer, IStream, IStreamCoder, ICodec, ICodec.guessEncodingCodec(com.xuggle.xuggler.IContainerFormat, String, String, String, com.xuggle.xuggler.ICodec.Type)

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   ICodec.ID codecId,
                   IRational frameRate,
                   int width,
                   int height)
Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
codecId - the codec to used to encode data, to establish the codec see ICodec
frameRate - The frame rate if known or required by the output codec. See addVideoStream(int, int, com.xuggle.xuggler.ICodec.ID, IRational, int, int) .
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
UnsupportedOperationException - if the given codec cannot be used for encoding.
See Also:
addVideoStream(int, int, com.xuggle.xuggler.ICodec.ID, IRational, int, int), IContainer, IStream, IStreamCoder, ICodec

addVideoStream

int addVideoStream(int inputIndex,
                   int streamId,
                   ICodec codec,
                   IRational frameRate,
                   int width,
                   int height)
Add a video stream that will later have data encoded with encodeVideo(int, IVideoPicture).

The time base defaults to getDefaultTimebase() and the pixel format defaults to getDefaultPixelType().

Parameters:
inputIndex - the index that will be passed to encodeVideo(int, IVideoPicture) for this stream
streamId - a format-dependent id for this stream
codec - the codec to used to encode data, to establish the codec see ICodec
frameRate - if non null, then this is the frame-rate you will encode video at. Some codecs (e.g. MPEG2 video) require this to be fixed and will effectively ignore timestamps in favor of this. If you do not specify, we'll guess the highest frame-rate that can fit in the output container, and then try to honor the actual timestamps encoded.
width - width of video frames
height - height of video frames
Returns:
<0 on failure; otherwise returns the index of the new stream added by the writer.
Throws:
IllegalArgumentException - if inputIndex < 0, the stream id < 0, the codec is NULL or if the container is already open.
IllegalArgumentException - if width or height are <= 0
See Also:
IContainer, IStream, IStreamCoder, ICodec

encodeAudio

void encodeAudio(int streamIndex,
                 IAudioSamples samples)
Encodes audio from samples into the stream with the specified index.

Callers must ensure that IMediaData.getTimeStamp(), if specified is always monotonically increasing or an error will be returned.

Parameters:
streamIndex - The stream index, as returned from addAudioStream(int, int, ICodec, int, int).
samples - A set of samples to add.

encodeAudio

void encodeAudio(int streamIndex,
                 short[] samples)
Encoded audio from samples into the stream with the specified index.

IMediaWriter will assume that these samples are to played immediately after the last set of samples, or with the earliest time stamp in the container if they are the first samples.

Parameters:
streamIndex - The stream index, as returned from addAudioStream(int, int, ICodec, int, int).
samples - A set of samples to add.

encodeAudio

void encodeAudio(int streamIndex,
                 short[] samples,
                 long timeStamp,
                 TimeUnit timeUnit)
Encoded audio from samples into the stream with the specified index.

If timeUnit is null, IMediaWriter will assume that these samples are to played immediately after the last set of samples, or with the earliest time stamp in the container if they are the first samples.

Callers must ensure that timeStamp, if timeUnit is non-null, is always monotonically increasing or an runtime exception will be raised.

Parameters:
streamIndex - The stream index, as returned from addAudioStream(int, int, ICodec, int, int).
samples - A set of samples to add.
timeStamp - The time stamp for this media.
timeUnit - The units of timeStamp, or null if you want IMediaWriter to assume these samples immediately precede any prior samples.

encodeVideo

void encodeVideo(int streamIndex,
                 IVideoPicture picture)
Encodes video from the given picture into the stream with the specified index.

Callers must ensure that IMediaData.getTimeStamp(), if specified is always monotonically increasing or an RuntimeException will be raised.

Parameters:
streamIndex - The stream index, as returned from addVideoStream(int, int, ICodec, int, int).
picture - A picture to encode

encodeVideo

void encodeVideo(int streamIndex,
                 BufferedImage image,
                 long timeStamp,
                 TimeUnit timeUnit)
Encodes video from the given picture into the stream with the specified index.

Callers must ensure that IMediaData.getTimeStamp(), if specified is always monotonically increasing or an RuntimeException will be raised.

Parameters:
streamIndex - The stream index, as returned from addVideoStream(int, int, ICodec, int, int).
image - A BufferedImage to encode
timeStamp - The time stamp for this image
timeUnit - The time unit of timeStamp. Cannot be null.

flush

void flush()
Flushes all encoders and writes their contents.

Callers should call this when they have finished encoding all audio and video to ensure that any cached data necessary for encoding was written.


getOutputStreamIndex

Integer getOutputStreamIndex(int inputStreamIndex)
Map an input stream index to an output stream index.

Parameters:
inputStreamIndex - the input stream index value
Returns:
the associated output stream index or null, if the input stream index has not been mapped to an output index.


Copyright © 2008, 2010 Xuggle