io.humble.video

Class MediaAudio

java.lang.Object

io.humble.ferry.RefCounted

io.humble.video.Media

io.humble.video.MediaRaw

io.humble.video.MediaSampled

io.humble.video.MediaAudio

public class MediaAudio
extends MediaSampled

Raw audio data.

The data described by the sample format is always in native-endian order.

The floating-point formats are based on full volume being in the range
[-1.0, 1.0]. Any values outside this range are beyond full volume level.

The data layout is as follows:

For planar sample formats, each audio channel is in a separate data plane,
and MediaAudio#getDataLineSize(int) is the buffer size, in bytes, for a single plane. All data
planes must be the same size. For packed sample formats, only the first data
plane is used, and samples for each channel are interleaved. In this case,
MediaAudio#getDataLineSize(int) is the buffer size, in bytes, for the 1 plane.

Field Summary

Fields inherited from class io.humble.video.Media

DEFAULT_TIME_STAMP_FORMAT

Method Summary

Modifier and Type	Method and Description
MediaAudio	copyReference() Create a new MediaAudio 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	getBytesPerSample() Number of bytes in one sample of one channel of audio in this object.
AudioChannel.Layout	getChannelLayout() What is the channel layout of the audio in this buffer?
int	getChannels() Number of channels of audio in this object.
Buffer	getData(int plane) Get any underlying raw data available for this object.
int	getDataPlaneSize(int plane) The total number of bytes in #getData() that represent valid audio data. If #isComplete() returns true, this returns the total number of bytes returned by #getData(int) that are readable from.
AudioFormat.Type	getFormat() Format of audio in this object.
int	getMaxNumSamples()
int	getNumDataPlanes() Returns the number of data planes in this object.
int	getNumSamples() The number of samples in this frame of sampled data.
int	getSampleRate() Sample rate of audio, or 0 if unknown.
int	hashCode() Get a hashable value for this object.
boolean	isComplete() Does this object have complete data? If not, other methods may return unknown.
boolean	isKey() Was this audio decoded from a key packet?
boolean	isPlanar() Is audio laid out in a planar format?
static MediaAudio	make(Buffer buffer, int numSamples, int sampleRate, int channels, AudioChannel.Layout channelLayout, AudioFormat.Type format) Create a MediaAudio using the given buffer. Note: that the Buffer.getBufferSize() constraints the max number of samples we can place in here, and HumbleVideo needs to reserve some of the buffer for, um, stuff (assume at least 64 bytes).
static MediaAudio	make(int numSamples, int sampleRate, int channels, AudioChannel.Layout channelLayout, AudioFormat.Type format) Create a MediaAudio and the underlying data.
static MediaAudio	make(MediaAudio src, boolean copy) Create a MediaAudio by either referencing or copying another MediaAudio.
void	setComplete(boolean complete) Call this if you modify the samples and are now done.
void	setNumSamples(int numSamples) Set the number of samples in the buffer.
String	toString()

Methods inherited from class io.humble.video.MediaRaw

getBestEffortTimeStamp, getMetaData, getPacketDts, getPacketDuration, getPacketPts, getPacketSize, getPts, getTimeBase, getTimeStamp, setTimeBase, setTimeStamp

Methods inherited from class io.humble.video.Media

getFormattedTimeStamp, getFormattedTimeStamp

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

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

Overrides:

copyReference in class MediaSampled

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 MediaSampled

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 MediaSampled

Returns:

the hashable value.

toString

public String toString()

Overrides:

toString in class Object

make

public static MediaAudio make(int numSamples,
                              int sampleRate,
                              int channels,
                              AudioChannel.Layout channelLayout,
                              AudioFormat.Type format)

Create a MediaAudio and the underlying data. Will allocate a buffer to back this data.

Parameters:

numSamples - The number of samples of audio that will be placed in this MediaAudio object.

sampleRate - The sample rate (per second) of this audio.

channels - The number of channels of audio that will be placed in this MediaAudio object.
channelLayout The channel layout of audio that will be placed in this MediaAudio object.

