com.xuggle.xuggler
Class IStream

Package class diagram package IStream
java.lang.Object
  extended by com.xuggle.ferry.RefCounted
      extended by com.xuggle.xuggler.IStream

public class IStream
extends RefCounted

Represents a stream of similar data (eg video) in a IContainer.

Streams are really virtual concepts; IContainers really just contain a bunch of IPackets. But each IPacket usually has a stream id associated with it, and all IPackets with that stream id represent the same type of (usually time-based) data. For example in many FLV video files, there is a stream with id "0" that contains all video data, and a stream with id "1" that contains all audio data.

You use an IStream object to get properly configured IStreamCoder for decoding, and to tell IStreamCoders how to encode IPackets when decoding.


Nested Class Summary
static class IStream.Direction
           
static class IStream.ParseType
           
 
Field Summary
 
Fields inherited from class com.xuggle.ferry.RefCounted
swigCMemOwn
 
Constructor Summary
protected IStream(long cPtr, boolean cMemoryOwn)
          Internal Only.
protected IStream(long cPtr, boolean cMemoryOwn, AtomicLong ref)
          Internal Only.
 
Method Summary
 int addIndexEntry(IIndexEntry entry)
          Adds an index entry into the stream's sorted index list.
 IStream copyReference()
          Create a new IStream object that is actually referring to the exact same underlying native object.
 boolean equals(Object obj)
          Compares two values, returning true if the underlying objects in native code are the same object.
 IIndexEntry findTimeStampEntryInIndex(long wantedTimeStamp, int flags)
          Search for the given time stamp in the key-frame index for this IStream.
 int findTimeStampPositionInIndex(long wantedTimeStamp, int flags)
          Search for the given time stamp in the key-frame index for this IStream.
 IContainer getContainer()
          Get the underlying container for this stream, or null if Xuggler doesn't know.
