# zpleum/star-player architecture

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

- Interactive diagram: https://gitdiagram.com/zpleum/star-player
- Repository: https://github.com/zpleum/star-player

## Overview

Star Player is a cross-platform music player whose main workflow is importing or downloading audio into a local library, then organizing, analyzing, and playing it through a queue and player interface. Its other major capabilities include playlists and favorites, mood-based discovery, audio effects, and YouTube downloads/conversion backed by a documented POT Server integration. The graph reflects the shown imports and calls plus README claims; some routes and integrations are represented only at the documented level because their implementation was not sampled.

Main entry points: [`src/contexts/LibraryContext.tsx`](https://github.com/zpleum/star-player/blob/main/src/contexts/LibraryContext.tsx) (Library State), [`src/components/player/FullPlayer.tsx`](https://github.com/zpleum/star-player/blob/main/src/components/player/FullPlayer.tsx) (Full Player), [`src/hooks/useAudioAnalysis.ts`](https://github.com/zpleum/star-player/blob/main/src/hooks/useAudioAnalysis.ts) (Analysis Workflow), [`src/components/library/SongList.tsx`](https://github.com/zpleum/star-player/blob/main/src/components/library/SongList.tsx) (Song Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Music Library"]
  node_home["Library Browse<br/>[page.tsx]"]
  node_favorites["Favorites<br/>[page.tsx]"]
  node_playlists["Playlists<br/>[page.tsx]"]
  node_playlist_view["Playlist View<br/>[page.tsx]"]
  node_library_state["Library State<br/>[LibraryContext.tsx]"]
  node_library_views["Song Views<br/>[SongList.tsx]"]
  node_library_db[("Local Library DB<br/>[db.ts]")]
  node_settings["Library Settings<br/>[page.tsx]"]
end

subgraph group_playback["Playback"]
  node_queue_page["Queue View<br/>[page.tsx]"]
  node_player_state["Player State<br/>[PlayerContext.tsx]"]
  node_full_player["Full Player<br/>[FullPlayer.tsx]"]
  node_equalizer["Equalizer<br/>[Equalizer.tsx]"]
  node_lyrics["Lyrics View<br/>[LyricsView.tsx]"]
  node_visualizer["Visualizer<br/>[Visualizer.tsx]"]
end

subgraph group_analysis["Audio Discovery"]
  node_moods["Mood Browser<br/>[page.tsx]"]
  node_mood_view["Mood Results<br/>[page.tsx]"]
  node_analysis_hook["Analysis Workflow"]
  node_analyzer["Audio Analyzer<br/>[audioAnalyzer.ts]"]
  node_classifier["Mood Classifier<br/>[moodClassifier.ts]"]
end

subgraph group_media["Media Import"]
  node_youtube_page["YouTube Download<br/>[page.tsx]"]
  node_youtube_download["YouTube Downloader"]
  node_youtube_mp3_page["YouTube to MP3<br/>[page.tsx]"]
  node_youtube_mp3["MP3 Converter<br/>[YouTubeToMP3.tsx]"]
end

node_user(("Listener"))
node_pot_server{{"POT Server"}}

node_user -->|"browses"| node_home
node_home -->|"reads library"| node_library_state
node_home -->|"renders songs"| node_library_views
node_favorites -->|"reads favorites"| node_library_state
node_favorites -->|"renders songs"| node_library_views
node_playlists -->|"reads playlists"| node_library_state
node_playlist_view -->|"reads playlist"| node_library_state
node_playlist_view -->|"renders songs"| node_library_views
node_library_state -->|"reads and writes"| node_library_db
node_settings -->|"manages library"| node_library_state
node_settings -->|"starts analysis"| node_analysis_hook
node_user -.->|"opens queue"| node_queue_page
node_queue_page -->|"reads queue"| node_player_state
node_player_state -->|"reads song data"| node_library_db
node_full_player -->|"controls playback"| node_player_state
node_full_player -->|"renders"| node_equalizer
node_full_player -->|"renders"| node_lyrics
node_full_player -->|"renders"| node_visualizer
node_moods -->|"analyzes songs"| node_analysis_hook
node_mood_view -->|"reads songs"| node_library_state
node_mood_view -->|"renders songs"| node_library_views
node_analysis_hook -->|"reads audio and saves analysis"| node_library_db
node_analysis_hook -->|"analyzes audio"| node_analyzer
node_analyzer -->|"classifies mood"| node_classifier
node_youtube_page -->|"renders"| node_youtube_download
node_youtube_mp3_page -->|"renders"| node_youtube_mp3
node_youtube_download -->|"adds media"| node_library_state
node_youtube_mp3 -->|"adds media"| node_library_state
node_youtube_download -.->|"uses service"| node_pot_server
node_youtube_mp3 -.->|"uses service"| node_pot_server

click node_home "https://github.com/zpleum/star-player/blob/main/src/app/page.tsx"
click node_favorites "https://github.com/zpleum/star-player/blob/main/src/app/favorites/page.tsx"
click node_playlists "https://github.com/zpleum/star-player/blob/main/src/app/playlists/page.tsx"
click node_playlist_view "https://github.com/zpleum/star-player/blob/main/src/app/playlists/view/page.tsx"
click node_library_state "https://github.com/zpleum/star-player/blob/main/src/contexts/LibraryContext.tsx"
click node_library_views "https://github.com/zpleum/star-player/blob/main/src/components/library/SongList.tsx"
click node_library_db "https://github.com/zpleum/star-player/blob/main/src/lib/db.ts"
click node_settings "https://github.com/zpleum/star-player/blob/main/src/app/settings/page.tsx"
click node_queue_page "https://github.com/zpleum/star-player/blob/main/src/app/queue/page.tsx"
click node_player_state "https://github.com/zpleum/star-player/blob/main/src/contexts/PlayerContext.tsx"
click node_full_player "https://github.com/zpleum/star-player/blob/main/src/components/player/FullPlayer.tsx"
click node_equalizer "https://github.com/zpleum/star-player/blob/main/src/components/player/Equalizer.tsx"
click node_lyrics "https://github.com/zpleum/star-player/blob/main/src/components/player/LyricsView.tsx"
click node_visualizer "https://github.com/zpleum/star-player/blob/main/src/components/player/Visualizer.tsx"
click node_moods "https://github.com/zpleum/star-player/blob/main/src/app/moods/page.tsx"
click node_mood_view "https://github.com/zpleum/star-player/blob/main/src/app/moods/view/page.tsx"
click node_analysis_hook "https://github.com/zpleum/star-player/blob/main/src/hooks/useAudioAnalysis.ts"
click node_analyzer "https://github.com/zpleum/star-player/blob/main/src/lib/audioAnalyzer.ts"
click node_classifier "https://github.com/zpleum/star-player/blob/main/src/lib/moodClassifier.ts"
click node_youtube_page "https://github.com/zpleum/star-player/blob/main/src/app/youtube/page.tsx"
click node_youtube_download "https://github.com/zpleum/star-player/blob/main/src/components/youtube/YouTubeDownloader.tsx"
click node_youtube_mp3_page "https://github.com/zpleum/star-player/blob/main/src/app/youtube-to-mp3/page.tsx"
click node_youtube_mp3 "https://github.com/zpleum/star-player/blob/main/src/components/youtube/YouTubeToMP3.tsx"

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_home,node_favorites,node_playlists,node_playlist_view,node_library_state,node_library_views,node_library_db,node_settings toneBlue
class node_queue_page,node_player_state,node_full_player,node_equalizer,node_lyrics,node_visualizer toneAmber
class node_moods,node_mood_view,node_analysis_hook,node_analyzer,node_classifier,node_pot_server toneMint
class node_youtube_page,node_youtube_download,node_youtube_mp3_page,node_youtube_mp3 toneRose
class node_user toneIndigo
```

## Components

### Music Library

- [Library Browse](https://github.com/zpleum/star-player/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Favorites](https://github.com/zpleum/star-player/blob/main/src/app/favorites/page.tsx): `src/app/favorites/page.tsx`
- [Playlists](https://github.com/zpleum/star-player/blob/main/src/app/playlists/page.tsx): `src/app/playlists/page.tsx`
- [Playlist View](https://github.com/zpleum/star-player/blob/main/src/app/playlists/view/page.tsx): `src/app/playlists/view/page.tsx`
- [Library State](https://github.com/zpleum/star-player/blob/main/src/contexts/LibraryContext.tsx): `src/contexts/LibraryContext.tsx`
- [Song Views](https://github.com/zpleum/star-player/blob/main/src/components/library/SongList.tsx): `src/components/library/SongList.tsx`
- [Local Library DB](https://github.com/zpleum/star-player/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Library Settings](https://github.com/zpleum/star-player/blob/main/src/app/settings/page.tsx): `src/app/settings/page.tsx`

### Playback

- [Queue View](https://github.com/zpleum/star-player/blob/main/src/app/queue/page.tsx): `src/app/queue/page.tsx`
- [Player State](https://github.com/zpleum/star-player/blob/main/src/contexts/PlayerContext.tsx): `src/contexts/PlayerContext.tsx`
- [Full Player](https://github.com/zpleum/star-player/blob/main/src/components/player/FullPlayer.tsx): `src/components/player/FullPlayer.tsx`
- [Equalizer](https://github.com/zpleum/star-player/blob/main/src/components/player/Equalizer.tsx): `src/components/player/Equalizer.tsx`
- [Lyrics View](https://github.com/zpleum/star-player/blob/main/src/components/player/LyricsView.tsx): `src/components/player/LyricsView.tsx`
- [Visualizer](https://github.com/zpleum/star-player/blob/main/src/components/player/Visualizer.tsx): `src/components/player/Visualizer.tsx`

### Audio Discovery

- [Mood Browser](https://github.com/zpleum/star-player/blob/main/src/app/moods/page.tsx): `src/app/moods/page.tsx`
- [Mood Results](https://github.com/zpleum/star-player/blob/main/src/app/moods/view/page.tsx): `src/app/moods/view/page.tsx`
- [Analysis Workflow](https://github.com/zpleum/star-player/blob/main/src/hooks/useAudioAnalysis.ts): `src/hooks/useAudioAnalysis.ts`
- [Audio Analyzer](https://github.com/zpleum/star-player/blob/main/src/lib/audioAnalyzer.ts): `src/lib/audioAnalyzer.ts`
- [Mood Classifier](https://github.com/zpleum/star-player/blob/main/src/lib/moodClassifier.ts): `src/lib/moodClassifier.ts`

### Media Import

- [YouTube Download](https://github.com/zpleum/star-player/blob/main/src/app/youtube/page.tsx): `src/app/youtube/page.tsx`
- [YouTube Downloader](https://github.com/zpleum/star-player/blob/main/src/components/youtube/YouTubeDownloader.tsx): `src/components/youtube/YouTubeDownloader.tsx`
- [YouTube to MP3](https://github.com/zpleum/star-player/blob/main/src/app/youtube-to-mp3/page.tsx): `src/app/youtube-to-mp3/page.tsx`
- [MP3 Converter](https://github.com/zpleum/star-player/blob/main/src/components/youtube/YouTubeToMP3.tsx): `src/components/youtube/YouTubeToMP3.tsx`

### Other components

- **Listener**
- **POT Server**

## Connections

- Listener → Library Browse: browses (evidence: `src/app/page.tsx`)
- Library Browse → Library State: reads library (evidence: `src/app/page.tsx`)
- Library Browse → Song Views: renders songs (evidence: `src/app/page.tsx`)
- Favorites → Library State: reads favorites (evidence: `src/app/favorites/page.tsx`)
- Favorites → Song Views: renders songs (evidence: `src/app/favorites/page.tsx`)
- Playlists → Library State: reads playlists (evidence: `src/app/playlists/page.tsx`)
- Playlist View → Library State: reads playlist (evidence: `src/app/playlists/view/page.tsx`)
- Playlist View → Song Views: renders songs (evidence: `src/app/playlists/view/page.tsx`)
- Library State → Local Library DB: reads and writes (evidence: `src/contexts/LibraryContext.tsx`)
- Library Settings → Library State: manages library (evidence: `src/app/settings/page.tsx`)
- Library Settings → Analysis Workflow: starts analysis (evidence: `src/app/settings/page.tsx`)
- Listener → Queue View: opens queue
- Queue View → Player State: reads queue (evidence: `src/app/queue/page.tsx`)
- Player State → Local Library DB: reads song data (evidence: `src/contexts/PlayerContext.tsx`)
- Full Player → Player State: controls playback (evidence: `src/components/player/FullPlayer.tsx`)
- Full Player → Equalizer: renders (evidence: `src/components/player/FullPlayer.tsx`)
- Full Player → Lyrics View: renders (evidence: `src/components/player/FullPlayer.tsx`)
- Full Player → Visualizer: renders (evidence: `src/components/player/FullPlayer.tsx`)
- Mood Browser → Analysis Workflow: analyzes songs (evidence: `src/app/moods/page.tsx`)
- Mood Results → Library State: reads songs (evidence: `src/app/moods/view/page.tsx`)
- Mood Results → Song Views: renders songs (evidence: `src/app/moods/view/page.tsx`)
- Analysis Workflow → Local Library DB: reads audio and saves analysis (evidence: `src/hooks/useAudioAnalysis.ts`)
- Analysis Workflow → Audio Analyzer: analyzes audio (evidence: `src/hooks/useAudioAnalysis.ts`)
- Audio Analyzer → Mood Classifier: classifies mood (evidence: `src/lib/audioAnalyzer.ts`)
- YouTube Download → YouTube Downloader: renders (evidence: `src/app/youtube/page.tsx`)
- YouTube to MP3 → MP3 Converter: renders (evidence: `src/app/youtube-to-mp3/page.tsx`)
- YouTube Downloader → Library State: adds media (evidence: `src/components/youtube/YouTubeDownloader.tsx`)
- MP3 Converter → Library State: adds media (evidence: `src/components/youtube/YouTubeToMP3.tsx`)
- YouTube Downloader → POT Server: uses service (evidence: `README.md`)
- MP3 Converter → POT Server: uses service (evidence: `README.md`)
