How swoogan/jbox works
Project type and purpose
• JBox is a full-stack web application: a remote MP3 jukebox server.
• The Python backend (CherryPy) provides HTTP and WebSocket APIs; the Angular/HTML/JS frontend (“site” directory) is the client UI.
File structure
• Top-level:
• jbox/ – Python application package
• jbox/core – core domain logic (configuration, JSON file I/O, song database, volume control)
• jbox/player – playback abstraction (song list, player wrapper)
• jbox/services – HTTP/WebSocket service layer (applications, controls, directories, mp3scan, nowplaying, songs, state, volume)
• jbox.py – CherryPy server entry point
• websocket.py & volume_thread.py – background threads for WS and volume polling
• site/ – static frontend: HTML, CSS, JS, Angular components, Gulp build, Bower dependencies
• songs.json – local song metadata store
• jbox.conf & requirements.txt – configuration & Python dependencies
• Recognize MVC-style layering:
• Model/Core (jbox/core)
• Controller/Services (jbox/services + jbox.py entry)
• View/Frontend (site/)
Extract insights from README
• Uses CherryPy, ws4py (WebSocket), Mutagen (MP3 metadata), vlc module (playback), amixer (Linux mixer).
• User flow: configure app locations → add directories → scan MP3 files → control playback via web UI.
Main components & interactions
a. Components:
1. Web Browser (Angular SPA)
2. CherryPy HTTP API
3. CherryPy WebSocket endpoint
4. Service Layer (jbox/services modules)
5. Core Engine (jbox/core modules)
6. Player Layer (jbox/player + VLC Python bindings)
7. songs.json (song metadata store)
8. Local filesystem (MP3 directories)
9. System mixer (amixer)
10. Volume thread
b. Data flows & interactions:
• Browser ⇄ HTTP API: REST calls to /applications, /directories, /songs, /state
• Browser ⇄ WebSocket: real-time updates (now playing, volume changes)
• HTTP API → Service Layer → Core Engine → songs.json / filesystem / VLC
• Core Engine triggers Player Layer for play/pause/skip via VLC
• Volume Thread polls ALSA mixer (amixer) and pushes updates via WebSocket
c. Architectural patterns:
• Layered (Controller → Service → Core → Infrastructure)
• Event-driven (WebSocket push for real-time)
• Modular services (one service module per resource)
d. Key technologies:
• Python 3 + CherryPy + ws4py + Mutagen + python-vlc
• AngularJS + Bower + Gulp on frontend
• JSON file store (songs.json)