# luqman234/meowplayer architecture

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

- Interactive diagram: https://gitdiagram.com/luqman234/meowplayer
- Repository: https://github.com/luqman234/meowplayer

## Overview

MeowPlayer is a local-first terminal music player. Its principal workflow is to scan local files, read and cache metadata, present a keyboard-driven library, and send playback commands to mpv; online search and lyrics are optional extensions. The graph preserves the README’s major discovery, desktop-control, and terminal-display capabilities. Some wiring is documented at product level rather than visible in the sampled excerpts, so those relationships cite the README; unsampled internals are not inferred.

Main entry points: [`meowplayer.py`](https://github.com/luqman234/meowplayer/blob/main/meowplayer.py) (Terminal player), [`youtube_online.py`](https://github.com/luqman234/meowplayer/blob/main/youtube_online.py) (Online streams), [`bad_larry.py`](https://github.com/luqman234/meowplayer/blob/main/bad_larry.py) (Bad Larry), [`lyrics_support.py`](https://github.com/luqman234/meowplayer/blob/main/lyrics_support.py) (Lyrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library and discovery"]
  node_scanner["Library scanning<br/>[meowplayer.py]"]
  node_watcher["Filesystem watcher<br/>[library_watcher.py]"]
  node_metadata["Local metadata<br/>[meowplayer.py]"]
  node_catalog[("SQLite catalog<br/>[meow_catalog.py]")]
  node_discovery["Library discovery<br/>[meowplayer.py]"]
  node_smart["Smart mixes<br/>[meow_smart.py]"]
end

subgraph group_playback["Playback and online"]
  node_mpv["mpv engine"]
  node_online["Online streams<br/>[youtube_online.py]"]
  node_provider["YouTube and NicoNico"]
end

subgraph group_interface["User interface"]
  node_tui["Terminal player<br/>[meowplayer.py]"]
  node_settings["Settings<br/>[settings_nest.py]"]
  node_art["Album art<br/>[album_art.py]"]
  node_visualizer["Spectrum display<br/>[visualizer.py]"]
  node_cat["Cat presence<br/>[cat_presence.py]"]
  node_chaos["Bad Larry<br/>[bad_larry.py]"]
  node_math["Chaos questions<br/>[bad_larry_math.py]"]
end

subgraph group_integrations["Desktop and enrichment"]
  node_lyrics["Lyrics<br/>[lyrics_support.py]"]
  node_lrclib["LRCLIB"]
  node_enrichment["Metadata enrichment<br/>[online_metadata.py]"]
  node_musicbrainz["MusicBrainz"]
  node_desktop["MPRIS controls<br/>[mpris_support.py]"]
end

node_user(("Listener"))
node_dbus["D-Bus clients"]

node_user -->|"controls"| node_tui
node_tui -->|"scans files"| node_scanner
node_scanner -->|"reads tags"| node_metadata
node_scanner -->|"caches metadata"| node_catalog
node_watcher -->|"signals changes"| node_tui
node_tui -->|"presents library"| node_discovery
node_discovery -->|"reads history"| node_catalog
node_discovery -->|"offers mixes"| node_smart
node_user -->|"chooses music"| node_tui
node_tui -->|"controls playback"| node_mpv
node_tui -->|"requests streams"| node_online
node_online -->|"searches streams"| node_provider
node_tui -->|"loads lyrics"| node_lyrics
node_lyrics -.->|"looks up lyrics"| node_lrclib
node_tui -->|"enriches missing tags"| node_enrichment
node_enrichment -->|"queries metadata"| node_musicbrainz
node_dbus -->|"sends controls"| node_desktop
node_desktop -->|"dispatches commands"| node_tui
node_tui -->|"configures player"| node_settings
node_tui -->|"shows cover art"| node_art
node_tui -->|"shows spectrum"| node_visualizer
node_tui -->|"updates mascot"| node_cat
node_tui -->|"runs incidents"| node_chaos
node_chaos -->|"uses questions"| node_math

click node_tui "https://github.com/luqman234/meowplayer/blob/main/meowplayer.py"
click node_scanner "https://github.com/luqman234/meowplayer/blob/main/meowplayer.py"
click node_watcher "https://github.com/luqman234/meowplayer/blob/main/library_watcher.py"
click node_metadata "https://github.com/luqman234/meowplayer/blob/main/meowplayer.py"
click node_catalog "https://github.com/luqman234/meowplayer/blob/main/meow_catalog.py"
click node_discovery "https://github.com/luqman234/meowplayer/blob/main/meowplayer.py"
click node_smart "https://github.com/luqman234/meowplayer/blob/main/meow_smart.py"
click node_settings "https://github.com/luqman234/meowplayer/blob/main/settings_nest.py"
click node_online "https://github.com/luqman234/meowplayer/blob/main/youtube_online.py"
click node_lyrics "https://github.com/luqman234/meowplayer/blob/main/lyrics_support.py"
click node_enrichment "https://github.com/luqman234/meowplayer/blob/main/online_metadata.py"
click node_desktop "https://github.com/luqman234/meowplayer/blob/main/mpris_support.py"
click node_art "https://github.com/luqman234/meowplayer/blob/main/album_art.py"
click node_visualizer "https://github.com/luqman234/meowplayer/blob/main/visualizer.py"
click node_cat "https://github.com/luqman234/meowplayer/blob/main/cat_presence.py"
click node_chaos "https://github.com/luqman234/meowplayer/blob/main/bad_larry.py"
click node_math "https://github.com/luqman234/meowplayer/blob/main/bad_larry_math.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_scanner,node_watcher,node_metadata,node_catalog,node_discovery,node_smart,node_dbus toneBlue
class node_mpv,node_online,node_provider toneAmber
class node_tui,node_settings,node_art,node_visualizer,node_cat,node_chaos,node_math toneMint
class node_lyrics,node_lrclib,node_enrichment,node_musicbrainz,node_desktop toneRose
class node_user toneIndigo
```

## Components

### Library and discovery

- [Library scanning](https://github.com/luqman234/meowplayer/blob/main/meowplayer.py): `meowplayer.py`
- [Filesystem watcher](https://github.com/luqman234/meowplayer/blob/main/library_watcher.py): `library_watcher.py`
- [Local metadata](https://github.com/luqman234/meowplayer/blob/main/meowplayer.py): `meowplayer.py`
- [SQLite catalog](https://github.com/luqman234/meowplayer/blob/main/meow_catalog.py): `meow_catalog.py`
- [Library discovery](https://github.com/luqman234/meowplayer/blob/main/meowplayer.py): `meowplayer.py`
- [Smart mixes](https://github.com/luqman234/meowplayer/blob/main/meow_smart.py): `meow_smart.py`

### Playback and online

- **mpv engine**
- [Online streams](https://github.com/luqman234/meowplayer/blob/main/youtube_online.py): `youtube_online.py`
- **YouTube and NicoNico**

### User interface

- [Terminal player](https://github.com/luqman234/meowplayer/blob/main/meowplayer.py): `meowplayer.py`
- [Settings](https://github.com/luqman234/meowplayer/blob/main/settings_nest.py): `settings_nest.py`
- [Album art](https://github.com/luqman234/meowplayer/blob/main/album_art.py): `album_art.py`
- [Spectrum display](https://github.com/luqman234/meowplayer/blob/main/visualizer.py): `visualizer.py`
- [Cat presence](https://github.com/luqman234/meowplayer/blob/main/cat_presence.py): `cat_presence.py`
- [Bad Larry](https://github.com/luqman234/meowplayer/blob/main/bad_larry.py): `bad_larry.py`
- [Chaos questions](https://github.com/luqman234/meowplayer/blob/main/bad_larry_math.py): `bad_larry_math.py`

### Desktop and enrichment

- [Lyrics](https://github.com/luqman234/meowplayer/blob/main/lyrics_support.py): `lyrics_support.py`
- **LRCLIB**
- [Metadata enrichment](https://github.com/luqman234/meowplayer/blob/main/online_metadata.py): `online_metadata.py`
- **MusicBrainz**
- [MPRIS controls](https://github.com/luqman234/meowplayer/blob/main/mpris_support.py): `mpris_support.py`

### Other components

- **Listener**
- **D-Bus clients**

## Connections

- Listener → Terminal player: controls (evidence: `README.md`)
- Terminal player → Library scanning: scans files (evidence: `README.md`)
- Library scanning → Local metadata: reads tags (evidence: `README.md`)
- Library scanning → SQLite catalog: caches metadata (evidence: `README.md`)
- Filesystem watcher → Terminal player: signals changes (evidence: `README.md`)
- Terminal player → Library discovery: presents library (evidence: `README.md`)
- Library discovery → SQLite catalog: reads history (evidence: `README.md`)
- Library discovery → Smart mixes: offers mixes (evidence: `README.md`)
- Listener → Terminal player: chooses music (evidence: `README.md`)
- Terminal player → mpv engine: controls playback (evidence: `README.md`)
- Terminal player → Online streams: requests streams (evidence: `README.md`)
- Online streams → YouTube and NicoNico: searches streams (evidence: `README.md`)
- Terminal player → Lyrics: loads lyrics (evidence: `README.md`)
- Lyrics → LRCLIB: looks up lyrics (evidence: `README.md`)
- Terminal player → Metadata enrichment: enriches missing tags (evidence: `README.md`)
- Metadata enrichment → MusicBrainz: queries metadata (evidence: `README.md`)
- D-Bus clients → MPRIS controls: sends controls (evidence: `README.md`)
- MPRIS controls → Terminal player: dispatches commands (evidence: `README.md`)
- Terminal player → Settings: configures player (evidence: `README.md`)
- Terminal player → Album art: shows cover art (evidence: `README.md`)
- Terminal player → Spectrum display: shows spectrum (evidence: `README.md`)
- Terminal player → Cat presence: updates mascot (evidence: `README.md`)
- Terminal player → Bad Larry: runs incidents (evidence: `README.md`)
- Bad Larry → Chaos questions: uses questions (evidence: `bad_larry.py`)
