Timing
The two clocks, why calls arrive late, ordering and deduplication, and how to act on signals without flapping.
Two clocks
- Stream time (fields ending in
S): seconds on the media's own clock, from the first frame of a live stream or the start of a recording. Every moment an event names is on it. - Wall time (
wallTime): UTC, when the event was produced. For a recording it is when the analysis made the call, not a time in the recording.
Use stream time to place events relative to each other and to your own media; use wall time to relate them to the rest of your system.
Calls are retrospective
An orgasm call is made once the detector is sure, a few seconds after the moment it names:
{
"id": "evt_26m8iv7m9ik1q6bbpxah",
"object": "event",
"type": "orgasm.peak",
"mode": "test",
"sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
"sequence": 1293,
"streamTimeS": 704.2,
"confidence": "high",
"data": {
"orgasmIndex": 1,
"eventAtS": 701,
"calledAtS": 704.2,
"lagS": 3.2,
"detector": "peak",
"score": 0.66,
"threshold": 0.5
},
"wallTime": "2026-10-16T14:01:11.420Z"
}
eventAtS is when the peak happened; calledAtS is when it was called; lagS is the difference. Design for it:
- To act before a moment (back off at the edge, stop for a ruin), act on imminence.
- To act because of a moment (end a level, log an outcome), act on the call.
- Never assume no call means nothing happened: wait at least
lagSplus a margin.
Order and delivery
sequencenumbers a session's or recording's events from 1, without gaps. Sort by it and use it to spot a gap.- Delivery is at least once. A redelivered event keeps its
id; deduplicate on it. - The stream and the socket replay what you missed when you reconnect with the last
id(Last-Event-ID,afteror aresumemessage). Webhook retries can arrive out of order. - Every
imminence.updatedrepeats the last eight orgasm calls inrecentCalls. If you only follow imminence, a call whose own message was lost still reaches you within a second.
Acting without flapping
Imminence moves. Acting on every crossing of a threshold makes an experience stutter. Use hysteresis: enter a state above one level and leave it only below a lower one, and require the condition for a moment before acting.
type State = 'below' | 'above';
/** Enters `above` when p rises past `enter` for `holdS` seconds; leaves only when p falls past `exit`. */
export function threshold(enter: number, exit: number, holdS = 2) {
let state: State = 'below';
let since: number | null = null;
return (p: number | null, atS: number): State => {
if (p === null) return state; // no reading: keep the current state
if (state === 'below') {
since = p >= enter ? (since ?? atS) : null;
if (since !== null && atS - since >= holdS) state = 'above';
} else if (p < exit) {
state = 'below';
since = null;
}
return state;
};
}The presets apply the same idea: edge holds at one level and backs off at a higher one, and returns to building only well below.
How fast things arrive
- Imminence updates about once a second.
- Status changes and warnings arrive as they happen.
- Orgasm calls arrive a few seconds after the moment they name, plus your network.
- The first minute of a session is calibration: the subject read comes after about 30 seconds, imminence after about a minute.
- Starting a session can take a few minutes when no analysis capacity is warm;
session.statustells you when it isready.
Subject
How orgasm.dev decides whether the face reads as a woman's or a man's, why that decides the detectors, and how to treat the read.
Edge, ruin and finish
Three experiences as policies your product runs on the signals, with reference code, the cues each gives on the sandbox scenarios, and the safety they need.