stapel-video

Video calls: rooms with shareable join codes, an access-level admission model (public / scope-trusted / restricted lobby) with a realtime waiting room over WebSockets, host admit/deny controls, join-token minting through a pluggable video-provider seam (LiveKit by default), a recording-egress seam (start/stop + a video.egress_ended event) that integrates with stapel-recordings by event and never by import, and a presence meter — per-connection spans fed by the media server's own join/leave webhooks, reconciled by a sweeper so a crashed client cannot bill forever, and read back as unioned presence time and a co-presence matrix for whatever prices them, partitioned by an opaque scope_key carried on the join grant so a workspace administrator can read their own people's monthly call time behind their own mandate.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-video

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

• Rooms with human-shareable join codes (abc-defg-hij).
• Admission model — public (anyone with the code joins), scope_trusted (members of the room's scope join instantly, others wait), restricted (everyone but the host waits in a lobby).
• Realtime lobby on the fleet substrate (stapel-realtime) — one ephemeral stream video:lobby:<join_code> carrying lobby.waiting / lobby.admitted / lobby.denied on the v1 wire envelope, gated on room membership. A browser opens it with its JWT cookie (no header a browser cannot send), behind the origin guard that ambient credential requires.
• Host controls — admit / deny waiting guests.
• Provider seam — one VideoProvider ABC (mint join token, create room, start/stop recording egress, verify webhook). Swap vendors without forking.
• Recording is a seam, not a pipeline: start/stop_egress proxy the provider and a video.egress_ended comm event carries the storage key to stapel-recordings — by event, never by import.
• Presence metering — per-connection spans fed by the media server's own join/leave webhooks (the only departure signal that survives a closed laptop), reconciled by a sweeper so a lost webhook cannot bill forever, and read back as unioned presence time and a co-presence matrix. Raw seconds, no threshold: this instance meters, whatever prices it decides what counts.
• Per-tenant usage — spans carry an opaque scope_key set on the join grant, so "who in THIS workspace talked how much, per month" is a read this library answers, gated on the caller's mandate in that very scope. A foreign key answers 404, never 403.

Alpha. See MODULE.md for the agent-facing map of seams.

Quick start

pip install stapel-video            # core library
pip install 'stapel-video[livekit]' # + the default LiveKit backend
pip install 'stapel-video[realtime]'# + serving the lobby socket

# urls.py
path("video/", include("stapel_video.urls"))

# settings.py — deliver the lobby signals, and say which pages may open a socket
INSTALLED_APPS = [..., "stapel_realtime", "stapel_video"]
STAPEL_COMM = {"SIGNAL_TRANSPORT": "channels"}
STAPEL_REALTIME = {"ALLOWED_ORIGINS": ["https://app.example.com"]}

# asgi.py (realtime lobby) — routes discovered from INSTALLED_APPS
from django.core.asgi import get_asgi_application
from stapel_realtime.asgi import build_websocket_application

application = build_websocket_application(
    http_application=get_asgi_application()
)

API

Configuration (STAPEL_VIDEO)

VIDEO_PROVIDER, DEFAULT_ACCESS_LEVEL and DEFAULT_ADMIT_REQUIRED are the three CTO-facing config axes surfaced in docs/capabilities.json.

Presence metering

Turn the provider's webhooks on (they point at POST /video/api/webhook), and schedule the two jobs — a meter without the sweeper measures an upper bound, not a duration:

from stapel_video.tasks import get_video_beat_schedule

CELERY_BEAT_SCHEDULE = {**get_video_beat_schedule(), ...}

Celery is optional: manage.py video_sweep_presence and manage.py video_purge_spans are the cron form. Then read the numbers by comm Function:

from stapel_core.comm import call

call("video.presence.aggregate", {"user_id": uid, "period": "2026-08"})
# {"presence_seconds": 5400, "rooms_count": 3, ...} — unioned, so a laptop
# and a phone are one person present, not two.

call("video.presence.pairs_export", {"period": "2026-08", "limit": 500})
# {"rows": [{"room_key", "user_a", "user_b", "co_presence_seconds"}, ...],
#  "cursor": ..., "total": None} — raw overlaps; the "counts as a real
#  conversation" threshold belongs to whoever asks, not to the meter.

Per-tenant usage

Pass the partition on the grant and the provider echoes it back onto every span it reports:

provider.mint_join_token(room_ref, user.pk, name, scope_key=str(workspace_id))

Spans recorded before you did that are the host's to place — only you know which tenant a room_key belonged to:

manage.py video_backfill_scope --resolver myapp.reporting.scope_for_room

Then read a workspace's own numbers, over the bus or over HTTP:

call("video.presence.usage_rollup_by_month",
     {"scope_key": str(workspace_id), "months": 6, "tz": "Europe/Berlin"})
# {"months": [{"month": "2026-08", "users": [{"user_id", "presence_seconds",
#  "rooms", "connections", ...}]}]} — newest month first, buckets cut at LOCAL
#  midnight, so a DST month is genuinely an hour short.

GET /video/api/v1/scopes/{scope_key}/usage/?months=6&tz=Europe/Berlin is the same answer for a workspace-administration screen. It is not staff-gated: the caller must hold STAPEL_VIDEO["USAGE_MANDATE"] (default video.usage.read) in the workspace they are asking about, resolved through the workspaces access registry — register it on the roles you mean to grant it to. Asking about somebody else's workspace answers 404, identically to a workspace that does not exist: a 403 would confirm the id is real. Without workspaces in the picture, USAGE_AUTHORIZER decides (staff-only unless you replace it).

Rows carry user ids. This library never learns anybody's name; the host resolves it from the roster it already has.

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}