​

Video room engagement & chapter analytics pipeline

A video room produces three different analytics questions, and Orbit answers each with a dedicated endpoint pair. This page covers the three planes, the playback signal vocabulary each one captures, how each rolls its data up, and the retention and privacy guarantees every plane holds. The Broadcast analytics model covers the fourth plane — the CDN audience consuming a broadcast stream — and the endpoint-by-endpoint contract lives in the Video API reference.

​

The three planes

Pick the plane your question belongs to. Room usage aggregates the durable per-session rows the room-finished webhook persists. Engagement reads the per-participant detail the host browser flushes at room end. Chapter themes aggregate across recording rows, read-only — they never mutate the recordings they summarize.

​

Playback signal vocabulary

Each plane captures a different event vocabulary, sized to its population:

• Room usage keys on session lifecycle events — join, leave, and the end-reason vocabulary (error, or the neutral unused bucket for a room no participant ever connected to). The browser that buffers in-room signals distinguishes play, pause, and seek timestamps so the flush carries only finalized talk-time, screen-share, and hand-raise totals.
• Chapter themes come from chapter boundaries the post-recording chaptering pipeline writes onto each recording — the same chapter-enter and chapter-complete boundaries the playback sidebar renders. The analytics read aggregates those titles; it does not re-derive them.
• Broadcast-viewer events (play, pause, buffering, ended) are heartbeat signals on the CDN plane; see Broadcast analytics model.

​

How each plane aggregates

Roll-up dimension differs per plane, deliberately:

• By room — GET /video/usage?from=&to= returns a summary object (org-wide totals for the window) plus a daily time series, one UTC bucket per day, so a dashboard renders headline stat cards and a sessions-over-time sparkline from one read. avg_peak_participants excludes never-connected zero-participant rooms so idle rooms do not drag the average toward zero; recording_success_rate is null when no recording was attempted instead of a misleading 0 or 1.
• By registrant — GET /video/rooms/:name/sessions/:sessionId/engagement returns per-participant detail: speaking duration, the speaker-balance speaking_share computed against the whole-session sum (guarded so an all-silent session reports 0, not NaN), screen-share duration, hand-raise counts, each participant’s dominant_segments, and first/last spoke timestamps. The participant list is keyset-paginated (?limit=, ?offset=, ?after= with the previous page’s page.next_cursor), ranked by speaking time then identity — a total order, so paging never skips or duplicates a row. Session-scope aggregates resolve over the full roster, not the current page, so a page-bounded view never misreports them.
• By chapter — GET /video/chapter-analytics?from=&to= unwinds every recording’s chapters in the window and groups by the normalized title (lowercased, trimmed), reporting occurrence_count, avg_duration_ms averaged across occurrences, and recordings_count, capped at 50 themes sorted by occurrence count. Exact-match grouping is deliberate: the pipeline emits short normalized titles, and a fuzzy clusterer belongs to a separate analytics service, not a read path.

Both the usage and chapter windows default to the last 30 days when from and to are omitted, and an inverted window returns INVALID_WINDOW (400).

​

Retention, dashboards, and exports

• Durable planes. Engagement and usage reads query the workspace’s durable session and engagement rows directly — there is no cache to recompute, so a read always reflects the latest flush. Data remains available for as long as the underlying session or recording row exists.
• CDN plane. Broadcast-viewer aggregates live in Redis with short TTLs (presence keys expire 60 seconds after the last heartbeat; per-room health history stays readable for 24 hours) precisely so the pipeline touches no durable store — a recomputation model, not retention. See Broadcast analytics model.
• Degradation. A workspace not yet provisioned for engagement analytics degrades to the empty state on reads and a 503 SERVICE_UNAVAILABLE on flush writes — never a raw 500. A Redis outage degrades the CDN plane to the same clean 503.

​

Privacy and isolation

• Identity. CDN viewers identify themselves with a player-minted opaque session id, never personal data. Engagement participants key on the media server’s own participant identity plus an optional display name the host supplies — no cross-workspace identifier ever enters the pipeline.
• Tenant-scoped reads. The usage, engagement, and chapter planes resolve every request through the workspace’s private data schema, and the CDN plane namespaces every key by workspace — a cross-workspace aggregate is structurally impossible on any plane.
• Erasure. Soft-deleted sessions and recordings are excluded from every aggregate, so a GDPR-erased session or call never leaks back into usage totals or theme lists.

​

Contrast with broadcast-analytics-model

The Broadcast analytics model covers the aggregate broadcast funnel — viewers consuming the HLS/WHEP stream through a CDN, measured by player heartbeats in Redis. The planes on this page are the in-room and post-recording planes: engagement, usage, and chapters measure connected participants and realised sessions, not the anonymous broadcast audience. A webinar usually runs both: the in-room panel uses the engagement plane, the public broadcast link uses the CDN plane, and the recording feeds the chapter plane afterward.

​

See also