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.
| Channel | Use it from | Notes |
|---|---|---|
Server-sent events (results.streamUrl) | Browsers, devices, servers | The device SDK's subscribe reads it with the token in a header |
WebSocket (results.websocketUrl) | Devices and servers that also report a device | Events out, stimulation reports in, over one connection |
| Webhooks | Your server | Every type but imminence.updated, signals.updated and stimulation.updated; see webhooks |
Long polling (listLiveSessionEvents with wait) | Agents, serverless functions | One request per batch |
In the browser: subscribe
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 readingsubscribe 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:
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.
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=faceadds face frames.- The client sends
stimulation, the same report asreportStimulation, andresumewith anafterto replay without reconnecting. A message it can't take is answered with asocket.errorframe (invalid_message,unknown_action,session_ended), and the socket stays open. - It closes with
1000after the session's final status,1008when its token stops working, and1013when 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:
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 changedOn 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.
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.
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 readsIt 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:
subscriberesumes by itself.- Server-sent events: browsers send
Last-Event-IDautomatically on reconnect; elsewhere send it yourself, or?after=. - The socket: reconnect with
?after=and the last event'sid, or sendresumeon 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 asocket.errorand1013, until one closes. - A stream or socket is closed after an hour; reconnect after the last event, as
subscribedoes 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:
subscribewith the client token, or the HUD. - A game:
subscribewhere 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.reportStimulationbesidesubscribe. - 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_eventover MCP.
Recordings
Submit a recorded video by upload or by URL, follow its processing, and read its result and timeline.
Show the HUD
A heads-up display of the session for your users, as a siderail, a bottom bar, a card in a game or the whole panel with the face and the timeline, or drawn natively from the same model.