Package: 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.Installationpipinstallmpv…though you can also realistically just copympv.pyinto your project as it’s all nicely contained in one file.Requirementslibmpvlibmpv.soeither locally (in your current working directory) or somewhere in your system library search path. This
module is somewhat lenient as far aslibmpvversions are concerned but sincelibmpvis 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 anissueor
submit apull requeston github.On Windows you can place libmpv anywhere in your%PATH%(e.g. next topython.exe) or next to this module’smpv.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. Consultthis stackoverflow postfor details.Python >= 3.7 (officially)Themainbranch officially only supports recent python releases (3.5 onwards), but there is the somewhat outdated
but functionalpy2compat branchproviding Python 2 compatibility.Supported PlatformsLinux,WindowsandOSXall seem to work mostly fine. For some notes on the installation on Windows seethis 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. Seeissue 36andissue 61for 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.Usageimportmpvplayer=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 inthe sourcefor things you can do. Additional controls and status information are exposed throughMPV properties. These can be accessed likeplayer.metadata,player.fullscreenandplayer.loop_playlist.ThreadingThempvmodule starts one thread for event handling, since MPV sends events that must be processed quickly. The
event queue has a fixed maximum size and some operations can cause a large number of events to be sent.If you want to handle threading yourself, you can passstart_event_thread=Falseto theMPVconstructor and
manually call theMPVobject’s_loopfunction. 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 Clibmpvhas 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 UsageLogging, Properties, Python Key Bindings, Screenshots and youtube-dl#!/usr/bin/env python3importmpvdefmy_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')deftime_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=Trueplayer.loop_playlist='inf'# Option access, in general these require the core to reinitializeplayer['vo']='gpu'@player.on_key_press('q')defmy_q_binding():print('THERE IS NO ESCAPE')@player.on_key_press('s')defmy_s_binding():pillow_img=player.screenshot_raw()pillow_img.save('screenshot.png')player.play('https://youtu.be/DLzxrzFCyOs')player.wait_for_playback()delplayerSkipping silence using libav filtersThe 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 python3importsysimportmpvp=mpv.MPV()p.play(sys.argv[1])defskip_silence():p.set_loglevel('debug')p.af='lavfi=[silencedetect=n=-20dB:d=1]'p.speed=100defcheck(evt):toks=evt['event']['text'].split()if'silence_end:'intoks:returnfloat(toks[2])p.time_pos=p.wait_for_event('log_message',cond=check)p.speed=1p.af=''skip_silence()p.wait_for_playback()Video overlays#!/usr/bin/env python3importtimefromPILimportImage,ImageDraw,ImageFontimportmpvplayer=mpv.MPV()player.loop=Trueplayer.play('test.webm')player.wait_until_playing()font=ImageFont.truetype('DejaVuSans.ttf',40)whilenotplayer.core_idle:time.sleep(0.5)overlay=player.create_image_overlay()forposinrange(0,500,5):ts=player.time_posiftsisNone:breakimg=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 python3importmpvplayer=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=0whileTrue:# To modify the playlist, use player.playlist_{append,clear,move,remove}. player.playlist is read-onlyprint(player.playlist)player.wait_for_playback()Directly feeding mpv data from python#!/usr/bin/env python3importmpvplayer=mpv.MPV()@player.python_stream('foo')defreader():withopen('test.webm','rb')asf:whileTrue:yieldf.read(1024*1024)player.play('python://foo')player.wait_for_playback()Using external subtitlesThe easiest way to load custom subtitles from a file is to pass the--sub-fileoption to theloadfilecall:#!/usr/bin/env python3importmpvplayer=mpv.MPV()player.loadfile('test.webm',sub_file='test.srt')player.wait_for_playback()Note that you can also pass many other options toloadfile. See the mpv docs for details.If you want to add subtitle files or streams at runtime, you can use thesub-addcommand.sub-addcan 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 thecore-idleproperty.#!/usr/bin/env python3importmpvplayer=mpv.MPV()player.play('test.webm')player.wait_until_playing()player.sub_add('test.srt')player.wait_for_playback()Using MPV’s built-in GUIpython-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. SeeIssue 102for more details# Enable the on-screen controller and keyboard shortcutsplayer=mpv.MPV(input_default_bindings=True,input_vo_keyboard=True,osc=True)# Alternative version using the old "floating box" style on-screen controllerplayer=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 python3importmpvimportsysfromPyQt5.QtWidgetsimport*fromPyQt5.QtCoreimport*classTest(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 thislog_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.importlocalelocale.setlocale(locale.LC_NUMERIC,'C')win=Test()win.show()sys.exit(app.exec_())PyGObject embedding#!/usr/bin/env python3importgiimportmpvgi.require_version('Gtk','3.0')fromgi.repositoryimportGtkclassMainClass(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 Noneself.mpv=mpv.MPV(wid=str(widget.get_property("window").get_xid()))self.mpv.play("test.webm")defon_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.importlocalelocale.setlocale(locale.LC_NUMERIC,'C')application=MainClass()Gtk.main()Using OpenGL from PyGObjectJust like it is possible to render into a GTK widget through X11 windows, italso is possible to render into a GTK
widget using OpenGLthrough this python API.Using OpenGL from PyQt5/QMLRobozmanhas mangaed tomake mpv render into a PyQt5/QML widget using OpenGLthrough this python API.Using mpv inside imgui inside OpenGL via GLFWdfakerhas written a demo (link) that uses mpv to render video into animguiUI running on an OpenGL context insideGLFW. 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 testsUse pytest to run tests.Coding ConventionsThe general aim isPEP 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 itreallyhelps readability or itreallyirks you if you don’t.Licensepython-mpv inherits the underlying libmpv’s license, which can be either GPLv2 or later (default) or LGPLv2.1 or later.
For details, seethe mpv copyright page.