The Event System

The application PolytempoNetwork is controlled by events. The application's internal functions and everything it can display on-screen (images, beats, bar numbers, text boxes, etc.) can be encoded in events.

Depending on whether the music is predefined or generated in real-time, PolytempoNetwork either reads these events from a text file or receives them via the network. Hence, PolytempoNetwork can operate in two different modes: stand-alone and message-driven.

The two modes are not mutually exclusive. You may use them concurrently.

Stand-Alone Mode

The stand-alone operation mode uses a JSON-formatted text file which lists all events. This text file is called a polytempo score. The application PolytempoNetwork employs its built-in scheduler to play though this score. This mode is useful for compositions with a predetermined tempo and a linear time structure in a traditional fashion.

A polytempo score contains all events to be executed to perform a certain piece of music. Every event is expressed as a JSON object, i.e. a collection of comma separated name/value pairs enclosed in curly braces. Every event is structured as follows: The name indicates the event's type and the value itself is a JSON object that lists the event's parameters as name/value pairs.

Pattern:

 { <event-type> : { <param1> : <val1>, <param2> : <val2>, ... <paramN> : <valN> }}

Examples:

 { "beat" : { "time" : 0, "duration" : 1, "pattern" : 12 }}
 { "addRegion" : { "regionID" : 1, "rect" : [0,0,1,0.5] }}

(Note that the parameter rect is followed by an array of four values.)

One convenient way to calculate the exact times of all events and generate a well-formed polytempo score is the usage of the application PolytempoComposer.

Message-Driven Mode

In the message-driven mode, the application PolytempoNetwork is controlled remotely over the network. This mode is used for music whose tempos and/or form are to be generated in real-time. In the message-driven operation mode the built-in scheduler remains inactive and all functions are controlled from the outside by messages received over the network.

Events sent via the network are formatted according to the Open Sound Control (OSC) protocol. The application PolytempoNetwork listens to incoming OSC messages on port 47522.

Use the following messages to start or stop the playback or to set the current playback position to a certain time or marker:

/start
/stop
/gotoTime 10
/gotoMarker 5

You can even remotely open a polytempo score file. This can be particularly handy, if you want to switch from one piece to the next in the course of a concert:

/open <absolute path to a ptsco-file>

All available events and their parameters are listed in the event glossary.

To explore how to control the application PolytempoNetwork from Max, you can download an example patch.

Forward Messages

If you connect multiple instances of PolytempoNetwork in a network and synchronise them, you can send OSC messages to the master instance to be forwarded to other instances.

/violin/beat duration 1 pattern 12

The master instance sends this beat event to all connected instances whose name is "violin". You can set an instance name in the applications preferences. This name is associated with the hardware and remains even if you restart the application or reboot the computer. Or you can set an instrument name through a settings event in the polytempo score. The master instance will try to find a remote instance with either of these two names set to "violin".

/*/beat duration 1 pattern 12
/*/start
/*/stop

To broadcast an event to all instances in the network, prefix it with the wildcard /*. All instances will execute this event perfectly in sync because they automatically compensate for any network latency.