# zydr114/easydesktoplyrics architecture

> Architecture diagram of the GitHub repository zydr114/easydesktoplyrics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zydr114/easydesktoplyrics
- Repository: https://github.com/zydr114/easydesktoplyrics

## Overview

EasyDesktopLyrics is a Windows desktop lyrics overlay that follows system media sessions, finds and times lyrics, then renders synchronized lyrics and optional visual effects. The main workflow is documented and the startup wiring is sampled; several internal lyric-processing and rendering links are inferred only at subsystem level, so uncertain call-level relationships are omitted.

Main entry points: [`Services/LyricsOrchestrator.cs`](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsOrchestrator.cs) (Lyrics orchestration), [`Services/Providers/ILyricsProvider.cs`](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/ILyricsProvider.cs) (Lyrics providers), [`Services/SettingsService.cs`](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SettingsService.cs) (Settings service), [`Services/SmtcService.cs`](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SmtcService.cs) (Media sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Playback and lyrics"]
  node_smtc["Media sessions<br/>[SmtcService.cs]"]
  node_orchestrator["Lyrics orchestration"]
  node_matcher["Lyrics matching<br/>[LyricsMatcher.cs]"]
  node_timeline["Lyrics timeline"]
  node_parser["LRC parsing<br/>[LrcParser.cs]"]
  node_providers["Lyrics providers<br/>[ILyricsProvider.cs]"]
  node_local["Local LRC"]
  node_netease["Netease lyrics"]
  node_qq["QQ lyrics"]
  node_lrclib["LRCLIB lyrics"]
  node_lyriccache[("Lyrics cache<br/>[LyricsCache.cs]")]
end

subgraph group_visuals["Overlay and visuals"]
  node_overlayvm["Overlay state"]
  node_overlay["Lyrics window"]
  node_lyricmodes["Lyric modes"]
  node_background["Background effects"]
  node_presets["Visual presets"]
  node_palette["Cover palette"]
end

subgraph group_configuration["Settings and persistence"]
  node_settingsui["Settings interface"]
  node_settings["Settings service<br/>[SettingsService.cs]"]
  node_settingsstore[("Settings file<br/>[AppPaths.cs]")]
end

subgraph group_audio["Audio features"]
  node_features["Audio features"]
  node_spectrum["Spectrum engine<br/>[SpectrumEngine.cs]"]
  node_wasapi["Loopback capture"]
end

node_listener(("Listener"))
node_players(("SMTC players"))
node_lyricapi(("Lyrics services"))
node_audioinput(("Windows audio"))

node_players -->|"publish sessions"| node_smtc
node_smtc -->|"track updates"| node_orchestrator
node_orchestrator -->|"playback state"| node_smtc
node_orchestrator -->|"request lyrics"| node_providers
node_orchestrator -->|"read and write"| node_lyriccache
node_orchestrator -->|"publish lyrics"| node_overlayvm
node_providers -->|"dispatch local"| node_local
node_providers -->|"dispatch source"| node_netease
node_providers -->|"dispatch source"| node_qq
node_providers -->|"dispatch source"| node_lrclib
node_local -.->|"read local files"| node_lyricapi
node_netease -.->|"fetch lyrics"| node_lyricapi
node_qq -.->|"fetch lyrics"| node_lyricapi
node_lrclib -.->|"fetch lyrics"| node_lyricapi
node_overlayvm -->|"update display"| node_overlay
node_overlay -->|"render lyrics"| node_lyricmodes
node_overlay -->|"render effects"| node_background
node_overlay -->|"extract cover colors"| node_palette
node_settingsui -->|"update options"| node_settings
node_settings -->|"load and save"| node_settingsstore
node_settingsui -->|"manage presets"| node_presets
node_settings -->|"configure sources"| node_orchestrator
node_settings -->|"configure players"| node_smtc
node_background -->|"consume features"| node_features
node_features -->|"analyze frames"| node_spectrum
node_spectrum -->|"capture samples"| node_wasapi
node_wasapi -->|"read loopback"| node_audioinput
node_listener -->|"view lyrics"| node_overlay

click node_smtc "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SmtcService.cs"
click node_orchestrator "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsOrchestrator.cs"
click node_matcher "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsMatcher.cs"
click node_timeline "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsTimelineBuilder.cs"
click node_parser "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LrcParser.cs"
click node_providers "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/ILyricsProvider.cs"
click node_local "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/LocalLrcProvider.cs"
click node_netease "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/NeteaseLyricsProvider.cs"
click node_qq "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/QQMusicLyricsProvider.cs"
click node_lrclib "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/LrclibLyricsProvider.cs"
click node_lyriccache "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsCache.cs"
click node_overlayvm "https://github.com/zydr114/easydesktoplyrics/blob/main/ViewModels/OverlayViewModel.cs"
click node_lyricmodes "https://github.com/zydr114/easydesktoplyrics/blob/main/Views/Lyrics/LyricVisualModeRegistry.cs"
click node_background "https://github.com/zydr114/easydesktoplyrics/blob/main/Views/BackgroundFxLayer.cs"
click node_presets "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/VisualPresetService.cs"
click node_settingsui "https://github.com/zydr114/easydesktoplyrics/blob/main/ViewModels/SettingsViewModel.cs"
click node_settings "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SettingsService.cs"
click node_settingsstore "https://github.com/zydr114/easydesktoplyrics/blob/main/Infrastructure/AppPaths.cs"
click node_features "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/AudioFeatureService.cs"
click node_spectrum "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SpectrumEngine.cs"
click node_wasapi "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/WasapiLoopbackCapture.cs"
click node_palette "https://github.com/zydr114/easydesktoplyrics/blob/main/Services/CoverPaletteExtractor.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_smtc,node_orchestrator,node_matcher,node_timeline,node_parser,node_providers,node_local,node_netease,node_qq,node_lrclib,node_lyriccache toneBlue
class node_overlayvm,node_overlay,node_lyricmodes,node_background,node_presets,node_palette toneAmber
class node_settingsui,node_settings,node_settingsstore toneMint
class node_features,node_spectrum,node_wasapi toneRose
class node_listener,node_players,node_lyricapi,node_audioinput toneIndigo
```

## Components

### Playback and lyrics

- [Media sessions](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SmtcService.cs): `Services/SmtcService.cs`
- [Lyrics orchestration](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsOrchestrator.cs): `Services/LyricsOrchestrator.cs`
- [Lyrics matching](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsMatcher.cs): `Services/LyricsMatcher.cs`
- [Lyrics timeline](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsTimelineBuilder.cs): `Services/LyricsTimelineBuilder.cs`
- [LRC parsing](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LrcParser.cs): `Services/LrcParser.cs`
- [Lyrics providers](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/ILyricsProvider.cs): `Services/Providers/ILyricsProvider.cs`
- [Local LRC](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/LocalLrcProvider.cs): `Services/Providers/LocalLrcProvider.cs`
- [Netease lyrics](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/NeteaseLyricsProvider.cs): `Services/Providers/NeteaseLyricsProvider.cs`
- [QQ lyrics](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/QQMusicLyricsProvider.cs): `Services/Providers/QQMusicLyricsProvider.cs`
- [LRCLIB lyrics](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/Providers/LrclibLyricsProvider.cs): `Services/Providers/LrclibLyricsProvider.cs`
- [Lyrics cache](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/LyricsCache.cs): `Services/LyricsCache.cs`

### Overlay and visuals

- [Overlay state](https://github.com/zydr114/easydesktoplyrics/blob/main/ViewModels/OverlayViewModel.cs): `ViewModels/OverlayViewModel.cs`
- **Lyrics window**
- [Lyric modes](https://github.com/zydr114/easydesktoplyrics/blob/main/Views/Lyrics/LyricVisualModeRegistry.cs): `Views/Lyrics/LyricVisualModeRegistry.cs`
- [Background effects](https://github.com/zydr114/easydesktoplyrics/blob/main/Views/BackgroundFxLayer.cs): `Views/BackgroundFxLayer.cs`
- [Visual presets](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/VisualPresetService.cs): `Services/VisualPresetService.cs`
- [Cover palette](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/CoverPaletteExtractor.cs): `Services/CoverPaletteExtractor.cs`

### Settings and persistence

- [Settings interface](https://github.com/zydr114/easydesktoplyrics/blob/main/ViewModels/SettingsViewModel.cs): `ViewModels/SettingsViewModel.cs`
- [Settings service](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SettingsService.cs): `Services/SettingsService.cs`
- [Settings file](https://github.com/zydr114/easydesktoplyrics/blob/main/Infrastructure/AppPaths.cs): `Infrastructure/AppPaths.cs`

### Audio features

- [Audio features](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/AudioFeatureService.cs): `Services/AudioFeatureService.cs`
- [Spectrum engine](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/SpectrumEngine.cs): `Services/SpectrumEngine.cs`
- [Loopback capture](https://github.com/zydr114/easydesktoplyrics/blob/main/Services/WasapiLoopbackCapture.cs): `Services/WasapiLoopbackCapture.cs`

### Other components

- **Listener**
- **SMTC players**
- **Lyrics services**
- **Windows audio**

## Connections

- SMTC players → Media sessions: publish sessions
- Media sessions → Lyrics orchestration: track updates
- Lyrics orchestration → Media sessions: playback state
- Lyrics orchestration → Lyrics providers: request lyrics
- Lyrics orchestration → Lyrics cache: read and write
- Lyrics orchestration → Overlay state: publish lyrics
- Lyrics providers → Local LRC: dispatch local
- Lyrics providers → Netease lyrics: dispatch source
- Lyrics providers → QQ lyrics: dispatch source
- Lyrics providers → LRCLIB lyrics: dispatch source
- Local LRC → Lyrics services: read local files
- Netease lyrics → Lyrics services: fetch lyrics
- QQ lyrics → Lyrics services: fetch lyrics
- LRCLIB lyrics → Lyrics services: fetch lyrics
- Overlay state → Lyrics window: update display
- Lyrics window → Lyric modes: render lyrics
- Lyrics window → Background effects: render effects
- Lyrics window → Cover palette: extract cover colors
- Settings interface → Settings service: update options
- Settings service → Settings file: load and save
- Settings interface → Visual presets: manage presets
- Settings service → Lyrics orchestration: configure sources
- Settings service → Media sessions: configure players
- Background effects → Audio features: consume features
- Audio features → Spectrum engine: analyze frames
- Spectrum engine → Loopback capture: capture samples
- Loopback capture → Windows audio: read loopback
- Listener → Lyrics window: view lyrics