io.humble.video

Class MediaPacket

java.lang.Object

io.humble.ferry.RefCounted

io.humble.video.Media

io.humble.video.MediaEncoded

io.humble.video.MediaPacket

public class MediaPacket
extends MediaEncoded

A packet of encoded data that was read from a Demuxer or
will be written to a Muxer.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MediaPacket.SideDataType

Field Summary

Fields inherited from class io.humble.video.Media

DEFAULT_TIME_STAMP_FORMAT

Method Summary

Modifier and Type	Method and Description
MediaPacket	copyReference() Create a new MediaPacket 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.
long	getConvergenceDuration() Time difference in IStream#getTimeBase() units from the presentation time stamp of this packet to the point at which the output from the decoder has converged independent from the availability of previous frames.
Buffer	getData() Get any underlying raw data available for this packet.
long	getDts() Get the Decompression Time Stamp (DTS) for this packet.
long	getDuration() Return the duration of this packet, in units of #getTimeBase()
int	getFlags() Get any flags set on this packet, as a 4-byte binary-ORed bit-mask. This is access to raw FFMPEG flags, but it is easier to use the is* methods below.
int	getMaxSize() Get the maximum size (in bytes) of payload this packet can hold.
int	getNumSideDataElems() Get the number of side data elements in this packet.
long	getPosition() Return the position (in bytes) of this packet in the stream.
long	getPts() Get the Presentation Time Stamp (PTS) for this packet. This is the time at which the payload for this packet should be presented to the user, in units of #getTimeBase(), relative to the start of stream.
Buffer	getSideData(int n) Get the n'th item of SideData.
MediaPacket.SideDataType	getSideDataType(int n) Get the n'th item of SideData.
int	getSize() Get the size in bytes of the payload currently in this packet.
int	getStreamIndex() Get the container-specific index for the stream this packet is part of.
int	hashCode() Get a hashable value for this object.
boolean	isKeyPacket() Does this packet contain Key data? i.e.
static MediaPacket	make() Create a new Packet
static MediaPacket	make(Buffer buffer) Allocate a new packet that wraps an existing Buffer. NOTE: At least 16 bytes of the passed in buffer will be used for header information, so the resulting Packet.getSize() will be smaller than Buffer.getBufferSize() .
static MediaPacket	make(int size) Allocate a new packet.
static MediaPacket	make(MediaPacket packet, boolean copyData) Allocate a new packet wrapping the existing contents of a passed in packet.
void	reset(int payloadSize) Discard the current payload and allocate a new payload.
void	setConvergenceDuration(long duration) Set the convergence duration.
void	setDts(long aDts) Set a new Decompression Time Stamp (DTS) for this packet.
void	setDuration(long duration) Set the duration.
void	setFlags(int flags) Set any internal flags.
void	setKeyPacket(boolean keyPacket) Set if this is a key packet.
void	setPosition(long position) Set the position.
void	setPts(long aPts) Set a new Presentation Time Stamp (PTS) for this packet.
void	setStreamIndex(int streamIndex) Set the stream index for this packet.
String	toString()

Methods inherited from class io.humble.video.MediaEncoded

setTimeBase

Methods inherited from class io.humble.video.Media

getFormattedTimeStamp, getFormattedTimeStamp, getTimeBase, getTimeStamp, isComplete, isKey, setTimeStamp

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 MediaPacket copyReference()

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

Overrides:

copyReference in class MediaEncoded

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 MediaEncoded

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 MediaEncoded

Returns:

the hashable value.

toString

public String toString()

Overrides:

toString in class Object

make

public static MediaPacket make()

Create a new Packet

make

public static MediaPacket make(Buffer buffer)

Allocate a new packet that wraps an existing Buffer.

NOTE: At least 16 bytes of the passed in buffer will be used
for header information, so the resulting Packet.getSize()
will be smaller than Buffer.getBufferSize() .

Parameters:

buffer - The Buffer to wrap.

Returns:

a new packet or null on error.

make

public static MediaPacket make(MediaPacket packet,
                               boolean copyData)

Allocate a new packet wrapping the existing contents of
a passed in packet. Callers can then modify
#getPts(),
#getDts() and other get/set methods without
modifying the original packet.

Parameters:

packet - Packet to reuse buffer from and to
copy settings from.

copyData - if true copy data from packet
into our own buffer. If false, share the same
data buffer that packet uses

Returns:

a new packet or null on error.

make

public static MediaPacket make(int size)

Allocate a new packet.

Note that any buffers this packet needs will be
lazily allocated (i.e. we won't actually grab all
the memory until we need it).

Parameters:

size - The maximum size, in bytes, of data you
want to put in this packet.

Returns:

a new packet, or null on error.

getData

public Buffer getData()

Get any underlying raw data available for this packet.

Returns:

The raw data, or null if not accessible.

getNumSideDataElems

public int getNumSideDataElems()

Get the number of side data elements in this packet.

getSideData

public Buffer getSideData(int n)

Get the n'th item of SideData.

