Playback & Display Modes¶

Cantus is engineered to deliver a seamless, distraction-free lyrics display across any screen format—from a secondary desktop monitor to a dedicated living room TV kiosk.

Responsive Multi-Form-Factor Layouts¶

Cantus features a dynamic responsive layout engine that automatically and fluidly adapts to any screen size and aspect ratio:

flowchart TD
    Screen["Screen Size & Form Factor"] --> RLM["Responsive Layout Engine"]
    RLM --> Small["Small / Mobile (< 680px)"]
    RLM --> Medium["Medium / Tablet (680-1080px)"]
    RLM --> Large["Large / Desktop (>= 1080px)"]
    RLM --> TV["Fullscreen / TV 10-Foot (Kiosk Toggle)"]

    Small --> S_View["Compact Header + Swipeable Lyrics/Track/Sync Tabs + Mini Strip"]
    Medium --> M_View["Streamlined Dual-Column + 230px Album Art + Compact Telemetry"]
    Large --> L_View["Expansive Dual-Column + 332px Track Card + Full Diagnostics Pills"]
    TV --> TV_View["Centered 10-Foot Karaoke Stage + Floating Bottom HUD Bar"]

Form Factor Specifications¶

Form Factor	Breakpoint	Header Mode	Track Card	Lyrics Stage	Navigation
Small (Mobile)	`< 680px`	Minimal + Overflow Flyout	Compact 56px thumbnail strip or dedicated tab	Touch-focused, 24px active line	3-Tab Bottom Bar (Lyrics / Track / Sync & Info)
Medium (Tablet)	`680px - 1079px`	Compact status + quick action icons	Side-by-side 290px rail with 230px artwork	Balanced 32px active line	Direct dual-pane or adaptive portrait flow
Large (Desktop)	`>= 1080px`	Full telemetry pills + actions	Expansive 380px card with 332px artwork	Grand 38px active line with smooth auto-scroll	Dual-column workspace
Fullscreen (TV)	Kiosk toggle (`K` / `F11`)	Hidden	Floating minimal 10-foot HUD	Centered 50px high-contrast karaoke lyrics	Keyboard / remote navigation

Auto-Scrolling & Interactive Controls¶

Cantus combines automated karaoke-style tracking with full manual freedom:

1. Dynamic Auto-Centering¶

During playback, the lyrics stage dynamically scrolls to maintain the active singing line in the optical center of the display. Padding at the top and bottom of the container dynamically adjusts based on viewport height so the first and last lines can be centered comfortably.

2. Manual Scroll Detection & Free Browsing¶

If you want to read ahead or check previous lyrics: - Simply scroll using your mouse wheel, trackpad gesture, or touchscreen drag. - Cantus immediately detects user intervention and sets auto-scroll to Paused. - The active line continues to highlight in time with the music, but the scroll position will not jump or fight against your scrolling.

3. Floating Resume Button & 3-Second Auto-Resume¶

When manual scrolling pauses the display: - A floating "Resume Auto-Scroll" pill button appears at the bottom-center of the stage. - If no scrolling interaction occurs for 3 seconds, Cantus automatically resumes auto-scrolling with a smooth transition back to the currently active line. - You can also tap the floating Resume button at any time to re-center immediately.

Display Environments¶

1. Smart TV & Kiosk Display¶

To use Cantus as an ambient music visualizer on a TV or dedicated Raspberry Pi display:

Open your browser on the smart TV (or launch a Chromium kiosk on Raspberry Pi) to your Cantus URL: http://<your-server-ip>:5000.
Select your user room from the room selector.
Enter fullscreen mode (press F11 or use the TV browser's fullscreen button).
Press K (or F11 in the app) to switch into the 10-foot kiosk lyrics stage. Kiosk mode is an explicit toggle, so large monitors keep the full desktop controls unless you opt in; press Esc to exit.
The cursor will auto-hide after 3 seconds of inactivity to keep the display clean.

Raspberry Pi & Kiosk Launch

If using a Raspberry Pi or wall tablet, launch Chromium in kiosk mode:

chromium-browser --kiosk --noerrdialogs --disable-infobars http://cantus.local:5000

2. Multi-Room & Shared Displays¶

Cantus supports multi-room subscriptions: - Each authenticated Spotify account generates a dedicated Room ID. - Any device on your local network (or the internet if reverse-proxied) can navigate to that Room URL. - When you change tracks on your phone or Spotify desktop app, all connected room displays update simultaneously in real-time.

Keyboard Shortcuts¶

When the Cantus display window is focused, you can use keyboard shortcuts for quick control:

Key	Action	Description
`F11` / `F`	Toggle Fullscreen	Expands viewport to fill the entire monitor.
`[`	Delay Lyrics (-50ms)	Decreases timing offset if lyrics are appearing too early.
`]`	Advance Lyrics (+50ms)	Increases timing offset if lyrics are appearing too late.
`0`	Reset Calibration	Resets custom latency offset for the current track to `0ms`.
`D`	Toggle Diagnostics HUD	Shows real-time NTP roundtrip, clock skew, and SignalR latency.
`T`	Toggle Theme Mode	Cycles between Dynamic Cover Art, Dark Slate, and Light themes.

Diagnostics HUD¶

Pressing D opens the built-in Diagnostics HUD overlay. This displays live performance metrics useful for debugging latency and connection quality:

SignalR State: Connection status (Connected, Reconnecting, Disconnected).
NTP Clock Offset: Current estimated clock skew relative to the server (typically < 2ms).
Round-Trip Delay (RTT): WebSocket ping latency.
Active Polling Cadence: Current server-side poll interval for your Spotify account (e.g. 500ms).
Lyrics Source: LRCLIB query result status (Direct Hit, Fuzzy Match, Cache Hit, Instrumental).