GlueGen v2.6.0-rc-20250712
GlueGen, Native Binding Generator for Java™ (public API).
com.jogamp.common.av.AudioSink Interface Reference
Collaboration diagram for com.jogamp.common.av.AudioSink:

Classes

class  AudioDataFrame
 Audio data frame example of AudioFrame with actual audio data being attached. More...
 
class  AudioFrame
 Abstract audio frame containing multiple audio samples per channel, tracking TimeFrameI pts and size in bytes. More...
 

Public Member Functions

boolean makeCurrent (final boolean throwException)
 Makes the audio context current on the calling thread, if implementation utilizes context locking. More...
 
boolean release (final boolean throwException)
 Releases control of this audio context from the current thread, if implementation utilizes context locking. More...
 
boolean isAvailable ()
 Returns the available state of this instance. More...
 
float getPlaySpeed ()
 Returns the playback speed. More...
 
boolean setPlaySpeed (float s)
 Sets the playback speed. More...
 
float getVolume ()
 Returns the volume. More...
 
boolean setVolume (float v)
 Sets the volume [0f..1f]. More...
 
int getSourceCount ()
 Returns the number of sources the used device is capable to mix. More...
 
float getDefaultLatency ()
 Returns the default (minimum) latency in seconds. More...
 
AudioFormat getNativeFormat ()
 Returns the native AudioFormat by this sink. More...
 
AudioFormat getPreferredFormat ()
 Returns the preferred AudioFormat by this sink. More...
 
void setChannelLimit (final int cc)
 Limit maximum supported audio channels by user. More...
 
boolean isSupported (AudioFormat format)
 Returns true if the given format is supported by the sink, otherwise false. More...
 
boolean init (AudioFormat requestedFormat, int frameDurationHint, int queueSize)
 Initializes the sink. More...
 
AudioFormat getChosenFormat ()
 Returns the AudioFormat as chosen by init(AudioFormat, float, int), i.e. More...
 
float getLatency ()
 Returns the (minimum) latency in seconds of this sink as set by init(AudioFormat, float, int), see getDefaultLatency(). More...
 
boolean isPlaying ()
 Returns true, if play() has been requested and the sink is still playing, otherwise false. More...
 
void play ()
 Play buffers queued via enqueueData(AudioFrame) from current internal position. More...
 
void pause ()
 Pause playing buffers while keeping enqueued data incl. More...
 
void flush ()
 Flush all queued buffers, implies pause(). More...
 
void destroy ()
 Destroys this instance, i.e. More...
 
int getFrameCount ()
 Returns the number of allocated buffers as requested by init(AudioFormat, float, int). More...
 
int getEnqueuedFrameCount ()
 Returns the current enqueued frames count since init(AudioFormat, float, int). More...
 
int getQueuedFrameCount ()
 Returns the current number of frames queued for playing. More...
 
int getQueuedByteCount ()
 Returns the current number of bytes queued for playing. More...
 
float getQueuedDuration ()
 Returns the current queued frame time in seconds for playing. More...
 
float getAvgFrameDuration ()
 Returns average frame duration last assessed @ enqueueData(int, ByteBuffer, int) when queue was full. More...
 
PTS getPTS ()
 Return the audio presentation timestamp (PTS). More...
 
int getLastBufferedPTS ()
 Return the last buffered audio presentation timestamp (PTS) in milliseconds. More...
 
int getFreeFrameCount ()
 Returns the current number of frames in the sink available for writing. More...
 
AudioFrame enqueueData (int pts, ByteBuffer bytes, int byteCount)
 Enqueue byteCount bytes as a new AudioFrame to this sink. More...
 
PTS updateQueue ()
 Update queue beyond enqueueData(int, ByteBuffer, int) including audio PTS. More...
 

Static Public Attributes

static final boolean DEBUG = Debug.debug("AudioSink")
 
static final int DefaultFrameDuration = 32
 Default frame duration in millisecond, i.e. More...
 
static final int DefaultQueueSize = 16 * 32
 Initial audio queue size in milliseconds. More...
 
