sc-scheduling

Simple library to schedule events in Node.js and the browser.

The abstractions provided by the library are built in such way that they can be used in distributed contexts, allowing to synchronize events and controls among multiple devices and clients.

Install

npm install --save @ircam/sc-scheduling

Example Use

import { Scheduler } from '@ircam/sc-scheduling';

const audioContext = new AudioContext();
// create a scheduler in the timeline of the audio context
const scheduler = new Scheduler(() => audioContext.currentTime);
// schedule an audio event to be scheduler every seconds
schedule.add(currentTime => {
  doSomethingAtCurrentTime(currentTime);
  // ask to be called back in 1 second from currentTime
  return currentTime + 1;
});

Terminology

time refers to the timeline of the parent
position refers to the timeline of the children
Transport is the thing that control timelines or engines with play / pause / etc.
Timeline is an abstraction that can host abstractions and place them in time according to each others

API

SchedulerProcessor
- Parameters
Scheduler
- Parameters
- Examples
- period
- lookahead
- currentTime
- audioTime
- processorTime
- defer
- has
- add
- reset
- remove
- clear
SchedulerEvent
- tickLookahead
TransportProcessor
- Parameters
Transport
- Parameters
- Examples
- serialize
- scheduler
- currentTime
- processorTime
- currentPosition
- getPositionAtTime
- start
- stop
- pause
- seek
- loop
- loopStart
- loopEnd
- speed
- cancel
- addEvent
- addEvents
- add
- has
- remove
- clear
TransportEvent
- Parameters
- type
- time
- position
- speed
- loop
- loopStart
- loopEnd
- tickLookahead

SchedulerProcessor

Processor to add into a Scheduler.

The processor will be called back by the Scheduler at the time it request, do some processing and return the next time at which it wants to be called back.

Note that the APIs of the SchedulerProcessor and of a TransportProcessor are made in such way that it is possible to implement generic processors that can be added both to a Scheduler and to a Transport.

Type: function

Parameters

currentTime number Current time in the timeline of the scheduler
processorTime number Current time in the timeline of the processor see Scheduler#options.currentTimeToProcessorTimeFunction.
event SchedulerEvent Event that holds informations about the current scheduler call.

Scheduler

The Scheduler interface implements a lookahead scheduler that can be used to schedule events in an arbitrary timelines.

It aims at finding a tradeoff between time precision, real-time responsiveness and the weaknesses of the native timers (i.e. setTimeout and setInterval)

For an in-depth explaination of the pattern, see https://web.dev/audio-scheduling/

Parameters

getTimeFunction function Function that returns a time in seconds, defining the timeline in which the scheduler is running.
$1 Object (optional, default {})
- $1.period (optional, default 0.025)
- $1.lookahead (optional, default 0.1)
- $1.queueSize (optional, default 1e3)
- $1.currentTimeToProcessorTimeFunction (optional, default identity)
- $1.currentTimeToAudioTimeFunction (optional, default null)
- $1.maxRecursions (optional, default 100)
- $1.verbose (optional, default false)
options object Options of the scheduler

Examples

import { Scheduler } from '@ircam/sc-scheduling';
import { getTime } from '@ircam/sc-utils';

const scheduler = new Scheduler(getTime);

const processor = (currentTime, processorTime, infos) => {
  console.log(currentTime);
  return currentTime + 0.1; // ask to be called back every 100ms
}

// start processor in 1 second
scheduler.add(processor, getTime() + 1);

period

Period of the scheduler, in seconds.

Minimum time span between the scheduler checks for events, in seconds. Throws if negative or greater than lookahead.

Type: number

lookahead

Lookahead duration, in seconds. Throws if negative or lower than period.

Type: number

currentTime

Current time in the scheduler timeline, in seconds.

Basically an accessor for getTimeFunction parameter given in constructor.

Type: number

audioTime

[deprecated] Scheduler current audio time according to currentTime

Type: number

processorTime

Processor time, in seconds, according to currentTime and the transfert function provided in options.currentTimeToProcessorTimeFunction.

If options.currentTimeToProcessorTimeFunction has not been set, is equal to currentTime.

Type: number

defer

Execute a function once at a given time.

Calling defer compensates for the tick lookahead introduced by the scheduling with a setTimeout. Can be usefull for example to synchronize audio events which natively scheduled with visuals which have no internal timing/scheduling ability.