static long getCPtr(IStream obj)
          Internal Only.
 long getCurrentDts()
          The current Decompression Time Stamp that will be used on this stream, in getTimeBase() units.
 IStream.Direction getDirection()
          Get the IStream.Direction this stream is pointing in.
 long getDuration()
          Return the duration, in getTimeBase() units, of this stream, or Global.NO_PTS if unknown.
 IRational getFrameRate()
          Get the (sometimes estimated) frame rate of this container.
 int getId()
          Return a container format specific id for this stream.
 int getIndex()
          Get the relative position this stream has in the hosting IContainer object.
 List<IIndexEntry> getIndexEntries()
          Get an ordered sequence of index entries in this IStream.
 IIndexEntry getIndexEntry(int position)
          Get the IIndexEntry at the given position in this IStream object's index.
 String getLanguage()
          Get the 4-character language setting for this stream.
 IMetaData getMetaData()
          Get the IMetaData for this object, or null if none.
 long getMyCPtr()
          Internal Only.
 long getNumFrames()
          Returns the number of encoded frames if known.
 int getNumIndexEntries()
          Get the number of index entries in this stream.
 IStream.ParseType getParseType()
          Get how the decoding codec should parse data from this stream.
 IRational getSampleAspectRatio()
          Gets the sample aspect ratio.
 long getStartTime()
          Return the start time, in getTimeBase() units, when this stream started.
 IStreamCoder getStreamCoder()
          Get the StreamCoder than can manipulate this stream.
 IRational getTimeBase()
          The time base in which all timestamps (e.g.
 int hashCode()
          Get a hashable value for this object.
 void setLanguage(String language)
          Set the 4-character language setting for this stream.
 void setMetaData(IMetaData data)
          Set the IMetaData on this object, overriding any previous meta data.
 void setParseType(IStream.ParseType type)
          Set the parse type the decoding codec should use.
 void setSampleAspectRatio(IRational newRatio)
          Sets the sample aspect ratio.
 int setStreamCoder(IStreamCoder newCoder)
          Sets the stream coder to use for this stream.
 int setStreamCoder(IStreamCoder newCoder, boolean assumeOnlyStream)
          Sets the stream coder to use for this stream.
 int stampOutputPacket(IPacket packet)
          Takes a packet destined for this stream, and stamps the stream index, and converts the time stamp to the correct units (adjusting for rounding errors between stream conversions).
 String toString()
          info about this stream
 
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
 

Constructor Detail

IStream

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


IStream

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

Method Detail

getCPtr

public static long getCPtr(IStream 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 IStream copyReference()
Create a new IStream 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 stream

Overrides:
toString in class Object
Returns:
information about this stream

getIndexEntries

public List<IIndexEntry> getIndexEntries()
Get an ordered sequence of index entries in this IStream.

Returns:
A list of entries. Will always return a non-null list, but if there are no entries the list size will be zero.

getDirection

public IStream.Direction getDirection()
Get the IStream.Direction this stream is pointing in.

Returns:
The direction of this stream.

getIndex

public int getIndex()
Get the relative position this stream has in the hosting IContainer object.

Returns:
The Index within the Container of this stream.

getId

public int getId()
Return a container format specific id for this stream.

Returns:
The (container format specific) id of this stream.

getStreamCoder

public IStreamCoder getStreamCoder()
Get the StreamCoder than can manipulate this stream. If the stream is an INBOUND stream, then the StreamCoder can do a IStreamCoder::DECODE. IF this stream is an OUTBOUND stream, then the StreamCoder can do all IStreamCoder::ENCODE methods.

Returns:
The StreamCoder assigned to this object.

getFrameRate

public IRational getFrameRate()
Get the (sometimes estimated) frame rate of this container. an approimation. Better to use getTimeBase(). For contant frame-rate containers, this will be 1 ( getTimeBase() )

Returns:
The frame-rate of this container.

getTimeBase

public IRational getTimeBase()
The time base in which all timestamps (e.g. Presentation Time Stamp (PTS) and Decompression Time Stamp (DTS)) are represented. For example if the time base is 1/1000, then the difference between a PTS of 1 and a PTS of 2 is 1 millisecond. If the timebase is 1/1, then the difference between a PTS of 1 and a PTS of 2 is 1 second.

Returns:
The time base of this stream.

getStartTime

public long getStartTime()
Return the start time, in getTimeBase() units, when this stream started.

Returns:
The start time.

getDuration

public long getDuration()
Return the duration, in getTimeBase() units, of this stream, or Global.NO_PTS if unknown.

Returns:
The duration (in getTimeBase units) of this stream, if known.

getCurrentDts

public long getCurrentDts()
The current Decompression Time Stamp that will be used on this stream, in getTimeBase() units.

Returns:
The current Decompression Time Stamp that will be used on this stream.

getNumIndexEntries

public int getNumIndexEntries()
Get the number of index entries in this stream.

Returns:
The number of index entries in this stream.
See Also:
getIndexEntry(int)

getNumFrames

public long getNumFrames()
Returns the number of encoded frames if known. Note that frames here means encoded frames, which can consist of many encoded audio samples, or an encoded video frame.

Returns:
The number of frames (encoded) in this stream.

getSampleAspectRatio

public IRational getSampleAspectRatio()
Gets the sample aspect ratio.

Returns:
The sample aspect ratio.

setSampleAspectRatio

public void setSampleAspectRatio(IRational newRatio)
Sets the sample aspect ratio.

Parameters:
newRatio - The new ratio.

getLanguage

public String getLanguage()
Get the 4-character language setting for this stream. This will return null if no setting. When calling from C++, callers must ensure that the IStream outlives the value returned.


setLanguage

public void setLanguage(String language)
Set the 4-character language setting for this stream. If a string longer than 4 characters is passed in, only the first 4 characters is copied.

Parameters:
language - The new language setting. null is equivalent to the empty string. strings longer than 4 characters will be truncated to first 4 characters.

getContainer

public IContainer getContainer()
Get the underlying container for this stream, or null if Xuggler doesn't know.

Returns:
the container, or null if we don't know.

setStreamCoder

public int setStreamCoder(IStreamCoder newCoder)
Sets the stream coder to use for this stream. This method will only cause a change if the IStreamCoder currently set on this IStream is not open. Otherwise the call is ignore and an error is returned.

Parameters:
newCoder - The new stream coder to use.
Returns:
>= 0 on success; < 0 on error.

getParseType

public IStream.ParseType getParseType()
Get how the decoding codec should parse data from this stream.

Returns:
the parse type.
Since:
3.0

setParseType

public void setParseType(IStream.ParseType type)
Set the parse type the decoding codec should use. Set to IStream.ParseType.PARSE_NONE if you don't want any parsing to be done.

Warning: do not set this flag unless you know what you're doing, and do not set after you've started decoding.

Parameters:
type - The type to set.
Since:
3.0

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 IContainer.writeHeader() is called.

Returns:
the IMetaData.
Since:
3.1

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 IContainer.writeHeader(), as it probably won't do anything after that.

Since:
3.1
See Also:
getMetaData()

stampOutputPacket

public int stampOutputPacket(IPacket packet)
Takes a packet destined for this stream, and stamps the stream index, and converts the time stamp to the correct units (adjusting for rounding errors between stream conversions).

Parameters:
packet - to stamp
Returns:
>= 0 on success; <0 on failure.
Since:
3.2

setStreamCoder

public int setStreamCoder(IStreamCoder newCoder,
                          boolean assumeOnlyStream)
Sets the stream coder to use for this stream. This method will only cause a change if the IStreamCoder currently set on this IStream is not open. Otherwise the call is ignored and an error is returned.

Parameters:
newCoder - The new stream coder to use.
assumeOnlyStream - If true then this IStream will notify the IStreamCoder that it is the only stream and the IStreamCoder may use it to determine time stamps to output packets with. If false then the IStreamCoder does not support automatic stamping of packets with stream index IDs and users must call stampOutputPacket(IPacket) themselves.
Returns:
>= 0 on success; < 0 on error.
Since:
3.2

findTimeStampEntryInIndex

public IIndexEntry findTimeStampEntryInIndex(long wantedTimeStamp,
                                             int flags)
Search for the given time stamp in the key-frame index for this IStream.

Not all IContainerFormat implementations maintain key frame indexes, but if they have one, then this method searches in the IStream index to quickly find the byte-offset of the nearest key-frame to the given time stamp.

Parameters:
wantedTimeStamp - the time stamp wanted, in the stream's time base units.
flags - A bitmask of the SEEK_FLAG_* flags, or 0 to turn all flags off. If IContainer.SEEK_FLAG_BACKWARDS then the returned index will correspond to the time stamp which is <= the requested one (not supported by all demuxers). If IContainer.SEEK_FLAG_BACKWARDS is not set then it will be >=. if IContainer.SEEK_FLAG_ANY seek to any frame, only keyframes otherwise (not supported by all demuxers).
Returns:
The IIndexEntry for the nearest appropriate timestamp in the index, or null if it can't be found.
Since:
3.4

findTimeStampPositionInIndex

public int findTimeStampPositionInIndex(long wantedTimeStamp,
                                        int flags)
Search for the given time stamp in the key-frame index for this IStream.

Not all IContainerFormat implementations maintain key frame indexes, but if they have one, then this method searches in the IStream index to quickly find the index entry position of the nearest key-frame to the given time stamp.

Parameters:
wantedTimeStamp - the time stamp wanted, in the stream's time base units.
flags - A bitmask of the SEEK_FLAG_* flags, or 0 to turn all flags off. If IContainer.SEEK_FLAG_BACKWARDS then the returned index will correspond to the time stamp which is <= the requested one (not supported by all demuxers). If IContainer.SEEK_FLAG_BACKWARDS is not set then it will be >=. if IContainer.SEEK_FLAG_ANY seek to any frame, only keyframes otherwise (not supported by all demuxers).
Returns:
The position in this IStream index, or -1 if it cannot be found or an index is not maintained.
Since:
3.4
See Also:
getIndexEntry(int)

getIndexEntry

public IIndexEntry getIndexEntry(int position)
Get the IIndexEntry at the given position in this IStream object's index.

Not all IContainerFormat types maintain IStream indexes, but if they do, this method can return those entries.

Do not modify the IContainer this stream is from between calls to this method and getNumIndexEntries() as indexes may be compacted while processing.

Parameters:
position - The position in the index table.
Since:
3.4

addIndexEntry

public int addIndexEntry(IIndexEntry entry)
Adds an index entry into the stream's sorted index list. Updates the entry if the list already contains it.

Parameters:
entry - The entry to add.
Returns:
>=0 on success; <0 on error.
Since:
3.4


Copyright © 2008, 2010 Xuggle