orgasm.dev

Realtime

The event stream and subscribe, the WebSocket and stimulation reports, face frames, view tokens for other screens, long polling, how to resume after a drop, and which to choose.

Every live session's events reach you four ways. They carry the same event objects; pick by where your code runs.

ChannelUse it fromNotes
Server-sent events (results.streamUrl)Browsers, devices, serversThe device SDK's subscribe reads it with the token in a header
WebSocket (results.websocketUrl)Devices and servers that also report a deviceEvents out, stimulation reports in, over one connection
WebhooksYour serverEvery type but imminence.updated, signals.updated and stimulation.updated; see webhooks
Long polling (listLiveSessionEvents with wait)Agents, serverless functionsOne request per batch

In the browser: subscribe

device.ts
import { subscribe, streamOf } from '@orgasm-dev/device';

const subscription = subscribe({
  ...streamOf(session), // results.streamUrl and the client token
  onEvent: (event) => {
    if (event.type === 'imminence.updated') meter.value = event.data.p30 ?? 0;
    if (event.type === 'orgasm.onset') onOnset(event);
  },
  onState: (state) => (status.textContent = state), // connecting, open, reconnecting, ended, refused, closed
});
// subscription.close() to stop reading

subscribe sends the token in Authorization, so it never sits in a URL or a server log. It delivers each event once and in order, resumes from the last event after a dropped connection, reports a gap in sequence through onGap, and ends by itself after the final session.status. A token that no longer works ends it with refused instead of retrying. On the device that publishes, live.subscribe(...) does the same for its session, and the HUD is built on it.

Server-sent events

Any SSE client reads the stream:

browser.ts
const source = new EventSource(`${session.results.streamUrl}?token=${clientToken}`);
source.addEventListener('imminence.updated', (message) => {
  meter.value = JSON.parse(message.data).data.p30 ?? 0;
});
source.addEventListener('session.status', (message) => {
  if (JSON.parse(message.data).data.status === 'ended') source.close();
});

Each message's id: is the event id, and event: its type. A comment line every 15 seconds keeps proxies from closing the connection. Filter with ?types=orgasm.onset,orgasm.peak,orgasm.end. On a server, send the secret key in Authorization. EventSource can't set headers, so it is the one reader that puts a client token in the URL, as token; a view token is never accepted there.

The WebSocket

The socket carries the same events as the stream, one JSON text frame each in sequence order, and takes your product's stimulation reports the other way. Connect with ?token= and the session's client token, or, where your client can set headers, Authorization: Bearer with the secret key or the client token. A view token never goes in a URL, so view tokens read the stream instead.

device.ts
const socket = new WebSocket(`${session.results.websocketUrl}?token=${clientToken}&types=imminence.updated,session.status`);
socket.onmessage = (message) => {
  const event = JSON.parse(message.data);
  if (event.type === 'imminence.updated') meter.value = event.data.p30 ?? 0;
};
// the toy's level changed
socket.send(JSON.stringify({ action: 'stimulation', state: 'on', level: 34, levelMax: 60, mode: 'waves' }));
  • ?after= replays from an event, ?types= filters, and ?frames=face adds face frames.
  • The client sends stimulation, the same report as reportStimulation, and resume with an after to replay without reconnecting. A message it can't take is answered with a socket.error frame (invalid_message, unknown_action, session_ended), and the socket stays open.
  • It closes with 1000 after the session's final status, 1008 when its token stops working, and 1013 when the session already has its 12 readers.

Reporting the device

If your product drives a device, tell orgasm.dev what it is doing: on or off, its level and the most it will go to (levelMax), each output's level for a device with more than one (channels, up to four), its mode and modeLabel, who sets the level (drive: auto, manual, hold or paused), and whether it is connected. A report updates the fields it carries and keeps the rest; null clears one. state alone is enough for imminence to account for time under stimulation, and for a stop to make an orgasm a ruin (presets).

Each report reaches every reader of the session as stimulation.updated, at most four a second, reports in between merged into the next: a HUD shows it as the stimulation strip and a lane of its timeline. The SDK does the merging and the pacing for you, over the socket while it is open and over HTTP while it is not:

