# termuxbash/musicify architecture

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

- Interactive diagram: https://gitdiagram.com/termuxbash/musicify
- Repository: https://github.com/termuxbash/musicify

## Overview

Musicify is a Flask music streamer that lets users browse local audio or find YouTube tracks, queue playback, and send the resulting Icecast stream to a Bose SoundTouch speaker. The main path runs from a source route through playback ownership and the queue player, then through FFmpeg to Icecast; speaker controls separately direct the Bose device to the stream. Other capabilities include queue/status controls, playlists and history, lyrics display, autoplay/recommendations, and local/YouTube search. The map follows the shown calls and README-described features; unsampled implementation links are omitted or marked unverified.

Main entry points: [`app.py`](https://github.com/termuxbash/musicify/blob/main/app.py) (Flask App), [`core/stream_manager.py`](https://github.com/termuxbash/musicify/blob/main/core/stream_manager.py) (Queue Player), [`core/playback_controller.py`](https://github.com/termuxbash/musicify/blob/main/core/playback_controller.py) (Playback Ownership), [`apps/local/routes.py`](https://github.com/termuxbash/musicify/blob/main/apps/local/routes.py) (Local Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Music Sources"]
  node_local["Local Library<br/>[routes.py]"]
  node_youtube["YouTube Routes<br/>[routes.py]"]
  node_ytservice["YouTube Service<br/>[yt_service.py]"]
  node_localmusic[("Music Files")]
  node_youtubeapi["YouTube API"]
end

subgraph group_playback["Playback Core"]
  node_app["Flask App<br/>[app.py]"]
  node_playbackctl["Playback Ownership"]
  node_queue["Queue Player<br/>[stream_manager.py]"]
end

subgraph group_device["Speaker and Stream"]
  node_ffmpeg["FFmpeg Streaming<br/>[ffmpeg_service.py]"]
  node_icecast[("Icecast Stream")]
  node_boseroutes["Speaker Controls<br/>[bose_routes.py]"]
  node_boseworker["Bose Device Client<br/>[bose_worker.py]"]
  node_bose["Bose Speaker"]
end

subgraph group_features["Player Features"]
  node_stats["Status and History<br/>[stats.py]"]
  node_lyrics["Lyrics Service<br/>[lyrics_service.py]"]
  node_display["Lyrics Display<br/>[display.py]"]
  node_settings["Runtime Settings<br/>[settings.py]"]
  node_lastfm["Last.fm"]
  node_lrclib["LRCLIB"]
end

subgraph group_interface["Web Interface"]
  node_webui["Web Pages and Assets"]
  node_javascript["Browser Interactions<br/>[common.js]"]
end

node_user(("Listener"))

node_user -->|"uses"| node_webui
node_app -->|"registers routes"| node_local
node_app -->|"registers routes"| node_youtube
node_app -->|"registers routes"| node_boseroutes
node_app -->|"registers routes"| node_stats
node_app -->|"starts player"| node_queue
node_app -->|"creates controller"| node_playbackctl
node_app -->|"configures player"| node_ffmpeg
node_app -->|"configures player"| node_boseworker
node_local -->|"browses files"| node_localmusic
node_local -->|"acquires and enqueues"| node_playbackctl
node_youtube -->|"searches and resolves"| node_ytservice
node_youtube -->|"acquires playback"| node_playbackctl
node_ytservice -->|"searches"| node_youtubeapi
node_ytservice -->|"enqueues tracks"| node_playbackctl
node_playbackctl -->|"delegates playback"| node_queue
node_queue -.->|"starts streams"| node_ffmpeg
node_ffmpeg -->|"publishes audio"| node_icecast
node_boseroutes -->|"dispatches commands"| node_boseworker
node_boseworker -->|"controls and queries"| node_bose
node_boseroutes -->|"selects stream URL"| node_icecast
node_stats -->|"reads player status"| node_queue
node_stats -->|"requests track lookup"| node_ytservice
node_queue -.->|"gets recommendations"| node_lastfm
node_lyrics -->|"fetches synced lyrics"| node_lrclib
node_lyrics -->|"sends lyric lines"| node_display
node_app -->|"creates service"| node_lyrics
node_local -->|"reads library root"| node_settings
node_youtube -->|"reads configuration"| node_settings
node_boseroutes -->|"reads speaker config"| node_settings
node_javascript -.->|"supports interactions"| node_webui

click node_app "https://github.com/termuxbash/musicify/blob/main/app.py"
click node_local "https://github.com/termuxbash/musicify/blob/main/apps/local/routes.py"
click node_youtube "https://github.com/termuxbash/musicify/blob/main/apps/yt/routes.py"
click node_ytservice "https://github.com/termuxbash/musicify/blob/main/services/yt_service.py"
click node_playbackctl "https://github.com/termuxbash/musicify/blob/main/core/playback_controller.py"
click node_queue "https://github.com/termuxbash/musicify/blob/main/core/stream_manager.py"
click node_ffmpeg "https://github.com/termuxbash/musicify/blob/main/services/ffmpeg_service.py"
click node_boseroutes "https://github.com/termuxbash/musicify/blob/main/core/bose_routes.py"
click node_boseworker "https://github.com/termuxbash/musicify/blob/main/core/bose_worker.py"
click node_stats "https://github.com/termuxbash/musicify/blob/main/core/stats.py"
click node_lyrics "https://github.com/termuxbash/musicify/blob/main/services/lyrics_service.py"
click node_display "https://github.com/termuxbash/musicify/blob/main/core/display.py"
click node_settings "https://github.com/termuxbash/musicify/blob/main/core/settings.py"
click node_webui "https://github.com/termuxbash/musicify/tree/main/templates"
click node_javascript "https://github.com/termuxbash/musicify/blob/main/static/common.js"

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_local,node_youtube,node_ytservice,node_localmusic,node_youtubeapi toneBlue
class node_app,node_playbackctl,node_queue toneAmber
class node_ffmpeg,node_icecast,node_boseroutes,node_boseworker,node_bose toneMint
class node_stats,node_lyrics,node_display,node_settings,node_lastfm,node_lrclib toneRose
class node_webui,node_javascript,node_user toneIndigo
```

## Components

### Music Sources

- [Local Library](https://github.com/termuxbash/musicify/blob/main/apps/local/routes.py): `apps/local/routes.py`
- [YouTube Routes](https://github.com/termuxbash/musicify/blob/main/apps/yt/routes.py): `apps/yt/routes.py`
- [YouTube Service](https://github.com/termuxbash/musicify/blob/main/services/yt_service.py): `services/yt_service.py`
- **Music Files**
- **YouTube API**

### Playback Core

- [Flask App](https://github.com/termuxbash/musicify/blob/main/app.py): `app.py`
- [Playback Ownership](https://github.com/termuxbash/musicify/blob/main/core/playback_controller.py): `core/playback_controller.py`
- [Queue Player](https://github.com/termuxbash/musicify/blob/main/core/stream_manager.py): `core/stream_manager.py`

### Speaker and Stream

- [FFmpeg Streaming](https://github.com/termuxbash/musicify/blob/main/services/ffmpeg_service.py): `services/ffmpeg_service.py`
- **Icecast Stream**
- [Speaker Controls](https://github.com/termuxbash/musicify/blob/main/core/bose_routes.py): `core/bose_routes.py`
- [Bose Device Client](https://github.com/termuxbash/musicify/blob/main/core/bose_worker.py): `core/bose_worker.py`
- **Bose Speaker**

### Player Features

- [Status and History](https://github.com/termuxbash/musicify/blob/main/core/stats.py): `core/stats.py`
- [Lyrics Service](https://github.com/termuxbash/musicify/blob/main/services/lyrics_service.py): `services/lyrics_service.py`
- [Lyrics Display](https://github.com/termuxbash/musicify/blob/main/core/display.py): `core/display.py`
- [Runtime Settings](https://github.com/termuxbash/musicify/blob/main/core/settings.py): `core/settings.py`
- **Last.fm**
- **LRCLIB**

### Web Interface

- [Web Pages and Assets](https://github.com/termuxbash/musicify/tree/main/templates): `templates`
- [Browser Interactions](https://github.com/termuxbash/musicify/blob/main/static/common.js): `static/common.js`

### Other components

- **Listener**

## Connections

- Listener → Web Pages and Assets: uses (evidence: `README.md`)
- Flask App → Local Library: registers routes (evidence: `app.py`)
- Flask App → YouTube Routes: registers routes (evidence: `app.py`)
- Flask App → Speaker Controls: registers routes (evidence: `app.py`)
- Flask App → Status and History: registers routes (evidence: `app.py`)
- Flask App → Queue Player: starts player (evidence: `app.py`)
- Flask App → Playback Ownership: creates controller (evidence: `app.py`)
- Flask App → FFmpeg Streaming: configures player (evidence: `app.py`)
- Flask App → Bose Device Client: configures player (evidence: `app.py`)
- Local Library → Music Files: browses files (evidence: `apps/local/routes.py`)
- Local Library → Playback Ownership: acquires and enqueues (evidence: `apps/local/routes.py`)
- YouTube Routes → YouTube Service: searches and resolves (evidence: `apps/yt/routes.py`)
- YouTube Routes → Playback Ownership: acquires playback (evidence: `apps/yt/routes.py`)
- YouTube Service → YouTube API: searches (evidence: `services/yt_service.py`)
- YouTube Service → Playback Ownership: enqueues tracks (evidence: `services/yt_service.py`)
- Playback Ownership → Queue Player: delegates playback (evidence: `core/playback_controller.py`)
- Queue Player → FFmpeg Streaming: starts streams
- FFmpeg Streaming → Icecast Stream: publishes audio (evidence: `services/ffmpeg_service.py`)
- Speaker Controls → Bose Device Client: dispatches commands (evidence: `core/bose_routes.py`)
- Bose Device Client → Bose Speaker: controls and queries (evidence: `core/bose_worker.py`)
- Speaker Controls → Icecast Stream: selects stream URL (evidence: `core/bose_routes.py`)
- Status and History → Queue Player: reads player status (evidence: `core/stats.py`)
- Status and History → YouTube Service: requests track lookup (evidence: `core/stats.py`)
- Queue Player → Last.fm: gets recommendations (evidence: `core/stream_manager.py`)
- Lyrics Service → LRCLIB: fetches synced lyrics (evidence: `services/lyrics_service.py`)
- Lyrics Service → Lyrics Display: sends lyric lines (evidence: `services/lyrics_service.py`)
- Flask App → Lyrics Service: creates service (evidence: `app.py`)
- Local Library → Runtime Settings: reads library root (evidence: `apps/local/routes.py`)
- YouTube Routes → Runtime Settings: reads configuration (evidence: `apps/yt/routes.py`)
- Speaker Controls → Runtime Settings: reads speaker config (evidence: `core/bose_routes.py`)
- Browser Interactions → Web Pages and Assets: supports interactions
