Skip to content

Home

Jump to bottom
Saul Gman edited this page Jan 24, 2026 · 30 revisions

Welcome to the lyrus wiki!

Lyrus Configuration Wiki

File Location

Default config is loaded from:

~/.config/lyrus/config.json

You can maintain a config.jsonc (with comments) for editing, and run a preprocessing script to generate the valid config.json.

Global Settings

"global": {
  "logs_dir": "~/.cache/lyrus",
  "log_file": "application.log",
  "log_level": "FATAL",
  "lyrics_timeout_log": "lyrics_timeouts.log",
  "debug_log": "debug.log",
  "log_retention_days": 10,
  "max_debug_count": 100,
  "max_log_count": 100,
  "enable_debug": {"env": "DEBUG", "default": "0"}
}
  • logs_dir: Directory where logs are stored (./logs also supported).
  • log_file: Main log file name.
  • log_level: Minimum log level. Options: DEBUG, INFO, WARNING, ERROR, FATAL.
  • lyrics_timeout_log: File for logging tracks that hit timeout.
  • debug_log: Debug-only log file.
  • log_retention_days: Days before timeout log resets.
  • max_debug_count: Max number of debug entries before truncation.
  • enable_debug: Controlled by environment var DEBUG. "1" enables debug mode.

Player Settings

"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
  }
}
  • enable_cmus: If true, cmus player takes priority over MPD.
  • enable_mpd: If true, MPD player takes priority over playerctl.
  • enable_playerctl: If true, playerctl player takes priority after mpd Its in order
  • mpd.host: MPD server hostname (string). Can be overridden by the MPD_HOST environment variable.
  • mpd.port: MPD server port (integer). Can be overridden by the MPD_PORT environment variable.
  • mpd.password: MPD password (null if not required). Can be overridden by the MPD_PASSWORD environment variable.
  • mpd.timeout: Timeout in seconds for MPD connections (integer).

Status Messages

"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": ""
}
  • Strings displayed for different states of lyric search.

Lyrics Settings

"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"]
}
  • search_timeout: Timeout for lyric searches in seconds.
  • cache_dir: Directory where synced lyrics are cached.
  • local_extensions: Supported local file extensions (a2 broken).
  • validation: Minimum match length for title/artist.
  • Syncedlyrics: Boolean to Syncedlyrics sources
  • Sources: LIst of the sources
  • FallbackL LRCLIB as fallback (legacy)
  • Format_priority: Can be adjusted to delete or added not to save in order

UI Settings

"ui": {
  "alignment": "left",
  "name": true,
  "colors": { ... },
  "scroll_timeout": 4,
  "sync": { ... }
}
  • alignment: "left", "center", or "right".
  • name: Show/hide song name.
  • colors: Define text/LRC/error colors (either numbers 0-256 or names).
  • scroll_timeout: Auto-scroll delay in seconds.
  • sync: Advanced lyric sync controls.

Sync Options

  • refresh_interval_ms: Update interval for syncing (default: 1000ms).
  • coolcpu_ms: CPU usage limiter; lower = higher CPU load.
  • smart-tracking: Enable predictive lyric tracking.
  • bisect_offset: Seconds offset applied before timestamp bisect.
  • proximity_threshold: Fractional threshold for line switching.
  • jump_threshold_sec: Max desync before a jump occurs.
  • sync_offset_sec: Manual sync offset adjustment.
  • VRR_bol / VRR_R_bol: Experimental frame-sync options.
  • proximity: Fine-tuning for proximity-based sync.

Key Bindings

"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"
}
  • Standard hotkeys for controlling lyric display and sync.
  • Any key can be reassigned.
  • Set to null to disable a binding.

Default configurations:

{
  "global": {
    "logs_dir": "~/.cache/lyrus",
    "log_file": "application.log",
    "log_level": "FATAL",
    "lyrics_timeout_log": "lyrics_timeouts.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"],
  "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"]
  },
  "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": "green"},
        "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": 1,
      "smart_coolcpu_ms": 20,
      "jump_threshold_sec": 1,
      "end_trigger_threshold_sec": 1,
      "proximity": {
        "smart-proximity": true,
        "refresh_proximity_interval_ms": 100,
        "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
      },
      "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"
  }
}

higher interval sync setting you might want, the default setting is actually not bad

    "sync": {
      "refresh_interval_ms": 500,
      "coolcpu_ms": 200,
      "smart-tracking": 0,
      "bisect_offset": 0,
      "proximity_threshold": 0,
      "wrap_width_percent": 90,
      "smart_refresh_duration": 1,
      "smart_coolcpu_ms": 25,
      "jump_threshold_sec": 1,
      "end_trigger_threshold_sec": 1,
      "proximity": {
        "smart-proximity": true,
        "refresh_proximity_interval_ms": 10,
        "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
      },
      "sync_offset_sec": 0.001,
      "VRR_R_bol": false,
      "VRR_bol": false
    }

Clone this wiki locally