SCLOrkClock Design Document

Extension

This is a design document for a centralized clock server system for the Santa Clara Laptop Orchestra. It describes a client-server protocol that allows for the centralized creation, control, and management of distributed network Clock objects for use in performance.

Requirements

There should be an easy way to create an object similar to a TempoClock but that has synchronized beat, beatsPerBar, and bar values across all instances of that clock across the network, which we call clock cohorts. Keeping the beat counters in sync allows for distributed compositions with a high degree of structure, in that all clocks in the cohort will have the same concept of where they are in a piece, because of the synchronized beat count.

All members of a clock cohort are equal in that they can each set the tempo or modify other clock parameters, with the expectation that the changes will propagate to all other clocks in cohort automatically.

• We need a way to enumerate all existing clock cohorts by name, as well as get a snapshot of their current state.
• The controller needs to be able to create new cohorts, set tempo and meter on existing cohorts, and clear and stop them.
• Clients should be able to register with the server to receive tempo and meter change commands, as well as notification about the creation and destruction of cohorts.
• Clocks should be within tens of milliseconds in synchrony from one another, and should have the same beat and bar number value, but need not have the same logical time.
• In addition to the traditional real-time clock functions to set tempo or meter, we will want to expand the capabilities for synchronized clock change coordination, including a cue concept which waits for a remote start command, and the ability to schedule changes for a future beat number with methods like setTempoAtBeat.
• All clocks must be permanent by default, meaning that they will survive cmd-period, to allow for their remote administration.
• Clocks may run for a long time, so should account for drift periodically, and be self-correcting.

Clock Client Design

The SCLOrkClock singleton maintains a per-machine SCLOrkWire connection back to the SCLOrkClockServer, to provide and receive clock updates. Because the server is the authoritative time keeper for all changes in clock state, all times communicated back to the server are converted back into server time using the most recent synchronization approximations. In this section we detail the protocol for communication between client and server, followed by some typical scenarios.

Clock Creation

The singleton SCLOrkClock code should check to ensure that the time synchronization service has already been started, or start it if it hasn't been, then checks for the viability of the SCLOrkWire connection back to the server. The singleton code maintains a map of cohort names as key and a list of clock instances as values, so any updates to state from the server can be propagated back to the individual clock instances. So this clock will be added to the map of cohort names, then the client code calls /clockRegister on the server, expecting a /clockUpdate callback on this cohort name as a response to registration.

Computation of Clock Current State

Using the following as reported by the server:

Assuming we have a means of computing local times relative to the provided server time, we can then compute the current clock state as follows:beat = beatAtLastTempoChange + (tempo * (elapsedTime - timeAtLastTempoChange)); beatInBar = (beat - baseBarBeat) % beatsPerBar; bar = barAtLastMeterChange + ((beat - baseBarBeat) / beatsPerBar);

To convert an inputBeat back to a local time elapsed seconds, or beats2secs, the formula is:beats2secs = timeAtLastTempoChange + ((inputBeat - beatAtLastTempoChange) / tempo);

Note that this formula only works for inputBeat >= beatAtLastTempoChange.

Propagating Clock Changes

All immediate changes, like the first line in the example code above, take some time to propagate out and so will arrive at the other clocks in the clock cohort as a retroactive change, meaning that the applyAtTime field is likely to be in the past. Therefore all changes are time-based in a distributed clock, so are reported back to the server using the same mechanism, which is a call to the /clockChange command. Immediate changes don't actually change clock state, rather they will rely on server responding with a /clockUpdate change for some time in the recent past (essentially minus the round-trip-time between client and server).

Server Design

The server has a central role in clock synchronization, but maintains no clocks of its own. Rather it maintains sufficient information that the clients can reconstruct the clock state from all reported information.

Clients should be able to request the names of all registered clock cohorts, requested detailed state information about any of the individual clock cohorts, and register to be informed of any further changes to the clocks. Given that the client and server time synchronization requires only one instance per computer, all clock cohorts can be managed by a per-machine singleton instance of client or server.

Time Synchronization

The server reports its current time when asked at /clockSyncGet by calling /clockSyncSet on the calling client on the supplied return port. The client keeps a rolling mean of the last several data points measuring difference between the client elapsed time and the reported server time, as well as the round-trip-time from request to responce. If the time diff is calculated on receipt at the client as:diff = localClientTime - reportedServerTime

Then the difference between local client time and server time is approximated by:timeDiff = meanDiff - (meanRoundTripTime / 2.0)

In this synthetic example the client is running consistently 5 minutes ahead of the server, and the round trip time between client and server is 1 minute:

Server Wire Command Reference

/clockRegister - needs to be different to prevent accidental clobbering

Informs the server about the creation of a new individual clock within a cohort of the provided name. If the cohort is already registered the provided parameters are ignored, to prevent clocks joining an existing cohort with default parameters from clobbering the existing cohort parameters. If the cohort is new, the sever treats the provided data as authoritative. In either event, the server will respond to the registering client only with canonical clock state information by calling /clockUpdate on the client.

/clockGetAll

Called with no arguments, this is a request by an individual client to return the state of all registered cohorts with individual /clockUpdate return calls on the client.

Client Wire Command Reference

/clockUpdate

Aspirational Code