evseq v0.0.5
evseq
A simple event sequencer for Node.js.
EvSeq is useful for controlling audio, lighting, and anything else that needs to be played, paused, stopped and/or resumed. It is especially well suited for use with RxJS.
Hello world
var EvSeq = require("evseq");
var ril = EvSeq.rerouteIfLate('foo', 'ignore');
var Rx = require('rx');
var Observable = Rx.Observable;
var EventEmitter = require('events').EventEmitter;
var P = require('bluebird').Promise;
var e = new EventEmitter();
var sum = 0;
var seq = new EvSeq(e).at('0s', ril, 1)
.at('1.5s', ril, 1)
.at('3.1s', ril, 1, 'aGroupName')
.at('4.5s', ril, 1, 'aGroupName')
.at('5.8s', ril, 1);
var subscription = Observable.fromEvent(e, 'foo')
.subscribe((x) => sum += x);
P.resolve(seq.play()).
delay(2000).
then(()=>{
console.log(sum); // 2
seq.stop(); // stop rewinds to beginning
sum=0; // rest to 0
return P.resolve(seq.play())
}).
delay(2000).
then(()=>P.resolve(seq.pause())).
delay(2000).
then(()=>{
console.log(sum); // pause works, will be 2
return P.resolve(seq.play());
}).
delay(2000).
then(()=>P.resolve(seq.softpause())).
delay(2000).
then(()=>{
// softpause allows pending members of a group to be emitted
console.log(sum); // will be 4 because of softpause
return P.resolve(seq.stop());
});
API
constructor
var myEvSeq = new EvSeq(e: EventEmitter, xtra ?: any)
Create a EvSeq
object that emits events from e
, passing xtra
to a calling function at the time of emission.
at
myEvSeq.at(t: string,
key: string | (x: number, y: any) => void,
val: mixed | (x: number, y: any) => void,
group ? : string): EvSeq
Schedules an event at time t
. Time t
can be expressed in seconds, milliseconds, microseconds or nanoseconds. It uses the same format of timing as nanotimer.
Key key
and value value
can be either literals or functions.
- If they are literals, the are emitted in the traditional sense from the event passed into the
EvSeq
constructor, ie:e.emit(key, value)
. - If they are functions, then the return value of the functions are used for the key and value to the emitter. The function takes two parameters: the first is the error (meaning how late the emission happens compared to the request) and the second are the extra arguments passed to the
EvSeq
constructor. See Functions passed as arguments toat
.
play
myEvSeq.play(): void
Plays a seequence, picking up from the point at which it was paused or to which it was seeked, otherwise starts from 0s
.
pause
myEvSeq.pause(): void
Pauses a sequence. pause
differs from stop
in that pause
does not set the timeline to 0s
.
stop
myEvSeq.stop(): void
Stops a sequence. stop
differs from pause
in that stop
sets the timeline to 0s
.
seek
myEvSeq.seek(t: string): void
Fastforwards a sequence to time t
. This does not interrupt playing if a sequence is currently playing.
softpause
myEvSeq.softpause(): void
Like pause, except events in the event's group will execute after the pause. For example, in:
var e = new EventEmitter();
var seq = new EvSeq(e).at('0s', 'foo', 1)
.at('2.1s', 'foo', 1)
.at('3.1s', 'foo', 1, 'aGroupName')
.at('4.5s', 'foo', 1, 'aGroupName')
.at('5.8s', 'foo', 1);
If softpause
is called between 3.1 and 4.5 seconds, the event at 4.5s
will be emitted.
print
myEvSeq.print(): void
Prints information about the sequence to the console.
rerouteIfLate
EvSeq.rerouteIfLate(ifOnTime: any, ifLate: any): (i: number) => any
Convenience static
method for rerouting an event if it is late (meaning if it has positive error for its time value - see (Functions passed as arguments to at
. The value at ifOnTime
is returned if the function is ontime, otherwise ifLate
is returned. For example:
mySequence.at('10s', EvSeq.rerouteIfLate('eventICareAbout', 'trashbin'), 1)
Functions passed as arguments to at
As stated above, a function passed to at
for the key or value is in the form:
function(i: number, x: any)
Where i
is the error in time and x
is whateve extra value is passed into the EvSeq
constructor. The error parameter is perhaps the most important thing to understand about EvSeq
and is where its power lies. If a sequence is paused after 3 seconds and then resumed, any event that happens before the 3 second mark is called again with the difference in time as the first argument. For example, an event scheduled to be emitted at 0.5s
will be called with an error of 2.5
if the pause happened at 3 seconds. This allows audio files, lighting cues, whatever to pick up where they left off after pausing. A utility function, rerouteIfLate
, helps ignore events that happen before a particular timestamp.