FluxPlayer Lite

v2 — Lightweight local music player for Windows

Everything v1.5 had, plus YouTube, lyrics, history, equalizer, and 6 themes.

---

What is this?

FluxPlayer Lite is a local-first music player for Windows. No accounts. No cloud. No ads. Works fully offline for playback. Optional internet features (YouTube download, lyrics) work when connected.

Built with Python, PySide6, and VLC. Runs on any Windows machine.

---

What's new since v1.5

• YouTube search and MP3 download — no API key needed
• Synced lyrics from lrclib.net — no API key needed
• Recently played history with timestamps
• 10-band equalizer with 10 presets
• Sleep timer
• Playback speed control 0.5×–2.0×
• 6 visual themes switchable at runtime
• Volume up to 150% with soft-knee compressor to prevent clipping
• ReplayGain normalisation — consistent loudness across all tracks
• Album art extracted from embedded tags
• Animated waveform when no art is available
• Glow progress bar with hover preview
• Queue panel with drag reorder and M3U save/load
• Mini player — always-on-top, never raises main window
• Drag and drop audio files onto the window
• Media key support (keyboard Play/Pause/Next/Prev buttons)
• Fully modular codebase — frontend and backend separated

---

Features

Playback

• MP3, FLAC, OGG, WAV, M4A, AAC, Opus, WMA
• Play, Pause, Stop, Previous, Next
• Shuffle and Repeat One
• Playback speed 0.5×–2.0×
• Volume 0–150% (amber tint above 100% warns of amplification)
• ReplayGain per-track loudness normalisation at −14 LUFS
• Media key support

Now Playing

• Album art from embedded tags (MP3, FLAC, M4A, OGG)
• Animated waveform with smooth bar animation when no art present
• Art-tinted card background using dominant colour from art
• Glow progress bar — gradient fill, playhead dot, hover seek preview
• Track counter (e.g. 3 / 47)

Library

• Auto-scan ~/Music and ~/Downloads
• Load folder or add individual files
• Drag and drop files onto the window
• Playlist with drag-to-reorder
• Tags and durations loaded in background thread

Queue

• Full queue panel
• Drag reorder, move up/down, remove individual tracks
• Save playlist as M3U
• Load playlist from M3U

Search and Download

• Search YouTube — no API key required
• Download result as MP3 at 192 kbps via yt-dlp
• Progress bar during download
• Configurable download folder

Lyrics

• Synced lyrics fetched from lrclib.net
• Active line highlighted and auto-scrolled during playback
• Distance-based font sizing — active line large, adjacent dimmed
• Plain text fallback when sync data unavailable
• Manual fetch button to retry

History

• Every played track logged with timestamp
• Shows relative time (e.g. "5m ago", "2h ago")
• Double-click any entry to replay
• Clear history button

Extras

• 10-band VLC equalizer — 10 presets (Flat, Bass Boost, Treble Boost, Rock, Pop, Jazz, Classical, Vocal, Night Mode, Loudness)
• Sleep timer — auto-stop after 1–240 minutes
• Playback speed dial with preset buttons
• 6 themes — Midnight, Pure Black, Arctic, Sunset, Forest, Discord
• Download folder setting

Mini Player

• Always-on-top floating overlay
• Draggable, never raises the main window
• Prev, Play/Pause, Stop, Next controls

---

Tabs

Tab	Contents
Player	Playback, playlist, transport controls
Lyrics	Synced lyrics with live highlighting
Search	YouTube search and MP3 download
Queue	Drag reorder, M3U save/load
History	Recently played with timestamps
Extras	EQ, sleep timer, speed, themes, settings

---

Requirements

Dependency	Version	Purpose
Python	3.11+	Runtime
PySide6	6.6.0+	UI
python-vlc	3.0.20301+	Audio playback
mutagen	1.47+	Tag reading
yt-dlp	2024.1.1+	YouTube download
VLC media player	3.0+	Required

pip install PySide6 mutagen python-vlc yt-dlp

---

Running

cd FluxPlayerLite_v2
python main.py

---

Building

pip install nuitka
python build.py

Output: dist/main.dist/. Place vlc/ folder and icon.png inside before distributing.

Installer: open installer.iss in Inno Setup → Ctrl+F9.

---

Keyboard shortcuts

Key	Action
Space	Play / Pause
Right	Next track
Left	Previous / Restart
Up	Volume +5%
Down	Volume -5%
Double-click	Play selected track
Media keys	System Play/Pause/Next/Prev

---

Audio quality

• SoX resampler when supported by the installed VLC build
• WASAPI output on Windows for bit-perfect playback
• Soft-knee compressor per track — prevents clipping at boosted volumes
• ReplayGain normalisation — same loudness target as Spotify and Apple Music
• VLC flags probed at startup — any unsupported flag is silently dropped; app always starts

---

File structure

FluxPlayerLite_v2/
├── main.py
├── build.py
├── installer.iss
├── requirements.txt
├── core/
│   ├── engine.py          VLC backend
│   ├── metadata.py        Tag reader (threaded)
│   ├── downloader.py      yt-dlp wrapper
│   ├── lyrics.py          lrclib.net + LRC parser
│   ├── history.py         Play log
│   ├── audio_analysis.py  ReplayGain + album art
│   ├── state.py           JSON persistence
│   ├── constants.py       Themes + app constants
│   └── utils.py           Helpers
└── ui/
    ├── main_window.py
    ├── styles.py
    ├── icons.py           QPainter icon set
    ├── now_playing_card.py
    ├── mini_player.py
    ├── widgets/
    │   ├── __init__.py
    │   └── speed_control.py
    └── panels/
        ├── player_panel.py
        ├── search_panel.py
        ├── queue_panel.py
        ├── lyrics_panel.py
        ├── history_panel.py
        └── extras_panel.py

---

Known limitations

• No tag editing (added in v2.5)
• No favourites system (added in v2.5)
• No statistics panel (added in v2.5)
• No library search filter (added in v2.5)
• Lyrics require internet; no offline cache

---

License

MIT License. See LICENSE for details.