PyPlay is a desktop media player I built from scratch with PyQt5 and libVLC. It was my way of digging into application architecture, GUI development and integrating a third-party C library into Python.
Python PyQt5 python-vlc libVLC
The problem
Building a media player means wiring a powerful C/C++ playback engine into a Python GUI framework — and keeping the code maintainable as features grow. I wanted a clean design where the interface and the playback logic never get tangled together.
How it works
I designed PyPlay with a clean three-tier architecture. This separation of concerns was crucial:
| Layer | File | Role |
|---|---|---|
| Entry point | main.py | Lightweight script that initialises the app environment, loads stylesheets and creates the main window. |
| UI layer ("View") | player_ui.py | Defines the whole PyQt5 interface — window, buttons, layouts — to capture user input. Contains zero media playback logic. |
| Backend controller | media_controls.py | The core engine: an abstraction layer over libVLC that loads files, plays, seeks and manages VLC events. |
Because the design is decoupled, the two sides talk cleanly:
- The UI calls simple methods like
play()on the backend. - The backend emits custom Qt signals (like
time_changed) that the UI listens to for updates.
Tech stack
PyQt5 python-vlc (libVLC)
- PyQt5 — a mature, cross-platform toolkit whose "signals and slots" mechanism is a natural fit for event-driven applications.
- python-vlc — direct bindings to the engine behind the official VLC Media Player. It gave PyPlay support for a massive range of audio and video codecs without writing any custom decoding logic.
Challenges & solutions
Integrating a C/C++ backend library with a Python GUI framework raised a few unique problems.
1. The "black screen" rendering issue
Problem: The biggest hurdle was rendering video onto the PyQt widget. At first the app played audio over a black screen. libVLC needs a platform-specific window handle — an HWND on Windows or an XID on Linux — to know where to draw frames, and getting that handle at the right time was tricky.
Solution:
- Calling
winId()during UI initialisation was too early — the native window didn't exist yet. - I overrode PyQt's
showEventand usedQTimer.singleShotto delay the call until the widget was fully rendered. - I passed the ID safely to the backend through a custom Qt signal.
- To fix hardware-acceleration conflicts, I tweaked VLC's video output modules (
--vout=glor--no-avcodec-hw) to get a compatible rendering path.
showEvent, then hand over the handle.2. Unreliable event syncing
Problem: I first relied only on VLC's built-in events (like MediaPlayerTimeChanged) to update the UI, but some — specifically playback rate changes — weren't always emitted.
Solution: I added a QTimer in the MediaController. It acts as the primary poller for states that lack dedicated events, and as a safety-net fallback: if VLC's events stop firing, the seek bar and other UI still don't get stuck.
3. Application hangs on shutdown
Problem: Closing the app would occasionally hang or throw decoding errors, because VLC's background threads were still active when the Python main thread tried to exit.
Solution: I built an explicit shutdown sequence in a release_resources method:
- Stop — call
stop()on the player. - Wait — loop briefly with
time.sleep()until the VLC thread reports a "Stopped" state. - Release — only then free the media player and VLC instance resources, for a clean exit every time.
What's next
- Streaming support — a dialog to open network streams (like YouTube or radio), with proper buffering UI overlays.
- Real-time video adjustments — sliders for live brightness, contrast and saturation using libVLC's filtering functions.
- UI code refactoring — grouping UI update logic by playback state to keep the codebase clean as features grow.
Case Study
Architecture
3 tiers
Entry point, UI layer, backend controller
Problem
Building a desktop media player means integrating a powerful C/C++ playback engine (libVLC) with a Python GUI framework (PyQt5). Early versions played audio over a black screen, missed some VLC events, and occasionally hung on shutdown because VLC's background threads were still running.
Approach
- Three-tier architecture:
main.pyentry point,player_ui.pyPyQt5 view with zero playback logic,media_controls.pybackend controller over libVLC - UI calls simple backend methods like
play(); the backend emits custom Qt signals such astime_changed - Fixed the black screen by overriding
showEventand usingQTimer.singleShotto fetch the native window handle (HWND/XID) after render, passing it via a custom Qt signal, and tweaking VLC output (--vout=glor--no-avcodec-hw) - Added a
QTimerpoller inMediaControllerfor states without dedicated events and as a fallback when VLC events stop firing - Explicit
release_resourcesshutdown:stop(), wait until VLC reports "Stopped", then release the player and VLC instance
- Three-tier architecture:
Results
- Video renders reliably onto the PyQt widget instead of a black screen
- The seek bar and UI no longer get stuck when VLC events stop firing
- Clean application exit every time
- Support for a massive range of audio and video codecs via libVLC, with no custom decoding logic
