> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Video room engagement & chapter analytics pipeline > The three room-analytics planes — per-room usage over session history, per-participant engagement buffered in the browser and flushed at room end, and chapter themes aggregated across recordings — how each aggregates, the playback signal vocabulary each captures, retention and empty-state behavior, and the privacy rules behind every plane # 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](/concepts/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](/api-reference/video). ## The three planes | Plane | Question it answers | Endpoints | | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | Room usage | How is the workspace using rooms — session counts, room-minutes, peak participants, recording success, unused rooms | `GET /video/usage` | | Per-participant engagement | Who spoke, shared screens, or raised hands in one realised session | `POST` + `GET /video/rooms/:name/sessions/:sessionId/engagement` | | Chapter themes | Which topics recur across recordings in a date window | `GET /video/chapter-analytics` | 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](/concepts/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](/concepts/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](/concepts/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 Room lifecycle, join tokens, and the sessions the usage plane aggregates. The CDN audience plane — heartbeat-based viewership for broadcast rooms. The endpoint-by-endpoint contract for all three planes. The hands-on guide to the engagement panel and its pagination. The egress and chaptering pipeline that writes the per-recording chapters the theme plane aggregates. The isolation model behind every plane's scoping.