Chaotic little Pygame music player with album art, a simple visualizer and a dumb cat moshpit in the background.
- left: album cover + visualizer + controls
- right: library (music + "videos audio")
- bottom-right: paste a YouTube link -> download/extract MP3
It's a hobby project. It works, but it's not polished - that's kind of the point.
- Play local audio from
./library/ - Download/extract audio from YouTube using
yt-dlp - Search/filter the library
- Seek by clicking the progress bar
- Volume knob
- Reads metadata + tries to fetch album art
- Reactive visuals + cat moshpit
.
|- main.py # app entrypoint
|- library.py # library indexing/render items
|- library/ # your music (mp3)
|- videos/ # optional: audio extracted from videos
|- *.png # UI images
`- requirements.txt
- Python 3.11+ recommended
- Windows tested (should also run on Linux/macOS if dependencies are available)
Python deps are listed in requirements.txt.
The app will run with just pygame, but some features need extra packages:
mutagen: track length + tag readingrequests: album art fetchingyt-dlp: YouTube downloadsnumpy+soundfile/pydub: better audio-energy visualization (PCM-based)pydubtypically requires ffmpeg installed and available on PATH
Create a venv and install dependencies:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txtpython main.pypython -m unittest discover -vThere’s a build workspace folder so we don’t spam the repo root with build junk:
cd D:\PythonShit\UkasCoUmis
.\.venv\Scripts\Activate.ps1
\# outputs go to build_workspace\out\...
powershell -ExecutionPolicy Bypass -File .\build_workspace\windows\build_windows.ps1Output:
build_workspace\out\dist\...
The in-app YouTube download/extract feature uses yt-dlp and (usually) ffmpeg.
yt-dlpis installed as a Python dependency viarequirements.txtffmpegis expected to be available on PATH (or shipped alongside the exe in your release zip)
If users report that downloads fail, include ffmpeg.exe and ffprobe.exe next to the exe in your release archive.
Android builds are meant to be done with Buildozer (usually via WSL/Linux). If you like pain and want to help: this is a great area to contribute.
High-level:
cd /mnt/d/PythonShit/UkasCoUmis
buildozer android debugIf you manage to get a clean APK build on real devices, please open a PR with notes (and what device/Android version you tested).
- Click a song in the right-side library to play it.
- Space: play/pause
- Left/Right arrows: seek -5s/+5s
- Click the progress bar to jump
- Drag the volume knob to change volume
- In the right half header, click top submenu Download, then go through source -> options -> confirm.
- Download UI shows explicit states (idle/queued/downloading/success/error), progress, and error next steps.
If you want to help out, pick anything from this list:
- Android APK build (Buildozer recipe, packaging assets, ffmpeg situation)
- bugfixes / UI cleanup / performance (library scanning can get heavy)
- issues tagged “good first issue” (if/when we add them)
PRs are welcome. Keep it simple and try not to reformat the whole file unless you have to.
Stuff that actually helps on GitHub:
- Add a short description + topics in the repo settings (e.g.
pygame,music-player,yt-dlp,visualizer). - Cut a Release with a zip (EXE + assets + ffmpeg binaries if needed).
- Keep the two screenshots above up to date (people click when they see UI).
- Post a 10–20s clip/gif (cats going crazy while playing) in the README.
- Share it in places where it fits: r/Python, r/pygame, relevant Discord servers, and show it to classmates.
Install ffmpeg:
- Windows:
winget install Gyan.FFmpeg - Or download from https://ffmpeg.org/ and add to PATH
On Windows it usually works via wheels. If not, try upgrading pip:
python -m pip install --upgrade pipNo license file yet.