Skip to content
Saul Gman edited this page Oct 11, 2026 · 36 revisions

Lyrus Configuration Wiki

This document describes all configuration options available in Lyrus.

The configuration file is loaded from:

~/.config/lyrus/config.json

Fallbacks (in order):

config1.json
config2.json

You may maintain a commented JSONC version and pre-process it into plain JSON before use.


Global Settings

"global": {
  "logs_dir": "~/.cache/lyrus",
  "log_file": "application.log",
  "log_level": "FATAL",
  "lyrics_timeout_log": "lyrics_timeouts.log",
  "lyrics_instrument_log": "instrument.log",
  "debug_log": "debug.log",
  "log_retention_days": 10,
  "max_debug_count": 100,
  "max_log_count": 100,
  "enable_debug": {"env": "DEBUG", "default": "0"}
}
Field Type Default Description
logs_dir string ~/.cache/lyrus Directory where log files are stored.
log_file string application.log Main application log file name.
log_level string FATAL Minimum log level shown. Options: FATAL, ERROR, WARN, INFO, DEBUG, TRACE.
lyrics_timeout_log string lyrics_timeouts.log File for tracks that hit timeout.
lyrics_instrument_log string instrument.log File for tracks detected as instrumental. Prevents repeat lookups for known-instrumental tracks.
debug_log string debug.log Debug-only log file (when enabled).
log_retention_days integer 10 Days before timeout log resets.
max_debug_count integer 100 Maximum debug log entries before truncation.
max_log_count integer 100 Maximum main log entries before truncation.
enable_debug object {"env":"DEBUG","default":"0"} Enables debug logging if environment variable DEBUG=1.

Player Settings

Controls which music players are monitored and MPD connection details.

"player": {
  "enable_cmus": true,
  "enable_mpd": true,
  "enable_playerctl": true,
  "mpd": {
    "host": {"env": "MPD_HOST", "default": "localhost"},
    "port": {"env": "MPD_PORT", "default": 6600},
    "password": {"env": "MPD_PASSWORD", "default": null},
    "timeout": 10
  }
}
Field Type Default Description
enable_cmus boolean true Enable cmus detection (highest priority).
enable_mpd boolean true Enable MPD detection (second priority).
enable_playerctl boolean true Enable playerctl/MPRIS detection (lowest priority).
mpd.host object {"env":"MPD_HOST","default":"localhost"} MPD server hostname. Override with MPD_HOST.
mpd.port object {"env":"MPD_PORT","default":6600} MPD server port. Override with MPD_PORT.
mpd.password object {"env":"MPD_PASSWORD","default":null} MPD password (if any). Override with MPD_PASSWORD.
mpd.timeout integer 10 Connection timeout (seconds) for MPD.

Status Messages

Text shown in the status bar during lyric fetching.

terminal_states defines states that automatically clear after 2 seconds.

"status_messages": {
  "start": "Starting lyric search...",
  "local": "Checking local files",
  "synced": "Searching online sources",
  "lrc_lib": "Checking LRCLIB database",
  "instrumental": "Instrumental track detected",
  "time_out": "In time-out log",
  "failed": "No lyrics found",
  "no_player": "scanning for activity",
  "mpd": "",
  "cmus": "loading cmus",
  "done": "Loaded",
  "clear": ""
},
"terminal_states": ["done", "instrumental", "time_out", "failed", "mpd", "clear", "cmus", "no_player"]

You may customise any message. Setting a message to an empty string ("") hides it.


Lyrics Settings

Controls how lyrics are discovered, cached, and validated.

