media.mpv#

Description#

Plugin to control MPV instances.

Configuration#

media.mpv:
  # [Optional]
  # Default arguments that will be passed to the mpv executable
  # as a key-value dict (names without the `--` prefix). See `man mpv`
  # for available options.
  # args:   # type=Optional[Dict[str, Any]]

  # [Optional]
  # Set to True if you want media files to be opened in
  # fullscreen by default (can be overridden by `.play()`) (default: False)
  # fullscreen: False  # type=bool

  # [Optional]
  # Directories that will be scanned for media files when
  # a search is performed (default: none)
  # media_dirs:   # type=Optional[List[str]]

  # [Optional]
  # Directory where external resources/torrents will be
  # downloaded (default: ~/Downloads)
  # download_dir:   # type=Optional[str]

  # [Optional]
  # Environment variables key-values to pass to the
  # player executable (e.g. DISPLAY, XDG_VTNR, PULSE_SINK etc.)
  # env:   # type=Optional[Dict[str, str]]

  # [Optional]
  # Default volume for the player (default: None, maximum volume).
  # volume:   # type=Union[float, int, NoneType]

  # [Optional]
  # Optional plugin to be used for torrent download. Possible values:
  #
  # - ``torrent`` - native ``libtorrent``-based plugin (default, recommended)
  # - ``rtorrent`` - torrent support over rtorrent RPC/XML interface
  # - ``webtorrent`` - torrent support over webtorrent (unstable)
  # torrent_plugin: torrent  # type=str

  # [Optional]
  # Select the preferred video/audio format for
  # YouTube videos - and any media supported by youtube-dl or the
  # selected fork. See the `youtube-dl documentation
  # <https://github.com/ytdl-org/youtube-dl#format-selection>`_ for more
  # info on supported formats. Default:
  # ``bv*[height<=?1080][ext=mp4]+bestaudio/best`` - select the best
  # mp4 video with a resolution <= 1080p, and the best audio format.
  # youtube_format: best[height<=?1080][ext=mp4]  # type=Optional[str]

  # [Optional]
  # Path to the ``youtube-dl`` executable, used to
  # extract information from YouTube videos and other media platforms.
  # Default: ``yt-dlp``. The default has changed from ``youtube-dl`` to
  # the ``yt-dlp`` fork because the former is badly maintained and its
  # latest release was pushed in 2021.
  # youtube_dl: yt-dlp  # type=str

Dependencies#

pip

pip install yt-dlp python-mpv

Alpine

apk add yt-dlp mpv py3-mpv

Debian

apt install python3-mpv mpv yt-dlp

Fedora

yum install yt-dlp mpv

Arch Linux

pacman -S yt-dlp mpv python-mpv

Actions#

Module reference#

class platypush.plugins.media.mpv.MediaMpvPlugin(args: Dict[str, Any] | None = None, fullscreen: bool = False, **kwargs)[source]#

Bases: MediaPlugin

Plugin to control MPV instances.

__init__(args: Dict[str, Any] | None = None, fullscreen: bool = False, **kwargs)[source]#
Parameters:
  • args – Default arguments that will be passed to the mpv executable as a key-value dict (names without the prefix). See man mpv for available options.

  • fullscreen – Set to True if you want media files to be opened in fullscreen by default (can be overridden by .play()) (default: False)

add_subtitles(filename)[source]#

Add a subtitles file

back(offset=30.0, **_)[source]#

Back by (default: 30) seconds

download(url: str, filename: str | None = None, directory: str | None = None)#

Download a media URL to a local file on the Platypush host.

Parameters:
  • url – Media URL.

  • filename – Media filename (default: inferred from the URL basename).

  • directory – Destination directory (default: download_dir).

Returns:

The absolute path to the downloaded file.

execute(cmd, **args)[source]#

Execute a raw mpv command.

forward(offset=30.0, **_)[source]#

Forward by (default: 30) seconds

get_media_file_duration(filename)#

Get the duration of a media file in seconds. Requires ffmpeg

get_property(property)[source]#

