# Show the HUD (https://orgasm.dev/docs/guides/hud)

`<orgasm-hud>` shows a live session to the person as it happens: how close they are, what just happened, and what needs their attention. It is part of the [device SDK](https://github.com/Orgasm-dev/device-sdk), draws only from the session's [events](/docs/concepts/signals), and has no dependencies.

<HudDemo layout="rail" caption="The edge scenario, played in your browser: no network, no camera." />

## What it shows [#what-it-shows]

- **The phase**, in a word. It says Calibrating while the person's baseline is taken (about a minute), then Building, then Rising, Close and Very close at the [presets'](/docs/concepts/presets) levels (`p30` at 0.3, 0.6 and 0.75). After a call it says Onset, Peak or Afterglow.
- **The gauge**: the chance that orgasm begins within 30 seconds (`p30`), with the 60-second chance as a ghost mark. It eases between the once-a-second readings, and it reads as a chance within 30 seconds, never as a countdown ([timing](/docs/concepts/timing)).
- **The trend**: the last three minutes, with each onset, peak, end and edge marked at the moment it names rather than when it arrived.
- **The counts** of orgasms, ruins and edges, and the session's clock.
- **The signals** from `signals.updated`: vocalizations, contractions and movement as tiles, and how far each region of the face has moved. Each appears only while its input is there.
- **The device**, when your product drives one and [reports it](/docs/guides/realtime#reporting-the-device): its name, its mode in words, who sets the level, and a bar per output toward the most it will go to.
- **The face**: a generic face (the Momentum Human Rig's mean head, which is no one's, its two sides each other's mirror) moving as the person's does, from their expression channels and the turn of their head, with the face's seven regions as meters beside it. It glides between readings, and follows the face five times a second when it reads frames. Where frames carry the head as the camera sees it (`cameraHead`), the head is drawn by that: a head held tilted, or lying on its side, is drawn as it is, and during the baseline a face at rest follows the head under the waiting words.
- **The timeline**: the whole session, up to three hours in five-second bins, in three lanes on one time axis: imminence, the device's level per output with each change of mode, and the body's rates. Each lane draws only once it has something to show, and each call and edge is marked across them.
- **Notices**, such as the face out of view, the baseline being taken or no microphone.
- **The subject read**, only when you ask for it with `show` ([subject](/docs/concepts/subject)).

On the person's device the HUD always shows that analysis is on, and a Stop control. The [Acceptable use](/docs/concepts/compliance) rules ask for both: the person sees when analysis runs, and can stop it at any moment.

## Install [#install]

```sh title="Terminal"
npm install @orgasm-dev/device
```

```ts
import '@orgasm-dev/device/hud'; // defines <orgasm-hud> and <orgasm-capture-primer>
```

The import is safe in server rendering: the elements are defined only where the browser has a registry.

## On the person's device [#on-the-persons-device]

The device that publishes reads the session's events with its client token. Feed them to the HUD, and end the session when the person presses Stop:

```html
<orgasm-hud layout="rail"></orgasm-hud>
```

```ts title="device.ts"
const hud = document.querySelector('orgasm-hud');
const live = await publishLiveSession({ session, capability, stream });
live.subscribe({ frames: ['face'], onEvent: (event) => hud.feed(event), onFaceFrame: (frame) => hud.feedFrame(frame) });
hud.addEventListener('orgasm-hud-stop', async () => {
  await live.stop({ releaseCamera: true });
  await fetch('/api/session/end', { method: 'POST' }); // your server ends it with the secret key
});
```

A page that only displays the session can let the HUD subscribe itself: `hud.connect({ streamUrl, token })`, which asks for face frames when the HUD shows the face. `orgasm-hud-phase` fires on each change of phase, with `phase`, `previous` and the whole `view` in its `detail`.

If your product drives a device, report it as it changes, and the HUD shows it beside the person's signals. The HUD only displays the device; your own controls set it.

```ts title="device.ts"
live.reportStimulation({ state: 'on', level: 31, levelMax: 60, mode: 'waves', device: { label: 'Unit' } });
```

### The whole panel [#the-whole-panel]

`layout="panel"` is the whole display: the phase, the gauge and the device's strip over three pages, Signals, Face and Timeline, turned with tabs or a swipe. Pick the first with `page="face"`.

<HudDemo layout="panel" scenario="edge" caption="The edge scenario with a scripted two-channel device: its level follows the person, it is held near the edge, and its mode changes as imminence rises." />

### A siderail [#a-siderail]

`layout="rail"` is a panel down the side of a page, beside a video or a scene: every part but the subject read, the face and the timeline, which you can add with `show`.

```html
<aside style="position: fixed; top: 80px; right: 16px; width: 320px">
  <orgasm-hud layout="rail"></orgasm-hud>
</aside>
```

### A bottom bar [#a-bottom-bar]

`layout="bar"` is a strip across the page: the phase, the gauge, the device, the counts, the clock and the notices.

<HudDemo layout="bar" scenario="finish" />

### A card in a game [#a-card-in-a-game]

`layout="card"` sits in a corner of a game or a scene, with the phase and the chance only.

<HudDemo layout="card" scenario="ruin" />

## On another screen [#on-another-screen]

A display that someone else watches, such as a coach's view, a second monitor or a stream, reads with a **view token** instead of the client token. Your server makes one per screen:

```ts title="server.ts"
const response = 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: 3 * 3600 }),
});
const { token } = await response.json(); // vt_…, shown only now
```

```ts title="screen.ts"
hud.connect({ streamUrl: session.results.streamUrl, token }); // sent in a header, never in the URL
```

A view token reads the session's display events and nothing else. It cannot read the session object with its metadata and references, and it cannot report stimulation. The subject read is left out unless you pass `includeSubject: true`, and the face's channels unless you pass `includeFace: true`: without them a `face` part shows nothing. The token stops at its `expiresAt` or five minutes after the session ends, whichever comes first ([`createViewToken`](/docs/api/live-sessions/createViewToken)).

Give a screen other than the person's the `stream` attribute, or use `layout="overlay"`, which implies it. Both leave out the indicator and the Stop control, which belong on the person's own device.

<HudDemo layout="overlay" scenario="edge" theme="dark" />

## In a game engine [#in-a-game-engine]

To draw the HUD natively, use the model the element draws. `hudReducer` folds each event into a state, and `hudView` turns the state into what to show, as plain data, as often as you draw:

```ts
import { subscribe, streamOf } from '@orgasm-dev/device';
import { hudFrameReducer, hudReducer, hudView, initialHudState, loadFaceMesh, poseFace } from '@orgasm-dev/device/hud';

let state = initialHudState();
subscribe({
  ...streamOf(session),
  frames: ['face'],
  onEvent: (event) => (state = hudReducer(state, event, Date.now())),
  onFaceFrame: (face) => (state = hudFrameReducer(state, face, Date.now())),
});
const mesh = await loadFaceMesh(); // the generic face, about 40 KB, fetched once

function frame() {
  const view = hudView(state, Date.now());
  // view.word, view.gauge.p30, view.trend.points, view.counts, view.clock.text, view.notices, view.signals,
  // view.stimulation (the strip), view.timeline (its lanes as points 0 to 1), view.face (its channels, regions and cameraHead)
  const face = view.face;
  // x, y per point, the head 1000 tall, turned as the camera sees it where a frame says so
  const points = face?.channels ? poseFace(mesh, face.channels, undefined, undefined, { cameraHead: face.cameraHead }) : null;
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
```

Between frames, `headGlideTo` and `headAt` glide `cameraHead` the short way round, as `glideTo` and `faceAt` glide the channels.

An engine that does not run JavaScript reads the [stream](/docs/guides/realtime) itself. The model's source, held to the sandbox's scenarios by golden files, is the reference for the phases, how long each call holds the display, and when a reading counts as stale.

## Theme and words [#theme-and-words]

- `theme="dark"` (the default), `"light"` or `"auto"`, which follows the page's preference. `size` is `"sm"`, `"md"` or `"lg"`, and `brand="off"` hides the orgasm.dev mark.
- CSS custom properties restyle it: `--orgasm-hud-accent`, `--orgasm-hud-surface`, `--orgasm-hud-text`, `--orgasm-hud-muted`, `--orgasm-hud-font` and the others.
- `show` picks the parts, from `phase gauge percent trend counts clock signals notices subject stimulation face timeline`.
- `hud.strings` rewords any of it, for another language or your product's voice: `hud.strings = { phases: { close: 'Nearly there' } }`.

```css title="styles.css"
orgasm-hud {
  --orgasm-hud-accent: #ff4f8b;
  --orgasm-hud-font: 'Inter', system-ui, sans-serif;
}
```

## Accessibility [#accessibility]

The gauge is a `meter` whose value text gives the phase and the chance in words. Each change of phase is announced politely, once; nothing else is. When the system asks for reduced motion, nothing eases or pulses.

## Without a camera [#without-a-camera]

- `hud.demo({ scenario: 'edge' })` plays a scripted session in the browser with no network, a face and a scripted device included: `edge`, `finish`, `ruin` or `face-lost`.
- A [sandbox](/docs/guides/sandbox) session with `speed: 1` plays in real time against the API with a test key, so the whole loop, the HUD included, works before any camera is involved.
