Package net.paulhertz.pixelaudio.schedule

Class AudioScheduler<H>

java.lang.Object

net.paulhertz.pixelaudio.schedule.AudioScheduler<H>

public final class AudioScheduler<H>
extends Object

AudioScheduler A sample-accurate scheduler for things that should occur at specific times in an audio stream.

Two event shapes

• PointEvent: happens once at an absolute sample time.
• SpanEvent: is active over an interval [startSample, endSample) and can report start/end offsets plus per-block callbacks while active.

Threading model

• schedulePoint(...) and scheduleSpan(...) may be called from any thread.
• processBlock(...) must be called exactly once per audio block on the audio thread.

Happenings

The generic type parameter H is a user-defined "Happening": a compact piece of information that you want to schedule in time (e.g., x/y coordinates, pan/gain, an instrument id, a brush reference, or a small command object). A Happening is carried by events and delivered to handlers at the correct time.

Sample accuracy

processBlock(...) reports an offsetInBlock for point events and span boundaries, so you can align actions to an exact sample within the current audio block. If your instrument can only start on block boundaries, you can still use this scheduler for deterministic block timing today, and later upgrade your instrument to accept offsets without changing scheduling code.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	AudioScheduler.LatePolicy	Policy for point events whose sampleTime is already in the past when processed.
static final class	AudioScheduler.PointEvent<H>	A one-shot event that occurs at an absolute sample index.
static interface	AudioScheduler.PointHandler<H>
static final class	AudioScheduler.SpanEvent<H>	A duration event active on [startSample, endSample) where endSample is exclusive.
static interface	AudioScheduler.SpanHandler<H>

Field Summary

Fields

Modifier and Type	Field	Description
private final ConcurrentLinkedQueue<Object>	inbox
private AudioScheduler.LatePolicy	latePolicy
private final PriorityQueue<Object>	queue

Constructor Summary

Constructors

Constructor	Description
AudioScheduler()

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears all pending events (both newly scheduled and already queued).
private void	drainInbox()	Called only on the audio thread.
AudioScheduler.LatePolicy	latePolicy()
void	processBlock(long blockStartSample, int blockSize, AudioScheduler.PointHandler<H> pointHandler, AudioScheduler.SpanHandler<H> spanHandler)	Process one audio block.
void	schedulePoint(long sampleTime, H happening)	Schedule a point event at an absolute sample time.
void	scheduleSpan(long startSample, long endSample, H happening)	Schedule a span event active on [startSample, endSample).
void	setLatePolicy(AudioScheduler.LatePolicy policy)	Set how late point events are handled.
private static long	startSampleOf(Object o)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

inbox

private final ConcurrentLinkedQueue<Object> inbox

queue

private final PriorityQueue<Object> queue

latePolicy

private AudioScheduler.LatePolicy latePolicy

Constructor Details

AudioScheduler

public AudioScheduler()

Method Details

setLatePolicy

public void setLatePolicy(AudioScheduler.LatePolicy policy)

Set how late point events are handled. Default is AudioScheduler.LatePolicy.DROP.

latePolicy

public AudioScheduler.LatePolicy latePolicy()

schedulePoint

public void schedulePoint(long sampleTime,
 H happening)

Schedule a point event at an absolute sample time.

Parameters:

sampleTime - absolute sample index (0-based)

happening - the Happening to deliver

scheduleSpan

public void scheduleSpan(long startSample,
 long endSample,
 H happening)

Schedule a span event active on [startSample, endSample).

Parameters:

startSample - absolute start sample (inclusive)

endSample - absolute end sample (exclusive)

happening - the Happening to deliver

clear

public void clear()

Clears all pending events (both newly scheduled and already queued). Safe to call from any thread.

drainInbox

private void drainInbox()

Called only on the audio thread.

startSampleOf

private static long startSampleOf(Object o)

processBlock

public void processBlock(long blockStartSample,
 int blockSize,
 AudioScheduler.PointHandler<H> pointHandler,
 AudioScheduler.SpanHandler<H> spanHandler)

Process one audio block. Call exactly once per block on the audio thread.

All point events that occur within this block (or earlier, if AudioScheduler.LatePolicy.CLAMP_TO_BLOCK_START) will be delivered to pointHandler. Span events will deliver start/end callbacks (when the boundary falls within this block) and an onBlock callback for each block they overlap.

Parameters:

blockStartSample - absolute sample index of the first sample in this block

blockSize - number of samples in this block

pointHandler - handler for point events (may be null if you never schedule points)

spanHandler - handler for span events (may be null if you never schedule spans)