Get a player property (e.g. pause, fullscreen etc.). See man mpv for a full list of the available properties

is_playing(**_)[source]#
Returns:

True if it’s playing, False otherwise

load(resource, **args)[source]#

Load/queue a resource/video to the player

mute(**_)[source]#

Toggle mute state

next(**_)[source]#

Play the next item in the queue

pause(*_, **__)[source]#

Toggle the paused state

play(resource: str, *_, subtitles: str | None = None, fullscreen: bool | None = None, **args)[source]#

Play a resource.

Parameters:
  • resource – Resource to play - can be a local file or a remote URL

  • subtitles – Path to optional subtitle file

  • args – Extra runtime arguments that will be passed to the mpv executable as a key-value dict (keys without prefix)

prev(**_)[source]#

Play the previous item in the queue

quit(*_, **__)[source]#

Stop and quit the player

remove_subtitles(sub_id=None, **_)[source]#

Removes (hides) the subtitles

search(query: str, types: Iterable[str] | None = None, queue_results: bool = False, autoplay: bool = False, timeout: float = 60)#

Perform a video search.

Parameters:
  • query – Query string, video name or partial name

  • types – Video types to search (default: ["youtube", "file", "torrent"])

  • queue_results – Append the results to the current playing queue (default: False)

  • autoplay – Play the first result of the search (default: False)

  • timeout – Search timeout (default: 60 seconds)

seek(position: float, **_)[source]#

Seek backward/forward by the specified number of seconds

Parameters:

position – Number of seconds relative to the current cursor

set_position(position: float, **_)[source]#

Seek backward/forward to the specified absolute position (same as seek)

set_property(**props)[source]#

Set the value of an mpv property (e.g. fullscreen, sub_visibility etc.). See man mpv for a full list of properties

Parameters:

props (dict) – Key-value args for the properties to set

set_subtitles(filename, *_, **__)[source]#

Sets media subtitles from filename

set_volume(volume)[source]#

Set the volume

Parameters:

volume (float) – Volume value between 0 and 100

start_streaming(media: str, subtitles: str | None = None, download: bool = False)#

Starts streaming local media over the specified HTTP port. The stream will be available to HTTP clients on http://{this-ip}:{http_backend_port}/media/<media_id>

Parameters:
  • media – Media to stream

  • subtitles – Path or URL to the subtitles track to be used

  • download – Set to True if you prefer to download the file from the streaming link instead of streaming it

Returns:

dict containing the streaming URL.Example:

{
    "id": "0123456abcdef.mp4",
    "source": "file:///mnt/media/movies/movie.mp4",
    "mime_type": "video/mp4",
    "url": "http://192.168.1.2:8008/media/0123456abcdef.mp4"
}
status(**_)[source]#

Get the current player state.

Returns:

A dictionary containing the current state.

Example:

{
    "audio_channels": 2,
    "audio_codec": "mp3",
    "delay": 0,
    "duration": 300.0,
    "file_size": 123456,
    "filename": "filename or stream URL",
    "fullscreen": false,
    "mute": false,
    "name": "mpv",
    "pause": false,
    "percent_pos": 10.0,
    "position": 30.0,
    "seekable": true,
    "state": "play",  // or "stop" or "pause"
    "title": "filename or stream URL",
    "url": "file:///path/to/file.mp3",
    "video_codec": "h264",
    "video_format": "avc1",
    "volume": 50.0,
    "volume_max": 100.0,
    "width": 1280
}
stop(*_, **__)[source]#

Stop and quit the player

toggle_fullscreen()[source]#

Toggle the fullscreen mode

toggle_property(property)[source]#

Toggle or sets the value of an mpv property (e.g. fullscreen, sub_visibility etc.). See man mpv for a full list of properties

Parameters:

property – Property to toggle

toggle_subtitles(*_, **__)[source]#

Toggle the subtitles visibility

voldown(*_, step: float = 10.0, **__)[source]#

Volume down by (default: 10)%

volup(step: float = 10.0, **_)[source]#

Volume up by (default: 10)%