RadioTEDU Jukebox is a comprehensive school radio and interactive music selection system designed for campus environments. It empowers students to listen to live radio, access podcasts, and democratically choose music in common areas (like the cafeteria/restaurant) using a QR-code-based voting system.
This project is a "Superapp" comprising multiple modules:
The central hub for students & listeners.
- Live Radio: Listen to the school radio stream with background playback and lock screen controls.
- Podcasts: Browse and listen to school podcasts (fetched from WordPress/RSS).
- Juicebox Controller: Scan a QR code in the cafeteria to join the active "Session".
- Voting System: Add songs to the queue, Upvote your favorites, and Downvote tracks you want to skip.
- Ranking: Earn points for good song selections and climb the user leaderboard.
Running in Windows browser kiosk mode or on a cafeteria display.
- Now Playing: Displays the current song and upcoming queue.
- QR Code: Dynamic QR code for students to scan and join.
- Smart Queue: Prioritizes songs based on votes, user rank, and wait time. abuse prevention included.
juke-local plays music from a separate school music PC rather than Spotify.
Configure media-agent/.env with that PC's LOCAL_MUSIC_ROOT; configure the
web backend with the corresponding media-agent secrets and
PUBLIC_BASE_PATH=/juke-local. The controller's Tara action imports the
music-PC catalogue. The kiosk, QR-phone clients, and controller use only
https://radiotedu.com/juke-local; the web backend proxies the complete-song
stream from the music PC without disclosing its IP or file paths.
Cover art is scanned with the local catalogue. Downloader filenames keep the
YouTube video ID in square brackets, for example Artist - Song [videoid].mp3;
the media agent converts that ID into an i.ytimg.com thumbnail URL and the
backend stores it in songs.cover_url. New playlist downloads should run with
yt-dlp --embed-thumbnail --write-thumbnail --convert-thumbnails jpg so MP3
files also carry embedded artwork.
Do not publish or share the local music directory. The music PC accepts only HMAC-signed, private-network requests from the web server; the public web server is the sole internet-facing component.
- Web Dashboard: For managing the system, song catalog, and monitoring active sessions.
The project is structured into several key components:
| Component | Path | Technology Stack | Description |
|---|---|---|---|
| Backend | rtjukebox-main/backend |
Node.js, TypeScript, Express, PostgreSQL | The core API handling auth, voting logic, queue management, and radio streams. |
| Mobile App | rtjukebox-main/mobile |
React Native | Cross-platform mobile application for end-users. |
| Kiosk Web | rtjukebox-main/kiosk-web |
HTML/JS (Legacy/Simple) | Simple web interface for the kiosk display (likely superseded by the mobile app's kiosk mode). |
| Web Controller | rtjukebox-main/jukebox-web-controller |
React, Vite | Web-based admin or control dashboard. |
📦 rtjukebox-main
┣ 📂 backend # Node.js API Server
┃ ┣ 📂 src
┃ ┃ ┣ 📂 routes # API Endpoints (auth, jukebox, radio)
┃ ┃ ┗ 📂 services # Business logic (Queue algorithm, Push notifications)
┃ ┗ 📜 package.json
┣ 📂 mobile # React Native User App
┃ ┣ 📂 src
┃ ┃ ┗ 📂 screens # UI Screens (Jukebox, Radio, Profile)
┃ ┗ 📜 package.json
┣ 📂 kiosk-web # Simple Kiosk Display (Web)
┣ 📂 jukebox-web-controller # Admin/Controller Dashboard
┗ 📜 Kiosk App Setup & Build.md # Detailed setup documentation
This project is open to everyone! You are free to use, modify, and deploy this system for your own school or community.
Requirement:
You must include a visible reference to "RadioTEDU" in your deployment. This project was originally developed for RadioTEDU, and we appreciate the credit.
For setup and deployment instructions, please refer to the internal documentation or contact the maintainers.
- Fork the repository.
- Create a feature branch.
- Commit your changes.
- Push to the branch.
- Open a Pull Request.
[License Information Here]
Generated based on codebase analysis of rtjukebox-main.