• Stars
    star
    524
  • Rank 83,946 (Top 2 %)
  • Language
    Python
  • License
    Other
  • Created about 10 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python interface to the awesome mpv media player

python-mpv

python-mpv is a ctypes-based python interface to the mpv media player. It gives you more or less full control of all features of the player, just as the lua interface does.

Installation

pip install mpv

...though you can also realistically just copy mpv.py into your project as it's all nicely contained in one file.

Requirements

libmpv

libmpv.so either locally (in your current working directory) or somewhere in your system library search path. This module is somewhat lenient as far as libmpv versions are concerned but since libmpv is changing quite frequently you'll only get all the newest features when using an up-to-date version of this module. The unit tests for this module do some basic automatic version compatibility checks. If you discover anything missing here, please open an issue or submit a pull request on github.

On Windows you can place libmpv anywhere in your %PATH% (e.g. next to python.exe) or next to this module's mpv.py. Before falling back to looking in the mpv module's directory, python-mpv uses the DLL search order built into ctypes, which is different to the one Windows uses internally. Consult this stackoverflow post for details.

Python >= 3.7 (officially)

The main branch officially only supports recent python releases (3.5 onwards), but there is the somewhat outdated but functional py2compat branch providing Python 2 compatibility.

Supported Platforms

Linux, Windows and OSX all seem to work mostly fine. For some notes on the installation on Windows see this comment. Shared library handling is quite bad on windows, so expect some pain there. On OSX there seems to be some bug int the event logic. See issue 36 and issue 61 for details. Creating a pyQT window and having mpv draw into it seems to be a workaround (about 10loc), but in case you want this fixed please weigh in on the issue tracker since right now there is not many OSX users.

Usage

import mpv
player = mpv.MPV(ytdl=True)
player.play('https://youtu.be/DOmdB7D-pUU')
player.wait_for_playback()

python-mpv mostly exposes mpv's built-in API to python, adding only some porcelain on top. Most "input commands" are mapped to methods of the MPV class. Check out these methods and their docstrings in the source for things you can do. Additional controls and status information are exposed through MPV properties. These can be accessed like player.metadata, player.fullscreen and player.loop_playlist.

Threading

The mpv module starts one thread for event handling, since MPV sends events that must be processed quickly. The event queue has a fixed maxmimum size and some operations can cause a large number of events to be sent.

If you want to handle threading yourself, you can pass start_event_thread=False to the MPV constructor and manually call the MPV object's _loop function. If you have some strong need to not use threads and use some external event loop (such as asyncio) instead you can do that, too with some work. The API of the backend C libmpv has a function for producing a sort of event file descriptor for a handle. You can use that to produce a file descriptor that can be passed to an event loop to tell it to wake up the python-mpv event handler on every incoming event.

All API functions are thread-safe. If one is not, please file an issue on github.

Advanced Usage

Logging, Properties, Python Key Bindings, Screenshots and youtube-dl

#!/usr/bin/env python3
import mpv

def my_log(loglevel, component, message):
    print('[{}] {}: {}'.format(loglevel, component, message))

player = mpv.MPV(log_handler=my_log, ytdl=True, input_default_bindings=True, input_vo_keyboard=True)

# Property access, these can be changed at runtime
@player.property_observer('time-pos')
def time_observer(_name, value):
    # Here, _value is either None if nothing is playing or a float containing
    # fractional seconds since the beginning of the file.
    print('Now playing at {:.2f}s'.format(value))

player.fullscreen = True
player.loop_playlist = 'inf'
# Option access, in general these require the core to reinitialize
player['vo'] = 'gpu'

@player.on_key_press('q')
def my_q_binding():
    print('THERE IS NO ESCAPE')

@player.on_key_press('s')
def my_s_binding():
    pillow_img = player.screenshot_raw()
    pillow_img.save('screenshot.png')

player.play('https://youtu.be/DLzxrzFCyOs')
player.wait_for_playback()

del player

Skipping silence using libav filters

The following code uses the libav silencedetect filter to skip silence at the beginning of a file. It works by loading the filter, then parsing its output from mpv's log. Thanks to Sean DeNigris on github (#202) for the original code!

#!/usr/bin/env python3
import sys
import mpv

p = mpv.MPV()
p.play(sys.argv[1])

def skip_silence():
    p.set_loglevel('debug')
    p.af = 'lavfi=[silencedetect=n=-20dB:d=1]'
    p.speed = 100
    def check(evt):
        toks = evt['event']['text'].split()
        if 'silence_end:' in toks:
            return float(toks[2])
    p.time_pos = p.wait_for_event('log_message', cond=check)
    p.speed = 1
    p.af = ''