WARNING: Callers must ensure that the the packet object
this is called form is NOT reset or destroyed while using this buffer,
as unfortunately we cannot ensure this buffer survives the
underlying packet data.

Parameters:

n - The n'th item to get.

Returns:

the data, or null if none found

Throws:

InvalidArgument - if n < 0 || n >= #getNumSideDataElems()

getSideDataType

public MediaPacket.SideDataType getSideDataType(int n)

Get the n'th item of SideData.

Parameters:

n - The n'th item to get.

Returns:

the data, or SideDataType.DATA_UNKNOWN if none found

Throws:

InvalidArgument - if n < 0 || n >= #getNumSideDataElems()

getPts

public long getPts()

Get the Presentation Time Stamp (PTS) for this packet.

This is the time at which the payload for this packet should
be presented to the user, in units of
#getTimeBase(), relative to the start of stream.

Returns:

Get the Presentation Timestamp for this packet.

setPts

public void setPts(long aPts)

Set a new Presentation Time Stamp (PTS) for this packet.

Parameters:

aPts - a new PTS for this packet.

See Also:

getPts()

getDts

public long getDts()

Get the Decompression Time Stamp (DTS) for this packet.

This is the time at which the payload for this packet should
be decompressed, in units of
#getTimeBase(), relative to the start of stream.

Some media codecs can require packets from the "future" to
be decompressed before earliest packets as an additional way to compress
data. In general you don't need to worry about this, but if you're
curious start reading about the difference between I-Frames, P-Frames
and B-Frames (or Bi-Directional Frames). B-Frames can use information
from future frames when compressed.

Returns:

Get the Decompression Timestamp (i.e. when this was read relative
to the start of reading packets).

setDts

public void setDts(long aDts)

Set a new Decompression Time Stamp (DTS) for this packet.

Parameters:

aDts - a new DTS for this packet.

See Also:

getDts()

getSize

public int getSize()

Get the size in bytes of the payload currently in this packet.

Returns:

Size (in bytes) of payload currently in packet.

getMaxSize

public int getMaxSize()

Get the maximum size (in bytes) of payload this packet can hold.

Returns:

Get maximum size (in bytes) of payload this packet can hold.

getStreamIndex

public int getStreamIndex()

Get the container-specific index for the stream this packet is
part of.

Returns:

Stream in container that this packet has data for, or <0 if unsure.

getFlags

public int getFlags()

Get any flags set on this packet, as a 4-byte binary-ORed bit-mask.
This is access to raw FFMPEG
flags, but it is easier to use the is* methods below.

Returns:

Any flags on the packet.

isKeyPacket

public boolean isKeyPacket()

Does this packet contain Key data? i.e. data that needs no other
frames or samples to decode.

Returns:

true if key; false otherwise.

getDuration

public long getDuration()

Return the duration of this packet, in units of #getTimeBase()

Returns:

Duration of this packet, in same time-base as the PTS.

getPosition

public long getPosition()

Return the position (in bytes) of this packet in the stream.

Returns:

The position of this packet in the stream, or -1 if
unknown.

setKeyPacket

public void setKeyPacket(boolean keyPacket)

Set if this is a key packet.

Parameters:

keyPacket - true for yes, false for no.

setFlags

public void setFlags(int flags)

Set any internal flags.

Parameters:

flags - Flags to set

setStreamIndex

public void setStreamIndex(int streamIndex)

Set the stream index for this packet.

Parameters:

streamIndex - The stream index, as determined from the IContainer this packet will be written to.

setDuration

public void setDuration(long duration)

Set the duration.

Parameters:

duration - new duration

See Also:

getDuration()

setPosition

public void setPosition(long position)

Set the position.

Parameters:

position - new position

See Also:

getPosition()

getConvergenceDuration

public long getConvergenceDuration()

Time difference in IStream#getTimeBase() units
from the presentation time stamp of this
packet to the point at which the output from the decoder has converged
independent from the availability of previous frames. That is, the
frames are virtually identical no matter if decoding started from
the very first frame or from this keyframe.
Is Global#NO_PTS if unknown.
This field is not the display duration of the current packet.

The purpose of this field is to allow seeking in streams that have no
keyframes in the conventional sense. It corresponds to the
recovery point SEI in H.264 and match_time_delta in NUT. It is also
essential for some types of subtitle streams to ensure that all
subtitles are correctly displayed after seeking.

If you didn't follow that, try drinking one to two glasses
of Absinthe. It won't help, but it'll be more fun.

Returns:

the convergence duration

setConvergenceDuration

public void setConvergenceDuration(long duration)

Set the convergence duration.

Parameters:

duration - the new duration

reset

public void reset(int payloadSize)

Discard the current payload and allocate a new payload.

Note that if any people have access to the old payload using
getData(), the memory will continue to be available to them
until they release their hold of the Buffer.

When requesting a packet size, the system
may allocate a larger payloadSize.

Parameters:

payloadSize - The (minimum) payloadSize of this packet in bytes. It is ok to
pass in 0 here, in which case the packet will later allocate memory if needed.