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

#include <IStream.h>

Inheritance diagram for com::avpkit::core::IStream:

Collaboration diagram for com::avpkit::core::IStream:

Public Types
enum	Direction { INBOUND , OUTBOUND }
	The direction this stream is going (based on the container). More...

enum	ParseType { PARSE_NONE , PARSE_FULL , PARSE_HEADERS , PARSE_TIMESTAMPS , PARSE_FULL_ONCE , PARSE_FULL_RAW }
	What types of parsing can we do on a call to IContainer#readNextPacket(IPacket). More...

typedef enum com::avpkit::core::IStream::Direction	Direction
	The direction this stream is going (based on the container). More...

typedef enum com::avpkit::core::IStream::ParseType	ParseType
	What types of parsing can we do on a call to IContainer#readNextPacket(IPacket).

Public Member Functions
virtual Direction	getDirection ()=0
	Get the Direction this stream is pointing in. More...

virtual int	getIndex ()=0
	Get the relative position this stream has in the hosting IContainer object. More...

virtual int	getId ()=0
	Return a container format specific id for this stream. More...

virtual IStreamCoder *	getStreamCoder ()=0
	Get the StreamCoder than can manipulate this stream. More...

virtual IRational *	getFrameRate ()=0
	Get the (sometimes estimated) frame rate of this container. More...

virtual IRational *	getTimeBase ()=0
	The time base in which all timestamps (e.g. More...

virtual int64_t	getStartTime ()=0
	Return the start time, in getTimeBase() units, when this stream started. More...

virtual int64_t	getDuration ()=0
	Return the duration, in getTimeBase() units, of this stream, or Global#NO_PTS if unknown. More...

virtual int64_t	getCurrentDts ()=0
	The current Decompression Time Stamp that will be used on this stream, in getTimeBase() units. More...

virtual int	getNumIndexEntries ()=0
	Get the number of index entries in this stream. More...

virtual int64_t	getNumFrames ()=0
	Returns the number of encoded frames if known. More...

virtual IRational *	getSampleAspectRatio ()=0
	Added in 1.17. More...

virtual void	setSampleAspectRatio (IRational *newRatio)=0
	Sets the sample aspect ratio. More...

virtual const char *	getLanguage ()=0
	Get the 4-character language setting for this stream. More...

virtual void	setLanguage (const char *language)=0
	Set the 4-character language setting for this stream. More...

virtual IContainer *	getContainer ()=0
	Get the underlying container for this stream, or null if AVPKit doesn't know. More...

virtual int32_t	setStreamCoder (IStreamCoder *newCoder)=0
	Sets the stream coder to use for this stream. More...

virtual IStream::ParseType	getParseType ()=0
	Get how the decoding codec should parse data from this stream. More...

virtual void	setParseType (ParseType type)=0
	Set the parse type the decoding codec should use. More...

virtual int	setBitstreamFilter (const char *name)=0
	Set a bitstream filter on this stream. More...

virtual IMetaData *	getMetaData ()=0
	Get the IMetaData for this object, or null if none. More...

virtual void	setMetaData (IMetaData *data)=0
	Set the IMetaData on this object, overriding any previous meta data. More...

virtual int32_t	stampOutputPacket (IPacket *packet)=0
	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). More...

virtual int32_t	setStreamCoder (IStreamCoder *newCoder, bool assumeOnlyStream)=0
	Sets the stream coder to use for this stream. More...

virtual IIndexEntry *	findTimeStampEntryInIndex (int64_t wantedTimeStamp, int32_t flags)=0
	Search for the given time stamp in the key-frame index for this IStream. More...

virtual int32_t	findTimeStampPositionInIndex (int64_t wantedTimeStamp, int32_t flags)=0
	Search for the given time stamp in the key-frame index for this IStream. More...

virtual IIndexEntry *	getIndexEntry (int32_t position)=0
	Get the IIndexEntry at the given position in this IStream object's index. More...

virtual int32_t	addIndexEntry (IIndexEntry *entry)=0
	Adds an index entry into the stream's sorted index list. More...

virtual void	setId (int32_t id)=0
	Set the format-specific stream id. More...

Public Member Functions inherited from com::avpkit::ferry::RefCounted
virtual int32_t	acquire ()
	Internal Only. More...

virtual int32_t	release ()
	Internal Only. More...

virtual RefCounted *	copyReference ()
	Create a new Java object that refers to the same native object. More...

virtual int32_t	getCurrentRefCount ()
	Return the current reference count on this object. More...

void	setJavaAllocator (void *allocator)
	This method is public but not part of the standard API. More...

void *	getJavaAllocator ()
	This method is public but not part of the standard API. More...

