com.xuggle.xuggler
Class IContainer

Package class diagram package IContainer
java.lang.Object
  extended by com.xuggle.ferry.RefCounted
      extended by com.xuggle.xuggler.IContainer
All Implemented Interfaces:
IConfigurable

public class IContainer
extends RefCounted
implements IConfigurable

A file (or network data source) that contains one or more IStream objects of audio and video data.

Typical usage for reading looks like this:

  
 IContainer container = IContainer.make();  
 if (container.open("myfile.flv", IContainer.Type.READ, null) <0) 
  
   throw new RuntimeException("failed to open");  
 int numStreams = container.getNumStreams();  
 for(i = 0; i < numStreams; i++) {  
   IStream stream = container.getStream(i);  
   ...query IStream for stream information...  
 }  
 IPacket packet = IPacket.make();  
 while(container.readNextPacket(packet) >= 0)  
 {  
   ... Do something with the packet...  
 }  
 container.close();  
 

Typical usage for writing looks like this (makes an FLV file with one audio track encoded as mp3 data):

  
 IContainer container = IContainer.make();  
 if (container.open("myfile.flv", IContainer.Type.WRITE, null) <0) 
  
   throw new RuntimeException("failed to open");  
 IStream stream = container.addNewStream(0);  
 IStreamCoder coder = stream.getStreamCoder();  
 coder.setCodec(ICodec.ID.CODEC_ID_MP3);  
 coder.setSampleRate(22050);  
 coder.setChannels(2);  
 coder.setBitRate(64000);  
 if (coder.open()<0) throw new RuntimeException("could not open coder"); 
  
 if (container.writeHeader() < 0) throw new RuntimeException();  
 IPacket packet = IPacket.make();  
 while( ... have more data to process ... ) {  
  
   then assuming it generated an IPacket for you...  
   if (container.writePacket(packet)<0)  
     throw new RuntimeException("could not write 
 packet");  
 }  
 if (container.writeTrailer() <0) throw new RuntimeException();  
 container.close();  
 


Nested Class Summary
static class IContainer.Flags
           
static class IContainer.Type
           
 
Field Summary
static int SEEK_FLAG_ANY
          Flag; Seek to any frame, even non-keyframes
static int SEEK_FLAG_BACKWARDS
          Flag; Seek backwards
static int SEEK_FLAG_BYTE
          Flag; Use bytes instead of time stamps for seeking
static int SEEK_FLAG_FRAME
          Flag; Seek based on frame number instead of time stamps
 
Fields inherited from class com.xuggle.ferry.RefCounted
swigCMemOwn
 
Constructor Summary
protected IContainer(long cPtr, boolean cMemoryOwn)
          Internal Only.
protected IContainer(long cPtr, boolean cMemoryOwn, AtomicLong ref)
          Internal Only.
 
Method Summary
 IStream addNewStream(int id)
          Creates a new stream in this container and returns it.
 boolean canStreamsBeAddedDynamically()
          Can streams be added dynamically to this container?
 int close()
          Close the container.
 IContainer copyReference()
          Create a new IContainer object that is actually referring to the exact same underlying native object.
 String createSDPData()
          Gets the SDP data as a Java string.
 int createSDPData(IBuffer buffer)
          Fills the given buffer with a null-terminated ASCII set of bytes representing SDP data that is suitable for use with an RTSP-based system.
 boolean equals(Object obj)
          Compares two values, returning true if the underlying objects in native code are the same object.
 int flushPackets()
          Flush all packets to output.
 int getBitRate()
          Get the calculated overall bit rate of this file.
 IContainerFormat getContainerFormat()
          Returns the IContainerFormat object being used for this IContainer, or null if the IContainer doesn't yet know.
static long getCPtr(IContainer obj)
          Internal Only.
 long getDuration()
          Gets the duration, if known, of this container.
 long getFileSize()
          Get the file size in bytes of this container.
 boolean getFlag(IContainer.Flags flag)
          Get the setting for the specified flag
 int getFlags()
          Get the flags associated with this object.
 long getInputBufferLength()
          Return the input buffer length.
 int getMaxDelay()
          Gets the AVFormatContext.max_delay property if possible.
 IMetaData getMetaData()
          Get the IMetaData for this object, or null if none.
 long getMyCPtr()
          Internal Only.
 int getNumProperties()
          Returns the total number of settable properties on this object
 int getNumStreams()
          The number of streams in this container.
 IContainerParameters getParameters()
          Get the parameters that will be used when opening.
 int getPreload()
          The amount container will attemtp to preload.
 boolean getPropertyAsBoolean(String name)
          Gets the value of this property, and returns as a boolean
 double getPropertyAsDouble(String name)
          Gets the value of this property, and returns as a double;
 long getPropertyAsLong(String name)
          Gets the value of this property, and returns as an long;
 IRational getPropertyAsRational(String name)
          Gets the value of this property, and returns as an IRational;
 String getPropertyAsString(String name)
          Gets a property on this Object.
 IProperty getPropertyMetaData(int propertyNo)
          Returns the name of the numbered property.
 IProperty getPropertyMetaData(String name)
          Returns the name of the numbered property.
 Collection<String> getPropertyNames()
          Gets a collection of all properties settable on this object.
 int getReadRetryCount()
          Get the number of times readNextPacket(IPacket) will retry a read if it gets a IError.Type.ERROR_AGAIN value back.
 long getStartTime()
          Get the starting timestamp in microseconds of the first packet of the earliest stream in this container.
 IStream getStream(long streamIndex)
          Get the stream at the given position.
 IContainer.Type getType()
          Find out the type of this container.
 String getURL()
          Get the URL the IContainer was opened with.
 int hashCode()
          Get a hashable value for this object.
 boolean isHeaderWritten()
          Has a header been successfully written?
 boolean isOpened()
          Is this container opened?
static IContainer make()
          Create a new container object.
 int open(ByteChannel channel, IContainer.Type type, IContainerFormat format)
          Open this container and make it ready for reading or writing.
 int open(ByteChannel channel, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading or writing.
 int open(DataInput input, IContainerFormat format)
          Open this container and make it ready for reading.
 int open(DataInput input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading.
 int open(DataInputStream input, IContainerFormat format)
          Open this container and make it ready for reading.
 int open(DataInputStream input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading.
 int open(DataOutput output, IContainerFormat format)
          Open this container and make it ready for writing.
 int open(DataOutput output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for writing.
 int open(DataOutputStream output, IContainerFormat format)
          Open this container and make it ready for writing.
 int open(DataOutputStream output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for writing.
 int open(InputStream input, IContainerFormat format)
          Open this container and make it ready for reading.
 int open(InputStream input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading.
 int open(IURLProtocolHandler handler, IContainer.Type type, IContainerFormat format)
          Open this container and make it ready for reading or writing.
 int open(IURLProtocolHandler handler, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading or writing, optionally reading as far into the container as necessary to find all streams.
 int open(OutputStream output, IContainerFormat format)
          Open this container and make it ready for writing.
 int open(OutputStream output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for writing.
 int open(RandomAccessFile file, IContainer.Type type, IContainerFormat format)
          Open this container and make it ready for reading or writing.
 int open(RandomAccessFile file, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading or writing.
 int open(ReadableByteChannel input, IContainerFormat format)
          Open this container and make it ready for reading.
 int open(ReadableByteChannel input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for reading.
 int open(String url, IContainer.Type type, IContainerFormat pContainerFormat)
          Open this container and make it ready for reading or writing.
 int open(String url, IContainer.Type type, IContainerFormat pContainerFormat, boolean aStreamsCanBeAddedDynamically, boolean aQueryStreamMetaData)
          Open this container and make it ready for reading or writing, optionally reading as far into the container as necessary to find all streams.
 int open(WritableByteChannel output, IContainerFormat format)
          Open this container and make it ready for writing.
 int open(WritableByteChannel output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
          Open this container and make it ready for writing.
 int queryStreamMetaData()
          Attempts to read all the meta data in this stream, potentially by reading ahead and decoding packets.
 int readNextPacket(IPacket packet)
          Reads the next packet into the IPacket.
 int seekKeyFrame(int streamIndex, long timestamp, int flags)
          Seeks to the key frame at (or the first one after) the given timestamp.
 int seekKeyFrame(int streamIndex, long minTimeStamp, long targetTimeStamp, long maxTimeStamp, int flags)
          EXPERIMENTAL - Seeks to timestamp in the container.
 void setFlag(IContainer.Flags flag, boolean value)
          Set the flag.
 void setFlags(int newFlags)
          Set the flags to use with this object.
 int setForcedAudioCodec(ICodec.ID id)
          Forces the IContainer to assume all audio streams are encoded with the given audio codec when demuxing.
 int setForcedSubtitleCodec(ICodec.ID id)
          Forces the IContainer to assume all subtitle streams are encoded with the given subtitle codec when demuxing.
 int setForcedVideoCodec(ICodec.ID id)
          Forces the IContainer to assume all video streams are encoded with the given video codec when demuxing.
 int setInputBufferLength(long size)
          Set the buffer length Xuggler will suggest to FFMPEG for reading inputs.
 int setMaxDelay(int maxdelay)
          Sets the max delay for the AVFormatContext.max_delay property.
 void setMetaData(IMetaData data)
          Set the IMetaData on this object, overriding any previous meta data.
 void setParameters(IContainerParameters parameters)
          Set the parameters for this container.
 int setPreload(int preload)
          If the container has not already been opened, sets the AVFormatContext.preload property which can be useful in some circumstances such as when dealing with mpeg formats.
 int setProperty(String name, boolean value)
          Looks up the property 'name' and sets the value of the property to 'value'.
 int setProperty(String name, double value)
          Looks up the property 'name' and sets the value of the property to 'value'.
 int setProperty(String name, IRational value)
          Looks up the property 'name' and sets the value of the property to 'value'.
 int setProperty(String name, long value)
          Looks up the property 'name' and sets the value of the property to 'value'.
 int setProperty(String name, String value)
          Sets a property on this Object.
 void setReadRetryCount(int count)
          Sets the read retry count.
 String toString()
          info about this container.
 int writeHeader()
          Adds a header, if needed, for this container.
 int writePacket(IPacket packet)
          Writes the contents of the packet to the container, but make sure the packets are interleaved.
 int writePacket(IPacket packet, boolean forceInterleave)
          Writes the contents of the packet to the container.
 int writeTrailer()
          Adds a trailer, if needed, for this container.
 
Methods inherited from class com.xuggle.ferry.RefCounted
acquire, delete, getCPtr, getCurrentRefCount, getJavaRefCount, release
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SEEK_FLAG_BACKWARDS

public static final int SEEK_FLAG_BACKWARDS
Flag; Seek backwards


SEEK_FLAG_BYTE

public static final int SEEK_FLAG_BYTE
Flag; Use bytes instead of time stamps for seeking


SEEK_FLAG_ANY

public static final int SEEK_FLAG_ANY
Flag; Seek to any frame, even non-keyframes


SEEK_FLAG_FRAME

public static final int SEEK_FLAG_FRAME
Flag; Seek based on frame number instead of time stamps

Constructor Detail

IContainer

protected IContainer(long cPtr,
                     boolean cMemoryOwn)
Internal Only.


IContainer

protected IContainer(long cPtr,
                     boolean cMemoryOwn,
                     AtomicLong ref)
Internal Only.

Method Detail

getCPtr

public static long getCPtr(IContainer obj)
Internal Only. Not part of public API. Get the raw value of the native object that obj is proxying for.

Parameters:
obj - The java proxy object for a native object.
Returns:
The raw pointer obj is proxying for.

getMyCPtr

public long getMyCPtr()
Internal Only. Not part of public API. Get the raw value of the native object that we're proxying for.

Overrides:
getMyCPtr in class RefCounted
Returns:
The raw pointer we're proxying for.

copyReference

public IContainer copyReference()
Create a new IContainer object that is actually referring to the exact same underlying native object.

Overrides:
copyReference in class RefCounted
Returns:
the new Java object.

equals

public boolean equals(Object obj)
Compares two values, returning true if the underlying objects in native code are the same object. That means you can have two different Java objects, but when you do a comparison, you'll find out they are the EXACT same object.

Overrides:
equals in class Object
Returns:
True if the underlying native object is the same. False otherwise.

hashCode

public int hashCode()
Get a hashable value for this object.

Overrides:
hashCode in class Object
Returns:
the hashable value.

toString

public String toString()
info about this container. We only print information that can be determined without reading data from the container.

Overrides:
toString in class Object
Returns:
a string representation of this object

open

public int open(IURLProtocolHandler handler,
                IContainer.Type type,
                IContainerFormat format)
Open this container and make it ready for reading or writing. Reading or writing ability is determined by what the IURLProtocolHandler passed in supports.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(OutputStream output,
                IContainerFormat format)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(InputStream input,
                IContainerFormat format)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(DataOutput output,
                IContainerFormat format)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(DataOutputStream output,
                IContainerFormat format)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(DataInput input,
                IContainerFormat format)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(DataInputStream input,
                IContainerFormat format)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(RandomAccessFile file,
                IContainer.Type type,
                IContainerFormat format)
Open this container and make it ready for reading or writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(WritableByteChannel output,
                IContainerFormat format)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(ReadableByteChannel input,
                IContainerFormat format)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(ByteChannel channel,
                IContainer.Type type,
                IContainerFormat format)
Open this container and make it ready for reading or writing.

See Also:
open(String, IContainer.Type, IContainerFormat)

open

public int open(IURLProtocolHandler handler,
                IContainer.Type type,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading or writing, optionally reading as far into the container as necessary to find all streams.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(OutputStream output,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(InputStream input,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(DataOutput output,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(DataOutputStream output,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(DataInput input,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(DataInputStream input,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(RandomAccessFile file,
                IContainer.Type type,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading or writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(WritableByteChannel output,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(ReadableByteChannel input,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

open

public int open(ByteChannel channel,
                IContainer.Type type,
                IContainerFormat format,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData)
Open this container and make it ready for reading or writing.

See Also:
open(String, IContainer.Type, IContainerFormat, boolean, boolean)

createSDPData

public String createSDPData()
Gets the SDP data as a Java string.

This method only supports SDP files up to 4K in size. If you have a larger SDP file, use the createSDPData(com.xuggle.ferry.IBuffer) method and pass in your own IBuffer object.

Returns:
A String representing the data.
See Also:
createSDPData(IBuffer)

getPropertyNames

public Collection<String> getPropertyNames()
Gets a collection of all properties settable on this object. You can then query current settings with IConfigurable.getPropertyAsString(String) and set properties with IConfigurable.setProperty(String, String).

Specified by:
getPropertyNames in interface IConfigurable
Returns:
a collection of all properties for this object.

setInputBufferLength

public int setInputBufferLength(long size)
Set the buffer length Xuggler will suggest to FFMPEG for reading inputs. If called when a IContainer is open, the call is ignored and -1 is returned.

Parameters:
size - The suggested buffer size.
Returns:
size on success; <0 on error.

getInputBufferLength

public long getInputBufferLength()
Return the input buffer length.

Returns:
The input buffer length Xuggler's told FFMPEG to assume. 0 means FFMPEG should choose it's own size (and it'll probably be 32768).

isOpened

public boolean isOpened()
Is this container opened?

Returns:
true if opened; false if not.

isHeaderWritten

public boolean isHeaderWritten()
Has a header been successfully written?

Returns:
true if yes, false if no.

open

public int open(String url,
                IContainer.Type type,
                IContainerFormat pContainerFormat)
Open this container and make it ready for reading or writing.

The caller must call close() when done, but if not, the IContainer will eventually close them later but warn to the logging system.

This just forwards to open(String, Type, IContainerFormat, boolean, boolean) passing false for aStreamsCanBeAddedDynamically, and true for aLookForAllStreams.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Parameters:
url - The resource to open; The format of this string is any url that FFMPEG supports (including additional protocols if added through the xuggler.io library).
type - The type of this container.
pContainerFormat - A pointer to a ContainerFormat object specifying the format of this container, or 0 (NULL) if you want us to guess.
Returns:
>= 0 on success; < 0 on error.

open

public int open(String url,
                IContainer.Type type,
                IContainerFormat pContainerFormat,
                boolean aStreamsCanBeAddedDynamically,
                boolean aQueryStreamMetaData)
Open this container and make it ready for reading or writing, optionally reading as far into the container as necessary to find all streams.

The caller must call close() when done, but if not, the IContainer will eventually close them later but warn to the logging system.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Parameters:
url - The resource to open; The format of this string is any url that FFMPEG supports (including additional protocols if added through the xuggler.io library).
type - The type of this container.
pContainerFormat - A pointer to a ContainerFormat object specifying the format of this container, or 0 (NULL) if you want us to guess.
aStreamsCanBeAddedDynamically - If true, open() will expect that new streams can be added at any time, even after the format header has been read.
aQueryStreamMetaData - If true, open() will call queryStreamMetaData() on this container, which will potentially block until it has ready enough data to find all streams in a container. If false, it will only block to read a minimal header for this container format.
Returns:
>= 0 on success; < 0 on error.

getContainerFormat

public IContainerFormat getContainerFormat()
Returns the IContainerFormat object being used for this IContainer, or null if the IContainer doesn't yet know.

Returns:
the IContainerFormat object, or null.

close

public int close()
Close the container. open() must have been called first, or else an error is returned.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

If this method exits because of an interruption, all resources will be closed anyway.

Returns:
>= 0 on success; < 0 on error.

getType

public IContainer.Type getType()
Find out the type of this container.

Returns:
The Type of this container. IContainer.Type.READ if not yet opened.

getNumStreams

public int getNumStreams()
The number of streams in this container.

If opened in IContainer.Type.READ mode, this will query the stream and find out how many streams are in it.

If opened in IContainer.Type.WRITE mode, this will return the number of streams the caller has added to date.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Returns:
The number of streams in this container.

getStream

public IStream getStream(long streamIndex)
Get the stream at the given position.

Parameters:
streamIndex - the index of this stream in the container
Returns:
The stream at that position in the container, or null if none there.

addNewStream

public IStream addNewStream(int id)
Creates a new stream in this container and returns it.

Parameters:
id - A format-dependent id for this stream.
Returns:
A new stream.

writeHeader

public int writeHeader()
Adds a header, if needed, for this container.

Call this AFTER you've added all streams you want to add, opened all IStreamCoders for those streams (with proper configuration) and before you write the first frame. If you attempt to write a header but haven't opened all codecs, this method will log a warning, and your output file will likely be corrupt.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Returns:
0 if successful. < 0 if not. Always -1 if this is a READ container.

writeTrailer

public int writeTrailer()
Adds a trailer, if needed, for this container. Call this AFTER you've written all data you're going to write to this container but BEFORE you call IStreamCoder.close() on your IStreamCoder objects.

You must call writeHeader() before you call this (and if you don't, the IContainer will warn loudly and not actually write the trailer).

If you have closed any of the IStreamCoder objects that were open when you called writeHeader(), then this method will fail.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Returns:
0 if successful. < 0 if not. Always <0 if this is a READ container.

readNextPacket

public int readNextPacket(IPacket packet)
Reads the next packet into the IPacket. This method will release any buffers currently held by this packet and allocate new ones.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Parameters:
packet - [In/Out] The packet the IContainer will read into.
Returns:
0 if successful, or <0 if not.

writePacket

public int writePacket(IPacket packet,
                       boolean forceInterleave)
Writes the contents of the packet to the container.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Parameters:
packet - [In] The packet to write out.
forceInterleave - [In] If true, then this IContainer will make sure all packets are interleaved by DTS (even across streams in a container). If false, the IContainer won't, and it's up to the caller to interleave if necessary.
Returns:
# of bytes written if successful, or <0 if not.

writePacket

public int writePacket(IPacket packet)
Writes the contents of the packet to the container, but make sure the packets are interleaved.

This means the IContainer may have to queue up packets from one stream while waiting for packets from another.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Parameters:
packet - [In] The packet to write out.
Returns:
# of bytes written if successful, or <0 if not.

make

public static IContainer make()
Create a new container object.

Returns:
a new container, or null on error.

queryStreamMetaData

public int queryStreamMetaData()
Attempts to read all the meta data in this stream, potentially by reading ahead and decoding packets.

Any packets this method reads ahead will be cached and correctly returned when you read packets, but this method can be non-blocking potentially until end of container to get all meta data. Take care when you call it.

After this method is called, other meta data methods like getDuration() should work.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Returns:
>= 0 on success; <0 on failure.

seekKeyFrame

public int seekKeyFrame(int streamIndex,
                        long timestamp,
                        int flags)
Seeks to the key frame at (or the first one after) the given timestamp. This method will always fail for any IContainer that is not seekable (e.g. is streamed). When successful the next call to readNextPacket(IPacket) will get the next keyframe from the sought for stream.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

WARNING:: This method will be deprecated in a future Xuggler release and replaced with the new API seekKeyFrame(int, long, long, long, int).

Parameters:
streamIndex - The stream to search for the keyframe in; must be a stream the IContainer has either queried meta-data about or already ready a packet for.
timestamp - The timestamp, in the timebase of the stream you're looking in (not necessarily Microseconds).
flags - Flags to pass to com.xuggle.xuggler.io.IURLProtocolHandler's seek method.
Returns:
>= 0 on success; <0 on failure.

getDuration

public long getDuration()
Gets the duration, if known, of this container. This will only work for non-streamable containers where IContainer can calculate the container size.

Returns:
The duration, or Global.NO_PTS if not known.

getStartTime

public long getStartTime()
Get the starting timestamp in microseconds of the first packet of the earliest stream in this container.

This will only return value values either either (a) for non-streamable (b) after IContainer has actually read the first packet from a streamable source.

Returns:
The starting timestamp in microseconds, or Global.NO_PTS if not known.

getFileSize

public long getFileSize()
Get the file size in bytes of this container. This will only return a valid value if the container is non-streamed and supports seek.

Returns:
The file size in bytes, or <0 on error.

getBitRate

public int getBitRate()
Get the calculated overall bit rate of this file.

This will only return a valid value if the container is non-streamed and supports seek.

Returns:
The overall bit rate in bytes per second, or <0 on error.

getNumProperties

public int getNumProperties()
Returns the total number of settable properties on this object

Specified by:
getNumProperties in interface IConfigurable
Returns:
total number of options (not including constant definitions)

getPropertyMetaData

public IProperty getPropertyMetaData(int propertyNo)
Returns the name of the numbered property.

Specified by:
getPropertyMetaData in interface IConfigurable
Parameters:
propertyNo - The property number in the options list.
Returns:
an IProperty value for this properties meta-data

getPropertyMetaData

public IProperty getPropertyMetaData(String name)
Returns the name of the numbered property.

Specified by:
getPropertyMetaData in interface IConfigurable
Parameters:
name - The property name.
Returns:
an IProperty value for this properties meta-data

setProperty

public int setProperty(String name,
                       String value)
Sets a property on this Object. All AVOptions supported by the underlying AVClass are supported.

Specified by:
setProperty in interface IConfigurable
Parameters:
name - The property name. For example "b" for bit-rate.
value - The value of the property.
Returns:
>= 0 if the property was successfully set; <0 on error

setProperty

public int setProperty(String name,
                       double value)
Looks up the property 'name' and sets the value of the property to 'value'.

Specified by:
setProperty in interface IConfigurable
Parameters:
name - name of option
value - Value of option
Returns:
>= 0 on success; <0 on error.

setProperty

public int setProperty(String name,
                       long value)
Looks up the property 'name' and sets the value of the property to 'value'.

Specified by:
setProperty in interface IConfigurable
Parameters:
name - name of option
value - Value of option
Returns:
>= 0 on success; <0 on error.

setProperty

public int setProperty(String name,
                       boolean value)
Looks up the property 'name' and sets the value of the property to 'value'.

Specified by:
setProperty in interface IConfigurable
Parameters:
name - name of option
value - Value of option
Returns:
>= 0 on success; <0 on error.

setProperty

public int setProperty(String name,
                       IRational value)
Looks up the property 'name' and sets the value of the property to 'value'.

Specified by:
setProperty in interface IConfigurable
Parameters:
name - name of option
value - Value of option
Returns:
>= 0 on success; <0 on error.

getPropertyAsString

public String getPropertyAsString(String name)
Gets a property on this Object.

Note for C++ callers; you must free the returned array with delete[] in order to avoid a memory leak. If you call from Java or any other language, you don't need to worry about this.

Specified by:
getPropertyAsString in interface IConfigurable
Parameters:
name - property name
Returns:
an string copy of the option value, or null if the option doesn't exist.

getPropertyAsDouble

public double getPropertyAsDouble(String name)
Gets the value of this property, and returns as a double;

Specified by:
getPropertyAsDouble in interface IConfigurable
Parameters:
name - name of option
Returns:
double value of property, or 0 on error.

getPropertyAsLong

public long getPropertyAsLong(String name)
Gets the value of this property, and returns as an long;

Specified by:
getPropertyAsLong in interface IConfigurable
Parameters:
name - name of option
Returns:
long value of property, or 0 on error.

getPropertyAsRational

public IRational getPropertyAsRational(String name)
Gets the value of this property, and returns as an IRational;

Specified by:
getPropertyAsRational in interface IConfigurable
Parameters:
name - name of option
Returns:
long value of property, or 0 on error.

getPropertyAsBoolean

public boolean getPropertyAsBoolean(String name)
Gets the value of this property, and returns as a boolean

Specified by:
getPropertyAsBoolean in interface IConfigurable
Parameters:
name - name of option
Returns:
boolean value of property, or false on error.

getFlags

public int getFlags()
Get the flags associated with this object.

Returns:
The (compacted) value of all flags set.

setFlags

public void setFlags(int newFlags)
Set the flags to use with this object. All values must be ORed (|) together.

Parameters:
newFlags - The new set flags for this codec.
See Also:
IContainer.Flags

getFlag

public boolean getFlag(IContainer.Flags flag)
Get the setting for the specified flag

Parameters:
flag - The flag you want to find the setting for
Returns:
0 for false; non-zero for true

setFlag

public void setFlag(IContainer.Flags flag,
                    boolean value)
Set the flag.

Parameters:
flag - The flag to set
value - The value to set it to (true or false)

getURL

public String getURL()
Get the URL the IContainer was opened with. May return null if unknown.

Returns:
the URL opened, or null.

flushPackets

public int flushPackets()
Flush all packets to output.

Will only work on IContainer.Type.WRITE containers.

If the current thread is interrupted while this blocking method is running the method will return with a negative value. To check if the method exited because of an interruption pass the return value to IError.make(int) and then check IError.getType() to see if it is IError.Type.ERROR_INTERRUPTED.

Returns:
>= 0 on success; <0 on error

getReadRetryCount

public int getReadRetryCount()
Get the number of times readNextPacket(IPacket) will retry a read if it gets a IError.Type.ERROR_AGAIN value back. Defaults to 1 times. <0 means it will keep retrying indefinitely.

Returns:
the read retry count

setReadRetryCount

public void setReadRetryCount(int count)
Sets the read retry count.

Parameters:
count - The read retry count. <0 means keep trying.
See Also:
getReadRetryCount()

getParameters

public IContainerParameters getParameters()
Get the parameters that will be used when opening.

Returns:
The parameters
See Also:
setParameters(IContainerParameters)

setParameters

public void setParameters(IContainerParameters parameters)
Set the parameters for this container.

Normally this is not required, but if you're opening something like a webcam, you need to specify to the IContainer parameters such as a time base, width, height, etc.

Parameters:
parameters - The parameters to set. Ignored if null.

canStreamsBeAddedDynamically

public boolean canStreamsBeAddedDynamically()
Can streams be added dynamically to this container?

Returns:
true if streams can be added dynamically

getMetaData

public IMetaData getMetaData()
Get the IMetaData for this object, or null if none.

If the IContainer or IStream object that this IMetaData came from was opened for reading, then changes via IMetaData.setValue(String, String) will have no effect on the underlying media.

If the IContainer or IStream object that this IMetaData came from was opened for writing, then changes via IMetaData.setValue(String, String) will have no effect after writeHeader() is called.

Returns:
the IMetaData.

setMetaData

public void setMetaData(IMetaData data)
Set the IMetaData on this object, overriding any previous meta data. You should call this method on writable containers and before you call writeHeader(), as it probably won't do anything after that.

See Also:
getMetaData()

createSDPData

public int createSDPData(IBuffer buffer)
Fills the given buffer with a null-terminated ASCII set of bytes representing SDP data that is suitable for use with an RTSP-based system.

This method only works if Xuggler is linking against a version of FFmpeg that supports RTSP.

Parameters:
buffer - the IBuffer object to fill with data.
Returns:
the number of bytes written, including the terminating 0 byte, or < 0 on error.

setForcedAudioCodec

public int setForcedAudioCodec(ICodec.ID id)
Forces the IContainer to assume all audio streams are encoded with the given audio codec when demuxing.

Parameters:
id - The codec id
Returns:
< 0 on error (e.g. not an audio codec); >= 0 on success.
Since:
3.3

setForcedVideoCodec

public int setForcedVideoCodec(ICodec.ID id)
Forces the IContainer to assume all video streams are encoded with the given video codec when demuxing.

Parameters:
id - The codec id
Returns:
< 0 on error (e.g. not an video codec); >= 0 on success.
Since:
3.3

setForcedSubtitleCodec

public int setForcedSubtitleCodec(ICodec.ID id)
Forces the IContainer to assume all subtitle streams are encoded with the given subtitle codec when demuxing.

Parameters:
id - The codec id
Returns:
< 0 on error (e.g. not an subtitle codec); >= 0 on success.
Since:
3.3

seekKeyFrame

public int seekKeyFrame(int streamIndex,
                        long minTimeStamp,
                        long targetTimeStamp,
                        long maxTimeStamp,
                        int flags)
EXPERIMENTAL - Seeks to timestamp in the container.

Seeking will be done so that the point from which all active streams can be presented successfully will be closest to targetTimeStamp and within minTimeStamp/maxTimeStamp.

If flags contain SEEK_FLAG_BYTE, then all time stamps are in bytes and are the file position (this may not be supported by all demuxers). If flags contain SEEK_FLAG_FRAME, then all time stamps are in frames in the stream with streamIndex (this may not be supported by all demuxers). Otherwise all time stamps are in units of the stream selected by stream_index or if stream_index is -1, in microseconds. If flags contain SEEK_FLAG_ANY, then non-keyframes are treated as keyframes (this may not be supported by all demuxers). If flags contain SEEK_FLAG_BACKWARDS, then we will attempt to search backwards in the container (this may not be supported by all demuxers and file protocols).

This is part of the new seek API which is still under construction. It may change in future Xuggler versions.

Parameters:
streamIndex - index of the stream which is used as time base reference
minTimeStamp - smallest acceptable time stamp.
targetTimeStamp - target time stamp.
maxTimeStamp - largest acceptable time stamp.
flags - A bitmask of the SEEK_FLAG_* flags, or 0 to turn all flags off.
Returns:
>=0 on success, error code otherwise
Since:
3.4

setPreload

public int setPreload(int preload)
If the container has not already been opened, sets the AVFormatContext.preload property which can be useful in some circumstances such as when dealing with mpeg formats.

Parameters:
preload - amount to preload
Returns:
>= 0 on success, error code otherwise
Since:
4.0

getPreload

public int getPreload()
The amount container will attemtp to preload.

Returns:
The amount to preload, error code otherwise.

setMaxDelay

public int setMaxDelay(int maxdelay)
Sets the max delay for the AVFormatContext.max_delay property.

Parameters:
maxdelay - maximum delay for container
Returns:
>= 0 on success, error code otherwise
Since:
4.0

getMaxDelay

public int getMaxDelay()
Gets the AVFormatContext.max_delay property if possible.

Returns:
The max delay, error code otherwise.
Since:
4.0


Copyright © 2008, 2010 Xuggle