Markers

curl -s -H "$H" -X POST localhost:7447/takes/tk_7f3a/markers -d '{"label": "cold-open out"}'

{ "t": 38.7, "label": "cold-open out" }

t is host time in seconds from the cue, stamped by Rheocles at the moment the request arrived. label is whatever you sent. That is the whole feature.

The separation of concerns

Rheocles knows when; the client knows what. A prompter knows that the presenter just crossed the eyeline on the token that means “quick hits, in”. It does not know, to the millisecond, where that moment falls in the file being written — only the process holding the writer knows that. So the prompter says what, Rheocles says when, and the pair lands in the manifest.

Rheocles never interprets a label. It does not pair in with out, does not colour retakes, does not know what a sting is. It could, and it would be wrong occasionally, and a wrong judgement baked into the take is much harder to notice than one made at the point of reading. Interpretation is cheap and can be redone as many times as you like; a time that is quietly four seconds out cannot be recovered from at all.

What an editor does with them

The manifest’s markers[] is a flat list: a time and a name, in order. What an editor wants — spans, retakes, colours — is derived by whatever reads it. Pteroprompter’s convention, which Rheocles neither enforces nor knows about, is that two markers sharing a name bracket a span and a repeated name is a retake:

[ { "t":  38.7, "label": "cold-open out" },
  { "t":  65.2, "label": "quick-hits in" },
  { "t": 111.0, "label": "quick-hits out" },
  { "t": 118.4, "label": "quick-hits in" },       ← went again
  { "t": 164.6, "label": "quick-hits out" } ]

Because every marker’s t is from the cue and every file’s timecode is from the same host clock, a marker converts to a timecode in any file by adding t to that file’s timecode — including a file that joined late, whose own started is just later.

Markers are not join and leave

A stream joining a take is recorded per stream in events[], with a t of its own. A marker is a note about the take. They are separate lists because they answer different questions — what was written when versus what happened when — and because a client should not have to filter one out of the other.