Helm Clock

Helm Clock is a compact hardware timecode interface for live production — a central generator, distributor, and monitor for the timing that holds a show together. Inspired by the Rosendahl MIF4, it bridges LTC, MTC and a Helm Cues session so DJ hardware, lighting consoles, video servers, and DAWs all run on one clock.

What it does

Timecode processing. SMPTE LTC and MIDI Timecode at 24/25/30 fps, with re-clocking of incoming timecode to suppress jitter and drop-outs.
Multi-source sync. Priority-ordered sources (LTC → MTC → network → internal) with automatic failover.
Audio routing. Acts as a USB/network soundcard for Helm software. Playback audio goes to RCA and minijack outputs; LTC goes exclusively to the XLR outputs — the two never mix.
Follows a Cues session. Joins a Helm Cues session on the LAN and generates LTC from the host’s playhead. See below.
Hardware UI. 8-digit 7-segment LED for the timecode readout (HH:MM:SS:FF), a small OLED for menus, and a rotary encoder for control — minimal by design, for use under pressure in the dark.

I/O

Direction	Connections
Inputs	XLR (LTC), MIDI in, USB-C (power/data), Ethernet
Outputs	2× XLR (LTC), MIDI out, RCA stereo, 3.5mm minijack

How it’s built

Raspberry Pi-based hardware running a custom boot image that starts straight into the application. Everything timing-critical lives in a Rust daemon (helm-timekeeperd) built on the shared helm-timecode crate — the LTC encoder runs inside the audio device callback so the DAC crystal is the timebase, and MTC quarter-frames run on a dedicated real-time thread.

The daemon also owns the network: it joins the Cues session itself. A Python control plane drives the daemon over a Unix socket and owns the UI and configuration. The old Python network package and its build script are removed.

Performance targets: <0.1 frames RMS timecode jitter, <5ms end-to-end audio latency, <30s boot.

Follow a Cues session

What this does: the Clock joins a session that Helm Cues hosts and makes LTC from Cues’ playhead. The target is within ±1 frame of Cues’ own LTC out. Cable the Clock’s XLR to any desk that needs timecode.

Before you start

How the Clock gets in depends on how the Cues host is set.

Cues host	In the session file	On Cues
Ask, passcode off	No passcode	The operator presses Allow
Ask, passcode on	The 6 digits	The operator presses Allow
Open, passcode off	No passcode	Nothing. The Clock is in at once.
Open, passcode on	The 6 digits	Nothing. The Clock is in at once.
Members only	Only a Clock Cues let in before can join	—

Set it up

On Cues, open the show. Settings → Helm Sessions (⇧⌘D) → Host this show.
Click Show join code…. Note the Address and the Fingerprint (26 characters). Passcode on: note the Passcode too.
On the Clock, write /etc/timekeeper/session.json:
```
{ "host_fp": "<26-character fingerprint>", "host": "192.168.2.10:5355", "name": "Clock FOH" }
```
Passcode on: add "passcode": "123456" with Cues’ code.
Restart the daemon:
Terminal window
```
sudo systemctl restart helm-timekeeperd
```
Under Ask, Cues shows Clock FOH wants to join. Press Allow on the toast or in Requests. Under Open the Clock is in at once.
In Cues Devices the Clock’s status reads Joined · LTC 25 fps · parked at ….
Press GO on Cues. The status reads Joined · LTC 25 fps · locked +0.2 ms. The Clock’s LTC out follows the show.
Feed the Clock’s LTC to a reader. Compare it with Cues’ own LTC: within 1 frame.

The session file

/etc/timekeeper/session.json

Key	Needed	Sets
`host_fp`	Yes	Cues’ 26-character Fingerprint
`passcode`	Only when Cues has a passcode on	The 6 digits. Not needed once Cues has let the Clock in.
`host`	No	Cues’ Address. Left out: the Clock looks for Cues on its own subnet.
`name`	No	The Clock’s name in Cues’ Devices. Left out: the board’s model.
`freewheel_ms`	No	How long LTC runs on if the link drops while rolling, in ms. Default `5000`.

