Inspiration
I have a huge, carefully assembled local phono library - gigabytes of FLACs, rare B-sides and old demos that just can't be found on streaming services. It's all on my main computer, but I'm constantly moving between my desk, my laptop bed, and the kitchen. I'm sick of using a clunky remote desktop or slow file synchronization just to listen to my own music. Plus, I've long been looking for a practical "weekend" project to finally get a proper handle on the Flask framework in Python. It seemed like a classic "scratch your own itch" kind of problem - creating something I'd actually use every day, rather than another useless "to-do list".
What it does
Audio Jukebox is an extremely lightweight, almost dependency-free web server. You run a single Python script. It immediately scans the folder you specify (and all its subfolders) for audio files (.mp3, .flac, .wav, etc.).
It then launches a web page on your local host. This page is just a minimalistic, fast-loading list of all your music. You click on a track, and it instantly starts playing in the HTML5 player at the top of the page. No databases, no accounts, no album cover scraping. Just a raw, functional index of your files that plays them.
How we built it
The basis of everything is Python 3 and Flask. Basically, there are only two main routes (routes) in the application:
/ (Home page): This route scans the file system using the built-in os.walk() and passes the list of found files to the HTML template.
/play/path:filepath (Streaming): This route is responsible for the music streaming itself. It securely opens the requested audio file on the server and gives it to the browser as a stream, so that playback starts immediately rather than after the file has been fully downloaded.
The frontend is intentionally made primitive: it's a single HTML template embedded directly into the Python script as a string, with a bit of CSS to create a clean "dark mode" interface. All the "magic" is a few lines of pure JavaScript (vanilla JS). It intercepts clicks on links in the playlist, overrides the standard link click, takes the URL of the file and updates the src at the single tag on the page, then runs play(). No React or Vue, just the basics.
Challenges we ran into
The biggest headache, oddly enough, was file paths and URL encoding. Files with names like My Chemical Romance - Song (Live @ Demo).mp3 with spaces, brackets and the @ symbol turned the URL into a mess. I had to work hard to learn how to properly encode paths on the backend when generating the list and decode them correctly in the Flask route.
The second problem was streaming large files (FLAC). At first, the browser tried to download a 100 MB FLAC file in its entirety before starting playback, which killed the whole idea. I had to figure out how to use Response in Flask with a generator to give the file in pieces (chunks), and how to set the MIME types (Content-Type) correctly so the browser would realize it was an audio stream and not a download file.
Accomplishments that we're proud of
What I'm most proud of is that it just works. And it works fast. The server starts up instantly, the web page loads in a millisecond. There's no configuration whatsoever. I can just drop that one .py file into any folder, run it, and access all my music from my phone while on the same Wi-Fi network.
I'm also glad to have figured out from scratch how audio streaming over HTTP actually works. Understanding how to manage byte streams and headers was a big win. It's not just "another CRUD app", it's a utility with real utility.
What we learned
This project reinforced in me that the best way to learn a new technology is to create a real tool that solves your personal problem (especially relevant with ADHD, when you need a constant feeding of interest).
I learned that Flask is incredibly powerful for creating small, self-contained utilities like this, not just big APIs. And I finally realized that for 90% of simple frontend tasks, you don't need any framework - pure JavaScript does just fine if you know what you're doing.
What's next for Audio Jukebox
The current version is just a giant list of files, which is not very convenient.
Search: Absolute priority. When you have 10,000 tracks, scrolling is not an option. We need to add a simple client-side JavaScript search that filters the list in real time.
Reading metadata: Right now I can only see file paths. I want to use a library like mutagen to read ID3 tags from files. This would allow me to group tracks by Artist and Album, which would dramatically improve the interface.
Basic Play Queue: Add "Play Next" and "Add to Queue" buttons. This will turn the project from a simple "player" into a true "Jukebox".
Log in or sign up for Devpost to join the conversation.