Additional Inherited Members
Protected Member Functions inherited from com::avpkit::ferry::RefCounted
virtual void	destroy ()
	This method is called by RefCounted objects when their Ref Count reaches zero and they are about to be destroyed.

Protected Attributes inherited from com::avpkit::ferry::RefCounted
AtomicInteger *	mRefCount
	This is the internal reference count, represented as an AtomicInteger to make sure it is thread safe.

void *	mAllocator
	Not part of public API.

Detailed Description

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.

Definition at line 49 of file IStream.h.

Member Typedef Documentation

◆ Direction

typedef enum com::avpkit::core::IStream::Direction com::avpkit::core::IStream::Direction

The direction this stream is going (based on the container).

If the container Container is opened in Container::READ mode then this will be INBOUND. If it's opened in Container::WRITE mode, then this will be OUTBOUND.

Member Enumeration Documentation

◆ Direction

enum com::avpkit::core::IStream::Direction

The direction this stream is going (based on the container).

If the container Container is opened in Container::READ mode then this will be INBOUND. If it's opened in Container::WRITE mode, then this will be OUTBOUND.

Definition at line 59 of file IStream.h.

                            {
       INBOUND,
       OUTBOUND,
     } Direction;

◆ ParseType

enum com::avpkit::core::IStream::ParseType

What types of parsing can we do on a call to IContainer#readNextPacket(IPacket).

Enumerator
PARSE_FULL	full parsing and repack
PARSE_HEADERS	Only parse headers, do not repack.
PARSE_TIMESTAMPS	full parsing and interpolation of timestamps for frames not starting on a packet boundary
PARSE_FULL_ONCE	full parsing and repack of the first frame only, only implemented for H.264 currently
PARSE_FULL_RAW	full parsing and repack with timestamp and position generation by parser for raw this assumes that each packet in the file contains no demuxer level headers and just codec level data, otherwise position generation would fail

Definition at line 222 of file IStream.h.

                            {
       PARSE_NONE,
       PARSE_FULL,       
       PARSE_HEADERS,    
       PARSE_TIMESTAMPS, 
       PARSE_FULL_ONCE,  
       PARSE_FULL_RAW,       
     } ParseType;

Member Function Documentation

◆ addIndexEntry()

virtual int32_t com::avpkit::core::IStream::addIndexEntry ( IIndexEntry * entry )

pure virtual

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

Implemented in com::avpkit::core::Stream.

◆ findTimeStampEntryInIndex()

virtual IIndexEntry* com::avpkit::core::IStream::findTimeStampEntryInIndex	(	int64_t	wantedTimeStamp,
		int32_t	flags
	)

pure virtual

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

Implemented in com::avpkit::core::Stream.

◆ findTimeStampPositionInIndex()

virtual int32_t com::avpkit::core::IStream::findTimeStampPositionInIndex	(	int64_t	wantedTimeStamp,
		int32_t	flags
	)

pure virtual

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.

See also: #getIndexEntry(int)

Since: 3.4

Implemented in com::avpkit::core::Stream.

◆ getContainer()

virtual IContainer* com::avpkit::core::IStream::getContainer ( )

pure virtual

Get the underlying container for this stream, or null if AVPKit doesn't know.

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

Implemented in com::avpkit::core::Stream.

◆ getCurrentDts()

virtual int64_t com::avpkit::core::IStream::getCurrentDts ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ getDirection()

virtual Direction com::avpkit::core::IStream::getDirection ( )

pure virtual

Get the Direction this stream is pointing in.

Returns: The direction of this stream.

Implemented in com::avpkit::core::Stream.

◆ getDuration()

virtual int64_t com::avpkit::core::IStream::getDuration ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ getFrameRate()

virtual IRational* com::avpkit::core::IStream::getFrameRate ( )

pure virtual

Get the (sometimes estimated) frame rate of this container.

For variable frame-rate containers (they do exist) this is just an approimation. Better to use getTimeBase().

For contant frame-rate containers, this will be 1 / ( getTimeBase() )

Returns: The frame-rate of this container.

Implemented in com::avpkit::core::Stream.

◆ getId()

virtual int com::avpkit::core::IStream::getId ( )

pure virtual

Return a container format specific id for this stream.

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

Implemented in com::avpkit::core::Stream.

◆ getIndex()

virtual int com::avpkit::core::IStream::getIndex ( )

pure virtual

Get the relative position this stream has in the hosting IContainer object.

Returns: The Index within the Container of this stream.

Implemented in com::avpkit::core::Stream.

◆ getIndexEntry()

virtual IIndexEntry* com::avpkit::core::IStream::getIndexEntry ( int32_t position )

pure virtual

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

Implemented in com::avpkit::core::Stream.

◆ getLanguage()

