Recording
In MOQOM a recorder is not a hidden participant. It is a watchdog: an observer attached to a room through the admin API, disclosed to everyone in it, and governed by the room’s recording policy.
Recording policy
Section titled “Recording policy”Every room has a recording policy, set on CreateRoom or changed with UpdateRoomPolicy.
| Policy | Meaning |
|---|---|
allowed |
The default. A recording watchdog may be attached, and a hosted recording may be started. |
required |
A hosted recording starts with the room and can’t be stopped while the room is open. With your own recorder instead, attach it before the room goes live. |
prohibited |
Attaching a recording watchdog or starting a hosted recording is refused with FAILED_PRECONDITION, including from your own backend. |
r := client.Room("board-meeting")_, err := r.UpdatePolicy(ctx, moqom.PolicyUpdate{ Policy: moqom.Policy{Recording: moqom.RecordingProhibited}, Fields: []string{"recording"},})Name recording in the update mask. A policy update without a mask applies every field. See
RoomPolicy.
Attach a recorder
Section titled “Attach a recorder”- Mint your recorder a token for the room with no publish rights, and start it.
- Attach a watchdog of kind
recording, so the room knows it is being recorded and by whom. - Detach it when the recorder stops.
w, err := client.Room("live/42").AttachWatchdog(ctx, moqom.NewWatchdog{ Kind: moqom.WatchdogRecording, OperatedBy: moqom.OperatedByTenant, Descriptor: "This session is recorded by Example Inc.",})// later_, err = client.Room("live/42").DetachWatchdog(ctx, w.ID, moqom.Actor{})| Field | Notes |
|---|---|
Descriptor |
Shown to participants. Write it for a person. |
OperatedBy |
tenant for your own recorder. third_party needs OperatorName, so the room can say who is recording. |
Scope |
A namespace prefix to record, for example one participant. Empty records the whole room. |
PinnedLayer |
Subscribe to one rung of the layer ladder only. |
What the room sees:
- The watchdog is listed in room state with its kind, operator and descriptor, so your app can show a recording indicator. It is never in the roster or the participant count.
Room.is_recordingis true while a recording watchdog is attached and has not failed.- Every attach and detach is written to the room’s moderation log.
- A room’s
watchdog_limit(default 8) caps how many observers can attach.
Billing
Section titled “Billing”A recorder is billed as a subscriber for the bytes it receives, at the same per-minute rate, as any viewer at the same tier. There is no recording fee. Storage is wherever your recorder writes, so you pay your own storage costs. If the recorder subscribes through a relay you host, only the platform fee applies.
Pin a lower layer (PinnedLayer) if you don’t need full resolution; a recorder that takes the
top rung pays for the top rung.
Recording and end-to-end encryption
Section titled “Recording and end-to-end encryption”Every room is end-to-end encrypted, with no way to turn it off. Relays and any server-side process see ciphertext only, so MOQOM’s servers cannot record the plaintext of a room, and a hosted recording stays ciphertext for good. To record what people saw:
| Option | Result |
|---|---|
| Run your recorder as an agent | Attach a watchdog to the room, mint a token for watchdog.<id>, and run MoqomKit’s RoomAgent with it. It joins the room’s encrypted group as a member every participant can see, and decrypts on your side. The recording is plaintext in your storage; MOQOM still sees only ciphertext. The recorder is inside your trust boundary, so treat its host and storage accordingly. |
| Record on the device | A participant’s app records what it already decrypts. Nothing extra leaves the device. |
Participants’ devices hold back their media while the group contains an agent the room’s signed control log hasn’t disclosed, so nobody is recorded without being told. Hosted rooms don’t publish that log yet, so agents work in self-hosted deployments first; see Recording and classifiers.
Hosted recording API
Section titled “Hosted recording API”The moqom.admin.v1.Recordings service starts, stops and lists recordings made by the hosted
recorder. Every call is scoped to a tenant, and a key scoped to one tenant cannot see another
tenant’s recordings.
| Method | What it does |
|---|---|
StartRecording |
Starts recording a room. The room must be open and its policy not prohibited. Needs the same standing as attaching a watchdog. |
StopRecording |
Asks a recording to stop. The recorder finishes its files, then the recording becomes COMPLETED. |
ListRecordings |
Lists recordings, newest first, optionally for one room. Paged with page_size and page_token. |
GetRecording |
One recording with its files and a signed download link for each. |
import adminpb "github.com/moqom-cloud/moqom-go/admin/adminpb"
recordings := adminpb.NewRecordingsClient(conn)
started, err := recordings.StartRecording(ctx, &adminpb.StartRecordingRequest{ Tenant: "acme", Room: "live/42", Options: &adminpb.RecordingOptions{ Format: adminpb.RecordingFormat_RECORDING_FORMAT_ARCHIVE_AND_CMAF, MaxDuration: durationpb.New(2 * time.Hour), }, Actor: &adminpb.ActorContext{OnBehalfOf: "alice", Reason: "weekly town hall"},})
// laterdone, err := recordings.GetRecording(ctx, &adminpb.GetRecordingRequest{ Tenant: "acme", RecordingId: started.Id, UrlLifetime: durationpb.New(time.Hour),})for _, file := range done.Artifacts { fmt.Println(file.Kind, file.Track, file.Bytes, file.DownloadUrl)}How recordings behave:
- Policy.
prohibitedrefusesStartRecordingwithFAILED_PRECONDITION, and changing a room toprohibitedstops any recording in progress.requiredstarts a recording when the room is created or the policy is set, andStopRecordingis refused while the room is open. Closing the room stops it. - One at a time. A second
StartRecordingfor a room that is already being recorded returnsALREADY_EXISTS. - Disclosure. A hosted recording attaches a
recordingwatchdog operated by MOQOM, so the room shows it is being recorded. The recorder never appears in the roster or the participant count. - States.
PENDINGuntil a recorder picks it up, thenRECORDING,STOPPINGandCOMPLETED, orFAILEDwitherrorset. A recording continues through a recorder restart, and files from each recorder session are kept. - Formats. Every recording includes a lossless archive of each track, with timing.
ARCHIVE_AND_CMAF(the default) also writes fragmented MP4 for tracks that can be packaged without re-encoding: H.264, HEVC and Opus in rooms where end-to-end encryption is off. Each recording also has a JSON manifest listing its files, linked frommanifest_url. - End-to-end encryption. In an E2EE room the hosted recorder stores ciphertext only, exactly
as it was received, and
encryptedis true. Decrypt it later with your own keys. MOQOM cannot play it back. - Downloads. Links in
GetRecordingare valid forurl_lifetime: 15 minutes by default, 7 days at most, with the expiry inurls_expire_at.ListRecordingsreturns the file list without links. A recording with more than 1,000 files setsartifacts_truncated, and the manifest lists the rest. - Storage. Files are stored under a path that begins with your tenant.
Billing. The hosted recorder is billed like any other viewer, for the bytes it receives. There is no recording fee. Storage is passed through at cost.
Related
Section titled “Related”- Moderation: the audit trail that attach and detach are written to.
- Control-plane gRPC API:
AttachWatchdog,DetachWatchdog,ListWatchdogs. - Threat model & controls: hidden observers.