# zeeynrs/senada architecture

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

- Interactive diagram: https://gitdiagram.com/zeeynrs/senada
- Repository: https://github.com/zeeynrs/senada

## Overview

Senada is a Windows/Linux desktop music player. The main workflow is to browse or search YouTube Music, select a track, resolve its audio, and play it through a local mpv engine; users can also import playlists, manage a local library, download tracks, and view synced lyrics. The graph includes the app’s major documented listening, customization, remote-control, and backup capabilities. Some subsystems are represented by their exact tree paths but were not sampled, so their internal connections are omitted.

Main entry points: [`senada/main.py`](https://github.com/zeeynrs/senada/blob/main/senada/main.py) (App startup), [`senada/player.py`](https://github.com/zeeynrs/senada/blob/main/senada/player.py) (Playback controls), [`senada/library.py`](https://github.com/zeeynrs/senada/blob/main/senada/library.py) (Library browsing), [`senada/resolver.py`](https://github.com/zeeynrs/senada/blob/main/senada/resolver.py) (Audio resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and preferences"]
  node_main["App startup<br/>[main.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_session["Window session<br/>[session.py]"]
end

subgraph group_discovery["Browse and library"]
  node_library["Library browsing<br/>[library.py]"]
  node_catalog["Catalog facade<br/>[catalog.py]"]
  node_ytmusic["YouTube Music<br/>[ytmusic.py]"]
  node_discover["Recommendations<br/>[discover.py]"]
  node_spotify["Spotify import<br/>[spotify_import.py]"]
  node_matching["Track matching<br/>[matching.py]"]
  node_store[("Local library store<br/>[store.py]")]
end

subgraph group_playback["Playback and lyrics"]
  node_player["Playback controls<br/>[player.py]"]
  node_resolver["Audio resolver<br/>[resolver.py]"]
  node_streams["Stream lookup<br/>[streams.py]"]
  node_engine["Audio engine<br/>[engine.py]"]
  node_downloads["Offline downloads<br/>[downloads.py]"]
  node_lyrics["Synced lyrics<br/>[lyrics.py]"]
  node_localfiles["Local music files<br/>[localfiles.py]"]
end

subgraph group_personal["Personal listening"]
  node_backup["Backup and restore<br/>[backup.py]"]
  node_effects["Audio effects<br/>[effects.py]"]
  node_crossfade["Crossfade<br/>[crossfade.py]"]
  node_stats["Listening stats<br/>[stats.py]"]
end

subgraph group_extensions["Companion features"]
  node_remote["Phone remote<br/>[remote.py]"]
  node_remote_page["Remote interface<br/>[remote_page.py]"]
  node_discord["Discord presence<br/>[discord.py]"]
  node_scrobble["Scrobbling<br/>[scrobble.py]"]
  node_visualizer["Full-screen views<br/>[visualizer.py]"]
  node_island["Mini player<br/>[island.py]"]
end

node_listener(("Listener"))
node_youtube_service["YouTube Music service"]
node_spotify_service["Spotify service"]
node_lyrics_services["Lyrics services"]
node_mpv["mpv player"]

node_listener -->|"opens app"| node_main
node_main -->|"loads"| node_settings
node_main -->|"creates"| node_catalog
node_main -->|"creates"| node_player
node_main -->|"creates"| node_resolver
node_main -->|"creates"| node_downloads
node_main -->|"creates"| node_library
node_main -->|"creates"| node_session
node_main -->|"creates"| node_backup
node_main -->|"creates"| node_effects
node_main -->|"creates"| node_discord
node_main -->|"creates"| node_crossfade
node_library -->|"requests catalog"| node_catalog
node_catalog -->|"queries"| node_ytmusic
node_ytmusic -->|"requests catalog"| node_youtube_service
node_library -->|"builds recommendations"| node_discover
node_library -->|"imports playlist"| node_spotify
node_library -->|"matches tracks"| node_matching
node_library -->|"reads and writes"| node_store
node_player -->|"resolves track"| node_resolver
node_player -->|"gets stream"| node_streams
node_resolver -->|"matches track"| node_matching
node_resolver -->|"searches track"| node_ytmusic
node_resolver -->|"resolves audio"| node_streams
node_player -->|"plays audio"| node_engine
node_engine -->|"controls playback"| node_mpv
node_player -->|"checks offline file"| node_downloads
node_player -->|"checks local file"| node_localfiles
node_player -->|"records history"| node_store
node_player -->|"provides track state"| node_lyrics
node_lyrics -->|"fetches lyrics"| node_lyrics_services
node_spotify -->|"reads public playlists"| node_spotify_service
node_main -->|"creates"| node_localfiles
node_main -->|"connects stats"| node_stats
node_backup -->|"backs up library"| node_store
node_main -->|"connects remote"| node_remote
node_remote -->|"serves interface"| node_remote_page
node_session -->|"manages mini player"| node_island
node_effects -->|"configures audio"| node_engine
node_discord -->|"reads playback state"| node_player
node_scrobble -.->|"reports listening"| node_player
node_visualizer -.->|"displays playback"| node_player
node_crossfade -->|"coordinates engines"| node_engine

click node_main "https://github.com/zeeynrs/senada/blob/main/senada/main.py"
click node_settings "https://github.com/zeeynrs/senada/blob/main/senada/config.py"
click node_session "https://github.com/zeeynrs/senada/blob/main/senada/session.py"
click node_library "https://github.com/zeeynrs/senada/blob/main/senada/library.py"
click node_catalog "https://github.com/zeeynrs/senada/blob/main/senada/catalog.py"
click node_ytmusic "https://github.com/zeeynrs/senada/blob/main/senada/ytmusic.py"
click node_discover "https://github.com/zeeynrs/senada/blob/main/senada/discover.py"
click node_spotify "https://github.com/zeeynrs/senada/blob/main/senada/spotify_import.py"
click node_matching "https://github.com/zeeynrs/senada/blob/main/senada/matching.py"
click node_store "https://github.com/zeeynrs/senada/blob/main/senada/store.py"
click node_player "https://github.com/zeeynrs/senada/blob/main/senada/player.py"
click node_resolver "https://github.com/zeeynrs/senada/blob/main/senada/resolver.py"
click node_streams "https://github.com/zeeynrs/senada/blob/main/senada/streams.py"
click node_engine "https://github.com/zeeynrs/senada/blob/main/senada/engine.py"
click node_downloads "https://github.com/zeeynrs/senada/blob/main/senada/downloads.py"
click node_lyrics "https://github.com/zeeynrs/senada/blob/main/senada/lyrics.py"
click node_localfiles "https://github.com/zeeynrs/senada/blob/main/senada/localfiles.py"
click node_backup "https://github.com/zeeynrs/senada/blob/main/senada/backup.py"
click node_effects "https://github.com/zeeynrs/senada/blob/main/senada/effects.py"
click node_crossfade "https://github.com/zeeynrs/senada/blob/main/senada/crossfade.py"
click node_stats "https://github.com/zeeynrs/senada/blob/main/senada/stats.py"
click node_remote "https://github.com/zeeynrs/senada/blob/main/senada/remote.py"
click node_remote_page "https://github.com/zeeynrs/senada/blob/main/senada/remote_page.py"
click node_discord "https://github.com/zeeynrs/senada/blob/main/senada/discord.py"
click node_scrobble "https://github.com/zeeynrs/senada/blob/main/senada/scrobble.py"
click node_visualizer "https://github.com/zeeynrs/senada/blob/main/senada/visualizer.py"
click node_island "https://github.com/zeeynrs/senada/blob/main/senada/island.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_main,node_settings,node_session toneBlue
class node_library,node_catalog,node_ytmusic,node_discover,node_spotify,node_matching,node_store toneAmber
class node_player,node_resolver,node_streams,node_engine,node_downloads,node_lyrics,node_localfiles toneMint
class node_backup,node_effects,node_crossfade,node_stats toneRose
class node_remote,node_remote_page,node_discord,node_scrobble,node_visualizer,node_island,node_listener,node_youtube_service,node_spotify_service,node_lyrics_services,node_mpv toneIndigo
```

## Components

### App and preferences

- [App startup](https://github.com/zeeynrs/senada/blob/main/senada/main.py): `senada/main.py`
- [Settings](https://github.com/zeeynrs/senada/blob/main/senada/config.py): `senada/config.py`
- [Window session](https://github.com/zeeynrs/senada/blob/main/senada/session.py): `senada/session.py`

### Browse and library

- [Library browsing](https://github.com/zeeynrs/senada/blob/main/senada/library.py): `senada/library.py`
- [Catalog facade](https://github.com/zeeynrs/senada/blob/main/senada/catalog.py): `senada/catalog.py`
- [YouTube Music](https://github.com/zeeynrs/senada/blob/main/senada/ytmusic.py): `senada/ytmusic.py`
- [Recommendations](https://github.com/zeeynrs/senada/blob/main/senada/discover.py): `senada/discover.py`
- [Spotify import](https://github.com/zeeynrs/senada/blob/main/senada/spotify_import.py): `senada/spotify_import.py`
- [Track matching](https://github.com/zeeynrs/senada/blob/main/senada/matching.py): `senada/matching.py`
- [Local library store](https://github.com/zeeynrs/senada/blob/main/senada/store.py): `senada/store.py`

### Playback and lyrics

- [Playback controls](https://github.com/zeeynrs/senada/blob/main/senada/player.py): `senada/player.py`
- [Audio resolver](https://github.com/zeeynrs/senada/blob/main/senada/resolver.py): `senada/resolver.py`
- [Stream lookup](https://github.com/zeeynrs/senada/blob/main/senada/streams.py): `senada/streams.py`
- [Audio engine](https://github.com/zeeynrs/senada/blob/main/senada/engine.py): `senada/engine.py`
- [Offline downloads](https://github.com/zeeynrs/senada/blob/main/senada/downloads.py): `senada/downloads.py`
- [Synced lyrics](https://github.com/zeeynrs/senada/blob/main/senada/lyrics.py): `senada/lyrics.py`
- [Local music files](https://github.com/zeeynrs/senada/blob/main/senada/localfiles.py): `senada/localfiles.py`

### Personal listening

- [Backup and restore](https://github.com/zeeynrs/senada/blob/main/senada/backup.py): `senada/backup.py`
- [Audio effects](https://github.com/zeeynrs/senada/blob/main/senada/effects.py): `senada/effects.py`
- [Crossfade](https://github.com/zeeynrs/senada/blob/main/senada/crossfade.py): `senada/crossfade.py`
- [Listening stats](https://github.com/zeeynrs/senada/blob/main/senada/stats.py): `senada/stats.py`

### Companion features

- [Phone remote](https://github.com/zeeynrs/senada/blob/main/senada/remote.py): `senada/remote.py`
- [Remote interface](https://github.com/zeeynrs/senada/blob/main/senada/remote_page.py): `senada/remote_page.py`
- [Discord presence](https://github.com/zeeynrs/senada/blob/main/senada/discord.py): `senada/discord.py`
- [Scrobbling](https://github.com/zeeynrs/senada/blob/main/senada/scrobble.py): `senada/scrobble.py`
- [Full-screen views](https://github.com/zeeynrs/senada/blob/main/senada/visualizer.py): `senada/visualizer.py`
- [Mini player](https://github.com/zeeynrs/senada/blob/main/senada/island.py): `senada/island.py`

### Other components

- **Listener**
- **YouTube Music service**
- **Spotify service**
- **Lyrics services**
- **mpv player**

## Connections

- Listener → App startup: opens app (evidence: `README.md`)
- App startup → Settings: loads (evidence: `senada/main.py`)
- App startup → Catalog facade: creates (evidence: `senada/main.py`)
- App startup → Playback controls: creates (evidence: `senada/main.py`)
- App startup → Audio resolver: creates (evidence: `senada/main.py`)
- App startup → Offline downloads: creates (evidence: `senada/main.py`)
- App startup → Library browsing: creates (evidence: `senada/main.py`)
- App startup → Window session: creates (evidence: `senada/main.py`)
- App startup → Backup and restore: creates (evidence: `senada/main.py`)
- App startup → Audio effects: creates (evidence: `senada/main.py`)
- App startup → Discord presence: creates (evidence: `senada/main.py`)
- App startup → Crossfade: creates (evidence: `senada/main.py`)
- Library browsing → Catalog facade: requests catalog (evidence: `senada/library.py`)
- Catalog facade → YouTube Music: queries (evidence: `senada/catalog.py`)
- YouTube Music → YouTube Music service: requests catalog (evidence: `senada/ytmusic.py`)
- Library browsing → Recommendations: builds recommendations (evidence: `senada/library.py`)
- Library browsing → Spotify import: imports playlist (evidence: `senada/library.py`)
- Library browsing → Track matching: matches tracks (evidence: `senada/library.py`)
- Library browsing → Local library store: reads and writes (evidence: `senada/library.py`)
- Playback controls → Audio resolver: resolves track (evidence: `senada/player.py`)
- Playback controls → Stream lookup: gets stream (evidence: `senada/player.py`)
- Audio resolver → Track matching: matches track (evidence: `senada/resolver.py`)
- Audio resolver → YouTube Music: searches track (evidence: `senada/resolver.py`)
- Audio resolver → Stream lookup: resolves audio (evidence: `senada/resolver.py`)
- Playback controls → Audio engine: plays audio (evidence: `senada/player.py`)
- Audio engine → mpv player: controls playback (evidence: `senada/engine.py`)
- Playback controls → Offline downloads: checks offline file (evidence: `senada/player.py`)
- Playback controls → Local music files: checks local file (evidence: `senada/player.py`)
- Playback controls → Local library store: records history (evidence: `senada/player.py`)
- Playback controls → Synced lyrics: provides track state (evidence: `senada/main.py`)
- Synced lyrics → Lyrics services: fetches lyrics (evidence: `senada/lyrics.py`)
- Spotify import → Spotify service: reads public playlists (evidence: `senada/spotify_import.py`)
- App startup → Local music files: creates (evidence: `senada/main.py`)
- App startup → Listening stats: connects stats (evidence: `senada/main.py`)
- Backup and restore → Local library store: backs up library (evidence: `senada/backup.py`)
- App startup → Phone remote: connects remote (evidence: `senada/main.py`)
- Phone remote → Remote interface: serves interface (evidence: `senada/remote.py`)
- Window session → Mini player: manages mini player (evidence: `senada/session.py`)
- Audio effects → Audio engine: configures audio
- Discord presence → Playback controls: reads playback state (evidence: `senada/discord.py`)
- Scrobbling → Playback controls: reports listening
- Full-screen views → Playback controls: displays playback
- Crossfade → Audio engine: coordinates engines (evidence: `senada/crossfade.py`)
