How whimsypingu/scuttle works
Scuttle is a self-hosted audio archive: users search their library or discover audio, queue downloads, then play and organize tracks through a browser. The graph follows documented backend REST/WebSocket and frontend responsibilities, with database, workers, playlist import, metadata enrichment, and audio processing represented as distinct stages. Source excerpts support selected calls; README statements support the client/server and remote-access links. Several router and integration implementations were not sampled, so uncertain internal wiring is omitted.
Main entry points: server.py FastAPI server · audio_database.py Audio library · search_router.py Search API · download.py Download worker
Components 33
Backend services
- FastAPI server
backend/server.py - Search API
backend/api/routers/search_router.py - Playlist API
backend/api/routers/playlists_router.py - Queue API
backend/api/routers/queue_router.py - Audio API
backend/api/routers/audio_router.py - WebSocket API
backend/api/routers/websocket_router.py - Audio library
backend/core/database/audio_database.py - Audio discovery
backend/core/youtube/client.py - Download worker
backend/core/worker/download.py - Download queue
backend/core/queue/implementations/download_queue.py - Audio processing
backend/core/audio/processor.py - Playback queue
backend/core/queue/implementations/play_queue.py - Audio streaming
backend/core/audio/stream.py - Playlist manager
backend/core/playlists/manager.py - Spotify import
backend/core/playlists/implementations/spotify_playlist_ext.py - Metadata enrichment
backend/core/worker/enrich.py - MusicBrainz client
backend/core/musicbrainz/client.py - Event bus
backend/core/events/event_bus.py - Event handlers
backend/core/events/handlers.py - WebSocket manager
backend/core/events/websocket/manager.py
Browser client
- Client bootstrap
frontend/js/main.js - Search interface
frontend/js/features/search/controller.js - Playback controls
frontend/js/features/audio/controller.js - Queue interface
frontend/js/features/queue/controller.js - Playlist interface
frontend/js/features/playlist/controller.js - Playlist dialogs
frontend/js/features/popup/controller.js - Client state
frontend/js/cache/TrackStore.js - Live updates
frontend/js/events/websocket/handlers.js
Desktop launcher
- Desktop controls
launcher/src/app.rs
Other components
- Listener
- Web browser
- Cloudflared tunnel
- Discord webhook
Connections 47
- Listener → Web browser: uses
- Web browser → FastAPI server: REST requests
- FastAPI server → Web browser: WebSocket events
- FastAPI server → Search API: routes to
backend/server.py - Search API → Audio library: searches
backend/api/routers/search_router.py - Search API → Audio discovery: deep searches
backend/api/routers/search_router.py - Search API → Download queue: enqueues job
- FastAPI server → Playlist API: routes to
backend/server.py - Playlist API → Audio library: reads library
backend/api/routers/playlists_router.py - Playlist API → Playlist manager: uses
backend/api/routers/playlists_router.py - FastAPI server → Queue API: routes to
backend/server.py - FastAPI server → Audio API: routes to
backend/server.py - FastAPI server → WebSocket API: routes to
backend/server.py - FastAPI server → Audio library: initializes
backend/server.py - FastAPI server → Download worker: starts
backend/server.py - FastAPI server → Download queue: configures
backend/server.py - FastAPI server → Playback queue: configures
backend/server.py - FastAPI server → Metadata enrichment: starts
backend/server.py - FastAPI server → Audio processing: configures
backend/server.py - FastAPI server → Audio discovery: configures
backend/server.py - FastAPI server → MusicBrainz client: configures
backend/server.py - FastAPI server → Event bus: configures
backend/server.py - FastAPI server → Event handlers: registers
backend/server.py - FastAPI server → WebSocket manager: configures
backend/server.py - Download worker → Audio discovery: downloads
- Download worker → Audio processing: processes audio
- Download worker → Audio library: registers tracks
- Metadata enrichment → MusicBrainz client: enriches from
- Metadata enrichment → Audio library: updates metadata
- Playlist manager → Spotify import: delegates to
backend/core/playlists/manager.py - Audio library → Event bus: publishes events
backend/core/database/audio_database.py - Event handlers → Event bus: subscribes
backend/core/events/handlers.py - Event handlers → WebSocket manager: broadcasts
backend/core/events/handlers.py - Client bootstrap → Search interface: initializes
- Search interface → FastAPI server: searches and queues
- Playback controls → Queue interface: controls playback
frontend/js/features/audio/controller.js - Playlist interface → Playback controls: loads tracks
frontend/js/features/playlist/controller.js - Playlist interface → Queue interface: adds tracks
frontend/js/features/playlist/controller.js - Playlist interface → Client state: updates state
frontend/js/features/playlist/controller.js - Playlist dialogs → Playlist interface: renders playlists
frontend/js/features/popup/controller.js - Playlist dialogs → FastAPI server: deletes playlists
- Live updates → Client state: updates state
frontend/js/events/websocket/handlers.js - Live updates → Web browser: refreshes interface
frontend/js/events/websocket/handlers.js - Desktop controls → FastAPI server: starts or stops
- FastAPI server → Cloudflared tunnel: exposes remotely
- Cloudflared tunnel → Discord webhook: shares link
- Desktop controls → Discord webhook: sets webhook