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: bv[height<=?1080][ext=mp4]+ba # 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
# [Optional]
# How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
# executed (default: 15 seconds). *NOTE*: For back-compatibility
# reasons, the `poll_seconds` argument is also supported, but it's
# deprecated.
# poll_interval: 15 # type=Optional[float]
# [Optional]
# How long we should wait for any running
# threads/processes to stop before exiting (default: 5 seconds).
# stop_timeout: 5 # type=Optional[float]
# [Optional]
# If set to True then the plugin will not monitor
# for new events. This is useful if you want to run a plugin in
# stateless mode and only leverage its actions, without triggering any
# events. Defaults to False.
# disable_monitor: False # type=bool
Dependencies#
pip
pip install python-mpv yt-dlp
Alpine
apk add py3-mpv mpv yt-dlp
Debian
apt install yt-dlp mpv python3-mpv
Fedora
yum install mpv yt-dlp
Arch Linux
pacman -S python-mpv mpv yt-dlp
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)
- cancel_download(url: str | None = None, path: str | None = None)#
Cancel a download in progress.
Either the URL or the path must be specified.
- Parameters:
url – URL of the download.
path – Path of the download (default: any path associated with the URL).
- clear_downloads(url: str | None = None, path: str | None = None)#
Clear completed/cancelled downloads from the queue.
- Parameters:
url – URL of the download (default: all downloads).
path – Path of the download (default: any path associated with the URL).
- download(url: str, filename: str | None = None, directory: str | None = None, timeout: int = 10, sync: bool = False, only_audio: bool = False, youtube_format: str | None = None)#
Download a media URL to a local file on the Platypush host (yt-dlp required for YouTube URLs).
This action is non-blocking and returns the path to the downloaded file once the download is initiated.
You can then subscribe to these events to monitor the download progress:
- Parameters:
url – Media URL.
filename – Media filename (default: inferred from the URL basename).
directory – Destination directory (default:
download_dir
).timeout – Network timeout in seconds (default: 10).
sync – If set to True, the download will be synchronous and the action will return only when the download is completed.
youtube_format – Override the default
youtube_format
setting.
- Returns:
The absolute path to the downloaded file.
- get_downloads(url: str | None = None, path: str | None = None)#
Get the download threads.
- Parameters:
url – URL of the download (default: all downloads).
path – Path of the download (default: any path associated with the URL).
- Returns:
[ { "ended_at": "2024-07-16T18:25:27.204236+00:00", "path": "/path/to/download/video.mp4", "size": 1024, "started_at": "2024-07-16T18:25:27.204210+00:00", "state": "Download state", "timeout": 60, "url": "https://example.com/video.mp4" } ]
- 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
- main()#
Implementation of the main loop of the plugin.
- pause_download(url: str | None = None, path: str | None = None)#
Pause a download in progress.
Either the URL or the path must be specified.
- Parameters:
url – URL of the download.
path – Path of the download (default: any path associated with the URL).
- 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)
- resume_download(url: str | None = None, path: str | None = None)#
Resume a paused download.
Either the URL or the path must be specified.
- Parameters:
url – URL of the download.
path – Path of the download (default: any path associated with the URL).
- 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_volume(volume)[source]#
Set the volume
- Parameters:
volume (float) – Volume value between 0 and 100
- start()#
Start the plugin.
- 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 }
- 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
- wait_stop(timeout=None)#
Wait until a stop event is received.