# swadesh-c0de/vibe-fi architecture

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

- Interactive diagram: https://gitdiagram.com/swadesh-c0de/vibe-fi
- Repository: https://github.com/swadesh-c0de/vibe-fi

## Overview

Vibe-Fi is a terminal music player. Its main workflow accepts a search, URL, or local file, resolves online audio when needed, plays it through mpv, and presents playback controls and visualizations in the terminal. The README also documents library browsing, playlists, synced lyrics, session/theme preferences, updates, and desktop integrations. Several source excerpts are partial or absent, so links for those documented capabilities are limited to supported modules and are not expanded into speculative call chains.

Main entry points: [`src/ui/ui.cpp`](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/ui/ui.cpp) (Terminal UI), [`src/main.cpp`](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/main.cpp) (CLI entry), [`src/core/player.cpp`](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/core/player.cpp) (Audio player), [`src/services/search.cpp`](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/search.cpp) (YouTube search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application"]
  node_main["CLI entry<br/>[main.cpp]"]
  node_terminal_ui["Terminal UI<br/>[ui.cpp]"]
end

subgraph group_playback["Playback"]
  node_player["Audio player<br/>[player.cpp]"]
  node_visualizer["Audio visualizers<br/>[visualizer.cpp]"]
end

subgraph group_content["Music features"]
  node_search["YouTube search<br/>[search.cpp]"]
  node_library["Local library<br/>[library.cpp]"]
  node_lyrics["Synced lyrics<br/>[lyrics.cpp]"]
  node_playlist_manager["Playlist manager"]
  node_playlist_files[("Playlist files")]
end

subgraph group_integrations["Integrations"]
  node_mpris["MPRIS controls<br/>[mpris.cpp]"]
  node_discord["Discord presence<br/>[discord_rpc.cpp]"]
end

subgraph group_support["App services"]
  node_utils["Stream resolution<br/>[utils.cpp]"]
  node_updater["Updater and bottle<br/>[updater.cpp]"]
end

node_listener(("Listener"))
node_yt_dlp["yt-dlp"]
node_mpv["mpv engine"]
node_lrclib["lrclib service"]
node_dbus["Session D-Bus"]
node_discord_app["Discord client"]

node_listener -->|"starts with input"| node_main
node_main -->|"searches query"| node_search
node_search -->|"runs search"| node_yt_dlp
node_main -->|"resolves URL"| node_utils
node_utils -->|"resolves stream"| node_yt_dlp
node_main -->|"loads track"| node_player
node_listener -->|"uses controls"| node_terminal_ui
node_terminal_ui -->|"browses files"| node_library
node_terminal_ui -->|"requests search"| node_search
node_terminal_ui -->|"manages playlists"| node_playlist_manager
node_playlist_manager -->|"reads and writes"| node_playlist_files
node_terminal_ui -->|"controls playback"| node_player
node_player -->|"controls audio"| node_mpv
node_visualizer -->|"reads audio stats"| node_player
node_terminal_ui -->|"requests lyrics"| node_lyrics
node_lyrics -.->|"fetches lyrics"| node_lrclib
node_terminal_ui -->|"starts and polls"| node_mpris
node_mpris -.->|"receives controls"| node_dbus
node_terminal_ui -.->|"updates presence"| node_discord
node_discord -.->|"sends activity"| node_discord_app
node_main -->|"handles update flags"| node_updater

click node_main "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/main.cpp"
click node_terminal_ui "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/ui/ui.cpp"
click node_search "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/search.cpp"
click node_utils "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/utils/utils.cpp"
click node_library "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/library.cpp"
click node_player "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/core/player.cpp"
click node_visualizer "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/ui/visualizer.cpp"
click node_lyrics "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/lyrics.cpp"
click node_playlist_manager "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/playlist_manager.cpp"
click node_mpris "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/integrations/mpris.cpp"
click node_discord "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/integrations/discord_rpc.cpp"
click node_updater "https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/updater.cpp"

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_terminal_ui,node_discord_app toneBlue
class node_player,node_visualizer toneAmber
class node_search,node_library,node_lyrics,node_playlist_manager,node_playlist_files toneMint
class node_mpris,node_discord toneRose
class node_utils,node_updater,node_listener,node_yt_dlp,node_mpv,node_lrclib,node_dbus toneIndigo
```

## Components

### Application

- [CLI entry](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/main.cpp): `src/main.cpp`
- [Terminal UI](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/ui/ui.cpp): `src/ui/ui.cpp`

### Playback

- [Audio player](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/core/player.cpp): `src/core/player.cpp`
- [Audio visualizers](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/ui/visualizer.cpp): `src/ui/visualizer.cpp`

### Music features

- [YouTube search](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/search.cpp): `src/services/search.cpp`
- [Local library](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/library.cpp): `src/services/library.cpp`
- [Synced lyrics](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/lyrics.cpp): `src/services/lyrics.cpp`
- [Playlist manager](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/playlist_manager.cpp): `src/services/playlist_manager.cpp`
- **Playlist files**

### Integrations

- [MPRIS controls](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/integrations/mpris.cpp): `src/integrations/mpris.cpp`
- [Discord presence](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/integrations/discord_rpc.cpp): `src/integrations/discord_rpc.cpp`

### App services

- [Stream resolution](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/utils/utils.cpp): `src/utils/utils.cpp`
- [Updater and bottle](https://github.com/swadesh-c0de/vibe-fi/blob/main/src/services/updater.cpp): `src/services/updater.cpp`

### Other components

- **Listener**
- **yt-dlp**
- **mpv engine**
- **lrclib service**
- **Session D-Bus**
- **Discord client**

## Connections

- Listener → CLI entry: starts with input
- CLI entry → YouTube search: searches query
- YouTube search → yt-dlp: runs search
- CLI entry → Stream resolution: resolves URL
- Stream resolution → yt-dlp: resolves stream
- CLI entry → Audio player: loads track
- Listener → Terminal UI: uses controls
- Terminal UI → Local library: browses files
- Terminal UI → YouTube search: requests search
- Terminal UI → Playlist manager: manages playlists
- Playlist manager → Playlist files: reads and writes
- Terminal UI → Audio player: controls playback
- Audio player → mpv engine: controls audio
- Audio visualizers → Audio player: reads audio stats
- Terminal UI → Synced lyrics: requests lyrics
- Synced lyrics → lrclib service: fetches lyrics
- Terminal UI → MPRIS controls: starts and polls
- MPRIS controls → Session D-Bus: receives controls
- Terminal UI → Discord presence: updates presence
- Discord presence → Discord client: sends activity
- CLI entry → Updater and bottle: handles update flags