io.humble.video

Class Demuxer

java.lang.Object

io.humble.ferry.RefCounted

io.humble.video.Configurable

io.humble.video.Container

io.humble.video.Demuxer

public class Demuxer
extends Container

A Container that MediaPacket objects can be read from.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Demuxer.SeekFlag Flags that can be bitmasked in the #seek method.
static class	Demuxer.State Demuxers can only be in one of these states:

Nested classes/interfaces inherited from class io.humble.video.Container

Container.Flag

Method Summary

Modifier and Type	Method and Description
boolean	canStreamsBeAddedDynamically() Can streams be added dynamically to this container?
void	close() Close the container.
Demuxer	copyReference() Create a new Demuxer 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.
int	getBitRate() Get the calculated overall bit rate of this file.
long	getDuration() Gets the duration, if known, of this container. This will only work for non-streamable containers where Demuxer can calculate the container size.
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.
boolean	getFlag(Container.Flag flag) Get the setting for the specified flag
int	getFlags() Get the flags associated with this object.
DemuxerFormat	getFormat() Get the DemuxerFormat associated with this Demuxer or null if unknown.
int	getInputBufferLength() Return the input buffer length.
int	getMaxDelay() Gets the AVFormatContext.max_delay property if possible.
KeyValueBag	getMetaData() Get the KeyValueBag of media MetaData for this object, or null if none.
int	getReadRetryCount() Get the number of times Demuxer#readNextPacket(Packet) will retry a read if it gets a Error.Type#ERROR_AGAIN value back. Defaults to 1 times.
long	getStartTime() Get the starting timestamp in microseconds of the first packet of the earliest stream in this container.
Demuxer.State	getState() Get the current state of the container.
DemuxerStream	getStream(int streamIndex) Get the stream at the given position.
String	getURL() Get the URL the Demuxer was opened with. May return null if unknown.
int	hashCode() Get a hashable value for this object.
static Demuxer	make() Create a new Demuxer
void	open(String url, DemuxerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData, KeyValueBag options, KeyValueBag optionsNotSet) Open this container and make it ready for reading, optionally reading as far into the container as necessary to find all streams.
void	pause() Pause a playing network source.
void	play() Start playing a network source.
void	queryStreamMetaData() Attempts to read all the meta data in this stream, potentially by reading ahead and decoding packets.
int	read(MediaPacket packet) Reads the next packet in the Demuxer into the Packet.
int	seek(int stream_index, long min_ts, long ts, long max_ts, int flags) Seek to timestamp ts. Seeking will be done so that the point from which all active streams can be presented successfully will be closest to ts and within min/max_ts. Active streams are all streams that have Stream.getDiscardSetting < Codec.DISCARD_ALL. If flags contain SeekFlags.SEEK_BYTE, then all timestamps are in bytes and are the file position (this may not be supported by all demuxers). If flags contain SeekFlags.SEEK_FRAME, then all timestamps are in frames in the stream with stream_index (this may not be supported by all demuxers). Otherwise all timestamps are in units of the stream selected by stream_index or if stream_index is -1, in (1/Global.DEFAULT_PTS_MICROSECONDS} units. If flags contain SeekFlags.SEEK_ANY, then non-keyframes are treated as keyframes (this may not be supported by all demuxers).
void	setFlag(Container.Flag flag, boolean value) Set the flag.
void	setFlags(int newFlags) Set the flags to use with this object.
int	setForcedAudioCodec(Codec.ID id) Forces the Demuxer to assume all audio streams are encoded with the given audio codec when demuxing.
int	setForcedSubtitleCodec(Codec.ID id) Forces the Demuxer to assume all subtitle streams are encoded with the given subtitle codec when demuxing.
int	setForcedVideoCodec(Codec.ID id) Forces the Demuxer to assume all video streams are encoded with the given video codec when demuxing.
void	setInputBufferLength(int size) Set the buffer length Humble Video will suggest to FFMPEG for reading inputs. If called when a Container is open, the call is ignored and -1 is returned.
void	setReadRetryCount(int count) Sets the read retry count.
String	toString()

Methods inherited from class io.humble.video.Container

getNumStreams

Methods inherited from class io.humble.video.Configurable

getNumProperties, getPropertyAsBoolean, getPropertyAsDouble, getPropertyAsInt, getPropertyAsLong, getPropertyAsRational, getPropertyAsString, getPropertyMetaData, getPropertyMetaData, setProperty, setProperty, setProperty, setProperty, setProperty, setProperty

Methods inherited from class io.humble.ferry.RefCounted

delete, getCurrentRefCount

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

copyReference

public Demuxer copyReference()

Create a new Demuxer object that is actually referring to the exact same underlying native object.

Overrides:

copyReference in class Container

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 Container

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 Container

Returns:

the hashable value.

toString

public String toString()

Overrides:

toString in class Container

make

public static Demuxer make()

Create a new Demuxer

getState

public Demuxer.State getState()

Get the current state of the container.

getFormat

public DemuxerFormat getFormat()

Get the DemuxerFormat associated with this Demuxer
or null if unknown.

setInputBufferLength

public void setInputBufferLength(int size)

Set the buffer length Humble Video will suggest to FFMPEG for reading inputs.

If called when a Container is open, the call is ignored and -1 is returned.

Parameters:

size - The suggested buffer size.

Throws:

InvalidArgument - if size <= 0

getInputBufferLength

public int getInputBufferLength()

Return the input buffer length.