static final int DefaultQueueSizeWithVideo = 32 * 32
 Audio queue size w/ video in milliseconds. More...
 
static final AudioFormat DefaultFormat
 Default AudioFormat, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian]. More...
 

Detailed Description

Definition at line 34 of file AudioSink.java.

Member Function Documentation

◆ destroy()

void com.jogamp.common.av.AudioSink.destroy ( )

Destroys this instance, i.e.

closes all streams and devices allocated.

◆ enqueueData()

AudioFrame com.jogamp.common.av.AudioSink.enqueueData ( int  pts,
ByteBuffer  bytes,
int  byteCount 
)

Enqueue byteCount bytes as a new AudioFrame to this sink.

The data must comply with the chosen AudioFormat as set via init(AudioFormat, float, int).

init(AudioFormat, float, int) must be called first.

Parameters
ptspresentation time stamp in milliseconds for the newly enqueued AudioFrame
bytesaudio data for the newly enqueued AudioFrame
Returns
the enqueued internal AudioFrame.
See also
#init(AudioFormat, float, int)

◆ flush()

void com.jogamp.common.av.AudioSink.flush ( )

Flush all queued buffers, implies pause().

init(AudioFormat, float, int) must be called first.

See also
play()
pause()
#enqueueData(AudioFrame)
#init(AudioFormat, float, int)

◆ getAvgFrameDuration()

float com.jogamp.common.av.AudioSink.getAvgFrameDuration ( )

Returns average frame duration last assessed @ enqueueData(int, ByteBuffer, int) when queue was full.

  avgFrameDuration = getQueuedDuration() / getQueuedFrameCount()

◆ getChosenFormat()

AudioFormat com.jogamp.common.av.AudioSink.getChosenFormat ( )

Returns the AudioFormat as chosen by init(AudioFormat, float, int), i.e.

it shall match the requestedFormat.

◆ getDefaultLatency()

float com.jogamp.common.av.AudioSink.getDefaultLatency ( )

Returns the default (minimum) latency in seconds.

Latency might be the reciprocal mixer-refresh-interval [Hz], e.g. 50 Hz refresh-rate = 20ms minimum latency.

May return 20ms for a 50 Hz refresh rate if undefined.

◆ getEnqueuedFrameCount()

int com.jogamp.common.av.AudioSink.getEnqueuedFrameCount ( )

Returns the current enqueued frames count since init(AudioFormat, float, int).

See also
#init(AudioFormat, float, int)

◆ getFrameCount()

int com.jogamp.common.av.AudioSink.getFrameCount ( )

Returns the number of allocated buffers as requested by init(AudioFormat, float, int).

See also
#init(AudioFormat, float, int)

◆ getFreeFrameCount()

int com.jogamp.common.av.AudioSink.getFreeFrameCount ( )

Returns the current number of frames in the sink available for writing.

init(AudioFormat, float, int) must be called first.

See also
#init(AudioFormat, float, int)

◆ getLastBufferedPTS()

int com.jogamp.common.av.AudioSink.getLastBufferedPTS ( )

Return the last buffered audio presentation timestamp (PTS) in milliseconds.

See also
getPTS()

◆ getLatency()

float com.jogamp.common.av.AudioSink.getLatency ( )

Returns the (minimum) latency in seconds of this sink as set by init(AudioFormat, float, int), see getDefaultLatency().

Latency might be the reciprocal mixer-refresh-interval [Hz], e.g. 50 Hz refresh-rate = 20ms minimum latency.

See also
#init(AudioFormat, float, int)

◆ getNativeFormat()

AudioFormat com.jogamp.common.av.AudioSink.getNativeFormat ( )

Returns the native AudioFormat by this sink.

The native format is guaranteed to be supported and shall reflect this sinks most native format, i.e. best performance w/o data conversion.

The native format is not impacted by setChannelLimit(int).

May return AudioSink#DefaultFormat if undefined.

See also
#init(AudioFormat, float, int)

◆ getPlaySpeed()

float com.jogamp.common.av.AudioSink.getPlaySpeed ( )

Returns the playback speed.

◆ getPreferredFormat()

