# paturrr/spolyrics architecture

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

- Interactive diagram: https://gitdiagram.com/paturrr/spolyrics
- Repository: https://github.com/paturrr/spolyrics

## Overview

SpoLyrics is a Windows desktop lyrics miniplayer. Its central workflow reads the active media session’s track and timing data, looks up synchronized lyrics, matches candidates by duration and title, and displays them in a transparent overlay. Tray controls, mouse gestures, persistent settings, Windows startup, and update checking are supporting capabilities. Most runtime behavior resides in one module; the excerpts do not show all internal call sites, so uncertain wiring is omitted.

Main entry points: [`spolyrics/__main__.py`](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py) (App Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Playback and Lyrics"]
  node_app["App Runtime<br/>[__main__.py]"]
  node_session["Session Sync<br/>[__main__.py]"]
  node_lookup["Lyrics Lookup<br/>[__main__.py]"]
  node_matcher["Duration Matcher<br/>[__main__.py]"]
end

subgraph group_ui["Window and Controls"]
  node_overlay["Lyrics Overlay<br/>[__main__.py]"]
  node_gestures["Mouse Gestures<br/>[__main__.py]"]
  node_tray["System Tray<br/>[__main__.py]"]
  node_settings["Settings UI<br/>[__main__.py]"]
end

subgraph group_support["Configuration and Updates"]
  node_config[("Saved Config<br/>[__main__.py]")]
  node_startup["Windows Startup<br/>[__main__.py]"]
  node_updates["Update Checker<br/>[__main__.py]"]
end

node_user(("Listener"))
node_media["Media Player"]
node_smtc["Windows SMTC"]
node_lrclib["LRCLIB"]
node_pypi["PyPI"]

node_user -->|"launches"| node_app
node_media -->|"publishes session"| node_smtc
node_smtc -->|"provides timing"| node_session
node_session -->|"updates playback"| node_app
node_app -->|"requests lyrics"| node_lookup
node_lookup -->|"searches tracks"| node_lrclib
node_lookup -->|"checks candidates"| node_matcher
node_matcher -->|"supplies lyrics"| node_overlay
node_app -->|"starts window"| node_overlay
node_user -->|"uses gestures"| node_gestures
node_gestures -->|"controls window"| node_overlay
node_user -->|"opens menu"| node_tray
node_tray -->|"opens settings"| node_settings
node_settings -->|"saves options"| node_config
node_app -->|"loads options"| node_config
node_app -->|"sets startup shortcut"| node_startup
node_app -->|"checks version"| node_updates
node_updates -->|"queries release"| node_pypi
node_updates -->|"offers update"| node_app

click node_app "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_session "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_lookup "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_matcher "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_overlay "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_gestures "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_tray "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_settings "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_config "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_startup "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"
click node_updates "https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py"

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_app,node_session,node_lookup,node_matcher toneBlue
class node_overlay,node_gestures,node_tray,node_settings toneAmber
class node_config,node_startup,node_updates toneMint
class node_user,node_media,node_smtc,node_lrclib,node_pypi toneIndigo
```

## Components

### Playback and Lyrics

- [App Runtime](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Session Sync](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Lyrics Lookup](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Duration Matcher](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`

### Window and Controls

- [Lyrics Overlay](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Mouse Gestures](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [System Tray](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Settings UI](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`

### Configuration and Updates

- [Saved Config](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Windows Startup](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`
- [Update Checker](https://github.com/paturrr/spolyrics/blob/main/spolyrics/__main__.py): `spolyrics/__main__.py`

### Other components

- **Listener**
- **Media Player**
- **Windows SMTC**
- **LRCLIB**
- **PyPI**

## Connections

- Listener → App Runtime: launches
- Media Player → Windows SMTC: publishes session
- Windows SMTC → Session Sync: provides timing
- Session Sync → App Runtime: updates playback
- App Runtime → Lyrics Lookup: requests lyrics
- Lyrics Lookup → LRCLIB: searches tracks
- Lyrics Lookup → Duration Matcher: checks candidates
- Duration Matcher → Lyrics Overlay: supplies lyrics
- App Runtime → Lyrics Overlay: starts window
- Listener → Mouse Gestures: uses gestures
- Mouse Gestures → Lyrics Overlay: controls window
- Listener → System Tray: opens menu
- System Tray → Settings UI: opens settings
- Settings UI → Saved Config: saves options
- App Runtime → Saved Config: loads options
- App Runtime → Windows Startup: sets startup shortcut
- App Runtime → Update Checker: checks version
- Update Checker → PyPI: queries release
- Update Checker → App Runtime: offers update