device.ts
live.reportStimulation({ state: 'on', level: 31, levelMax: 60, channels: [{ id: 'a', level: 31 }, { id: 'b', level: 24 }], mode: 'waves', device: { label: 'Unit' } });
live.reportStimulation({ state: 'on', level: 34 }); // only the level changed

On your server, stimulationReporter({ ...reporterOf(session), token: process.env.ORGASM_KEY }) does the same over HTTP, since a secret key never goes in a URL. Report changes, not a heartbeat. The device's name is what a display shows: never the person's.

Face frames

signals.updated carries the face's 24 expression channels and the head's turn once a second (face). A display that draws the face, like the HUD's face part, can ask for them about five times a second as well: add frames=face to the stream or the socket, or pass frames: ['face'] to subscribe.

device.ts
subscribe({ ...streamOf(session), frames: ['face'], onEvent: (event) => hud.feed(event), onFaceFrame: (frame) => hud.feedFrame(frame) });

A face.frame is not an event: it has no id or sequence, is never stored, replayed or sent to webhooks, and a reader that falls behind skips to the newest. Its face is null while the face is out of view and before the baseline is in.

A frame also carries cameraHead: the head as the camera sees it (yawDeg and rollDeg within 180, pitchDeg within 90, with head's senses), not its turn from the resting pose. A head held tilted through the baseline minute, or lying on its side, reads as it is, where head reads it as rest. It needs no baseline, so it arrives as soon as the face is in view; it is null while the face is out of view, and a frame without it is read the same way. Draw the head by cameraHead where a frame has it, and by face.head otherwise.

Another screen: view tokens

A screen other than the person's device, such as a coach's view, a second monitor or a stream overlay, reads with a view token. Your server creates one per screen with createViewToken and hands it over; the screen reads with subscribe or the HUD's connect.

server.ts
const view = await fetch(`https://orgasm.dev/v1/live-sessions/${session.id}/view-tokens`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ expiresInS: 3600 }),
}).then((response) => response.json());
// view.token is vt_…; view.eventTypes lists what it reads

It reads the stream and the event list, with the token in the header only, and only the display's events: imminence and the other signals, the device's stimulation.updated, the calls, edges, warnings and statuses. The subject read is included only when the token is created with includeSubject: true, and the face's channels, in signals.updated and as frames, only with includeFace: true: a screen others watch should not show either unasked. It can't read the session object, its metadata or its references, and can't report stimulation.

Long polling

curl -s "https://orgasm.dev/v1/live-sessions/ls_…/events?after=evt_…&types=orgasm.onset,orgasm.peak,orgasm.end&wait=30" \
  -H "Authorization: Bearer $ORGASM_KEY"

The request returns as soon as a matching event exists after after, or after wait seconds with an empty data. Pass nextCursor back as after next time. The action MCP server's wait_for_event is this loop.

Resuming

Connections drop. Nothing is lost if you resume from the last event you processed:

  • subscribe resumes by itself.
  • Server-sent events: browsers send Last-Event-ID automatically on reconnect; elsewhere send it yourself, or ?after=.
  • The socket: reconnect with ?after= and the last event's id, or send resume on an open socket.
  • Long polling: always pass after.

Missed events are replayed first, in sequence order. Deduplicate on id regardless; delivery is at least once.

Limits

  • A session serves at most 12 streams at once, sockets included, whoever reads them; another stream is refused with 429 rate_limited, another socket with a socket.error and 1013, until one closes.
  • A stream or socket is closed after an hour; reconnect after the last event, as subscribe does by itself.
  • Client and view tokens stop working five minutes after the session ends, which leaves time to read its final events. A view token stops sooner at its own expiresAt.

Which to choose

  • A browser experience that reacts on screen: subscribe with the client token, or the HUD.
  • A game: subscribe where it runs JavaScript; a native engine reads the stream with its own HTTP client.
  • A product that drives a device: the socket, which reads the events and takes the device's reports over one connection, or live.reportStimulation beside subscribe.
  • Another screen: a view token.
  • A backend that records outcomes: webhooks for calls, plus the stream if it needs imminence.
  • An agent: long polling, or wait_for_event over MCP.

On this page