A minimal, Python-Qt music player that opens .m3u / .m3u8 / .fplite playlists and plays them gap-lessly through VLC, and remembers playback history and position (per playlist).

• Folder scan – add all playlists beneath a chosen directory
• Gap-less playback – powered by libVLC
• Per-playlist history – resumes where you left off
• Auto-resume – optional, continue playing on startup
• Embedded cover-art – JPEG / PNG extracted automatically
• Timeline seek – click, drag or mouse-wheel (± 5 s, Ctrl ± 1 s)
• Light / Dark mode – follows your OS theme
• Play/Pause hotkey – responds to the global media key (requires keyboard on Windows)
• Volume normalization – optional filter for consistent loudness
• ✓ Volume boost (compressor) – amplifies quiet tracks

git clone https://github.com/your-name/playlist-player.git
cd playlist-player
python main.py          # first run sets up a local .venv
# alternatively install dependencies manually:
pip install -r requirements.txt
python main.py

or

Download as ZIP, make sure python and VLC are installed and double-click main.py

On first launch the script creates .venv/ beside itself and installs:

• PySide6 – Qt GUI bindings
• python-vlc – VLC Python wrapper
• mutagen – tag & cover-art reader
• Pillow – image helpers
• keyboard – global hotkey listener (required on Windows)
  • On Linux, capturing the media key may require running the app as root.
  • Global hotkeys are not fully supported on macOS.

You do not need to install these manually.

1. Click Scan and choose a folder → playlists appear on the left (or Drag and drop playlists into window).

2. Double-click a playlist to start playback.

3. Prev/Next (top-right) switch tracks.

4. Drag / wheel the timeline to seek.

5. Close the app – play positions & custom names are saved automatically.

playlist-player/
├─ main.py          # GUI + bootstrap
├─ player.py        # gap-less VLC wrapper
├─ scanner.py       # playlist discovery
├─ history.py       # per-playlist progress
├─ storage.py       # saved playlist list
└─ .venv/           # local virtual-env (auto)

Run the provided build_windows.bat script to create a standalone executable using PyInstaller. The script builds inside a temporary virtual environment so it doesn't touch your global Python install. Dependencies from requirements.txt (including mutagen) are installed into that venv before PyInstaller runs. Ensure Python 3 is available in your PATH – the script prefers the py launcher but falls back to python if the launcher is not installed:

build_windows.bat

The resulting dist/PlaylistPlayer.exe can be distributed without requiring Python on the target system.

If you see an error like

ModuleNotFoundError: No module named 'keyboard'

the dependencies were not installed. The first run requires an internet connection so pip can download packages. Either run python main.py once so the script can bootstrap a local .venv/ (with network access) or install them manually using:

pip install -r requirements.txt

MIT – free to use, modify, and distribute.