How jayfunc/betterlyrics works
1. Repository shape
- This is a multi-project .NET solution centered on a lyrics visualizer/music player.
- The main production app is BetterLyrics.WinUI3 for Windows.
- A second UI stack, BetterLyrics.Avalonia, provides a cross-platform client with Desktop, Browser, Android, and iOS hosts.
- BetterLyrics.Core holds the shared domain, logic, and persistence models.
- BetterLyrics.Sdk is the public plugin contract layer.
2. Shared core boundary
- BetterLyrics.Core is the architecture’s stable foundation: enums, models, helpers, interfaces, and database entities.
- It defines the app’s concepts such as lyrics formats, window modes, settings structures, playback/statistics models, and service abstractions.
- The UI projects and service implementations depend on Core, not the other way around.
3. Main Windows app shell
- BetterLyrics.WinUI3 is the feature-rich desktop client built with WinUI 3 and Win2D.
- It contains the app bootstrap, pages/windows, view models, converters, themes, and visual controls.
- The UI is organized as many specialized surfaces: Now Playing, Music Gallery, Lyrics Search, Settings, Stats Dashboard, Lyrics Share, System Tray, and Toast Overlay.
- This project is the one that exposes the full Windows-native experience described in the README.
4. Rendering pipeline
- The WinUI3 project has a dedicated rendering subsystem under Renderer, Shaders, and Helper/Lyrics.
- Renderers compose the visual output for lyrics, backgrounds, spectrum visualization, and special effects such as fog, snow, raindrops, and fluid backgrounds.
- Lyrics rendering is split by layout direction, with separate horizontal and vertical strategies and line renderers.
- The data flow here is: lyric data and playback state in → render model/layout calculation → composition/Win2D drawing out.
5. Lyrics processing pipeline
- BetterLyrics.Core.Helpers.Lyrics handles parsing, conversion, metadata extraction, and layout support for lyrics files.
- Supported formats include LRC, enhanced/extended variants, QRC/KRC, and TTML.
- Lyrics are normalized, filtered, and transformed before they reach the renderer.
- This is one of the main business pipelines: lyric source input → parse/convert → cache/search → render.
6. Playback and media integration
- The app is not just a visualizer; it integrates with external players and system playback state.
- WinUI3 services include SMTC/GSMTC, playback memory/history, song search mapping, and album-art updates.
- Hook classes such as GlobalHotKeyHook, AudioMixerHook, SystemThemeHook, TaskbarHook, and WindowHook show strong OS-level integration.
- These hooks and services turn system/player events into app state changes that drive the UI and rendering.
7. Storage and persistence
- Persistent data is split into several SQLite-style DbContexts in Core: FilesIndexDbContext, LyricsCacheDbContext, PlayHistoryDbContext, and SongSearchMapDbContext.
- The app keeps separate concerns for indexed media files, cached lyrics, playback history, and mapped search queries.
- SettingsService and SettingsIO manage app configuration, while resource/profile files define saved window layouts and statuses.
- This creates a clear boundary between transient runtime state and persisted app knowledge.
8. Media/file-system abstraction
- File access is abstracted behind IFileSystemService and IUnifiedFileSystem.
- Implementations support local storage as well as remote sources such as SMB, WebDAV, and FTP.
- A file-watch service keeps the library synchronized with filesystem changes.
- This subsystem feeds the library/indexing and playback layers rather than being owned by the UI.
9. Search, translation, and enrichment services
- Lyrics acquisition is handled by search services and provider abstractions.
- The repo references external lyrics and metadata ecosystems such as Apple Music, LRCLIB, and offline translation via LibreTranslate.
- Additional services cover transliteration, translation, and lyrics cache lookup.
- In architecture terms, these are enrichment adapters that sit between the media/song identity layer and the final rendered lyrics.
10. Plugin architecture
- BetterLyrics.Sdk defines the plugin-facing contracts for lyrics sources, translators, transliterators, AI services, configurators, and localization.
- Core’s plugin service loads plugins with isolated contexts/loaders and metadata helpers.
- This means third-party extensions can inject new lyrics sources or text-processing behaviors without changing the core app.
- The plugin boundary is explicit: SDK interfaces on one side, host-owned loading/runtime services on the other.
11. UI architecture on Windows
- The WinUI3 app uses a classic MVVM split: Views, ViewModels, Controls, Converters, and Services.
- The UI is heavily componentized for settings and feature modules, such as lyrics styling, window behavior, playback settings, plugins, and stats.
- Specialized windows like lyrics search/share and the window switcher indicate that the app supports multiple operational modes, not just a single main window.
- System tray and toast overlay components show that the app also behaves like a background utility.
12. Cross-platform Avalonia client
- BetterLyrics.Avalonia mirrors the app concept in a separate UI stack using Avalonia.
- It has shared app code plus platform hosts for Desktop, Browser, Android, and iOS.
- This project appears narrower than WinUI3, but architecturally it follows the same pattern: shared services/viewmodels plus platform entry points.
- For a diagram, it should be treated as a parallel client family backed by the shared Core layer.
13. External integrations and distribution
- Runtime integrations include Discord Rich Presence, Last.fm scrobbling, and Microsoft shell features like SMTC.
- The repository also contains GitHub Actions for store-app builds, issue translation, and release notifications to Discord/Telegram.
- These are not core business logic, but they matter because they connect the app to external services and the release pipeline.
14. What to show in an architecture diagram
- Put BetterLyrics.Core and BetterLyrics.Sdk in the center as shared foundations.
- Show BetterLyrics.WinUI3 as the main host with arrows to file/media sources, lyric search providers, cache/history databases, OS hooks, and external services.
- Show the rendering subsystem as a separate internal pipeline fed by playback state and lyrics data.
- Show BetterLyrics.Avalonia as a second host sharing Core/SDK but with its own platform-specific shells.
Main entry points: BetterLyrics.WinUI3 WinUI3 app · BetterLyrics.Core BetterLyrics.Core · Services App services · Renderer Rendering pipeline
Components 18
Shared foundation
Core domain models, helpers, persistence, and plugin contracts used across clients.
- BetterLyrics.Core · Stable shared foundation for domain concepts, lyrics processing, storage models, and service abstractions.
src/BetterLyrics.Core - BetterLyrics.Sdk · Public plugin contract layer for lyrics sources, translators, configurators, localizers, and AI services.
src/BetterLyrics.Sdk - Lyrics pipeline · Shared lyrics parsing, conversion, metadata extraction, and layout helpers for LRC, QRC/KRC, and TTML.
src/BetterLyrics.Core/Helpers/Lyrics - Persistence models · SQLite-style contexts and entities for files index, lyrics cache, play history, and song-search mapping.
src/BetterLyrics.Core/Models/DbContext - Media abstraction · Unified file-system contracts and implementations for local and remote sources such as SMB, WebDAV, and FTP.
src/BetterLyrics.Core/Implementations/Services/FileSystemService - Plugin runtime · Plugin loading, isolated contexts, configuration, and localization support on the host side.
src/BetterLyrics.Core/Implementations/Services/PluginService
Windows client
Main WinUI 3 application with UI, services, hooks, and rendering pipeline.
- WinUI3 app · Feature-rich Windows shell with bootstrap, navigation, MVVM, and app-wide composition.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3 - UI surfaces · Main Windows screens and controls for now playing, gallery, search, settings, stats, share, tray, and overlays.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Views - Settings modules · Componentized settings and configuration panels for playback, lyrics styling, window behavior, media, and plugins.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Controls - Rendering pipeline · Composition and Win2D rendering pipeline for lyrics, backgrounds, spectrum, and visual effects.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Renderer - Lyrics layout · Horizontal and vertical layout strategies plus line renderers that turn normalized lyric data into visual regions.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Helper/Lyrics - App services · Runtime services for playback, search, cache, history, localization, updates, translation, and plugin hosting.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Services - OS hooks · Windows hooks for hotkeys, audio mix, theme, taskbar, window, IME, monitor, and worker-window behavior.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Hooks - Render models · Windows-specific lyrics render models and window-tracking state used by the shell and renderer.
src/BetterLyrics.WinUI3/BetterLyrics.WinUI3/Models/Lyrics
Avalonia client
Cross-platform client family with shared app code and platform hosts.
- Avalonia app · Shared Avalonia client code with its own shell, services, view models, and views.
src/BetterLyrics.Avalonia/BetterLyrics.Avalonia - Platform hosts · Desktop, browser, Android, and iOS host projects for the Avalonia client family.
src/BetterLyrics.Avalonia - Client services · Avalonia-side update, localization, cache, and settings services built on shared abstractions.
src/BetterLyrics.Avalonia/BetterLyrics.Avalonia/Services
External integrations
Third-party services and OS-level integrations that feed the app experience.
- External services · Lyrics providers, translation services, Discord/Last.fm, and Microsoft shell integrations consumed by the app.
Connections 23
- WinUI3 app → BetterLyrics.Core: depends on · Windows host builds on shared domain, settings, and persistence contracts.
- WinUI3 app → BetterLyrics.Sdk: loads plugins · WinUI3 host exposes the plugin boundary through shared SDK contracts.
- Avalonia app → BetterLyrics.Core: depends on · Avalonia client shares the same foundation models and abstractions.
- Avalonia app → BetterLyrics.Sdk: uses contracts · Avalonia client can participate in the same plugin contract layer.
- BetterLyrics.Core → Lyrics pipeline: contains · Shared helpers implement lyrics parsing, conversion, and layout support.
- BetterLyrics.Core → Persistence models: contains · Shared database contexts and entities model persisted app state.
- BetterLyrics.Core → Media abstraction: contains · Shared file-system abstractions and providers live in the core layer.
- BetterLyrics.Core → Plugin runtime: contains · Core owns plugin loading/runtime infrastructure.
- WinUI3 app → UI surfaces: composes · Main app shell navigates to the production views and windows.
- WinUI3 app → Settings modules: composes · Settings features are split into specialized controls and panels.
- WinUI3 app → Rendering pipeline: drives · Playback and lyric state feed the Windows rendering pipeline.
- WinUI3 app → App services: coordinates · Shell orchestration and app behavior are implemented by services.
- WinUI3 app → OS hooks: integrates · Windows-specific OS hooks are attached at the host boundary.
- Rendering pipeline → Lyrics layout: uses · Renderer delegates lyric layout and line composition to the layout strategies.
- Rendering pipeline → Render models: consumes · Renderers consume renderable lyric models and window state.
- App services → Persistence models: persists to · Caching, history, and file indexing flow into the shared database layer.
- App services → Media abstraction: reads from · Media and file-system services rely on unified local/remote access.
- App services → External services: calls · Lyrics search, translation, Discord, Last.fm, and SMTC integrate through service adapters.
- OS hooks → External services: bridges · OS hooks translate system events into app state and external integration flows.
- Client services → Persistence models: persists to · Avalonia client reuses shared persistence concepts for cache and settings.
- Client services → External services: calls · Cross-platform client services reach out to update and localization backends.
- BetterLyrics.Sdk → Plugin runtime: implemented by · Host-side plugin runtime fulfills the public contracts declared in the SDK.
- Lyrics pipeline → Rendering pipeline: feeds · Normalized lyric data and layout metadata flow into rendering.