Time#

Clocks, delays, ramps, rate limiting and tempo.

17 objects. Every entry is pulled directly from the engine source via the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros (see YseEngine/patcher/pObject.h). The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects.

`.bline`#

Ramps a number to a target one step per bang, so whatever bangs it sets the pace. A list of target/count pairs makes a ramp of several segments; the right outlet bangs when the last target is reached.

Kind:: Control-rate

The ramp moves one step on every bang, and sends nothing between bangs.

Messages

bang: send the next step. With no ramp running it does nothing.
<target> <bangs>: reach the target over that many bangs.
four or more numbers: target/bangs pairs, travelled one after another. An odd last number is ignored. Three numbers are read as one pair and the third is ignored.
a number on its own: a target reached on the next bang.
stop: freeze where the ramp is and forget the rest, without a bang on the right outlet.
set <value>: move to that value without sending it, and stop the ramp.

A count of 0 or less takes one bang. A fractional count arrives on the first bang at or past it.

[.bline]   1 10 0 10, then 20 bangs  =>  0.1 0.2 ... 1. 0.9 ... 0.
                                         right outlet bangs on the 20th

New ramps, the output type and the length limit work as described under .line. Each value goes out on the thread of the bang that asked for it.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	A bang sends the next step. A target, ‘<target> <bangs>’, or target/bangs pairs set the ramp. ‘stop’ and ‘set <value>’ control it.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any number	The ramp, one value per bang, ending exactly on the target. An int or a float, as on .line.
1	done	BANG	—	A bang when the last target is reached. A ramp cut short by ‘stop’ sends none.

Parameters

Name	Default	Range	Description
initial	0	any number	The starting value. Written as a float (‘0.’) it makes the object send floats.

`.clocker`#

While running, sends the time since it was started, in milliseconds, every interval (5 ms by default). With a clock bound, a second outlet sends the beats that clock has moved in the same time.

Kind:: Control-rate

Use it to drive anything that needs a position in time rather than a pulse: an envelope, a progress display, a sweep.

Messages

a non-zero number: start, counting from 0. A running clocker starts again.
0 or stop: stop.
bang: start a stopped clocker. On a running one, set the count back to 0 and keep the reports at the same moments.
reset: the same reset. It does nothing while the clocker is stopped.
clock <name>: bind a clock for the beats outlet and for a beat interval. A bare clock removes it.

The first report comes one interval after the start, not at the start. The milliseconds are measured on the system’s steady clock, so a report that is late still carries the real time since the start.

The interval can be changed while the clocker runs; the reports carry on from where they were. A beat interval works as described under .delay: the reports then fall on that clock’s beat grid, and a clocker given a beat interval but no clock does not start.

The beats outlet

Whenever a clock is bound, each report also sends the beats that clock has moved since the start, just before the milliseconds. The two differ when the tempo changes, and the beats stand still while the clock is stopped. If the clock does not exist yet when the clocker starts, the beats are counted from the first report that finds it. Binding another clock while running starts the beat count again on the new clock and leaves the milliseconds alone.

The millisecond engine runs on the timer thread, like .metro’s. See Time, scheduling and clocks.

Inlets

#	Label	Accepts	Range	Description
0	on/off	FLOAT, INT, BANG, LIST	0 or 1, bang, ‘stop’, ‘reset’, ‘clock <name>’	A non-zero number starts or restarts the clocker; 0 or ‘stop’ stops it. A bang starts a stopped clocker and resets a running one to 0, as ‘reset’ does. ‘clock <name>’ sets the clock for the beats outlet and a beat interval.
1	interval	FLOAT, INT, LIST	1+ ms, or a note value / tick count	Sets the reporting interval, in milliseconds or as a beat time. A running clocker keeps going at the new interval without restarting.

Outlets

#	Label	Type	Range	Description
0	elapsed	INT	0+ ms	The time since the start, in whole milliseconds, once per interval while running.
1	beats	FLOAT	0+ beats	The beats the bound clock has moved since the start, sent just before the milliseconds. Silent without a clock.

Parameters