"lyrics": {
  "search_timeout": 15,
  "cache_dir": "~/.local/state/lyrus/synced_lyrics",
  "local_extensions": ["a2", "lrc", "txt"],
  "validation": {
    "title_match_length": 15,
    "artist_match_length": 15
  },
  "Syncedlyrics": true,
  "Sources": ["Musixmatch", "Lrclib", "NetEase", "Megalobiz", "Genius"],
  "Fallback": true,
  "Format_priority": ["a2", "lrc", "txt"],
  "read_embedded_lyrics": true,
  "skip_embedded_txt": true,
  "Translation": {
    "enable_translation": false,
    "language": "en"
  }
}
Field Type Default Description
search_timeout integer 15 Maximum seconds to wait for online searches.
cache_dir string ~/.local/state/lyrus/synced_lyrics Directory for downloaded lyrics cache.
local_extensions array ["a2","lrc","txt"] File extensions to look for locally.
validation.title_match_length integer 15 Minimum characters title must match.
validation.artist_match_length integer 15 Minimum characters artist must match.
Syncedlyrics boolean true Use syncedlyrics library to search multiple online sources.
Sources array ["Musixmatch","Lrclib","NetEase","Megalobiz","Genius"] Ordered list of providers for syncedlyrics.
Fallback boolean true Fallback to plain lyrics if synced not found.
Format_priority array ["a2","lrc","txt"] Preferred format order when multiple candidates exist.
read_embedded_lyrics boolean true Extract lyrics from audio file metadata (FLAC, OGG, MP3, MP4).
skip_embedded_txt boolean true Ignore embedded plain-text lyrics (keep only synced embedded).
Translation.enable_translation boolean false Request translated lyrics (if provider supports).
Translation.language string "en" Target language code (e.g. "en", "es").

UI Settings

Controls appearance and terminal behaviour.

"ui": {
  "alignment": "left",
  "name": true,
  "colors": {
    "txt": {
      "active": {"env": "TXT_ACTIVE", "default": "254"},
      "inactive": {"env": "TXT_INACTIVE", "default": "white"}
    },
    "lrc": {
      "active": {"env": "LRC_ACTIVE", "default": "046"},
      "inactive": {"env": "LRC_INACTIVE", "default": "250"}
    },
    "error": {"env": "ERROR_COLOR", "default": 196}
  },
  "scroll_timeout": 4,
  "sync": { }
}
Field Type Default Description
alignment string "left" Default lyric alignment. One of "left", "center", "right".
name boolean true Show/hide track name and artist in status bar.
scroll_timeout integer 4 Seconds after manual scroll before auto-scroll resumes.
colors object see config Color definitions. Colors may be numbers (0–255) or names (black, red, green, yellow, blue, magenta, cyan, white). Each can be overridden via environment variable.
sync object see below Advanced lyric synchronisation tuning.

Sync Options

"sync": {
  "refresh_interval_ms": 1000,
  "coolcpu_ms": 100,
  "smart-tracking": 0,
  "bisect_offset": 0,
  "proximity_threshold": 0,
  "wrap_width_percent": 90,
  "smart_refresh_duration": 2,
  "smart_coolcpu_ms": 20,
  "jump_threshold_sec": 1,
  "end_trigger_threshold_sec": 1,
  "proximity": {
    "smart-proximity": true,
    "refresh_proximity_interval_ms": 0,
    "smart_coolcpu_ms_v2": 50,
    "proximity_threshold_sec": 0.1,
    "proximity_threshold_percent": 200,
    "proximity_min_threshold_sec": 0.0,
    "proximity_max_threshold_sec": 1
  },
  "position_phase_lock": {
    "enabled": true,
    "max_window_ms": 80.0,
    "min_window_ms": 1.0,
    "auto_window": "warmup",
    "auto_window_factor": 1.5,
    "auto_window_samples": 10,
    "weighted_average": true,
    "weighted_average_decay": 0.98,
    "weighted_average_floor_var_ms2": 0.25,
    "seek_hard_reanchor": true
  },
  "subprocess_compensated_anchor": true,
  "fresh_position_clock": true,
  "sync_offset_sec": 0.005,
  "VRR_R_bol": false,
  "VRR_bol": false
}

Base Sync

