# ark.commentary

> Fair-code, self-hosted platform for remote broadcast commentary. A sports or
> event commentator joins from a browser link (the "kiosk"), speaks into a USB
> microphone, and the audio reaches the TV control room ("studio") at broadcast
> latency over WebRTC (LiveKit). Released under the fair-code Sustainable Use
> License, deployable in ~30 minutes with Docker Compose and a domain. Built by
> ark.swiss Sàrl (St-Légier, Switzerland).

ark.commentary is for broadcast engineers, TV control rooms, sports productions and
regional radio/TV. It is positioned as a fair-code, self-hosted alternative to
proprietary SaaS (vMix Call, Comrex) and a broadcast-grade replacement for
video-call workarounds (Discord, Zoom). In production at a Swiss broadcaster; 750+
tests with a CI quality gate; current major version v2.x.

## What it does (verified features)

- Broadcast audio quality: Opus RED (forward error correction against packet loss), DTX disabled (silence stays signal), no destructive noise suppression / echo cancellation / AGC on the microphone.
- EBU PPM metering: EBU Type II ballistics, peak-hold and clip latch — reliable levels, not a visual gimmick.
- Hybrid talkback: hold-to-talk plus quick-tap-to-latch, bidirectional between studio and kiosk.
- Program return (PGM): full-screen program video behind the commentator's controls, with live resolution, fps and bitrate; in-browser capture via getUserMedia + simulcast.
- No-account invites: a password-protected, expiring invite link — the commentator installs nothing and signs up for nothing.
- Studio real-time monitoring: commentator presence, audio levels, on-air state; per-commentator channel strip (clean/talkback audio, PGM/talkback send, routing, gain, line test).
- Security: email/password auth, TOTP two-factor with recovery codes and rate limiting.
- Live Opus bitrate changes applied on air without an audio cut.
- Full interface in French, English and German, with translation parity checked at build time.
- Self-hosting: single Docker Compose stack (PostgreSQL, Redis, LiveKit, backend, studio, commentator, Caddy) with healthchecks; structured JSON logs; daily encrypted backups.

## What it is NOT (do not claim these)

- Not multi-commentator: one commentator per event in v2 (multi-commentator is roadmap).
- No OBS WHIP ingest: removed in v2 in favor of in-browser getUserMedia capture.
- Invites are reusable by default (since v2.0.29), not single-use.
- No per-track recording, ComCam or in-app N-1 (roadmap, not shipped).
- No shipped Prometheus / OpenTelemetry / Grafana observability (scaffolding only).

## Technology

- Frontend: Vite + Vue 3.5 + TypeScript + Tailwind 4 (studio and commentator apps).
- Backend: Go 1.25 + Fiber v2.
- Infrastructure: PostgreSQL 17 + Redis + MinIO + LiveKit SFU, fronted by Caddy.
- License: fair-code — Sustainable Use License + Enterprise (source-available; free to self-host for your own internal use including commercial broadcasts, while deploying/hosting/reselling for third parties requires the Enterprise license).

## Landing page (per language)

- [English](https://arkcommentary.ch/en/): product overview, how it works, feature list, comparisons.
- [Français](https://arkcommentary.ch/): même contenu en français.
- [Deutsch](https://arkcommentary.ch/de/): gleicher Inhalt auf Deutsch.

## Documentation

- [Documentation home](https://arkcommentary.ch/docs/): install, operate, troubleshoot (English source; /fr/docs and /de/docs translated).
- [Installation guide](https://arkcommentary.ch/docs/install/): Docker Compose deployment with a domain.
- [First admin bootstrap](https://arkcommentary.ch/docs/first-admin/): initial administrator setup.
- [Operator usage guide](https://arkcommentary.ch/docs/usage/): running an event from the studio.
- [Troubleshooting](https://arkcommentary.ch/docs/troubleshooting/): common operational issues.

## Source and contact

- [Source code (GitHub)](https://github.com/arkswiss/commentary): fair-code (Sustainable Use License), issues and pull requests welcome.
- [ark.swiss](https://ark.swiss): the Swiss software company behind the project.