Name	Default	Range	Description
interval	5	1+ ms	The reporting interval in milliseconds, at least 1.
intervalbeats	0	0+ beats	The reporting interval in beats on the bound clock. 0 uses the millisecond interval instead. A plain number in the right inlet sets it back to 0.

`.delay`#

Sends a bang a set time after it receives one: 5 ms by default, or a beat time on a domain clock. It holds one bang at a time; a new bang restarts the wait and ‘stop’ cancels it.

Kind:: Control-rate

Messages

On the left inlet:

bang: start the wait. A bang that is already waiting is forgotten and the wait starts again.
a number or a beat time: set the time and start the wait.
stop: cancel the waiting bang without sending it.
clock <name>: the clock for beat times (see below).

A number in the right inlet sets the time for the next bang only. A bang that is already waiting keeps the time it started with.

A delay of 0 waits one audio block, so a .delay 0 wired into its own inlet bangs once per block instead of looping. Waits are rounded up to whole blocks and stop while nothing renders; see Time, scheduling and clocks.

Beat time

.delay, .metro, .clocker, .speedlim and .qlim also take a time in beats:

A note value (4n, 8nd, 8nt) or a tick count (1440 ticks) sets the time in beats.
The beats are counted on the clock named by clock <name> in the left inlet. A bare clock removes it.
A plain number switches back to milliseconds.

The wait then follows the clock: it stretches when the tempo falls, follows a glide, and stands still while the clock is stopped. On .delay, a beat time with no clock bound does nothing; send clock <name> and the next bang works. The binding is not saved with the patch. Bar-based times are not supported, because a domain clock has no bars. The note-value syntax and the rules for binding are in Time, scheduling and clocks.

Inlets

#	Label	Accepts	Range	Description
0	bang	FLOAT, INT, BANG, LIST	bang, int, float, list, ‘stop’, ‘clock <name>’	A bang starts the wait, forgetting a bang already waiting. A number or a beat time sets the time and starts the wait. ‘stop’ cancels the waiting bang; ‘clock <name>’ sets the clock for beat times.
1	time	FLOAT, INT, LIST	0+ ms, or a note value / tick count	Sets the time for the next bang, in milliseconds or as a beat time. A bang already waiting keeps its time.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	The delayed bang.

Parameters

Name	Default	Range	Description
delaytime	5	0+ ms	The delay in milliseconds. A negative value counts as 0.
delaybeats	0	0+ beats	The delay in beats on the bound clock. 0 uses the millisecond delay instead. A plain number in either inlet sets it back to 0.

`.line`#

Ramps a number to a target over a given time, sending a value every grain (20 ms by default) and a bang from the right outlet on arrival. A list of target/time pairs makes a ramp of several segments.

Kind:: Control-rate

Messages

On the left inlet:

a number: the target. It is reached over the time last sent to the middle inlet, and that time is then used up: the next target without a new time jumps there at once.
<target> <time>: a target and its time together. Use this form to ramp every target.
<target> <time> <grain>: also sets the grain, which stays set.
four or more numbers: target/time pairs, travelled one after another. An odd last number is ignored.
stop: freeze where the ramp is and forget the rest, without a bang on the right outlet.
pause / resume: hold the ramp and carry on with what was left.
set <value>: move to that value without sending it, and stop the ramp.

[.line 0.]   1 1000 0 1000  =>  rises to 1. over 1 s, falls to 0. over
                                the next second, then bangs the right outlet

Every new ramp starts from the current value and replaces the segments still to come, so it never jumps. A target reached with no time still bangs the right outlet.

Timing

The first value goes out one grain after the ramp starts. Each value is worked out from the time that has passed, so a late step jumps to the right value and the ramp arrives on time. Times are counted in audio blocks: a grain shorter than a block gives one value per block, and the ramp stands still while nothing renders (see Time, scheduling and clocks). A grain below 1 ms counts as 20.

Times are in milliseconds only, as described under .pipe.

Output type

A starting value written as a float (0., 1.5) makes the object send floats. Otherwise it sends ints, truncated toward 0, except on a segment that covers 1 or less in steps smaller than 0.4: that segment is sent as floats, so a ramp from 0 to 1 still moves.

