pyMusic — An Interactive Music Experience

pyMusic is an experimental desktop player that combines local and online music with a chat side panel: each track can drive an LLM persona inspired by lyrics and background context, so you can explore a song through dialogue as well as normal playback (playlist, seek bar, loop, folder load, YouTube Music search, and yt-dlp downloads into a cache folder).

Where every song can speak, feel, and respond — but music playback works without any API keys; you only need keys for the chat / AI features.

---

Requirements

Item	Notes
Python	3.11–3.13 recommended (prebuilt pygame wheels are most reliable; very new Python versions may lack wheels).
FFmpeg	Optional but strongly recommended for YouTube downloads and converting non-MP3 formats for pygame. ffmpeg.org — on Windows: winget install Gyan.FFmpeg or choco install ffmpeg. The app also honors FFMPEG_PATH / PYMUSIC_FFMPEG if ffmpeg is not on PATH.

---

Install from source

1. Get the code

git clone https://github.com/UIU-Developers-Hub/pyMusic.git
cd pyMusic

(Use your own fork or a downloaded ZIP if you prefer; the next steps assume the repository root contains requirements.txt and src/app.py.)

2. Create a virtual environment

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

From the repository root (the folder that contains requirements.txt):

python -m pip install --upgrade pip
pip install -r requirements.txt

This installs the desktop UI (ttkbootstrap), audio (pygame), metadata (mutagen), YouTube Music search (ytmusicapi), downloads (yt-dlp), optional cache watching (watchdog), and the LLM-related packages used by the chat panel.

4. Run the application

Still in the repo root, with the venv activated:

python src/app.py

On Windows you can also double-click or run the same command from cmd after .\.venv\Scripts\activate.bat.

---

Using pyMusic (quick tour)

1. Local MP3s: Click Load Folder and choose a directory of .mp3 files (other formats may work for the list, but MP3 is the most reliable for pygame; FFmpeg helps with conversion for streamed/downloaded tracks).
2. Playback: Select a track, press Play. Use the progress bar to seek; Loop repeats the current song; Prev / Next move in the playlist.
3. Online: Use Search & play to find tracks via YouTube Music; audio is downloaded into the app cache and played like a local file.
4. Playlist persistence: The playlist is saved automatically. Invalid paths are pruned on startup.

---

Chat / LLM (optional)

The right-hand chat needs a configured provider. You can set keys in the UI (Provider, Model, API key, Apply) or via environment variables:

Provider	Environment variables
Groq (default)	GROQ_API_KEY. Optional: GROQ_MODEL (default llama-3.3-70b-versatile), PYMUSIC_LLM_PROVIDER=groq.
Google Gemini	PYMUSIC_LLM_PROVIDER=gemini and GEMINI_API_KEY or GOOGLE_API_KEY. Optional: GEMINI_MODEL (default gemini-2.0-flash).

Keep secrets in the API key field or env vars — do not paste API keys into the Model field.

After you press Play, the app can gather song context (lyrics + snippets when possible) and the model replies in character as the song. If catalog lookup misses your file, naming files like Artist - Title.mp3 helps the fallback.

---

Online search, cache, and FFmpeg

• Cache directory: %APPDATA%\pyMusic\cache\audio on Windows, or ~/.local/share/pyMusic/cache/audio on Linux (and similar XDG layouts elsewhere).
• Playlist file: %APPDATA%\pyMusic\playlist.json on Windows, or ~/.local/share/pyMusic/playlist.json on Linux. Load Folder replaces the in-memory playlist and overwrites the save.
• With watchdog installed (included in requirements.txt), new files that appear in the cache folder can be picked up and added to the playlist.
• Downloads are typically named like Artist - Title [videoId].ext when metadata is available.

Use online search only for content you are allowed to access, and respect copyrights and service terms.

---

Troubleshooting

Issue	What to try
pip fails on pygame	Use Python 3.11–3.13, upgrade pip, or install a pygame wheel matching your OS/arch from pygame releases.
Playback errors (ModPlug / “Couldn’t open”)	Install FFmpeg on PATH so non-MP3 streams can be transcoded to MP3, or use MP3 files only.
Seek bar shows 0:00 / no duration	Install mutagen (pip install mutagen) if you edited deps; duration comes from file metadata.
YouTube / search fails	Update yt-dlp: pip install -U yt-dlp. Check network and region restrictions.

---

Author

Md Fatin Shadab Turja