skip_silence()
p.wait_for_playback()

Video overlays

#!/usr/bin/env python3
import time
from PIL import Image, ImageDraw, ImageFont
import mpv

player = mpv.MPV()

player.loop = True
player.play('test.webm')
player.wait_until_playing()

font = ImageFont.truetype('DejaVuSans.ttf', 40)

while not player.core_idle:

    time.sleep(0.5)
    overlay = player.create_image_overlay()

    for pos in range(0, 500, 5):
        ts = player.time_pos
        if ts is None:
            break

        img = Image.new('RGBA', (400, 150),  (255, 255, 255, 0))
        d = ImageDraw.Draw(img)
        d.text((10, 10), 'Hello World', font=font, fill=(0, 255, 255, 128))
        d.text((10, 60), f't={ts:.3f}', font=font, fill=(255, 0, 255, 255))

        overlay.update(img, pos=(2*pos, pos))
        time.sleep(0.05)

    overlay.remove()

Playlist handling

#!/usr/bin/env python3
import mpv

player = mpv.MPV(ytdl=True, input_default_bindings=True, input_vo_keyboard=True)

player.playlist_append('https://youtu.be/PHIGke6Yzh8')
player.playlist_append('https://youtu.be/Ji9qSuQapFY')
player.playlist_append('https://youtu.be/6f78_Tf4Tdk')

player.playlist_pos = 0

while True:
    # To modify the playlist, use player.playlist_{append,clear,move,remove}. player.playlist is read-only
    print(player.playlist)
    player.wait_for_playback()

Directly feeding mpv data from python

#!/usr/bin/env python3
import mpv

player = mpv.MPV()
@player.python_stream('foo')
def reader():
    with open('test.webm', 'rb') as f:
        while True:
            yield f.read(1024*1024)

player.play('python://foo')
player.wait_for_playback()

Using external subtitles

The easiest way to load custom subtitles from a file is to pass the --sub-file option to the loadfile call:

#!/usr/bin/env python3
import mpv

player = mpv.MPV()
player.loadfile('test.webm', sub_file='test.srt')
player.wait_for_playback()

Note that you can also pass many other options to loadfile. See the mpv docs for details.

If you want to add subtitle files or streams at runtime, you can use the sub-add command. sub-add can only be called once the player is done loading the file and starts playing. An easy way to wait for this is to wait for the core-idle property.

#!/usr/bin/env python3
import mpv

player = mpv.MPV()
player.play('test.webm')
player.wait_until_playing()
player.sub_add('test.srt')
player.wait_for_playback()

Using MPV's built-in GUI

python-mpv is using mpv via libmpv. libmpv is meant for embedding into other applications and by default disables most GUI features such as the OSD or keyboard input. To enable the built-in GUI, use the following options when initializing the MPV instance. See Issue 102 for more details

# Enable the on-screen controller and keyboard shortcuts
player = mpv.MPV(input_default_bindings=True, input_vo_keyboard=True, osc=True)

# Alternative version using the old "floating box" style on-screen controller
player = mpv.MPV(player_operation_mode='pseudo-gui',
                 script_opts='osc-layout=box,osc-seekbarstyle=bar,osc-deadzonesize=0,osc-minmousemove=3',
                 input_default_bindings=True,
                 input_vo_keyboard=True,
                 osc=True)

PyQT embedding

#!/usr/bin/env python3
import mpv
import sys

from PyQt5.QtWidgets import *
from PyQt5.QtCore import *

class Test(QMainWindow):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.container = QWidget(self)
        self.setCentralWidget(self.container)
        self.container.setAttribute(Qt.WA_DontCreateNativeAncestors)
        self.container.setAttribute(Qt.WA_NativeWindow)
        player = mpv.MPV(wid=str(int(self.container.winId())),
                vo='x11', # You may not need this
                log_handler=print,
                loglevel='debug')
        player.play('test.webm')

app = QApplication(sys.argv)

# This is necessary since PyQT stomps over the locale settings needed by libmpv.
# This needs to happen after importing PyQT before creating the first mpv.MPV instance.
import locale
locale.setlocale(locale.LC_NUMERIC, 'C')
win = Test()
win.show()
sys.exit(app.exec_())

PyGObject embedding

#!/usr/bin/env python3
import gi

import mpv

gi.require_version('Gtk', '3.0')
from gi.repository import Gtk