Limits

A ramp holds up to 64 segments; numbers past the 129th are ignored. If the patcher’s scheduler is full, the ramp jumps to its target.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	any	A target, ‘<target> <time> [<grain>]’, or target/time pairs. ‘stop’, ‘pause’, ‘resume’ and ‘set <value>’ control the ramp.
1	time	FLOAT, INT, LIST	0+ ms	The time in milliseconds the next target takes. It is used by one target only, then goes back to 0.
2	grain	FLOAT, INT, LIST	1+ ms	The time in milliseconds between values. Below 1 it counts as 20. It stays set.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any number	The ramp, one value per grain, ending exactly on the target. An int or a float: see the notes.
1	done	BANG	—	A bang when the last target is reached. A ramp cut short by ‘stop’ sends none.

Parameters

Name	Default	Range	Description
initial	0	any number	The starting value. Written as a float (‘0.’) it makes the object send floats.
grain	20	1+ ms	The time in milliseconds between values. Below 1 it counts as 20.

`.metro`#

Sends a bang at a regular interval while it runs, starting with one bang the moment it starts. The interval is in milliseconds (1000 by default) or a beat time on a domain clock.

Kind:: Control-rate

Messages

On the left inlet:

a non-zero number: start. A float is compared with 0, so 0.5 starts.
bang: start, or on a running metro, start again from now. One button wired to several metros brings them into step.
0 or stop: stop.
clock <name>: the clock for a beat interval.

Every start sends a bang straight away.

A number in the right inlet changes the interval of a running metro without restarting it: the next tick is due at the last tick plus the new interval, or at once if that has passed. Floats are truncated, and the shortest interval is 1 ms.

Beat interval

A note value or tick count works as described under .delay. A beat metro stays in step with every other object and clip on its clock. Whether a run uses milliseconds or beats is fixed when it starts, so a clock message or a switch between the two units takes effect at the next start. A new beat interval reaches a running beat metro at once and keeps its phase. A beat interval with no clock bound does not start the metro.

Timing

A millisecond metro runs on the engine’s timer thread, keeps running while nothing renders, and drives everything downstream on that thread. A beat metro runs at block boundaries on the audio thread. When its clock jumps ahead, it sends at most 64 catch-up bangs. See Time, scheduling and clocks and .metro in 3.0.

Inlets

#	Label	Accepts	Range	Description
0	on/off	FLOAT, INT, BANG, LIST	0 or 1, bang, ‘stop’, ‘clock <name>’	A non-zero number or a bang starts the metro (a bang restarts a running one from now); 0 or ‘stop’ stops it. ‘clock <name>’ sets the clock for a beat interval.
1	period	FLOAT, INT, LIST	1+ ms, or a note value / tick count	Sets the interval, in milliseconds or as a beat time. A running metro keeps going at the new interval without restarting.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	A bang on every tick, and one when the metro starts.

Parameters

Name	Default	Range	Description
period	1000	1+ ms	The interval in milliseconds. A change reaches a running metro one tick later.
periodbeats	0	0+ beats	The interval in beats on the bound clock. 0 uses the millisecond interval instead. A plain number in the right inlet sets it back to 0.

`.pipe`#

Delays ints, floats and lists by a set time (0 ms by default). It holds up to 64 values at once, and each one keeps the delay it arrived with.

Kind:: Control-rate

Each value waits on its own: a new value never cancels one that is waiting, so ten values in give ten values out. A number in the right inlet sets the delay for values that arrive after it.

Messages

an int, a float or a list: delayed and sent unchanged. A list that is a single number comes out as that number. A list travels whole; split it afterwards if needed.
clear: drop every waiting value.
flush: send every waiting value now, in the order they arrived.

A delay of 0 waits one audio block, so a .pipe 0 wired into itself does not loop. Waits are rounded up to whole blocks; see Time, scheduling and clocks.

Milliseconds only