Returns:

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

open

public void open(String url,
                 DemuxerFormat format,
                 boolean streamsCanBeAddedDynamically,
                 boolean queryStreamMetaData,
                 KeyValueBag options,
                 KeyValueBag optionsNotSet)
          throws InterruptedException,
                 IOException

Open this container and make it ready for reading, optionally
reading as far into the container as necessary to find all streams.

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

Parameters:

url - The resource to open; The format of this string is any
url that FFMPEG supports (including additional protocols if added
through the video.customio library).

format - A pointer to a InputFormat object specifying
the format of this container, or null if you want us to guess.

streamsCanBeAddedDynamically - If true, open() will expect that new
streams can be added at any time, even after the format header has been read.

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

options - If not null, a set of key-value pairs that will be set on the container immediately
the format is determined. Some options cannot be set on input formats until
the system has had a chance to determine what the format is, so this
is the only way to set InputFormat-specific options.

optionsNotSet - If not null, on return this KeyValueBag object will be cleared out, and
replace with any key/value pairs that were in options but could not be set on this
Demuxer.

Throws:

InterruptedException

IOException

close

public void close()
           throws InterruptedException,
                  IOException

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

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

Throws:

InterruptedException

IOException

getStream

public DemuxerStream getStream(int streamIndex)
                        throws InterruptedException,
                               IOException

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.

Throws:

InterruptedException

IOException

read

public int read(MediaPacket packet)
         throws InterruptedException,
                IOException

Reads the next packet in the Demuxer into the Packet. This method will
release any buffers currently held by this packet and allocate
new ones.

For non-blocking IO data sources, it is possible for this method
to return as successful but with no complete packet. In that case
the caller should retry again later (think EAGAIN) semantics.

Parameters:

packet - [In/Out] The packet the Demuxer will read into.

Returns:

0 if successful, or <0 if not.

Throws:

RuntimeException - if an error occurs except for EOF (in which case <0 returned)
or EAGAIN (in which case 0 returned with an incomplete packet).

InterruptedException

IOException

queryStreamMetaData

public void queryStreamMetaData()
                         throws InterruptedException,
                                IOException

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.

Throws:

InterruptedException

IOException

getDuration

public long getDuration()

Gets the duration, if known, of this container.

This will only work for non-streamable containers where Demuxer
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
containers where Demuxer can calculate the container size or
(b) after Demuxer has actually read the
first packet from a streamable Demuxer.

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.

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:




getFlag

public boolean getFlag(Container.Flag 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(Container.Flag 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 Demuxer was opened with.
May return null if unknown.

Returns:

the URL opened, or null.

getReadRetryCount

public int getReadRetryCount()

Get the number of times Demuxer#readNextPacket(Packet)
will retry a read if it gets a Error.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:




canStreamsBeAddedDynamically

public boolean canStreamsBeAddedDynamically()

Can streams be added dynamically to this container?

Returns:

true if streams can be added dynamically

getMetaData

public KeyValueBag getMetaData()

Get the KeyValueBag of media MetaData for this object,
or null if none.

If the Demuxer or IStream 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 Demuxer or IStream object
that this KeyValueBag came from was opened
for writing, then changes via KeyValueBag#setValue(String, String)
will have no effect after Demuxer#writeHeader()
is called.

Returns:

the KeyValueBag.

setForcedAudioCodec

public int setForcedAudioCodec(Codec.ID id)

Forces the Demuxer 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.

setForcedVideoCodec

public int setForcedVideoCodec(Codec.ID id)

Forces the Demuxer 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.

setForcedSubtitleCodec

public int setForcedSubtitleCodec(Codec.ID id)

Forces the Demuxer 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.

seek

public int seek(int stream_index,
                long min_ts,
                long ts,
                long max_ts,
                int flags)
         throws InterruptedException,
                IOException

Seek to timestamp ts.

Seeking will be done so that the point from which all active streams
can be presented successfully will be closest to ts and within min/max_ts.
Active streams are all streams that have Stream.getDiscardSetting <
Codec.DISCARD_ALL.

If flags contain SeekFlags.SEEK_BYTE, then all timestamps are in bytes and
are the file position (this may not be supported by all demuxers).
If flags contain SeekFlags.SEEK_FRAME, then all timestamps are in frames
in the stream with stream_index (this may not be supported by all demuxers).
Otherwise all timestamps are in units of the stream selected by stream_index
or if stream_index is -1, in (1/Global.DEFAULT_PTS_MICROSECONDS} units.
If flags contain SeekFlags.SEEK_ANY, then non-keyframes are treated as
keyframes (this may not be supported by all demuxers).

Parameters:

stream_index - index of the stream which is used as time base reference

min_ts - smallest acceptable timestamp

ts - target timestamp

max_ts - largest acceptable timestamp

flags - flags

Returns:

>=0 on success, error code otherwise

Note: This is part of the new seek API which is still under construction.
Thus do not use this yet. It may change at any time, do not expect
ABI compatibility yet!

Throws:

InterruptedException

IOException

getMaxDelay

public int getMaxDelay()

Gets the AVFormatContext.max_delay property if possible.

Returns:

The max delay, error code otherwise.

play

public void play()
          throws InterruptedException,
                 IOException

Start playing a network source. Call #pause() to pause.

Throws:

InterruptedException

IOException

pause

public void pause()
           throws InterruptedException,
                  IOException

Pause a playing network source. Call #play() to unpause.

Throws:

InterruptedException

IOException