Be aware that this method will introduce small timing error of 1-2 ms order of magnitude due to the setTimeout.

Parameters

deferedProcessor SchedulerProcessor Callback function to schedule.
time number Time at which the callback should be scheduled.

Examples

const scheduler = new Scheduler(getTime);

scheduler.add((currentTime, processorTime) => {
  // schedule some audio event
  playSomeSoundAt(processorTime);
  // defer execution of visual display to compensate the tickLookahead
  scheduler.defer(displaySomeSynchronizedStuff, currentTime);
  // ask the scheduler to call back in 1 second
  return currentTime + 1;
});

has

Check whether a given processor has been added to this scheduler

Parameters

processor SchedulerProcessor Processor to test.

Returns boolean

add

Add a processor to the scheduler.

Note that given time is considered a logical time and that no particular checks are made on it as it might break synchronization between several processors. So if the given time is in the past, the processor will be called in a recursive loop until it reaches current time. This is the responsibility of the consumer code to handle such possible issues.

Parameters

processor SchedulerProcessor Processor to add to the scheduler
time number Time at which the processor should be launched. (optional, default this.currentTime)
priority Number Additional priority in case of equal time between two processor. Higher priority means the processor will processed first. (optional, default 0)

reset

Reset next time of a given processor.

If time is not a number, the processor is removed from the scheduler.

Note that given time is considered a logical time and that no particular checks are made on it as it might break synchronization between several processors. So if the given time is in the past, the processor will be called in a recursive loop until it reaches current time. This is the responsibility of the consumer code to handle such possible issues.

Be aware that calling this method within a processor callback function won't work, because the reset will always be overriden by the processor return value.

Parameters

processor SchedulerProcessor The processor to reschedule
time number Time at which the processor must be rescheduled (optional, default undefined)

remove

Remove a processor from the scheduler.

Parameters

processor SchedulerProcessor The processor to reschedule

clear

Clear the scheduler.

SchedulerEvent

Scheduler information provided as third argument of a callback registered in the scheduler

tickLookahead

Delta time between tick time and current time, in seconds

Type: Number

TransportProcessor

Processor to add into a Transport.

The processor will be called back by the Transport on each transport event to define its behavior according to event. Between these events, it can be called as a regular SchedulerProcessor to do some processing.

Note that the APIs of the SchedulerProcessor and of a TransportProcessor are made in such way that it is possible to implement generic processors that can be added both to a Scheduler and to a Transport.

Type: function

Parameters

currentPosition number Current position in the timeline of the transport.
processorTime number Current time in the timeline of the processor see Scheduler#options.currentTimeToProcessorTimeFunction.
event (TransportEvent | SchedulerEvent) Event that holds informations about the current transport or scheduler call.

Transport

The Transport abstraction allows to define and manipulate a timeline.

All provided Transport commands (e.g. start, stop, etc) can be scheduled in the underlying scheduler timeline which makes it usable in distributed and synchronized contexts.

Parameters

scheduler Scheduler Instance of scheduler into which the transport should run
initialState object Initial state of the transport, to synchronize it from another transport state (see Transport#dumpState()). (optional, default null)

Examples

import { Scheduler, Transport, TransportEvent } from '@ircam/sc-scheduling';
import { getTime } from '@ircam/sc-utils';

const scheduler = new Scheduler(getTime);
const transport = new Transport(scheduler);

const processor = (position, time, infos) => {
  if (infos instanceof TransportEvent) {
     // ask to be called back only when the transport is running
     return infos.speed > 0 ? position : Infinity;
  }

  console.log(position);
  return position + 0.1; // ask to be called back every 100ms
}

transport.add(processor);
// start transport in 1 second
transport.start(getTime() + 1);

serialize

Retrieves the current state and event queue for the transport as a raw object.

The returned value can be used to initialize the state of another synchronized transport, cf. initialValue argument from constructor.

Returns object

scheduler

Pointer to the underlying scheduler

Type: Scheduler

currentTime

Current time from scheduler timeline, in seconds.

Type: number

processorTime

Current processor time, in seconds.

Type: number

currentPosition

Current transport position, in seconds.

Type: number

getPositionAtTime

Estimated position at given time according to the transport current state.

Parameters

time number Time to convert to position

Returns number