.pipe, .line, .thresh and .quickthresh take times in milliseconds only. A note value or tick count sent to a time inlet is ignored, and the time stays as it was.

Limits

Up to 64 values can wait at once, and a list can be up to 256 characters long. Each waiting value also takes one of the patcher’s 128 scheduler slots. A value that does not fit is dropped, not sent early.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, LIST	int, float, list, ‘clear’, ‘flush’	An int, float or list to delay; each value waits on its own. ‘clear’ drops every waiting value and ‘flush’ sends them all now.
1	time	FLOAT, INT, LIST	0+ ms	Sets the delay in milliseconds for values that arrive after it. Values already waiting keep their delay.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	Each value, unchanged, once its delay is up.

Parameters

Name	Default	Range	Description
delaytime	0	0+ ms	The delay in milliseconds. 0 still waits one audio block. A negative value counts as 0.

`.qlim`#

Limits how often messages pass. A message that arrives before the interval since the last output is up is held and sent when it is up; a newer message replaces it, or with ‘usurp 0’ joins a queue.

Kind:: Control-rate

A message that arrives too soon is held and sent when the interval is up, one interval after the previous output. What happens to the next message that arrives while one waits depends on usurp:

usurp 1 (the default): the new message replaces the waiting one, so a burst comes out as its last message. Use it for values such as a fader position, where the latest one matters.
usurp 0: messages queue, up to 32, and go out one per interval in the order they arrived. Use it for events that must all happen. When the queue is full, new messages are dropped.

usurp on its own means usurp 1.

A message that arrives inside the threshold window is dropped, not held. The interval, the threshold, quantize and the message rules work as described under .speedlim; with a grid set, a held message goes out on the first grid line at or after the end of its interval.

A held list can be up to 256 characters long. Holding uses one of the patcher’s scheduler slots, however long the queue; if none is free, the waiting messages are dropped.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	bang, int, float, list, ‘clock <name>’, ‘threshold <time>’, ‘quantize <time>’	Any message, passed or held. ‘clock <name>’, ‘threshold <time>’, ‘quantize <time>’ and ‘usurp <0\|1>’ are settings, not data.
1	interval	FLOAT, INT, LIST	0+ ms, or a note value / tick count	Sets the minimum time between outputs, in milliseconds or as a beat time. 0 lets everything through.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The messages that got through, unchanged. A held message goes out one interval after the previous output.

Parameters

Name	Default	Range	Description
interval	0	0+ ms	The minimum time between outputs in milliseconds. 0 lets everything through.
intervalbeats	0	0+ beats	The interval in beats on the bound clock. 0 uses the millisecond interval instead. A plain number in the right inlet sets it back to 0.
threshold	0	0+ ms	A window in milliseconds after each output in which every message is dropped. 0 is off.
thresholdbeats	0	0+ beats	The threshold in beats on the bound clock. 0 uses the millisecond threshold instead.
quantize	0	0+ beats	A beat grid that output lands on, at most one message per grid line. 0 is off. Needs a bound clock.
usurp	1	0 or 1	1: a new message replaces the one waiting. 0: messages queue, up to 32, and go out one per interval.

`.quickthresh`#

Collects values that arrive close together into one list, sent a fixed time (40 ms by default) after the first of them. Made for grouping the notes of a chord.

Kind:: Control-rate

The window opens with the first value of a group and closes threshold milliseconds later, however many values arrive in it. If a value lands in the last fudge milliseconds of the window, the window is extended once, by extension. A group therefore lasts at most threshold plus extension, and a steady stream cannot hold it back.

[.quickthresh]   60, 64 5 ms later, 67 12 ms later  =>  60 64 67
                                                        40 ms after the 60

Messages

an int, a float or a list: added to the group.
bang: send the group now.
set <threshold> [<fudge> [<extension>]]: set the times given.

A new threshold applies from the next group. A fudge or extension of 0 turns the extension off. Times are counted in whole audio blocks (about 2.9 ms at 44.1 kHz), which matters most for the short fudge time.