virtual const char* com::avpkit::core::IStream::getLanguage ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ getMetaData()

virtual IMetaData* com::avpkit::core::IStream::getMetaData ( )

pure virtual

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

Implemented in com::avpkit::core::Stream.

◆ getNumFrames()

virtual int64_t com::avpkit::core::IStream::getNumFrames ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ getNumIndexEntries()

virtual int com::avpkit::core::IStream::getNumIndexEntries ( )

pure virtual

Get the number of index entries in this stream.

Returns: The number of index entries in this stream.

See also: #getIndexEntry(int)

Implemented in com::avpkit::core::Stream.

◆ getParseType()

virtual IStream::ParseType com::avpkit::core::IStream::getParseType ( )

pure virtual

Get how the decoding codec should parse data from this stream.

Returns: the parse type.

Since: 3.0

Implemented in com::avpkit::core::Stream.

◆ getSampleAspectRatio()

virtual IRational* com::avpkit::core::IStream::getSampleAspectRatio ( )

pure virtual

Added in 1.17.

Gets the sample aspect ratio.

Returns: The sample aspect ratio.

Implemented in com::avpkit::core::Stream.

◆ getStartTime()

virtual int64_t com::avpkit::core::IStream::getStartTime ( )

pure virtual

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

Returns: The start time.

Implemented in com::avpkit::core::Stream.

◆ getStreamCoder()

virtual IStreamCoder* com::avpkit::core::IStream::getStreamCoder ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ getTimeBase()

virtual IRational* com::avpkit::core::IStream::getTimeBase ( )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ setBitstreamFilter()

virtual int com::avpkit::core::IStream::setBitstreamFilter ( const char * name )

pure virtual

Set a bitstream filter on this stream.

Parameters

name	The name of bitstream filter

Since: 6.0

Implemented in com::avpkit::core::Stream.

◆ setId()

virtual void com::avpkit::core::IStream::setId ( int32_t id )

pure virtual

Set the format-specific stream id.

Parameters

id	The id to set.

See also: getId()

Since: 5.0

Implemented in com::avpkit::core::Stream.

◆ setLanguage()

virtual void com::avpkit::core::IStream::setLanguage ( const char * language )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ setMetaData()

virtual void com::avpkit::core::IStream::setMetaData ( IMetaData * data )

pure virtual

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.

See also: getMetaData()

Since: 3.1

Implemented in com::avpkit::core::Stream.

◆ setParseType()

virtual void com::avpkit::core::IStream::setParseType ( ParseType type )

pure virtual

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 decoding.

Parameters

type	The type to set.

Since: 3.0

Implemented in com::avpkit::core::Stream.

◆ setSampleAspectRatio()

virtual void com::avpkit::core::IStream::setSampleAspectRatio ( IRational * newRatio )

pure virtual

Sets the sample aspect ratio.

Parameters

newRatio The new ratio.

Implemented in com::avpkit::core::Stream.

◆ setStreamCoder() [1/2]

virtual int32_t com::avpkit::core::IStream::setStreamCoder ( IStreamCoder * newCoder )

pure virtual

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.

Implemented in com::avpkit::core::Stream.

◆ setStreamCoder() [2/2]

virtual int32_t com::avpkit::core::IStream::setStreamCoder	(	IStreamCoder *	newCoder,
		bool	assumeOnlyStream
	)

pure virtual

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

Implemented in com::avpkit::core::Stream.

◆ stampOutputPacket()

virtual int32_t com::avpkit::core::IStream::stampOutputPacket ( IPacket * packet )

pure virtual

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

Implemented in com::avpkit::core::Stream.

The documentation for this class was generated from the following files:

csrc/com/avpkit/core/IStream.h
csrc/com/avpkit/core/IStream.cpp

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Direction

Member Enumeration Documentation

◆ Direction

◆ ParseType

Member Function Documentation

◆ addIndexEntry()

◆ findTimeStampEntryInIndex()

◆ findTimeStampPositionInIndex()

◆ getContainer()

◆ getCurrentDts()

◆ getDirection()

◆ getDuration()

◆ getFrameRate()

◆ getId()

◆ getIndex()

◆ getIndexEntry()

◆ getLanguage()

◆ getMetaData()

◆ getNumFrames()

◆ getNumIndexEntries()

◆ getParseType()

◆ getSampleAspectRatio()

◆ getStartTime()

◆ getStreamCoder()

◆ getTimeBase()

◆ setBitstreamFilter()

◆ setId()

◆ setLanguage()

◆ setMetaData()

◆ setParseType()

◆ setSampleAspectRatio()

◆ setStreamCoder() [1/2]

◆ setStreamCoder() [2/2]

◆ stampOutputPacket()