class MainClass(Gtk.Window):

    def __init__(self):
        super(MainClass, self).__init__()
        self.set_default_size(600, 400)
        self.connect("destroy", self.on_destroy)

        widget = Gtk.Frame()
        self.add(widget)
        self.show_all()

        # Must be created >after< the widget is shown, else property 'window' will be None
        self.mpv = mpv.MPV(wid=str(widget.get_property("window").get_xid()))
        self.mpv.play("test.webm")

    def on_destroy(self, widget, data=None):
        self.mpv.terminate()
        Gtk.main_quit()


if __name__ == '__main__':
    # This is necessary since like Qt, Gtk stomps over the locale settings needed by libmpv.
    # Like with Qt, this needs to happen after importing Gtk but before creating the first mpv.MPV instance.
    import locale
    locale.setlocale(locale.LC_NUMERIC, 'C')

    application = MainClass()
    Gtk.main()

Using OpenGL from PyGObject

Just like it is possible to render into a GTK widget through X11 windows, it also is possible to render into a GTK widget using OpenGL through this python API.

Using OpenGL from PyQt5/QML

Robozman has mangaed to make mpv render into a PyQt5/QML widget using OpenGL through this python API.

Using mpv inside imgui inside OpenGL via GLFW

dfaker has written a demo (link) that uses mpv to render video into an imgui UI running on an OpenGL context inside GLFW. Check out their demo to see how to integrate with imgui/OpenGL and how to access properties and manage the lifecycle of an MPV instance.

Running tests

Use pytest to run tests.

Coding Conventions

The general aim is PEP 8, with liberal application of the "consistency" section. 120 cells line width. Four spaces. No tabs. Probably don't bother making pure-formatting PRs except if you think it really helps readability or it really irks you if you don't.

License

python-mpv inherits the underlying libmpv's license, which can be either GPLv2 or later (default) or LGPLv2.1 or later. For details, see the mpv copyright page.

More Repositories

1

lolcat

High-performance implementation of https://github.com/busyloop/lolcat
C
362
star
2

gerbolyze

Directly render SVG overlays into Gerber and Excellon files
C++
345
star
3

matelight

Show text and gifs on mate crates. Uses C code orchestrated from Python via ctypes.
C
132
star
4

Model-M

cad files for model M keyboard key caps
80
star
5

ffi

A Foreign Function Call Through the TIOBE Top 20 and some
C++
47
star
6

pixelterm

Render pixel images (including animated GIFs) on 256-color ANSI terminals
Python
17
star
7

i3lock

My fork of git://code.i3wm.org/i3lock , the screen locker (not only) of the i3 window manager
C
15
star
8

openmind

An open source Brain-Computer-Interface hardware design
Prolog
12
star
9

sticker

10
star
10

cerebrum

RPC framework for interaction with c firmware from python host applications
C
9
star
11

python-lmap

A ldap object mapper for python, also containing a very minimal python ldap interface based on the openldap-libldap
Python
8
star
12

Better-XTrLock

This is a mod of xtrlock not displaying the blue lock but instead completely hiding the cursor.
C
8
star
13

tachibana_talk

7
star
14

infiray_irg

A simple python module to read Infiray C200 IRG thermal image files
Python
7
star
15

kimesh

KiMesh is a KiCad plugin that automatically generates security meshes
Python
6
star
16

gerbonara

Pythonic library for reading/modifying/writing Gerber/Excellon/IPC-356 files. docs: https://gerbolyze.gitlab.io/gerbonara
C++
6
star
17

espressif-esp8266-sdk

Espressif's SDK for the ESP8266 wifi chip, with some fixes applied.
C
5
star
18

openmind-viewer

A gnuradio-based viewer for brain waves captured with openmind hardware
C
5
star
19

openmind-firmware

The firmware of the OpenMind hardware. Note: This is still work in progress!
C
5
star
20

nyanping

Python
5
star
21

scripts

Small scripts I use for general housekeeping and other tasks
Shell
4
star
22

c-mote

Wire-bound sensor mote for c-base and AfRA
C++
4
star
23

gogs

Go
4
star
24

ips-announce

The announcement server for the indoor positioning system we develop at global android dev camp 2012
JavaScript
4
star
25

perceptron

This is a ruby implementation of a perceptron with stochastic gradien descent (for centered data). It is course work for a cognitive algorithms course at TU Berlin.
Python
4
star
26

kicad-xilinx

Here go any components I create for KiCAD
3
star
27

clippy

Clippy as a service
Python
3
star
28

altium_svg

Hacky script to import svg into altium
Python
3
star
29

pdp-6-frontpanel

C
3
star
30

OpenStep

One Step Beyond
C
3
star
31

locc-firmware

C
3
star
32

bitcoin_resource_calculation

A back-of-the-envelope calculation of Bitcoin's ecological footprint
Jupyter Notebook
3
star
33

