Skip to content

Timing & Latency Offset Adjustment

Different sound systems introduce varying degrees of audio transmission delay. Cantus includes a precision Latency Offset Engine that allows you to shift lyric timing in real time to match what your ears are actually hearing.

Why Audio Latency Occurs

When playing music from Spotify, the Spotify API reports where the playback cursor should be according to their servers. However, physical audio output often lags behind:

Audio Output Device Typical Delay Cause
Direct Headphone Jack / USB DAC < 10ms Negligible hardware buffering.
HDMI ARC / Optical Soundbar 30ms – 100ms TV audio processing & DSP decoding.
Standard Bluetooth (SBC / AAC) 120ms – 250ms Wireless packet buffering and encoding.
AirPlay / Chromecast Audio 1000ms – 2000ms Multi-room streaming buffer sync.

Without offset adjustment, lyrics would highlight slightly before you hear the vocal line on Bluetooth or AirPlay speakers.

Real-Time Offset Adjustment

Cantus allows you to adjust the timing offset on the fly while a song is playing:

flowchart LR
    A["Spotify Position: 01:23.400"] --> B["NTP Clock Synchronizer"]
    B --> C{"+ User Adjusted Offset"}
    C -->|Offset: +150ms| D["Effective Render Time: 01:23.550"]
    D --> E["Highlighted Lyric Matches Ear"]

Adjusting Timing via UI Steppers

In the Track Card (Desktop/Tablet) or Settings View (Mobile), use the SYNC OFFSET stepper buttons:

  • -0.5s / -0.1s: Nudges lyrics earlier if the text is highlighting after you hear the singer.
  • +0.1s / +0.5s: Nudges lyrics later if the text is highlighting before you hear the singer.
  • Reset: Resets the track offset back to +0.0s.

Adjusting Timing via Keyboard

  1. Listen to the vocals while watching the highlighted line on screen.
  2. If the lyrics highlight too early (before you hear the singer):
  3. Press [ to decrease offset by -50ms.
  4. If the lyrics highlight too late (after you hear the singer):
  5. Press ] to advance offset by +50ms.
  6. Press 0 at any time to reset the offset back to 0ms.

Per-Track Offset Persistence

Cantus automatically stores your adjusted offset in its SQLite database keyed by the Spotify Track ID:

  • When the same song plays again in the future, Cantus instantly applies your custom offset.
  • Track-level offsets do not affect other songs that may have different mastering or timing alignments.

Global Default Offset

If all your listening happens over a specific Bluetooth speaker or AirPlay setup with a constant delay across all tracks, you can set a global offset in your server environment:

# .env file
CANTUS_DEFAULT_LATENCY_OFFSET_MS=150

This base offset will apply automatically to all tracks, while per-track micro-adjustments made in the UI will stack on top of it.