# Recordings (https://orgasm.dev/docs/guides/recordings)

A recording is a video file analysed after the fact. It is a separate endpoint from live sessions, and it returns the same events as a timeline.

<Callout title="Status">
  Recordings are analysed in the sandbox only for now, with a key that starts with `sk_test_`. With a live key, `createRecording` answers `live_mode_unavailable`; [live sessions](/docs/guides/live-sessions) are open.
</Callout>

## Requirements [#requirements]

- The person's face, in view, in H.264 or H.265 video.
- Between two minutes and four hours. The first minute is the person's baseline.
- The audio track, if you want onset, peak and end (`inputs.audio`, true by default).
- A recording of a person who agreed to this analysis of it ([acceptable use](/docs/concepts/compliance)).

## Submit by upload [#submit-by-upload]

```bash
curl -s https://orgasm.dev/v1/recordings \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "document" },
    "source": { "type": "upload" }
  }'
```

The recording comes back `awaiting_upload`, with `uploads.face`: a URL, a method (`PUT`), headers, a size limit and an expiry. In live mode `uploads.face.sealed` is true: the SDK seals the file to the enclave before it leaves the device, so only the enclave can read it.

```bash
curl -X PUT --data-binary @session.mp4 -H "Content-Type: video/mp4" "<uploads.face.url>"
```

With `source.bodyView: true` you also upload a body video to `uploads.body`; `bodyOffsetS` says how many seconds after the face video it starts.

## Submit by URL [#submit-by-url]

```json
{
  "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "payment_card" },
  "source": { "type": "url", "url": "https://storage.example.com/sessions/1842.mp4?signature=…" }
}
```

The enclave fetches the file itself. Give a signed URL valid for at least an hour; the stored `source.url` drops its query string.

## Processing [#processing]

`awaiting_upload` → `queued` → `processing` → `completed` (or `failed`). Processing takes about as long as the recording. While it runs, `progress.processedS` counts up, and `listRecordingEvents` already returns what has been analysed.

When it finishes, a `recording.completed` webhook is sent to subscribed endpoints, and `getRecording` returns `result`:

- `subject`: the subject read.
- `summary`: the recording's length and one entry per orgasm: its onset, peak and end, its duration, the detectors that called it, and its confidence.
- `timeline`: the discrete events in order (orgasm calls, the subject read, input warnings).

Imminence for every second of analysed face is in `listRecordingEvents`; filter it with `types=imminence.updated`.

## Failure [#failure]

`recording.failed` and `failure.code` say why: `unreadable_media`, `no_face`, `too_short`, `too_long`, `fetch_failed`, `upload_expired` or `internal` (submit it again).

## Deletion [#deletion]

The video is deleted once analysed. `deleteRecording` deletes the result and the events now; otherwise they go at `resultsExpireAt` (`retentionDays`, 30 by default).

## In the sandbox [#in-the-sandbox]

The upload URL points at the sandbox, which reads and discards the bytes, then plays `sandbox.scenario` at `sandbox.speed` (60 by default, so a 13-minute scenario completes in 13 seconds). Upload any small video file, never a real recording of a person.