openmind-first-protoype

This is the first prototype of an open source EEG front-end based on the Texas Instruments ADS1194/ADS1294 and an ATMega8L-8-bit microcontroller. It can be battery powered and (hopefully) is small enough to be worn like a mp3-player.
Prolog
3
star
34

cerebrum-firmware

The arduino/avr-firmware for cerebrum-control. Allows the control of a load of switches, LEDs and analog meters via a serial port.
C
3
star
35

Internetinformation

just school stuff...
2
star
36

loccctrl

An LDAP-connected door lock written in python
Python
2
star
37

dazhbog

Various high-performance LED strip drivers
HTML
2
star
38

misc

2
star
39

Graf-Zahl

The first arithmantic programming language ever!
Ruby
2
star
40

rgbulb-arduino

An arduino mega-based 16 bit rgb dimmer controllable via USB
Arduino
2
star
41

archstrap

Bootstrap remote-unlockable encrypted-root arch installation over ssh using ansible
Shell
2
star
42

heartbeat

Ruby
2
star
43

avr-uip

C
2
star
44

arduino-mega-pwm16

Java
2
star
45

Hausaufgaben

Altes Zeug fรผr's Studium
Shell
2
star
46

polyIO

A board containing an embeedded linux module with wifi and ethernet and two FPGAs I want to use to control a lot of switches and LEDs
Prolog
2
star
47

Vintage-System-Monitor

I outfit two really old multimeters with new scales to display system stats (CPU/MEM/NET). They will be interfaced by some AVR which talks to the computer via software USB.
2
star
48

wsdiff

wsdiff: Produce pretty, single-file HTML-formatted diffs with a css-only adaptive inline/side-by-side layout
Python
2
star
49

kantinen

Scripts to access the menus of the various places providing food on TU Berlin's campus
Python
1
star
50

cerebrum-control

A server to control leds, analog meters and switches on old control panels through a certain series of tubes.
JavaScript
1
star
51

flipdot

mรถรถp
HTML
1
star
52

openstep2

KiCad Layout
1
star
53

RGBulb

Ruby
1
star
54

BUZ2-Master

1
star
55

usb-lamp

An atmega32u4-based soft-usb controllable 16-bit pwm led lamp with fading functionality (including linux driver)
Shell
1
star
56

Taskforce-Belegarbeit

1
star
57

qubes-intro-talk

1
star
58

servotest

C
1
star
59

Computer-Room-Network-Documentation

yeah, as said above.
1
star
60

k-chenschild

1
star
61

bt-lamp

C
1
star
62

physik-einf-hrungspraktikum

Ruby
1
star
63

OpenMind-colloquium

The presentation I used to replace a written abitur exam
1
star
64

python-jmdict

Python
1
star
65

bikelights

IDL
1
star
66

TheSwitch

The source code for the oversized evil mad scientist-type switch at c-base which is used to control the music server in severe motivational emergencies
Python
1
star
67

Taskforce

JavaScript
1
star
68

klingel

C
1
star
69

bvgflip

C
1
star
70

dussmann-ubiquity

An ubiquity command to access RCS order systems.
1
star
71

Arduino-CCD

An attempt at reverse-engineering a scanner CCD PCB and using it with an arduino
C
1
star
72

OpenMind-shield

An arduino shield to connect OpenMind electrodes.
1
star
73

cabinet

Work in progress
C
1
star
74

VFD-Hardware

My attempt at reverse engineering an old VFD I found.
1
star
75

avr-capacitive

1
star
76

DasTelefon

AVR sources (arduino-compatible) to connect an old rotary phone to an arduino
C
1
star
77

Relays

At c-base, we equipped 100 huge east-german relays with RGB leds. This is the software and hardware to control all this.
Prolog
1
star
78

wofs

FUSE Write-only Filesystem. The original is to be found at http://lordikc.free.fr/wordpress/?p=802
C++
1
star
79

Sharp-Stereo-Aux

An aux input for my sharp XL-40 stereo
C
1
star
80

RCActuator

1
star
81

cerebrum-control-python

A server to control LEDs, switches and analog meters from old control panels with an arduino via various interfaces (so far: REST, JSON-RPC)
Python
1
star
82

fish-config

My personal fish shell config
Shell
1
star
83

Penta

C
1
star
84

usbrng

An USB hardware random number generator (draft)
C
1
star
85

taep

taep: Print pictures as collages of label tape
Python
1
star
86

Buspirate-SPI-Sniffer

This is a variant of the original v0.3 code I use to output debug messages from an AVR microcontroller via SPI.
C
1
star