The output and the limits work as described under .thresh.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	—	An int, float or list to add to the group. A bang sends the group now; ‘set <threshold> [<fudge> [<extension>]]’ sets the times.
1	threshold	FLOAT, INT, LIST	0+ ms	The window length in milliseconds, counted from the first value of a group.
2	fudge	FLOAT, INT, LIST	0+ ms	The last part of the window, in milliseconds, in which a value extends the window. 0 turns the extension off.
3	extension	FLOAT, INT, LIST	0+ ms	How much longer the window runs, in milliseconds, when a value lands in the fudge time. It happens once per group.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The group: a list, or a single number when only one number was collected.

Parameters

Name	Default	Range	Description
threshold	40	0+ ms	The window length in milliseconds. A negative value counts as 0.
fudge	10	0+ ms	The last part of the window, in milliseconds, in which a value extends the window. 0 turns the extension off.
extension	20	0+ ms	How much longer the window runs, in milliseconds, when a value lands in the fudge time.

`.setclock`#

Creates a named domain clock that runs from the start, and sets its tempo: every number it receives is the new tempo in BPM. A bang sends the clock’s beat position.

Kind:: Control-rate

The clock is created when the object is added to a patcher, already running at the tempo argument. If a clock of that name exists already, it is left as it is, tempo included. Deleting the object leaves the clock in place; only the host destroys clocks. Other objects find the clock by name, so one .setclock can give part of a patch a tempo of its own:

[.setclock fast 240]   [.tempo fast 240 1 4]

Every number sets the tempo; 0 stops the clock. tempo <bpm> <ramp> also sets the glide time, which then applies to every later tempo change. Where .transport takes 0 and 1 as stop and start, a number here is always a tempo, so a slider can drive it directly.

There is no clock message: the clock is the creation argument. With no name the object does nothing.

Inlets

#	Label	Accepts	Range	Description
0	speed	FLOAT, INT, BANG, LIST	BPM, bang, ‘tempo <bpm> [<ramp>]’	A number sets the tempo in BPM; 0 stops the clock. ‘tempo <bpm> [<ramp>]’ does the same and can set a glide time. A bang sends the beat position.

Outlets

#	Label	Type	Range	Description
0	beat	FLOAT	—	The clock’s beat position, on bang.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to create, when the object is added to a patcher. Empty does nothing.
tempo	120	BPM	The tempo in BPM, used when the clock is created and replaced by every number received. Not clamped: 0 stops the clock, a negative tempo runs it backwards.
ramp	0	0+ seconds	Seconds each tempo change glides over. 0 is instant. The starting tempo is always instant.

`.speedlim`#

Limits how often messages pass. A message that arrives before the interval since the last output is up is dropped, so a burst comes out as its first message.

Kind:: Control-rate

A message passes when at least the interval has gone by since the last message the object sent. Anything earlier is dropped, so a burst comes out as its first message. Use .qlim instead when the last value of a burst matters.

Messages pass unchanged: bang, int, float or list. A list that is a single number passes as that number. The first message always passes, and an interval of 0 lets everything through.

Settings

On the left inlet, .speedlim and .qlim both read:

clock <name>: the clock for beat times, as described under .delay.
threshold <time>: a second window after each output in which every message is dropped. threshold 0 turns it off.
quantize <time>: a beat grid, set with a note value or tick count. At most one message passes per grid line, and only once the grid has moved past the line of the last output. quantize 0 turns it off. It needs a bound clock.

The interval and threshold take milliseconds or a beat time. A beat time with no clock bound does not limit anything, so the stream is never swallowed. A new interval is measured from the last output, so shortening it can open the window at once.

Time is counted in whole audio blocks: two messages in the same block are 0 ms apart.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	bang, int, float, list, ‘clock <name>’, ‘threshold <time>’, ‘quantize <time>’	Any message, passed or dropped. ‘clock <name>’, ‘threshold <time>’ and ‘quantize <time>’ are settings, not data.
1	interval	FLOAT, INT, LIST	0+ ms, or a note value / tick count	Sets the minimum time between outputs, in milliseconds or as a beat time. 0 lets everything through.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The messages that got through, unchanged.

Parameters