format - The format of the audio placed in this MediaAudio object.

Returns:

A MediaAudio object, or null on failure.

make

public static MediaAudio make(Buffer buffer,
                              int numSamples,
                              int sampleRate,
                              int channels,
                              AudioChannel.Layout channelLayout,
                              AudioFormat.Type format)

Create a MediaAudio using the given buffer.

Note: that the Buffer.getBufferSize() constraints the max number
of samples we can place in here, and HumbleVideo needs to reserve some
of the buffer for, um, stuff (assume at least 64 bytes). So #getMaxNumSamples()
may not return as many as you think you can fit in here.

Parameters:

buffer - A buffer to back the audio with. If not large enough to hold all the samples (with alignment on 32-bit boundaries if planar),
then an error results.

numSamples - The number of samples of audio that will be placed in this MediaAudio object.

sampleRate - The sample rate (per second) of this audio.

channels - The number of channels of audio that will be placed in this MediaAudio object.
channelLayout The channel layout of audio that will be placed in this MediaAudio object.

format - The format of the audio placed in this MediaAudio object.

Returns:

A MediaAudio object, or null on failure.

make

public static MediaAudio make(MediaAudio src,
                              boolean copy)

Create a MediaAudio by either referencing or copying another MediaAudio.

This method is very useful when you want to change some meta-data about MediaAudio (such as
changing a timestamp) without effecting other users of the same underlying data.

It can also be useful to create a copy of the raw audio data in the buffers in the
event you are doing audio manipulation and do not want to effect other people
using the audio.

Parameters:

src - MediaAudio to reference

copy - true if we should copy all data. false if we should just gain a reference to the same underlying data in src.

Returns:

a MediaAudio object, or null on failure.

getData

public Buffer getData(int plane)

Get any underlying raw data available for this object.

Parameters:

plane - The plane number if getFormat() is Planar (rather than packed) audio. Pass zero for packed data.

Returns:

The raw data, or null if not accessible.

getDataPlaneSize

public int getDataPlaneSize(int plane)

The total number of bytes in #getData() that represent valid audio data.
If #isComplete() returns true, this returns the total number of bytes
returned by #getData(int) that are readable from. Otherwise it will
return the total number of bytes that are writable to.

Returns:

The size in bytes of that plane of audio data.

getNumDataPlanes

public int getNumDataPlanes()

Returns the number of data planes in this object.

getMaxNumSamples

public int getMaxNumSamples()

Returns:

maximum of samples of #getChannels() #getFormat() audio that can be put in this MediaAudio object.

getNumSamples

public int getNumSamples()

Description copied from class: MediaSampled

The number of samples in this frame of sampled data.

Overrides:

getNumSamples in class MediaSampled

Returns:

the actual number of samples in this object

setNumSamples

public void setNumSamples(int numSamples)

Set the number of samples in the buffer. Must not be more than
#getMaxNumSamples(). Caller is responsible for making
sure buffer actually matches this.

getBytesPerSample

public int getBytesPerSample()

Number of bytes in one sample of one channel of audio in this object.

setComplete

public void setComplete(boolean complete)

Call this if you modify the samples and are now done. This
updates the pertinent information in the structure.

Overrides:

setComplete in class MediaRaw

Parameters:

complete - true if complete; false if not.

See Also:

Media.isComplete()

getSampleRate

public int getSampleRate()

Sample rate of audio, or 0 if unknown.

getChannels

public int getChannels()

Number of channels of audio in this object.

getFormat

public AudioFormat.Type getFormat()

Format of audio in this object.

isComplete

public boolean isComplete()

Does this object have complete data? If not, other methods may return unknown.

Overrides:

isComplete in class Media

Returns:

Has setComplete() been called and the buffer populated.

isKey

public boolean isKey()

Was this audio decoded from a key packet?

Overrides:

isKey in class MediaRaw

Returns:

true if it's a key, false if not

isPlanar

public boolean isPlanar()

Is audio laid out in a planar format?

getChannelLayout

public AudioChannel.Layout getChannelLayout()

What is the channel layout of the audio in this buffer?