csong

Lyrics viewer for MPD/ncmpcpp with terminal, X11, Wayland, and Windows backends.

• Follow MPD track changes
• Fetch and cache lyrics
• Render lyrics on all X11 workspaces

• libmpdclient
• libcurl
• libfribidi
• libdbus-1 (Spotify desktop on Linux)
• X11: libX11, libXft, libXfixes, libXrender, Xext, fontconfig + freetype
• Wayland: wayland-client, pangocairo, wlroots layer-shell

make

• Visual Studio 2022 dev command prompt
• Windows 10+ SDK with C++/WinRT
• vcpkg deps: curl:x64-windows fribidi:x64-windows

pwsh -File scripts/windows_build_msvc.ps1

./csong

Options:

• --config PATH (default: ~/.config/csong/config.toml or $XDG_CONFIG_HOME/csong/config.toml)
• --mpd-host HOST (default: 127.0.0.1)
• --mpd-port PORT (default: 6600)
• --once (print once and exit)
• --interval N (seconds between updates, default: 1)
• --show-plain (display untimed lyrics)

make
cp config/sample.toml ~/.config/csong/config.toml
./csong

Example config.toml snippet:

[ui]
backend = "x11"
opacity = 0.85
anchor = "bottom-right"
offset_x = 24
offset_y = 24
padding_x = 16
padding_y = 16
click_through = true
pause_hide_seconds = 5.0

make
cp config/sample.toml ~/.config/csong/config.toml
./csong

Example config.toml snippet:

[ui]
backend = "wayland"
opacity = 0.85
anchor = "bottom-right"
offset_x = 24
offset_y = 24
padding_x = 16
padding_y = 16
click_through = true
pause_hide_seconds = 5.0
width_min = 360
width_max = 900

If the compositor does not support wlr-layer-shell, the UI falls back to the terminal backend.

• Stores and reads lyrics in ~/lyrics/
• Prefers Artist - Title.lrc, then Artist - Title.txt
• If artist is missing, tries Title.lrc then Title.txt
• Fetches synced lyrics from lrclib when available; falls back to lyrics.ovh
• Shows an animated music icon during intros and instrumental gaps (based on LRC)
• Supports LRC [offset:+/-ms] tags
• Displays lyrics early to improve readability (configurable)
• Player order: MPD (ncmpcpp) -> Spotify Desktop -> YouTube Music (MPRIS)
• YouTube Music MPRIS bus names tried (Linux):
  • org.mpris.MediaPlayer2.youtube-music
  • org.mpris.MediaPlayer2.youtube_music
  • org.mpris.MediaPlayer2.YoutubeMusic
  • org.mpris.MediaPlayer2.ytmdesktop
  • org.mpris.MediaPlayer2.ytmdesktopapp
• Optional per-track offsets in ~/lyrics/.offsets:

  Dua Lipa - Houdini = -4.0
  Houdini = -4.0
  

• Default path: ~/.config/csong/config.toml (or $XDG_CONFIG_HOME/csong/config.toml)
• Supported keys:
  • interval (seconds between updates)
  • show_plain (boolean)
  • [mpd].host, [mpd].port
  • [lyrics].cache_dir (overrides default ~/lyrics cache)
  • [lyrics].lead_seconds (seconds to show lyrics early)
  • [ui].backend (terminal, x11, wayland, windows)
  • [ui].font (font name/size for GUI backends)
  • [ui].title_font (X11 only)
  • [ui].title_weight, [ui].title_style (X11 only, used when title_font is empty)
  • [ui].opacity (0.0-1.0)
  • [ui].anchor (top-right, bottom-right, etc.)
  • [ui].offset_x, [ui].offset_y (pixels)
  • [ui].padding_x, [ui].padding_y (pixels)
  • [ui].show_icons (boolean)
  • [ui].fg_color, [ui].title_color, [ui].dim_color, [ui].prev_color, [ui].bg_color, [ui].current_color (hex)
  • [ui].line_spacing (float, X11 only)
  • [ui].title_scale (float, X11 only)
  • [ui].width, [ui].height (pixels, 0 = auto)
  • [ui].click_through (boolean)
  • [render].bidi (fribidi, terminal)
  • [render].rtl_mode (auto, on, off)
  • [render].rtl_align (left, right)
  • [render].rtl_shape (auto, on, off)

To use a GUI backend, set [ui].backend to x11, wayland, or windows. The [ui] color and padding options also apply to the terminal renderer.

If Arabic words look reversed, set [render].bidi = "fribidi" (default) so the app locks visual order and avoids double BiDi from terminals.

• include/app/: public headers
• src/: implementation
• config/: sample config
• assets/: fonts
• tests/: test scaffolding
• scripts/: helper scripts