Published

Building PyPlay: A Custom Media Player with Python, PyQt5, and libVLC

March 2, 2026
https://aminilay.github.io/PyPlay-Official-Website
Building PyPlay: A Custom Media Player with Python, PyQt5, and libVLC
Position / Role

Lead Architect

Deployment

Published

Timeline

Mar 2026

Primary Artifact

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:

LayerFileRole
Entry pointmain.pyLightweight script that initialises the app environment, loads stylesheets and creates the main window.
UI layer ("View")player_ui.pyDefines the whole PyQt5 interface — window, buttons, layouts — to capture user input. Contains zero media playback logic.
Backend controllermedia_controls.pyThe 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 showEvent and used QTimer.singleShot to 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=gl or --no-avcodec-hw) to get a compatible rendering path.
LessonA native C library can only draw into a window that actually exists. Wait for 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:

  1. Stop — call stop() on the player.
  2. Wait — loop briefly with time.sleep() until the VLC thread reports a "Stopped" state.
  3. 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

  1. 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.

  2. Approach

    • Three-tier architecture: main.py entry point, player_ui.py PyQt5 view with zero playback logic, media_controls.py backend controller over libVLC
    • UI calls simple backend methods like play(); the backend emits custom Qt signals such as time_changed
    • Fixed the black screen by overriding showEvent and using QTimer.singleShot to fetch the native window handle (HWND/XID) after render, passing it via a custom Qt signal, and tweaking VLC output (--vout=gl or --no-avcodec-hw)
    • Added a QTimer poller in MediaController for states without dedicated events and as a fallback when VLC events stop firing
    • Explicit release_resources shutdown: stop(), wait until VLC reports "Stopped", then release the player and VLC instance
  3. 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