Field Type Default Description
refresh_interval_ms integer 1000 Base update interval (ms).
coolcpu_ms integer 100 CPU-saving idle interval (ms) when nothing changes.
smart-tracking integer 0 Enable predictive tracking. 0 = off, 1 = on.
bisect_offset float 0 Seconds offset applied before timestamp bisection.
proximity_threshold float 0 Legacy proximity threshold.
wrap_width_percent integer 90 Percentage of terminal width used for text wrapping.
smart_refresh_duration float 2 Seconds after a jump to use faster refresh. 2 s guarantees the smart-window burst brackets at least one 1 Hz tick, which the phase lock requires.
smart_coolcpu_ms integer 20 Fast refresh interval during smart refresh.
jump_threshold_sec float 1 Maximum allowed drift before triggering jump refresh.
end_trigger_threshold_sec float 1 Seconds before track end to trigger final update.
sync_offset_sec float 0.005 Global fine-tune offset applied to all timestamps.
VRR_R_bol boolean false Experimental: variable refresh rate sync.
VRR_bol boolean false Experimental: VRR mode.

Proximity

Field Type Default Description
smart-proximity boolean true Enable proximity-based accelerated polling near line changes.
refresh_proximity_interval_ms integer 0 Polling interval (ms) when near line change. 0 = poll as fast as the loop allows.
smart_coolcpu_ms_v2 integer 50 Alternate fast interval.
proximity_threshold_sec float 0.1 Absolute time threshold for proximity activation.
proximity_threshold_percent float 200 Relative threshold (% of line duration) for proximity.
proximity_min_threshold_sec float 0.0 Minimum time before next line to activate proximity.
proximity_max_threshold_sec float 1 Maximum time before next line to activate proximity.

Position Phase Lock

The phase lock predicts the wall-clock time of cmus's 1 Hz integer position ticks and anchors lyric extrapolation to the predicted tick time instead of the poll arrival time. This removes the up-to-1-second error caused by polling at a random phase within each second.

"position_phase_lock": {
  "enabled": true,
  "max_window_ms": 80.0,
  "min_window_ms": 1.0,
  "auto_window": "warmup",
  "auto_window_factor": 1.5,
  "auto_window_samples": 10,
  "weighted_average": true,
  "weighted_average_decay": 0.98,
  "weighted_average_floor_var_ms2": 0.25,
  "seek_hard_reanchor": true
}
Field Type Default Description
enabled boolean true Master switch for the phase lock.
max_window_ms float 80.0 Largest poll-to-poll interval (ms) that can produce a lock candidate. Values above the real inter-poll window prevent the lock from firing; values too large admit noisy candidates.
min_window_ms float 1.0 Smallest interval (ms) accepted as a candidate. Guards against ties caused by two polls landing in the same scheduler quantum.
auto_window string "warmup" Learn the machine's floor poll window from the smart-window burst: "off" (use max_window_ms verbatim), "warmup" (sample N observations once, freeze), "rolling" (recompute on every sample, adapt to load).
auto_window_factor float 1.5 Multiplier applied to the 20th percentile of the sampled windows to derive the effective max_window. 1.5 gives ~50% headroom above the machine's floor.
auto_window_samples integer 10 Ring-buffer size for the auto-window sampler. Larger values give more stable estimates but slower adaptation.
weighted_average boolean true Estimator selection. false = tightest-window ratchet (deterministic, monotonic, optimal for bounded noise). true = inverse-variance averaging over all observations with exponential forgetting (robust to outliers, optimal for Gaussian noise, ~20% tighter in steady state).
weighted_average_decay float 0.98 Per-observation decay of the running sums when weighted_average is enabled. 0.98 → ~50-observation effective memory. Lower = faster adaptation, higher = smoother. Valid range: (0, 0.9999).
weighted_average_floor_var_ms2 float 0.25 Minimum variance (in ms²) attributed to any single observation. Prevents a spuriously short window from contributing unbounded weight to the sum. 0.25 → $\sigma_{\min} = 0.5\text{ ms}$.
seek_hard_reanchor boolean true Seek handling. When true, a detected seek (drift > jump_threshold_sec while playing) becomes a hard position re-anchor: the poll timestamp of the seek observation is used verbatim as the extrapolation anchor, and the seek sample is excluded from phase-lock learning. When false, falls back to legacy behaviour where the seek sample still feeds observe() before the lock is reset.