AudioFormat com.jogamp.common.av.AudioSink.getPreferredFormat ( )

Returns the preferred AudioFormat by this sink.

The preferred format is a subset of getNativeFormat(), impacted by setChannelLimit(int).

Known AudioFormat attributes considered by implementations:

See also
getNativeFormat()
#init(AudioFormat, float, int)
setChannelLimit(int)
isSupported(AudioFormat)

◆ getPTS()

PTS com.jogamp.common.av.AudioSink.getPTS ( )

Return the audio presentation timestamp (PTS).

In case implementation updates the audio buffer passively, consider using updateQueue().

See also
updateQueue()
enqueueData(int, ByteBuffer, int)

◆ getQueuedByteCount()

int com.jogamp.common.av.AudioSink.getQueuedByteCount ( )

Returns the current number of bytes queued for playing.

init(AudioFormat, float, int) must be called first.

See also
#init(AudioFormat, float, int)

◆ getQueuedDuration()

float com.jogamp.common.av.AudioSink.getQueuedDuration ( )

Returns the current queued frame time in seconds for playing.

init(AudioFormat, float, int) must be called first.

See also
#init(AudioFormat, float, int)

◆ getQueuedFrameCount()

int com.jogamp.common.av.AudioSink.getQueuedFrameCount ( )

Returns the current number of frames queued for playing.

init(AudioFormat, float, int) must be called first.

See also
#init(AudioFormat, float, int)

◆ getSourceCount()

int com.jogamp.common.av.AudioSink.getSourceCount ( )

Returns the number of sources the used device is capable to mix.

This device attribute is only formally exposed and not used, since an audio sink is only utilizing one source.

May return -1 if undefined.

Returns

◆ getVolume()

float com.jogamp.common.av.AudioSink.getVolume ( )

Returns the volume.

◆ init()

boolean com.jogamp.common.av.AudioSink.init ( AudioFormat  requestedFormat,
int  frameDurationHint,
int  queueSize 
)

Initializes the sink.

Implementation must match the given requestedFormat AudioFormat.

Caller shall validate requestedFormat via isSupported(AudioFormat) beforehand and try to find a suitable supported one. getPreferredFormat() may help.

Parameters
requestedFormatthe requested AudioFormat.
frameDurationHintaverage AudioFrame duration hint in milliseconds. May assist to adjust latency of the backend, as currently used for JOAL's ALAudioSink. A value below 30ms or DefaultFrameDuration may increase the audio processing load. Assumed as DefaultFrameDuration, if frameDuration < 1 ms.
queueSizequeue size in milliseconds, see DefaultQueueSize.
Returns
true if successful, otherwise false
See also
enqueueData(int, ByteBuffer, int)
getAvgFrameDuration()

◆ isAvailable()

boolean com.jogamp.common.av.AudioSink.isAvailable ( )

Returns the available state of this instance.

The available state is affected by this instance overall availability, i.e. after instantiation, as well as by destroy().

Here is the caller graph for this function:

◆ isPlaying()

boolean com.jogamp.common.av.AudioSink.isPlaying ( )

Returns true, if play() has been requested and the sink is still playing, otherwise false.

◆ isSupported()

boolean com.jogamp.common.av.AudioSink.isSupported ( AudioFormat  format)

Returns true if the given format is supported by the sink, otherwise false.

The getPreferredFormat() is used to validate compatibility with the given format.

See also
#init(AudioFormat, float, int)
getPreferredFormat()

◆ makeCurrent()

boolean com.jogamp.common.av.AudioSink.makeCurrent ( final boolean  throwException)

Makes the audio context current on the calling thread, if implementation utilizes context locking.

If implementation doesn't utilizes context locking, method always returns true.

Recursive call to makeCurrent() and hence release() are supported.

At any point in time one context can only be current by one thread, and one thread can only have one context current.

Parameters
throwExceptionif true, throws ALException if context is null, current thread holds another context or failed to natively make current
Returns
true if current thread holds no other context and context successfully made current, otherwise false
See also
release()

◆ pause()

void com.jogamp.common.av.AudioSink.pause ( )

Pause playing buffers while keeping enqueued data incl.

