ContainerStream (humble-video-noarch 0.3.0 API)

java.lang.Object
- io.humble.ferry.RefCounted
- - io.humble.video.ContainerStream

Direct Known Subclasses:

DemuxerStream, MuxerStream
```
public class ContainerStream
extends RefCounted
```
Represents a stream of similar data (eg video) in a Container.

Streams are really virtual concepts; Container objects really just contain
a bunch of Packets. But each Packet usually has a stream
id associated with it, and all Packets 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 Stream object to get properly configured Decoders
for decoding, and to tell Encoders how to encode Packets when
decoding.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ContainerStream.Disposition` The disposition of this stream.
`static class`	`ContainerStream.ParseType` What types of parsing can we do on a call to Source#read(Packet)

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ContainerStream`	`copyReference()` Create a new ContainerStream 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.
`IndexEntry`	`findTimeStampEntryInIndex(long wantedTimeStamp, int flags)` Search for the given time stamp in the key-frame index for this Stream.
`int`	`findTimeStampPositionInIndex(long wantedTimeStamp, int flags)` Search for the given time stamp in the key-frame index for this Stream.
`MediaPacket`	`getAttachedPic()` For containers with Stream.Disposition.DISPOSITION_ATTACHED_PIC, this returns a read-only copy of the packet containing the picture (needs to be decoded separately).
`Container`	`getContainer()` Get the underlying container for this stream, or null if Humble Video doesn't know.
`long`	`getCurrentDts()` The current Decompression Time Stamp that will be used on this stream, in #getTimeBase() units.
`ContainerStream.Disposition`	`getDisposition()` Get the Stream.Disposition of this stream.
`long`	`getDuration()` Return the duration, in #getTimeBase() units, of this stream, or Global#NO_PTS if unknown.
`Rational`	`getFrameRate()` Get the (sometimes estimated) average frame rate of this container. For variable frame-rate containers (they do exist) this is just an approximation.
`int`	`getId()` Return a container format specific id for this stream.
`int`	`getIndex()` Get the relative position this stream has in the hosting Container object.
`List<IndexEntry>`	`getIndexEntries()` Get an ordered sequence of index entries in this `Stream`.
`IndexEntry`	`getIndexEntry(int position)` Get the IndexEntry at the given position in this Stream object's index.
`KeyValueBag`	`getMetaData()` Get the KeyValueBag for this object, or null if none.
`long`	`getNumFrames()` Returns the number of encoded frames if known.
`int`	`getNumIndexEntries()` Get the number of index entries in this stream.
`ContainerStream.ParseType`	`getParseType()` Get how the decoding codec should parse data from this stream.
`Rational`	`getSampleAspectRatio()` Gets the sample aspect ratio.
`long`	`getStartTime()` Return the start time, in #getTimeBase() units, when this stream started.
`Rational`	`getTimeBase()` The time base in which all timestamps (e.g.
`int`	`hashCode()` Get a hashable value for this object.
`boolean`	`matchSpecifier(String specifier)` Check if the stream is matched by the stream specifier. See the "stream specifiers" chapter in the FFmpeg documentation for the syntax of specifier: https://www.ffmpeg.org/ffmpeg.html#Stream-selection
`void`	`setParseType(ContainerStream.ParseType type)` Set the parse type the decoding codec should use.

Methods inherited from class io.humble.ferry.RefCounted
delete, getCurrentRefCount

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - copyReference
```
public ContainerStream copyReference()
```
    Create a new ContainerStream 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.
  - getIndexEntries
```
public List<IndexEntry> getIndexEntries()
```
    Get an ordered sequence of index entries in this Stream.
    
    Returns:
    
    A list of entries. Will always return a non-null list, but if there are no entries the list size will be zero.
  - getIndex
```
public int getIndex()
```
    Get the relative position this stream has in the hosting
    Container 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.
  - getFrameRate
```
public Rational getFrameRate()
```
    Get the (sometimes estimated) average frame rate of this container.
    For variable frame-rate containers (they do exist) this is just
    an approximation. Better to use getTimeBase().
    
    For contant frame-rate containers, this will be 1 / ( getTimeBase() )
    
    Returns:
    
    The frame-rate of this container.
  - getTimeBase
```
public Rational 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 Rational getSampleAspectRatio()
```
    Gets the sample aspect ratio.
    
    Returns:
    
    The sample aspect ratio.
  - getContainer
```
public Container getContainer()
```
    Get the underlying container for this stream, or null if Humble Video
    doesn't know.
    
    Returns:
    
    the container, or null if we don't know.
  - getParseType
```
public ContainerStream.ParseType getParseType()
```
    Get how the decoding codec should parse data from this stream.
    
    Returns:
    
    the parse type.
  - setParseType
```
public void setParseType(ContainerStream.ParseType type)
```
    Set the parse type the decoding codec should use. Set to
    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 reading packets.
    
    Parameters:
    
    type - The type to set.
  - getMetaData
```
public KeyValueBag getMetaData()
```
    Get the KeyValueBag for this object,
    or null if none.
    
    If the Container or Stream object
    that this KeyValueBag came from was opened
    for reading, then changes via KeyValueBag#setValue(String, String)
    will have no effect on the underlying media.
    
    If the Container or Stream object
    that this KeyValueBag came from was opened
    for writing, then changes via KeyValueBag#setValue(String, String)
    will have no effect after Container#writeHeader()
    is called.
    
    Returns:
    
    the KeyValueBag.
  - findTimeStampEntryInIndex
```
public IndexEntry findTimeStampEntryInIndex(long wantedTimeStamp,
                                            int flags)
```
    Search for the given time stamp in the key-frame index for this Stream.
    
    Not all ContainerFormat implementations
    maintain key frame indexes, but if they have one,
    then this method searches in the Stream 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 Container#SEEK_FLAG_BACKWARDS then the returned
    index will correspond to the time stamp which is <=
    the requested one (not supported by all demuxers).
    If Container#SEEK_FLAG_BACKWARDS is not set then it will be >=.
    if Container#SEEK_FLAG_ANY seek to any frame, only
    keyframes otherwise (not supported by all demuxers).
    
    Returns:
    
    The IndexEntry for the nearest appropriate timestamp
    in the index, or null if it can't be found.
  - findTimeStampPositionInIndex
```
public int findTimeStampPositionInIndex(long wantedTimeStamp,
                                        int flags)
```
    Search for the given time stamp in the key-frame index for this Stream.
    
    Not all ContainerFormat implementations
    maintain key frame indexes, but if they have one,
    then this method searches in the Stream 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 Container#SEEK_FLAG_BACKWARDS then the returned
    index will correspond to the time stamp which is <=
    the requested one (not supported by all demuxers).
    If Container#SEEK_FLAG_BACKWARDS is not set then it will be >=.
    if Container#SEEK_FLAG_ANY seek to any frame, only
    keyframes otherwise (not supported by all demuxers).
    
    Returns:
    
    The position in this Stream index, or -1 if it cannot
    be found or an index is not maintained.
    
    See Also:
    
    getIndexEntry(int)
  - getIndexEntry
```
public IndexEntry getIndexEntry(int position)
```
    Get the IndexEntry at the given position in this
    Stream object's index.
    
    Not all ContainerFormat types maintain
    Stream indexes, but if they do,
    this method can return those entries.
    
    Do not modify the Container 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.
  - getDisposition
```
public ContainerStream.Disposition getDisposition()
```
    Get the Stream.Disposition of this stream.
  - getAttachedPic
```
public MediaPacket getAttachedPic()
```
    For containers with Stream.Disposition.DISPOSITION_ATTACHED_PIC,
    this returns a read-only copy of the packet containing the
    picture (needs to be decoded separately).
  - matchSpecifier
```
public boolean matchSpecifier(String specifier)
```
    Check if the stream is matched by the stream specifier.
    
    See the "stream specifiers" chapter in the FFmpeg documentation for the syntax
    of specifier: https://www.ffmpeg.org/ffmpeg.html#Stream-selection
    
    Parameters:
    
    specifier - the specifier string
    
    Returns:
    
    true if this stream is matched by specifier; false if this stream is not
    matched by specifier;
    
    Throws:
    
    InvalidArgument - if the specifier is invalid.
    
    Note: A stream specifier can match several streams in a container.

Class ContainerStream

Nested Class Summary

Method Summary

Methods inherited from class io.humble.ferry.RefCounted

Methods inherited from class java.lang.Object

Method Detail

copyReference

equals

hashCode

getIndexEntries

getIndex

getId

getFrameRate

getTimeBase

getStartTime

getDuration

getCurrentDts

getNumIndexEntries

getNumFrames

getSampleAspectRatio

getContainer

getParseType

setParseType

getMetaData

findTimeStampEntryInIndex

findTimeStampPositionInIndex

getIndexEntry

getDisposition

getAttachedPic

matchSpecifier