Name	Range	Description
interval	0+ ms	The minimum time between outputs in milliseconds. 0 lets everything through.
intervalbeats	0+ beats	The interval in beats on the bound clock. 0 uses the millisecond interval instead. A plain number in the right inlet sets it back to 0.
threshold	0+ ms	A window in milliseconds after each output in which every message is dropped. 0 is off.
thresholdbeats	0+ beats	The threshold in beats on the bound clock. 0 uses the millisecond threshold instead.
quantize	0+ beats	A beat grid that output lands on, at most one message per grid line. 0 is off. Needs a bound clock.

`.tempo`#

Counts notes on a named domain clock: ‘.tempo main 120 1 16’ sends 0 to 15 in sixteenth notes, over and over. Starting it sets the clock’s tempo.

Kind:: Control-rate

The count moves every 4 × multiplier / division beats of the clock and runs from 0 to division - 1. A division of 4 counts quarter notes (one beat each), 16 sixteenths. The multiplier slows the count down without changing the length of the cycle.

Messages

On the left inlet:

bang or a non-zero number: start, or start again, from 0. The 0 goes out at once.
0 or stop: stop counting. The clock keeps running.
tempo <bpm> [<ramp>]: set the clock’s tempo, gliding over ramp seconds if given.
clock <name>: count on another clock. A bare clock stops the counting until a clock is named again.

The tempo belongs to the clock

Starting the count, the tempo inlet and tempo all write the tempo to the clock, which changes it for every object and clip on that clock. On a clock that something else drives, such as a .transport, give the .tempo the same tempo. Stopping never writes the clock.

Changing the multiplier or division while running keeps the count’s place. If the clock jumps ahead, the count still lands on the right step, but at most 64 steps are sent. The clock name works as described under .when.

Inlets

#	Label	Accepts	Range	Description
0	on/off	FLOAT, INT, BANG, LIST	0 or 1, bang, ‘stop’, ‘tempo <bpm> [<ramp>]’, ‘clock <name>’	A bang or a non-zero number starts or restarts the count from 0; 0 or ‘stop’ stops it. ‘tempo <bpm> [<ramp>]’ sets the clock’s tempo; ‘clock <name>’ changes the clock.
1	tempo	FLOAT, INT	BPM	The tempo in BPM, written to the clock at once. It changes the tempo for everything on that clock.
2	multiplier	FLOAT, INT	1+	Multiplies the time between counts, at least 1. A running count keeps its place.
3	division	FLOAT, INT	1-96	The note value to count in, as a division of a whole note (16 is a sixteenth), and the length of the cycle. 1 to 96.

Outlets

#	Label	Type	Range	Description
0	count	INT	0 to division - 1	The count, from 0 to division - 1 and round again. 0 goes out when the count starts.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to count on. Empty counts nothing. A ‘clock <name>’ message does not change it.
tempo	120	BPM	The tempo in BPM written to the clock on every start. Not clamped: 0 pauses the clock, a negative tempo runs it backwards.
multiplier	1	1+	Multiplies the time between counts. The cycle length stays the same.
division	16	1-96	The note value to count in, as a division of a whole note, and the length of the cycle.

`.thresh`#

Collects values that arrive close together into one list, and sends the list once no new value has arrived for the threshold (10 ms by default).

Kind:: Control-rate

Every value restarts the wait, so the group goes out once the input has been quiet for the threshold. A stream that never pauses never sends a group; use .quickthresh when the group has to come out a known time after it started.

Output

For .thresh and .quickthresh:

A list that arrives is added whole.
A group of one number comes out as that number, an int or a float by how it was written. A larger group comes out as a list.

Time is counted in whole audio blocks: values in the same block are 0 ms apart, and a threshold of 0 groups what arrives in one block. Times are in milliseconds only, as described under .pipe.

Limits

A group can be up to 256 characters long. A value that would make it longer is dropped, and the group keeps what it has.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	—	An int, float or list to add to the group. Each one restarts the wait.
1	threshold	FLOAT, INT, LIST	0+ ms	The quiet time in milliseconds that ends a group.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The group: a list, or a single number when only one number was collected.