No file: no session. The Clock runs as a standalone clock.
A broken file goes in the log. The Clock runs on without a session.
A passcode added while the log says PASSCODE REQUIRED is read within 5 s. No restart.

Log and restart

Read the log. Session lines start session:.
Terminal window
```
journalctl -u helm-timekeeperd -f
```
Restart the daemon.
Terminal window
```
sudo systemctl restart helm-timekeeperd
```

Approved

After the first Allow (or an Open join) Cues has approved the Clock.
Every rejoin after that: no passcode, no Allow.
Cues removes the approval (Devices → ⋯ → Remove approval): the Clock asks again and waits for Allow. With the passcode on, it needs the code in the file.

How it follows

Cues runs the transport. Play, pause and locate on the Clock’s menu do nothing while joined.
More than a frame out: the Clock jumps to Cues’ time.
Inside a frame: it eases back into line. No jump.
Link lost while rolling: LTC runs on for 5 s, then stops.
A show at 23.976, 50, 59.94 or 60 fps: the Clock keeps its own rate.
A desk assigned to the Clock in Cues gets its ONLINE beat only while the Clock is locked. See Assign a desk.

Read the state

Before it joins, read the log (see Log and restart). Once it joins, read Cues Devices.

Log line starts	Means
`session: following`	Looking for Cues on the network
`session: joining`	Joining
`session: Waiting for host`	Waiting for Allow in Cues’ Requests
`session: PASSCODE REQUIRED`	Cues has a passcode on. The file has none. Add it; the Clock picks it up within 5 s.
`session: DENIED by the host`	The Cues operator pressed Deny, or the session is Members only. The Clock stops asking until you restart it.
`session: joined`	In
`session: LINK LOST`	Cues gone. LTC runs on 5 s.

Status in Cues Devices	Means
`LTC 25 fps · parked at …`	Transport stopped. Holding Cues’ frame.
`LTC 25 fps · catching up`	Rolling. Not yet within a frame.
`LTC 25 fps · locked +0.2 ms`	Rolling, within a frame. The number is how far out.
`LTC 25 fps · no anchor, freewheeling`	Cues gone. LTC runs on 5 s.

Cues shows each after Joined · . Hover the cell for the full line.

Tested in a simulated 2-hour run: worst error 2.62 ms, jumps only at start, seek and resume. Not yet tested against a hardware LTC reader.

The Clock never shows in Cues’ Requests or Devices. No /etc/timekeeper/session.json, or the file is broken. Read the log.
Stuck on Waiting for host. Press Allow in Cues’ Requests. The Clock waits until someone does.
Log says PASSCODE REQUIRED. Cues has a passcode on. Add "passcode" to the file with the code from the Cues Session card. The Clock joins within 5 s. Or turn Cues’ passcode off: the Clock asks again within 5 minutes.
Denied. The Cues operator pressed Deny. Restart the daemon to ask again, then press Allow. Log says members only: switch Cues to Ask or Open first.
Log says wrong passcode. The code in the file is not Cues’ code. Copy it again from the Session card. Restart the daemon.
Log stays on following. No host in the file, and the Clock cannot find Cues. Add host, or put the Clock on Cues’ subnet.
Log stuck on joining. The address or fingerprint is wrong. Copy both again from Show join code…. Restart the daemon.
no anchor, freewheeling. Cues stopped answering. LTC runs 5 s more, then stops. Check the cable and that Cues still hosts. The Clock rejoins by itself.
The Clock’s menu transport does nothing. Expected while joined. Run the transport on Cues. Or remove the session file and restart the daemon.
LTC jumps after the start. Something moved Cues’ playhead (a seek, a resume), or the link is poor. Wire the Clock to the show switch.

Status

Prototype. The Rust timing engine is merged and the first on-device deployment is in progress. Detailed hardware, software, and testing documentation exists as drafts and will publish here as the design settles — this overview is the current canonical page.