diff options
Diffstat (limited to 'content/projects/python-mpv')
| -rw-r--r-- | content/projects/python-mpv/README.rst | 401 | ||||
| -rw-r--r-- | content/projects/python-mpv/index.rst | 18 |
2 files changed, 419 insertions, 0 deletions
diff --git a/content/projects/python-mpv/README.rst b/content/projects/python-mpv/README.rst new file mode 100644 index 0000000..26815d1 --- /dev/null +++ b/content/projects/python-mpv/README.rst @@ -0,0 +1,401 @@ +.. vim: tw=120 sw=4 et + +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 +------------ + +.. code:: bash + + 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 +<https://stackoverflow.com/a/23805306>`__ 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. + +.. _`py2compat branch`: https://github.com/jaseg/python-mpv/tree/py2compat +.. _`issue`: https://github.com/jaseg/python-mpv/issues +.. _`pull request`: https://github.com/jaseg/python-mpv/pulls + +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. + +.. __: https://github.com/jaseg/python-mpv/issues/60#issuecomment-352719773 +.. _`issue 61`: https://github.com/jaseg/python-mpv/issues/61 +.. _`issue 36`: https://github.com/jaseg/python-mpv/issues/36 + +Usage +----- + +.. code:: python + + 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 <https://mpv.io/manual/master/#list-of-input-commands>`_" are mapped to methods of the MPV class. Check out these methods and their docstrings in `the source <https://github.com/jaseg/python-mpv/blob/main/mpv.py>`__ for things you can do. Additional controls and status information are exposed through `MPV properties <https://mpv.io/manual/master/#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 +.................................................................... + +.. code:: python + + #!/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! + +.. code:: python + + #!/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 +.............. + +.. code:: python + + #!/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 +................. + +.. code:: python + + #!/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 +..................................... + +.. code:: 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: + +.. code:: python + + #!/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. + +.. code:: python + + #!/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 + +.. _`issue 102`: https://github.com/jaseg/python-mpv/issues/61 + +.. code:: python + + # 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 +.............. + +.. code:: python + + #!/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 +................... + +.. code:: python + + #!/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 <https://gist.github.com/jaseg/657e8ecca3267c0d82ec85d40f423caa>`__ through this python API. + +Using OpenGL from PyQt5/QML +........................... + +Robozman_ has mangaed to `make mpv render into a PyQt5/QML widget using OpenGL +<https://gitlab.com/robozman/python-mpv-qml-example>`__ through this python API. + +Using mpv inside imgui inside OpenGL via GLFW +............................................. + +dfaker_ has written a demo (`link <https://github.com/dfaker/imgui_glfw_pythonmpv_demo/blob/main/main.py>`__) that uses mpv to render video into an `imgui <https://github.com/ocornut/imgui>`__ UI running on an OpenGL context inside `GLFW <https://www.glfw.org/>`__. 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`_. + +.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/ +.. _`mpv.py`: https://raw.githubusercontent.com/jaseg/python-mpv/main/mpv.py +.. _cosven: https://github.com/cosven +.. _Robozman: https://gitlab.com/robozman +.. _dfaker: https://github.com/dfaker +.. _`the mpv copyright page`: https://github.com/mpv-player/mpv/blob/master/Copyright + diff --git a/content/projects/python-mpv/index.rst b/content/projects/python-mpv/index.rst new file mode 100644 index 0000000..a1bdcd5 --- /dev/null +++ b/content/projects/python-mpv/index.rst @@ -0,0 +1,18 @@ +--- +title: "python-mpv" +external_links: + - name: Sources + url: "https://git.jaseg.de/python-mpv.git" + - name: Issues + url: "https://github.com/jaseg/python-mpv/issues" + - name: Docs + url: "https://neinseg.gitlab.io/python-mpv" + - name: PyPI + url: "https://pypi.org/projects/mpv" +summary: > + python-mpv is a small, ctypes-based Python library wrapping the libmpv media player library. Despite its small size + and simple API, python-mpv allows advanced control over libmpv and beyond simple remote control of mpv can be used + to embed mpv in OpenGL, Qt, and GTK-based Python applications. +--- + +.. include:: content/projects/python-mpv/README.rst |