How heiphaistos/forge-audio- works
Forge Audio is a self-hosted, multi-source music player with web and Electron clients. The main workflow is discovery or link import, server-side media resolution, then client playback; library state can persist locally or sync across devices. The graph also preserves the documented radio, lyrics, catalog, social, account, download, and desktop capabilities. Several server and UI subsystems are represented by their exact paths but were not sampled; their documented capabilities are shown without asserting unverified internal calls.
Main entry points: app.js HTTP API routes · api.ts Web API client · main.js Electron host · player.ts Queue and player state
Components 27
Web experience
- App and navigation
web/src/App.tsx - Search and browse
web/src/views/Search.tsx - Catalog views
web/src/views/Catalog.tsx - Radio view
web/src/views/Radio.tsx - Library state
web/src/store/library.ts - Queue and player state
web/src/store/player.ts - Web API client
web/src/lib/api.ts - Cross-device sync
web/src/lib/sync.ts - Social and Jam
web/src/store/social.ts
Music discovery and playback
- Audio engine
web/src/audio/engine.ts
Server services
- HTTP API routes
server/src/app.js - Accounts and sessions
server/src/accounts.js - Source search
server/src/search.js - Media source resolver
server/src/ytdlp.js - Playback resolution
server/src/streaming.js - Media streaming
server/src/stream.js - Radio service
server/src/radio.js - Lyrics service
server/src/lyrics.js - Music catalog
server/src/catalog.js - User library data
server/src/userdata.js - Social services
server/src/social.js
Desktop runtime
- Electron host
desktop/main.js - Desktop yt-dlp manager
desktop/ytdlp-manager.js - Desktop updater
desktop/updater.js
Other components
- Listener
- Music source sites
- LRCLIB
Connections 35
- Listener → App and navigation: uses
README.md - App and navigation → Search and browse: routes to
web/src/App.tsx - Listener → Search and browse: searches
README.md - Search and browse → Web API client: requests search
web/src/views/Search.tsx - Web API client → HTTP API routes: calls API
README.md - HTTP API routes → Source search: dispatches search
server/src/app.js - Source search → Media source resolver: queries sources
server/src/search.js - Media source resolver → Music source sites: extracts media
README.md - Listener → Queue and player state: controls playback
README.md - Queue and player state → Audio engine: loads and controls
web/src/store/player.ts - Audio engine → Web API client: resolves tracks
web/src/audio/engine.ts - Web API client → HTTP API routes: requests resolution
README.md - HTTP API routes → Playback resolution: resolves playback
server/src/app.js - Playback resolution → Media source resolver: resolves media URL
server/src/streaming.js - HTTP API routes → Media streaming: serves media
README.md - Queue and player state → Library state: updates listening state
web/src/store/player.ts - Library state → Cross-device sync: syncs library state
web/src/lib/sync.ts - Cross-device sync → Web API client: reads and writes data
web/src/lib/sync.ts - HTTP API routes → User library data: persists user data
server/src/app.js - HTTP API routes → Accounts and sessions: authenticates users
server/src/app.js - Listener → Catalog views: browses catalog
README.md - Catalog views → Web API client: requests catalog
web/src/views/Catalog.tsx - HTTP API routes → Music catalog: serves catalog
server/src/app.js - Listener → Radio view: starts radio
README.md - Radio view → Web API client: requests stations
web/src/views/Radio.tsx - HTTP API routes → Radio service: routes radio
server/src/app.js - HTTP API routes → Lyrics service: serves lyrics
README.md - Lyrics service → LRCLIB: looks up lyrics
README.md - Listener → Social and Jam: uses social features
README.md - Social and Jam → Web API client: sends social requests
web/src/store/social.ts - HTTP API routes → Social services: routes social features
server/src/app.js - Listener → Electron host: uses desktop app
README.md - Electron host → HTTP API routes: starts embedded server
README.md - Electron host → Desktop yt-dlp manager: manages yt-dlp
desktop/main.js - Electron host → Desktop updater: checks updates
desktop/main.js