Parameters

Name	Default	Range	Description
threshold	10	0+ ms	The quiet time in milliseconds that ends a group. A negative value counts as 0.

`.timepoint`#

Sends a bang once when a named domain clock passes a beat position, as in ‘.timepoint main 128’.

Kind:: Control-rate

The bang comes on the way past: the first time the clock is at or past the target, the object bangs once and is then spent. A target that is already at or behind the clock when the object is armed never fires, so loading a patch in the middle of a piece does not fire every cue at once.

These arm the object again, and each one fires only if the target is still ahead of the clock:

a number: a new target.
active 1. active 0 disarms the object.
clock <name>. A bare clock stops it watching.

If the clock does not exist yet, the object waits for it. A target the clock passes while the object is still looking for it fires as soon as the clock is found. The bang is accurate to one audio block, and never comes while the clock is stopped short of the target. The clock name works as described under .when.

Inlets

#	Label	Accepts	Range	Description
0	time	FLOAT, INT, LIST	beats, ‘clock <name>’, ‘active 0\|1’	A number sets the beat position and arms the object. ‘active 0\|1’ disarms or re-arms it; ‘clock <name>’ changes the clock.

Outlets

#	Label	Type	Range	Description
0	out	BANG	—	A bang, once, when the clock passes the beat position.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to watch. Empty watches nothing. A ‘clock <name>’ message does not change it.
time	0	beats	The beat position to bang at.
active	1	0 or 1	1 watches the clock, 0 does not.

`.timer`#

Measures the time between a bang in the left inlet and a bang in the right inlet, in milliseconds and, with a clock name as argument, in beats.

Kind:: Control-rate

A bang in the right inlet sends the time since the last bang in the left inlet, and leaves the start where it is, so repeated right bangs give split times. A right bang before any start sends nothing.

The milliseconds are a float, measured on the system’s steady clock at the moment each bang arrives. A tap tempo:

tap -> [.t b b]   right outlet -> right inlet of [.timer]
                  left outlet  -> left inlet of [.timer]
                  each tap sends the time since the previous one

With a clock name as argument, the beats that clock moved in the same time go out just before the milliseconds. Nothing goes out on the beats outlet when the clock did not exist at the start. The clock name works as described under .when; there is no clock message.

Inlets

#	Label	Accepts	Range	Description
0	start	BANG	bang	A bang marks the start. Another bang moves the start to now.
1	report	BANG	bang	A bang sends the time since the start. The start stays where it is.

Outlets

#	Label	Type	Range	Description
0	ms	FLOAT	0+ ms	The time since the start, in milliseconds.
1	beats	FLOAT	beats	The beats the named clock moved in the same time, sent just before the milliseconds. Silent without a clock.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to measure beats on. Empty measures milliseconds only.

`.translate`#

Converts a time value between milliseconds, hertz, samples, beats and ticks. Converting between real time and beats uses the current tempo of a named domain clock.

Kind:: Control-rate

Formats

ms: milliseconds.
hz: repetitions per second. 2 Hz is 500 ms.
samples: at the current sample rate.
beats: quarter notes on the clock.
ticks: 480 per beat.

The arguments give the input format, the output format and the clock, in any order: the first two format words are the input and the output, and any other word is the clock. Without arguments the object converts milliseconds to ticks. bars.beats.units, hh:mm:ss and notevalues are not supported; as arguments they are ignored with an error in the log.

[.translate ms beats main]   at 120 BPM:  500  =>  1.

Messages

a number: a value in the input format.
a note value (4n, 8nt) or tick count (960 ticks): a value in beats, whatever the input format.
bang: convert the last value again, at the tempo of the moment. Bang it from a .metro to follow a tempo glide.
in <format> / out <format>: change a format. An unknown word is ignored.
clock <name>: use another clock. A bare clock removes it.

