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