orgasm.dev

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 lagS plus a margin.

Order and delivery

  • sequence numbers 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, after or a resume message). Webhook retries can arrive out of order.
  • Every imminence.updated repeats the last eight orgasm calls in recentCalls. 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.

hysteresis.ts
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.status tells you when it is ready.

On this page