Conversions within ms, hz and samples, or between beats and ticks, need no clock. Converting between the two groups uses the clock’s tempo at that moment. Nothing is sent when there is no clock, the tempo is 0, or the value is 0 Hz or 0 ms converted to Hz. A clock running backwards gives a negative result. The clock name works as described under .when.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	a number, a note value, ‘<n> ticks’, bang, ‘in\|out <format>’, ‘clock <name>’	A number in the input format, or a note value or tick count, to convert. A bang converts the last value again. ‘in <format>’, ‘out <format>’ and ‘clock <name>’ change the settings.

Outlets

#	Label	Type	Range	Description
0	converted	FLOAT	—	The value in the output format. Nothing when the conversion cannot be made.

Parameters

Name	Default	Range	Description
in out clock	ms ticks	[<format>] [<format>] [<clock name>]	The input format, the output format and the clock name, in any order: the first two format words are input and output, any other word is the clock.

`.transport`#

Starts, stops and sets the tempo of a named domain clock, creating the clock (stopped) if it does not exist yet. A bang sends the clock’s beat position and tempo.

Kind:: Control-rate

The clock is created when the object is added to a patcher, stopped, so adding a .transport never starts anything. A clock of that name that already exists is left as it is. Deleting the object leaves the clock in place; only the host destroys clocks.

Messages

On the left inlet:

a non-zero number or start: run the clock at the object’s tempo.
0 or stop: stop the clock at once. It keeps its beat position, and the next start carries on from there. There is no way to jump to another position.
tempo <bpm> [<ramp>]: set the tempo. A ramp, when given, is the glide time in seconds for every later start and tempo change.
bang: send the clock’s tempo, then its beat position.

A tempo sent while stopped is kept for the next start. Stopping sets the clock’s tempo to 0, even when the host started it. The tempo outlet reports the clock’s actual tempo, so it shows a glide in progress and changes made by the host.

Inlets

#	Label	Accepts	Range	Description
0	control	FLOAT, INT, BANG, LIST	0 or 1, bang, ‘start’, ‘stop’, ‘tempo <bpm> [<ramp>]’	A non-zero number or ‘start’ starts the clock; 0 or ‘stop’ stops it. ‘tempo <bpm> [<ramp>]’ sets the tempo. A bang sends the tempo and the beat position.
1	tempo	FLOAT, INT	BPM	The tempo in BPM. Applied at once while running, kept for the next start while stopped.

Outlets

#	Label	Type	Range	Description
0	beat	FLOAT	—	The clock’s beat position, on bang.
1	tempo	FLOAT	BPM	The clock’s tempo in BPM, on bang, sent just before the beat position. It shows a glide in progress and changes made by the host.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to control, created when the object is added to a patcher. Empty controls nothing.
tempo	120	BPM	The tempo in BPM the clock runs at while started. Not clamped: a negative tempo runs the clock backwards.
ramp	0	0+ seconds	Seconds each start or tempo change glides over. 0 is instant. A stop is always instant.

`.when`#

On any input, sends the beat position and tempo of a named domain clock. It only reads the clock and never creates one.

Kind:: Control-rate

Any message works as a query, so a .when can sit at the end of anything that already fires, such as a .metro. The tempo goes out first, then the beat position. A stopped clock reports tempo 0.

Clock names

.when, .tempo, .timepoint, .timer and .translate take the clock name as a creation argument:

The name refers to an engine clock, shared with the host and with clips.
These objects never create a clock. Until a .transport, a .setclock or the host creates it, they send nothing, and they start working once it exists.
A clock destroyed while they use it stands still.

See Time, scheduling and clocks for clocks and the limits on how many a patcher can use.

Inlets

#	Label	Accepts	Range	Description
0	query	FLOAT, INT, BANG, LIST	bang, int, float or any list	Any message sends the clock’s tempo and beat position. What the message says is ignored.

Outlets

#	Label	Type	Range	Description
0	beat	FLOAT	—	The clock’s beat position.
1	tempo	FLOAT	BPM	The clock’s tempo in BPM, sent just before the beat position. 0 while the clock is stopped; during a glide, the tempo reached so far.

Parameters

Name	Default	Range	Description
clockname	—	—	The domain clock to read. Empty reads nothing.

Time

Contents

Time#