How raitonoberu/sptlrx works
Project type and purpose
• It’s a cross-platform, single-binary CLI application written in Go.
• Purpose: fetch and display synchronized lyrics in the terminal or pipe them to stdout, supporting multiple “players” (Spotify, MPD, Mopidy, MPRIS, browser) and local files.
File structure
Top-level directories and files:
• cmd/ – CLI entrypoints (root command, “pipe” subcommand)
• config/ – configuration loader and structs
• services/ – player adapters (spotify, mpd, mopidy, mpris, browser, local, hosted)
• pool/ – lyric caching & synchronization logic
• lyrics/ – parsing .lrc files and calling external lyrics API
• player/ – generic player interface & helpers
• ui/ – terminal rendering logic
• main.go – application bootstrap
• building files – goreleaser, CI workflows, man pages
README for additional insights
• Describes supported players, configuration file, external dependencies (Spotify web, custom lyrics API, local .lrc).
• Mentions “pipe” mode for stdout integration.
Main components
1. CLI Layer
– cmd/root.go, cmd/pipe.go
– Parses flags, reads config, dispatches to either interactive UI or pipe mode
2. Config Manager
– config/config.go
– Loads config.yaml, merges flags and defaults
3. Player Adapters (“services” package)
– Each subpackage implements a common interface (GetTrackInfo, Position, etc.)
– Spotify: uses web cookie + Spotify web API
– MPD/Mopidy: TCP connections to music servers
– MPRIS: D-Bus on Linux
– Browser: HTTP server communicating with browser extension
– Local: scans folder for .lrc files
– Hosted: falls back to external lyrics API
4. Lyrics Fetcher
– lyrics/lyrics.go
– Given track metadata, fetches parsed lyrics (from local .lrc or HTTP)
5. Pool & Synchronizer
– pool/pool.go
– Caches parsed lyrics, manages timing (timerInterval, updateInterval)
– pool_test.go ensures timing logic
6. UI Renderer
– ui/ui.go
7. Pipe Mode
– Directly prints current line(s) to stdout for integration
8. External Systems
– Spotify web API
– Lyrics API server (lyricsapi.vercel.app or self-hosted)
– MPD/Mopidy servers
– D-Bus for MPRIS
– Browser extension HTTP endpoint
– Local file system for .lrc files
Relationships and data flow
• User invokes “sptlrx” or “sptlrx pipe”
• CLI layer reads flags → loads config
• Config determines which service adapter to initialize
• Service adapter polls the player for current track & position
• Lyrics Fetcher retrieves lyrics (via adapter to local/HTTP)
• Pool synchronizes lyrics lines to playback time
• UI Renderer subscribes to pool updates → draws to terminal
• In pipe mode, UI Renderer replaced by Pipe Writer (stdout)
Important architectural patterns
• Adapter/plugin pattern for player support (each service implements the same interface)
• Layered architecture: CLI → config → service → domain (lyrics+pools) → presentation (ui or pipe)
• Dependency injection via constructors in cmd/root.go
• Single binary distribution with Go modules and goreleaser