Event Glossary
The application Polytempo Network is controlled by events, formatted either as JSON objects when part of a polytempo score or as OSC messages when sent over the network in real-time. In either format, they have an identical effect.
An event formatted as JSON object:
{ event-type : { param1 : val1, param2 : val2, ... paramN : valN }}
Example:
{ "beat" : { "time" : 0, "duration" : 1, "pattern" : 12 }}
An event formatted as OSC message:
/event-type param1 value1 param2 value2 ... paramN valueN
Example:
/beat time 0 duration 1 pattern 12
All parameters are given as a list of name-value pairs. The order of the parameters does not matter.
Time Parameters
In addition to their individual parameters, all events can have one ore more of the following time parameters:
time |
(float) | The time to execute this event in seconds in respect to the score time (i. e. after the beginning of the piece). If this value is smaller than the current score time, the event is executed immediately. If the receiver's internal clock (the score clock) is not running, the event is ignored. Note that this parameter can also be a negative number. This can be useful to schedule events before the actual beginning of the piece, e.g. beats to count in. |
defer |
(float) | The time in seconds by which the execution of this event is deferred. |
timeTag |
(int) | A time tag used to synchronise several devices and to compensate for network latencies. This time tag is calculated automatically an mustn't be set by the user. |
#
In a polytempo score file, you can use this event to add a comment.
{"#": {"time" : 5, "value": "This is a comment" }
If you want the comment to stick to its position when the score is sorted by time, you must include a time parameter. You are free to choose the other parameters' names; they are not read by the application.
addRegion
Define a region of the program window in which graphical elements (images, texts, progressbars, etc.) can be displayed.
regionID |
(int/string) | A number or string to identify this region. Arbitrary but unique among all regions. |
rect |
(float array) | The region's size (x, y, width, height). All values are factors of the window's size, e.g. (0.2, 0.2, 0.5, 0.5) would give a region with half the width and height of the window, and a top-left position at 20% of the way across and down the window. |
layout |
(string) | Set "row" or "column" to specify how images are appended when using appendImage. |
xAlignment |
(string) | "left" (default), "center" or "right". |
yAlignment |
(string) | "top", "center" (default) or "bottom". |
maxZoom |
(float) | Maximum zoom factor of any image displayed in this region. |
A new region is always inserted in front of the others. You can control the z-index of the regions by the order in which you add them.
addSection
Define a section of an image previously previously loaded with loadImage.
sectionID |
(int/string) | A number or string to identify this section. Arbitrary but unique among all sections. |
imageID |
(int/string) | The identification of the image. |
rect |
(float array) | The section's size (x, y, width, height). All values are factors of the image's size, e.g. (0.2, 0.2, 0.5, 0.5) would give a section with half the width and height of the image, and a top-left position at 20% of the way across and down the image. |
addSender
Add a sender to emit OSC messages to other applications, e.g. to synchronise electroacoustic playback, video playback, lighting, etc. A sender can also send out the current internal time as tick events.
senderID |
(string) | A number or string to identify this sender. Arbitrary but unique among all senders. |
ip |
(string) | The IP-Number of the receiver (e.g. "127.0.0.1"). |
port |
(int) | The port number. |
tick |
(int) | The sender emits tick events, if value ≠ 0. |
appendImage
Append a section of an image to a region. This event works the same way as image except that it appends an image rather than overwriting the region's content.
audio
Play an audio file previously loaded with loadAudio.
audioID |
(int/string) | The identification of the audio file. |
gain |
(float) | A multiplication factor applied to the signal (default: 1.0). |
beat
Execute a single beat.
duration |
(float) | The duration of the beat, determines the speed of the animation. |
pattern |
(int) | The movement pattern of the animation, indicated by a two digit number. |
cue |
(int) | The beat is a cue, if value ≠ 0. |
linear |
(int) | The animation is executed linearly, if value ≠ 0. Suitable for very slow movements. |
The pattern is a two-digit number that indicates the initial and final position of the animated bar of the visual metronome. The positions are marked as follows: 1 = at the bottom of the vertical bar (a downbeat), 2 = on the left of the horizontal bar, 0 = the neutral position in the middle. Hence the pattern defines the direction of movement of the animation, e.g. the four beats of a 4/4 bar would have the patterns 12, 22, 22, and 21.
clearAll
Clear all graphics.
gotoMarker
Jump to an existing marker in the score. Typically, a marker is a bar number or a rehearsal letter. This event sets the internal clock to the marker's time which has the same effect as a gotoTime event. If the marker does not exist, nothing happens.
value |
(anything) | The marker to reach. |
gotoTime
Set the time of the internal clock and jump to this point in the score.
When receiving this event, all graphics are updated to reflect the given time. If the playback is started, the conducting (or click track) will not resume until the next downbeat.
value |
(float) | The time in seconds. |
image
Display a section of an image previously loaded with loadImage inside a region previously defined with addRegion.
Usage 1: The section of the image has already been defined with addSection.
sectionID |
(int/string) | The identification of the image section. |
regionID |
(int/string) | The identification of the region in which the image section is to be displayed. |
Usage 2: Provide the section's dimension.
imageID |
(int/string) | The identification of the image. |
rect |
(float array) | The section's size (x, y, width, height). All values are factors of the image's size, e.g. (0.2, 0.2, 0.5, 0.5) would give a section with half the width and height of the image, and a top-left position at 20% of the way across and down the image. |
regionID |
(int/string) | The identification of the region in which the image section is to be displayed. |
loadAudio
Load an audio file (format: WAV or AIFF).
audioID |
(int/string) | A number or string to identify this audio file. Arbitrary but unique among all audio files. |
url |
(string) | The file path, either absolute or relative to the score file. |
loadImage
Load an image file (format: JPEG or PNG).
imageID |
(int/string) | A number or string to identify this image. Arbitrary but unique among all images. |
url |
(string) | The file path, either absolute or relative to the score file. |
marker
Set the content of the marker field. This can be a number or a string. This has no effect on the internal clock (if you want to jump to a marker use gotoMarker.
value |
(anything) | Content of the marker field. |
open
Open a polytempo score file and execute its "init" section.
url |
(string) | The file path. |
osc
Send an OSC message via a sender previously defined with addSender.
address |
(string) | The address part of the OSC message. |
message |
(array)* | The message. |
senderID |
(int/string) | The identification of the sender. |
* In JSON, the value of the parameter message is formatted as array (i.e. comma-separated and enclosed in brackets); in OSC, message must be the last parameter, followed by an arbitrary number of values.
progressbar
Display a progress bar inside a region previously defined with addRegion. A progress bar is driven by the internal clock (or by tick events).
duration |
(float) | The duration to be indicated by the progressbar. |
regionID |
(int/string) | The identification of the region in which the image section is to be displayed. |
value |
(string) | An optional text above the progress bar to provide additional information, e.g "wait 30s". |
start
Start the internal scheduler.
stop
Stop the internal scheduler.
tempoFactor
Set the tempo factor for the internal scheduler (1.0 = original speed, 0.5 = half speed, 2.0 = double speed, etc.).
value |
(float) | The tempo factor. |
text
Display text inside a region previously defined with addRegion.
regionID |
(int/string) | The identification of the region in which the image section is to be displayed. |
value |
(string) | The text to display. |
tick
An event to communicate the current internal time. This event is typically sent out by an OSC sender in order to synchronise external devices (see addSender. To set the internal clock of the application Polytempo Network use the event gotoTime.
value |
(float) | The time in seconds. |
settings
This event can be used to change several settings of the application Polytempo Network.
name |
(string) | The instrument name. |
brightness |
(float) | The brightness of the application window (0–1). |
fullScreen |
(int) | Applications enters full-screen mode if value ≠ 0. |