Python interface to the awesome mpv media player

.. vim: tw=120 sw=4 et

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

.. code:: bash

    pip install python-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 ``master`` 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/master/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.play('test.webm', sub_file='test.srt')

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/master/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



python-mpv

Google Play Music Proxy - "Let's stream Google Play Music using any media-player"

:tv: Control OMXPlayer, the Raspberry Pi media player, from Python

Simple python over the network media player to playback on DLNA/UPnP devices

AceStream Launcher opens AceStream links with any Media Player

# Acestream Launcher
Acestream Launcher allows you to open Acestream links with a Media Player of your choice

## Dependencies
```text
python, pyhon-acestream, libnotify, acestream-engine
```

Since `v1.0.0` acestream-launcher uses [Acestream Engine HTTP API](https://wiki.acestream.media/Engine_HTTP_API) that is available on acestream-engine `v3.1` or later.

## Usage
```shell
acestream-launcher URL [--player PLAYER] [--engine ENGINE]
```

## Positional arguments
```text
URL                    The acestream url to play
```

## Optional arguments
```text
-h, --help             Show this help message and exit
-p, --player  PLAYER   The media player command to use (default: mpv)
-e, --engine  ENGINE   The engine command to use (default: acestreamengine --client-console)
-t, --timeout TIMEOUT  Time in seconds to wait for stream playback (default: 30)
-l, --hls              Get HLS stream instead of HTTP stream
-v, --verbose          Show engine and media player output in console
```

## Configuration
Create `~/.config/acestream-launcher/config` file to override the default arguments. Use `tty` and `browser` sections to set different options when executing the script from the console or the web browser.

```text
[DEFAULT]
player = vlc
verbose = true
timeout = 60
host = 127.0.0.1
port = 6878

[tty]
engine = acestreamengine --client-console --log-file /home/jonian/.ACEStream/engine.log

[browser]
engine = acestreamengine --client-gtk --log-file /home/jonian/.ACEStream/browser.log
verbose = false
```

## Requirements
Install required dependencies (compatible with python 2 and 3):

```shell
sudo apt-get install python python-pip
```

Install optional dependencies (support for desktop notifications):

```shell
sudo apt-get install libnotify
```

Install Acestream engine manually (you can find actual links [here](https://wiki.acestream.media/Download#Linux) and detailed instructions [here](https://wiki.acestream.media/Install_Ubuntu)):

```shell
sudo apt-get install python-setuptools python-m2crypto python-apsw

wget "http://download.acestream.media/linux/acestream_3.1.49_ubuntu_18.04_x86_64.tar.gz"
tar zxvf acestream_3.1.49_ubuntu_18.04_x86_64.tar.gz
sudo mv acestream_3.1.49_ubuntu_18.04_x86_64 /opt/acestream

sudo sed -i "/ROOT=/c\ROOT=\/opt\/acestream" /opt/acestream/start-engine
sudo ln -sf /opt/acestream/start-engine /usr/bin/acestreamengine
```

Install Acestream engine Snap package:

```shell
sudo snap install acestreamplayer
```

## Installation
Install the package with the Python Package Index using `pip` command.

```shell
pip install acestream-launcher
```

## Packages
Arch Linux: [AUR Package](https://aur.archlinux.org/packages/acestream-launcher)  
OpenSUSE: [Build Service](https://build.opensuse.org/project/show/home:drommer:p2pstreams) by [@Drommer](https://github.com/Drommer)

## Browser integration  
Once it is installed, you can set it as default for the `acestream://` links in your browser. Check your browser preferences for default applications.




acestream-launcher

Ace Stream server Docker image and playback CLI for media players.

6 best Python Media Player libraries in 2022

python-mpvby jaseg

python-mpvby jaseg

gmusicproxyby gmusicproxy

gmusicproxyby gmusicproxy

python-omxplayer-wrapperby willprice

python-omxplayer-wrapperby willprice

dlnapby cherezov

dlnapby cherezov

acestream-launcherby jonian

acestream-launcherby jonian

docker-acestream-serverby magnetikonline

docker-acestream-serverby magnetikonline