Cantus
Self-Hosted, Real-Time Synchronized Lyrics Display Platform.
Continuous Spotify tracking, sub-millisecond clock sync, and beautiful karaoke-style visual animations.
Sub-Millisecond Clock Sync
Continuous 4-timestamp NTP clock offset estimation and smooth interpolation filters network jitter to keep lyrics perfectly synchronized with your audio stream.
Read about NTP Sync →Adaptive Polling Engine
Intelligently modulates Spotify polling frequency (4s baseline playing, 2.5s/1.2s track-end acceleration, graduated backoff, and 20s background throttling) and sleeps when zero viewers are connected to conserve API rate limits.
Learn about Adaptive Polling →Multi-Tier Lyrics Caching
Instant local SQLite resolution, fallback to LRCLIB fuzzy matching, and negative caching for instrumental tracks with zero third-party tracking.
Explore Lyrics Caching →Dynamic Palette Theming
Extracts complementary accent colors and ambient gradients from active album artwork in real-time for an immersive listening environment.
Discover Theming Engine →Cross-Platform Display
Native desktop application on Linux (Skia/X11) and Windows alongside WebAssembly in modern desktop, tablet, and TV web browsers.
View Display Modes →Privacy & Self-Hosted
Complete data ownership. OAuth tokens are encrypted at rest with ASP.NET Core Data Protection, running locally inside a lightweight multi-arch Docker container.
Self-Hosting Guide →System Workflow Overview¶
sequenceDiagram
autonumber
actor Listener as Listener
participant Client as Uno Client (Browser / TV / App)
participant Hub as SignalR PlaybackHub
participant Poller as Adaptive Playback Engine
participant Spotify as Spotify Web API
participant Cache as SQLite & LRCLIB
Listener->>Client: Open Room / Connect
Client->>Hub: JoinRoom & NTP Clock Sync
Hub-->>Client: NTP Pong (Offset Estimation)
Poller->>Spotify: Poll Current Playback State
Spotify-->>Poller: Track ID, Progress, IsPlaying
Poller->>Cache: Query Synced Lyrics (LRC)
Cache-->>Poller: Parsed Line Timings
Poller->>Hub: Broadcast Playback State & Lyrics
Hub->>Client: Real-Time Stream (State + Lyrics)
Client->>Client: Smooth Scroll & Active Line HighlightDocumentation Tracks¶
📖 User Guide
Learn how to link your Spotify account, customize the lyric display, configure fullscreen TV kiosk modes, and calibrate audio latency offsets.
Go to User Guide →🚀 Operator Guide
Deploy Cantus in your home lab or cloud VM using Docker Compose, setup reverse proxies (Caddy, Nginx, Traefik), and configure Spotify Developer apps.
Go to Operator Guide →🏗️ Architecture & Concepts
Deep dive into the 5-layer system design, real-time SignalR hubs, NTP clock synchronization math, and Uno Platform MVVM rendering.
Explore Architecture →📚 Technical Reference
Complete reference manuals for SignalR PlaybackHub real-time protocol, REST Minimal APIs, Docker configuration, and environment variables.
View Technical Reference →