it's internal position.

See also
play()
flush()
#enqueueData(AudioFrame)

◆ play()

void com.jogamp.common.av.AudioSink.play ( )

Play buffers queued via enqueueData(AudioFrame) from current internal position.

If no buffers are yet queued or the queue runs empty, playback is being continued when buffers are enqueued later on.

See also
#enqueueData(AudioFrame)
pause()

◆ release()

boolean com.jogamp.common.av.AudioSink.release ( final boolean  throwException)

Releases control of this audio context from the current thread, if implementation utilizes context locking.

If implementation doesn't utilizes context locking, method always returns true.

Recursive call to makeCurrent() and hence release() are supported.

Parameters
throwExceptionif true, throws ALException if context has not been previously made current on current thread or native release failed.
Returns
true if context has previously been made current on the current thread and successfully released, otherwise false
See also
makeCurrent()

◆ setChannelLimit()

void com.jogamp.common.av.AudioSink.setChannelLimit ( final int  cc)

Limit maximum supported audio channels by user.

Must be set before getPreferredFormat(), isSupported(AudioFormat) and naturally init(AudioFormat, int, int).

May be utilized to enforce 1 channel (mono) downsampling in combination with JOAL/OpenAL to experience spatial 3D position effects.

Parameters
ccmaximum supported audio channels, will be clipped [1..getNativeFormat().channelCount]
See also
getNativeFormat()
getPreferredFormat()
isSupported(AudioFormat)
init(AudioFormat, int, int)

◆ setPlaySpeed()

boolean com.jogamp.common.av.AudioSink.setPlaySpeed ( float  s)

Sets the playback speed.

To simplify test, play speed is normalized, i.e.

  • 1.0f: if Math.abs(1.0f - rate) < 0.01f
Returns
true if successful, otherwise false, i.e. due to unsupported value range of implementation.

◆ setVolume()

boolean com.jogamp.common.av.AudioSink.setVolume ( float  v)

Sets the volume [0f..1f].

To simplify test, volume is normalized, i.e.

  • 0.0f: if Math.abs(v) < 0.01f
  • 1.0f: if Math.abs(1.0f - v) < 0.01f
Returns
true if successful, otherwise false, i.e. due to unsupported value range of implementation.

◆ updateQueue()

PTS com.jogamp.common.av.AudioSink.updateQueue ( )

Update queue beyond enqueueData(int, ByteBuffer, int) including audio PTS.

Useful in case implementation only updates the buffer passively via enqueueing data to add new data to the queue and not on a event basis.

Returns
the updated PTS instance
See also
getPTS()
enqueueData(int, ByteBuffer, int)

Member Data Documentation

◆ DEBUG

final boolean com.jogamp.common.av.AudioSink.DEBUG = Debug.debug("AudioSink")
static

Definition at line 35 of file AudioSink.java.

◆ DefaultFormat

final AudioFormat com.jogamp.common.av.AudioSink.DefaultFormat
static
Initial value:
= new AudioFormat(44100, 16, 2, true ,
true , false , true )

Default AudioFormat, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian].

Definition at line 46 of file AudioSink.java.

◆ DefaultFrameDuration

final int com.jogamp.common.av.AudioSink.DefaultFrameDuration = 32
static

Default frame duration in millisecond, i.e.

1 AudioFrame per {@value} ms.

Definition at line 38 of file AudioSink.java.

◆ DefaultQueueSize

final int com.jogamp.common.av.AudioSink.DefaultQueueSize = 16 * 32
static

Initial audio queue size in milliseconds.

{@value} ms, i.e. 16 AudioFrames per 32 ms. See init(AudioFormat, float, int).

Definition at line 41 of file AudioSink.java.

◆ DefaultQueueSizeWithVideo

final int com.jogamp.common.av.AudioSink.DefaultQueueSizeWithVideo = 32 * 32
static

Audio queue size w/ video in milliseconds.

{@value} ms, i.e. 32 AudioFrames per 32 ms. See init(AudioFormat, float, int).

Definition at line 43 of file AudioSink.java.


The documentation for this interface was generated from the following file: