Skip to main content

Python bindings for libwinmedia, a tiny yet powerful media playback library for Windows and Linux.

Project description


Python bindings for libwinmedia, a tiny yet powerful media playback library for Windows and Linux.

This library's goal is to make a beginner-friendly, easy-to-use API with many advanced features.


This library has NO DEPENDENCIES on Windows, except for C++ library.

Linux on the other hand requires some packages to be installed:

  • pygobject - This allows us to interact with GTK. This will be automatically installed when you install our library.
  • libgirepository1.0-dev - This dependency allows us to interact with GTK through PyGObject
  • python3-dev - This is required to build PyGObject
  • libwebkit2gtk-4.0-dev - This is required to summon the player in WebKit.

You can install this dependencies using this command on Debian/Ubuntu based operating systems: sudo apt install libgirepository1.0-dev python3-dev libwebkit2gtk-4.0-dev

After you installed this, you may proceed installing libwinmedia (see next step)


You can install latest stable version from PyPI using this command:

pip install libwinmedia

You can install the latest version from Git using this command:

pip install git+

This source might be more stable in some cases, but can be less stable than latest PyPI release


You need to download a libwinmedia.dll for Windows or for Linux from the releases page and set it up properly. You can either put it somewhere in the %PATH% or set the LIBWINMEDIA_PATH environment variable.

On Linux, I recommend using LIBWINMEDIA_PATH environment variable, since there were some troubles finding library in Python ctypes library.

Another way to deal with it is to ship libwinmedia shared library with your script and put the directory where your script is located in %PATH% before importing the library:

import os
os.environ["PATH"] = os.path.dirname(__file__) + os.pathsep + os.environ["PATH"]

If libwinmedia.dll (or is located elsewhere, you can add that path to os.environ["PATH"].

Linux limitations

While Linux support is amazing, it comes with some limitations.

For example, you can't use NativeControls class, tags_from_music & tags_from_video functions in Player class.

Otherwise, everything should work!

Simple start

import libwinmedia

player = libwinmedia.Player()

media = libwinmedia.Media("")

When you don't need any of the created instances, you can dispose them to free up system resources:



The program containing playing media must not exit before player is done playing.

To do this in examples we recommend adding this at the end:

while True:


You can open player ( with Playlist instance or with Media instance.

If you open Player with Media, then it will play only one song, but if you open it with Playlist, then it will create a playlist and play it like that...

Simple example:

import libwinmedia

player = libwinmedia.Player()
media1 = libwinmedia.Media("media1.ogg")
media2 = libwinmedia.Media("media2.ogg")
playlist = libwinmedia.Playlist(media1, media2)


You have access to these parameters of the Player instance:

  • looping
  • autoplay
  • audio_balance
  • rate
  • volume
  • position


This library provides callbacks. You need to decorate your functions as follows:

def callback(volume: float):
    print("Volume callback: " + str(volume * 100))
Callback decorator Type, returned from function
volume_callback float (between 0 and 1, thus you might have to multiply it by 100)
rate_callback float (between 0 and 1, thus you might have to multiply it by 100)
completed_callback bool
position_callback int (in milliseconds)
duration_callback int (in milliseconds)


  • Implement NativeControls
  • Implement Video support


Thanks to @alexmercerind. He created one of best libraries for playback, that work with Linux and Windows.

He didn't want to put any restrictions on it, so he used a MIT License. I also don't want to put any restrictions on Python binding, so I kept MIT License.

You can find license in LICENSE file

Support this project

Show some love to this project and consider starring the repository & check out a whole libwinmedia suite.

While you are at it, you can check also Harmonoid project. If you like this library, then share it.

Special thanks to @alexmercerind for C++ library. Without this library, this project wouldn't exist.

Huge thanks also to @raitonoberu for his massive contributions to Python bindings. He has brought current easy-to-use design to this library.


This repository includes an example file, called

In it, there is used almost every function this library provides.

Every function is documented (in code or in this file).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for libwinmedia, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size libwinmedia-1.0.1.tar.gz (11.1 kB) File type Source Python version None Upload date Hashes View
Filename, size libwinmedia-1.0.1-py3-none-any.whl (10.5 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page