Anchor Compensation

Two toggles that configure between default un-compensated polling and fully compensated position tracking:

"subprocess_compensated_anchor": true,
"fresh_position_clock": true
Field Type Default Description
subprocess_compensated_anchor boolean false When true, poll_time is captured after await get_player_info() returns rather than at loop start. Removes the subprocess round-trip bias (~rtt/2) from the anchor.
fresh_position_clock boolean false When true, the wall clock is re-read right before extrapolation and the standard re-anchor step is suppressed. Required for the phase lock to take effect — with this false, the loop re-anchors last_pos_time to current_time on every integer position change, overwriting the lock's anchor.

Effective Combinations

subprocess_compensated_anchor fresh_position_clock position_phase_lock.enabled Result
false false false Pure legacy — ±500 ms error, phase-dependent.
true false true fresh off, so the phase lock is silently bypassed. Same as legacy behaviour.
false true true Anchor uses current_time; lock fires but the anchor is not subprocess-compensated (~±50 ms).
true true true Fully compensated — ~±5 ms error. Recommended.

Key Bindings

All key bindings are fully customisable.

Supported key formats:

  • Single characters ("q")
  • KEY_ constants ("KEY_UP")
  • Arrays for multiple bindings
  • null to disable a binding
"key_bindings": {
  "quit": ["q", "Q"],
  "refresh": "R",
  "scroll_up": "KEY_UP",
  "scroll_down": "KEY_DOWN",
  "time_decrease": ["-", "_"],
  "time_increase": ["=", "+"],
  "time_jump_increase": ["]"],
  "time_jump_decrease": ["["],
  "time_reset": "0",
  "align_cycle_forward": "a",
  "align_cycle_backward": "A",
  "align_left": "1",
  "align_center": "2",
  "align_right": "3"
}
Action Default Description
quit q, Q Exit the program.
refresh R Force redraw.
scroll_up KEY_UP Scroll lyrics up (manual mode).
scroll_down KEY_DOWN Scroll lyrics down.
time_decrease -, _ Decrease sync offset by 0.1 s.
time_increase =, + Increase sync offset by 0.1 s.
time_jump_increase ] Increase sync offset by 5 s.
time_jump_decrease [ Decrease sync offset by 5 s.
time_reset 0 Reset sync offset to 0.
align_cycle_forward a Cycle alignment forward (left → center → right).
align_cycle_backward A Cycle alignment backward.
align_left 1 Set alignment to left.
align_center 2 Set alignment to center.
align_right 3 Set alignment to right.

Environment Variable Overrides

Several settings can be overridden at runtime using environment variables. These are configured as:

{"env": "VARNAME", "default": value}

Common Overrides

  • DEBUG=1 — enable debug logging
  • MPD_HOST, MPD_PORT, MPD_PASSWORD — MPD connection parameters
  • TXT_ACTIVE, TXT_INACTIVE, LRC_ACTIVE, LRC_INACTIVE, ERROR_COLOR — colour overrides

Default Configuration

{
  "global": {
    "logs_dir": "~/.cache/lyrus",
    "log_file": "application.log",
    "log_level": "FATAL",
    "lyrics_timeout_log": "lyrics_timeouts.log",
    "lyrics_instrument_log": "instrument.log",
    "debug_log": "debug.log",
    "log_retention_days": 10,
    "max_debug_count": 100,
    "max_log_count": 100,
    "enable_debug": {"env": "DEBUG", "default": "0"}
  },
  "player": {
    "enable_cmus": true,
    "enable_mpd": true,
    "enable_playerctl": true,
    "mpd": {
      "host": {"env": "MPD_HOST", "default": "localhost"},
      "port": {"env": "MPD_PORT", "default": 6600},
      "password": {"env": "MPD_PASSWORD", "default": null},
      "timeout": 10
    }
  },
  "status_messages": {
    "start": "Starting lyric search...",
    "local": "Checking local files",
    "synced": "Searching online sources",
    "lrc_lib": "Checking LRCLIB database",
    "instrumental": "Instrumental track detected",
    "time_out": "In time-out log",
    "failed": "No lyrics found",
    "no_player": "scanning for activity",
    "mpd": "",
    "cmus": "loading cmus",
    "done": "Loaded",
    "clear": ""
  },
  "terminal_states": ["done", "instrumental", "time_out", "failed", "mpd", "clear", "cmus", "no_player"],
  "lyrics": {
    "search_timeout": 15,
    "cache_dir": "~/.local/state/lyrus/synced_lyrics",
    "local_extensions": ["a2", "lrc", "txt"],
    "validation": {"title_match_length": 15, "artist_match_length": 15},
    "Syncedlyrics": true,
    "Sources": ["Musixmatch", "Lrclib", "NetEase", "Megalobiz", "Genius"],
    "Fallback": true,
    "Format_priority": ["a2", "lrc", "txt"],
    "read_embedded_lyrics": true,
    "skip_embedded_txt": true,
    "Translation": {
      "enable_translation": false,
      "language": "en"
    }
  },
  "ui": {
    "alignment": "left",
    "name": true,
    "colors": {
      "txt": {
        "active": {"env": "TXT_ACTIVE", "default": "254"},
        "inactive": {"env": "TXT_INACTIVE", "default": "white"}
      },
      "lrc": {
        "active": {"env": "LRC_ACTIVE", "default": "046"},
        "inactive": {"env": "LRC_INACTIVE", "default": "250"}
      },
      "error": {"env": "ERROR_COLOR", "default": 196}
    },
    "scroll_timeout": 4,
    "sync": {
      "refresh_interval_ms": 1000,
      "coolcpu_ms": 100,
      "smart-tracking": 0,
      "bisect_offset": 0,
      "proximity_threshold": 0,
      "wrap_width_percent": 90,
      "smart_refresh_duration": 2,
      "smart_coolcpu_ms": 20,
      "jump_threshold_sec": 1,
      "end_trigger_threshold_sec": 1,
      "proximity": {
        "smart-proximity": true,
        "refresh_proximity_interval_ms": 0,
        "smart_coolcpu_ms_v2": 50,
        "proximity_threshold_sec": 0.1,
        "proximity_threshold_percent": 200,
        "proximity_min_threshold_sec": 0.0,
        "proximity_max_threshold_sec": 1
      },
      "position_phase_lock": {
        "enabled": true,
        "max_window_ms": 80.0,
        "min_window_ms": 1.0,
        "auto_window": "warmup",
        "auto_window_factor": 1.5,
        "auto_window_samples": 10,
        "weighted_average": true,
        "weighted_average_decay": 0.98,
        "weighted_average_floor_var_ms2": 0.25,
        "seek_hard_reanchor": true
      },
      "subprocess_compensated_anchor": true,
      "fresh_position_clock": true,
      "sync_offset_sec": 0.005,
      "VRR_R_bol": false,
      "VRR_bol": false
    }
  },
  "key_bindings": {
    "quit": ["q", "Q"],
    "refresh": "R",
    "scroll_up": "KEY_UP",
    "scroll_down": "KEY_DOWN",
    "time_decrease": ["-", "_"],
    "time_increase": ["=", "+"],
    "time_jump_increase": ["]"],
    "time_jump_decrease": ["["],
    "time_reset": "0",
    "align_cycle_forward": "a",
    "align_cycle_backward": "A",
    "align_left": "1",
    "align_center": "2",
    "align_right": "3"
  }
}

Addendum: Recommended Configurations

Default (Balanced)

The standard configuration defined above. Works cleanly across varied environments with full phase-lock compensation and auto-tuned thresholds.

Higher-Resolution Sync (Lower Latency)

Designed for systems with low subprocess invocation overhead (e.g. fast cmus-remote) and predictable audio buffering. Cuts the base poll interval in half and sharpens proximity polling:

"sync": {
  "refresh_interval_ms": 500,
  "coolcpu_ms": 100,
  "smart-tracking": 0,
  "bisect_offset": 0,
  "proximity_threshold": 0,
  "wrap_width_percent": 90,
  "smart_refresh_duration": 2,
  "smart_coolcpu_ms": 25,
  "jump_threshold_sec": 1,
  "end_trigger_threshold_sec": 1,
  "proximity": {
    "smart-proximity": true,
    "refresh_proximity_interval_ms": 0,
    "smart_coolcpu_ms_v2": 10,
    "proximity_threshold_sec": 0.1,
    "proximity_threshold_percent": 200,
    "proximity_min_threshold_sec": 0.0,
    "proximity_max_threshold_sec": 1.5
  },
  "position_phase_lock": {
    "enabled": true,
    "max_window_ms": 80.0,
    "min_window_ms": 1.0,
    "auto_window": "warmup",
    "auto_window_factor": 1.5,
    "auto_window_samples": 10,
    "weighted_average": true,
    "weighted_average_decay": 0.98,
    "weighted_average_floor_var_ms2": 0.25,
    "seek_hard_reanchor": true
  },
  "subprocess_compensated_anchor": true,
  "fresh_position_clock": true,
  "sync_offset_sec": 0.001,
  "VRR_R_bol": false,
  "VRR_bol": false
}

Slow Machine / High-Latency Subprocess

If cmus-remote -Q takes >100 ms (test with time cmus-remote -Q), switch auto_window to "rolling" so thresholds adapt dynamically to system load, and expand auto_window_factor to 2.0:

"position_phase_lock": {
  "enabled": true,
  "max_window_ms": 80.0,
  "min_window_ms": 1.0,
  "auto_window": "rolling",
  "auto_window_factor": 2.0,
  "auto_window_samples": 20,
  "weighted_average": true,
  "weighted_average_decay": 0.95,
  "weighted_average_floor_var_ms2": 0.25
}

Disabling the Phase Lock Entirely

To restore uncompensated legacy polling:

"sync": {
  "position_phase_lock": { "enabled": false },
  "subprocess_compensated_anchor": false,
  "fresh_position_clock": false
}

Addendum: Debugging the Phase Lock

Enable debug logging (DEBUG=1 or "enable_debug": {"default": "1"}), run a track, then filter the debug log:

grep -E "Phase lock|Auto window" ~/.cache/lyrus/debug.log | tail -20

Expected log output:

  • An Auto window [warmup]: p20=...ms factor=... max=80.0ms→...ms entry once per session (in warmup mode) or periodically (in rolling mode).
  • Phase lock [weighted]: window=...ms phase=... σ_est=...ms w_sum=... n=... max=...ms output per position tick once the lock is active.
  • σ_est settling down from ~10 ms to ~1.8 ms over the first ~50 samples and remaining stable.

Troubleshooting: No Phase Lock Output

  1. Verify fresh_position_clock is set to true. When set to false, the event loop overwrites the phase-lock anchor at each integer tick.
  2. Confirm smart_refresh_duration is set to at least 1 (preferably 2). A 2-second burst ensures the window brackets at least one full 1 Hz tick.
  3. Verify that max_window_ms is larger than your system's actual poll interval. If cmus-remote -Q takes 100 ms while max_window_ms is 80 ms, no window candidate qualifies. Set auto_window to "warmup" or "rolling" to allow auto-calibration.