media.mplayer

media.mplayer#

Description#

Plugin to control MPlayer instances.

Note that some plugin methods are populated dynamically by introspecting the mplayer executable. You can verify the supported methods at runtime by running the list_actions() action.

Configuration#

media.mplayer:
  # [Optional]
  # If set to True then the player will be started in
  # fullscreen mode (default: False)
  # fullscreen: False  # type=bool

  # [Optional]
  # Path to the MPlayer executable (default: search for
  # the first occurrence in your system PATH environment variable)
  # mplayer_bin:   # type=Optional[str]

  # [Optional]
  # Timeout in seconds to wait for more data
  # from MPlayer before considering a response ready (default: 0.5 seconds)
  # mplayer_timeout: 0.5  # type=float

  # [Optional]
  # Default arguments that will be passed to the MPlayer
  # executable
  # args:   # type=Optional[Collection[str]]

  # [Optional]
  # Directories that will be scanned for media files when
  # a search is performed (default: only ``download_dir``). You can
  # specify it either:
  #
  #     - As a list of strings:
  #
  #       .. code-block:: yaml
  #
  #         media_dirs:
  #             - /mnt/hd/media/movies
  #             - /mnt/hd/media/music
  #             - /mnt/hd/media/series
  #
  #     - As a dictionary where the key is the name of the media display
  #       name and the value is the path:
  #
  #         .. code-block:: yaml
  #
  #           media_dirs:
  #               Movies: /mnt/hd/media/movies
  #               Music: /mnt/hd/media/music
  #               Series: /mnt/hd/media/series
  #
  #     - As a dictionary where the key is the name of the media display
  #       name and the value is a dictionary with the path and additional
  #       display information:
  #
  #           media_dirs:
  #               Movies:
  #                   path: /mnt/hd/media/movies
  #                   icon:
  #                       url: https://example.com/icon.png
  #                       # FontAwesome icon classes are supported
  #                       class: fa fa-film
  #
  #               Music:
  #                   path: /mnt/hd/media/music
  #                   icon:
  #                       url: https://example.com/icon.png
  #                       class: fa fa-music
  #
  #               Series:
  #                   path: /mnt/hd/media/series
  #                   icon:
  #                       url: https://example.com/icon.png
  #                       class: fa fa-tv
  # media_dirs:   # type=Union[str, Iterable[Union[str, dict]], Dict[str, Union[str, dict]], NoneType]

  # [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. Example:
  # ``bestvideo[height<=?1080][ext=mp4]+bestaudio`` - select the best
  # mp4 video with a resolution <= 1080p, and the best audio format.
  # youtube_format: bv[height<=?1080]+ba/bv+ba  # type=Optional[str]

  # [Optional]
  # Select the preferred audio format for
  # YouTube videos downloaded only for audio. Default: ``bestaudio``.
  # youtube_audio_format: 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]
  # If media download requires ``youtube_dl``,
  # and the upstream media contains both audio and video to be merged,
  # this can be used to specify the format of the output container -
  # e.g. ``mp4``, ``mkv``, ``avi``, ``flv``. Default: ``mp4``.
  # merge_output_format: mp4  # type=str

  # [Optional]
  # Directory where the media cache will be stored. If not
  # specified, the cache will be stored in the default cache directory
  # (usually ``~/.cache/platypush/media/<media_plugin>``).
  # cache_dir:   # type=Optional[str]

  # [Optional]
  # If set to True, streams transcoded via yt-dlp or
  # ffmpeg will be cached in ``cache_dir`` directory. If not set
  # (default), then streams will be played directly via memory pipe.
  # You may want to set this to True if you have a slow network, or if
  # you want to play media at high quality, even though the start time
  # may be delayed. If set to False, the media will start playing as
  # soon as the stream is ready, but the quality may be lower,
  # especially at the beginning, and seeking may not be supported.
  # cache_streams: False  # type=bool

  # [Optional]
  # Additional arguments to pass to the youtube-dl
  # executable. Default: None.
  # ytdl_args:   # type=Optional[Sequence[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#

Alpine

apk add mplayer yt-dlp

Debian

apt install mplayer yt-dlp

Fedora

yum install mplayer yt-dlp

Arch Linux

pacman -S mplayer yt-dlp

Actions#

Module reference#

class platypush.plugins.media.mplayer.MediaMplayerPlugin(fullscreen: bool = False, mplayer_bin: str | None = None, mplayer_timeout: float = 0.5, args: Collection[str] | None = None, **kwargs)[source]#

Bases: MediaPlugin

Plugin to control MPlayer instances.

Note that some plugin methods are populated dynamically by introspecting the mplayer executable. You can verify the supported methods at runtime by running the list_actions() action.

__init__(fullscreen: bool = False, mplayer_bin: str | None = None, mplayer_timeout: float = 0.5, args: Collection[str] | None = None, **kwargs)[source]#
Parameters:

  • fullscreen – If set to True then the player will be started in fullscreen mode (default: False)

  • mplayer_bin – Path to the MPlayer executable (default: search for the first occurrence in your system PATH environment variable)

  • mplayer_timeout – Timeout in seconds to wait for more data from MPlayer before considering a response ready (default: 0.5 seconds)

  • args – Default arguments that will be passed to the MPlayer executable

add_subtitles(filename: str, **__)[source]#

Sets media subtitles from filename

Parameters:

filename – Subtitles file.

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

Back by (default: 30) seconds

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, youtube_audio_format: str | None = None, merge_output_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.

  • only_audio – If set to True, only the audio track will be downloaded (only supported for yt-dlp-compatible URLs for now).

  • youtube_format – Override the default youtube_format setting.

  • youtube_audio_format – Override the default youtube_audio_format

  • merge_output_format – Override the default merge_output_format setting.

Returns:

The absolute path to the downloaded file.

execute(cmd, args=None)[source]#

Execute a raw MPlayer command. See https://www.mplayerhq.hu/DOCS/tech/slave.txt for a reference or call list_actions() to get a list

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

Forward by (default: 30) seconds

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": "2020-01-01T00:00:00+00:00",
    "path": "/path/to/download/video.mp4",
    "size": 1024,
    "started_at": "2020-01-01T00:00:00+00:00",
    "state": "Download state",
    "timeout": 60,
    "url": "https://example.com/video.mp4"
  }
]

get_media_dirs() → Dict[str, dict]#
Returns:

List of configured media directories.

get_property(property: str, args: Collection[str] | None = None)[source]#

Get a player property (e.g. pause, fullscreen etc.). See https://www.mplayerhq.hu/DOCS/tech/slave.txt for a full list of the available properties

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

True if it’s playing, False otherwise

load(resource, *_, mplayer_args: Collection[str] | None = None, **__)[source]#

Load a resource/video in the player.

main()#

Implementation of the main loop of the plugin.

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

Toggle mute state

next()#

Play the next item in the queue

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

Toggle the paused state

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, mplayer_args: List[str] | None = None, **kwargs)[source]#

Play a resource.

Parameters:

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

  • subtitles – Path to optional subtitle file

  • mplayer_args – Extra runtime arguments that will be passed to the MPlayer executable

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

Quit the player

remove_subtitles(*_, index: int | None = None, **__)[source]#

Removes the subtitle specified by the index (default: all)

Parameters:

index – (1-based) index of the subtitles track to remove.

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

Alias for set_position()

Parameters:

position – Number of seconds relative to the current cursor

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

Set the playback position.

Parameters:

position – Number of seconds from the start

set_property(property: str, value: Any, args: Collection[str] | None = None)[source]#

Set a player property (e.g. pause, fullscreen etc.). See https://www.mplayerhq.hu/DOCS/tech/slave.txt for a full list of the available properties

set_volume(volume: float, *_, **__)[source]#

Set the volume

Parameters:

volume – 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:

.. code-block:: javascript

    {
        "duration": 300.0,  // in seconds
        "filename": "video.mp4",
        "fullscreen": false,
        "mute": false,
        "name": "video.mp4",
        "path": "/path/to/video.mp4",
        "pause": false,
        "percent_pos": 30.0,
        "position": 90.0,  // in seconds
        "seekable": true,
        "state": "play",  // or "stop" or "pause"
        "title": "My Video",
        "volume": 50.0,
        "volume_max": 100.0,
        "url": "file:///path/to/video.mp4",
    }
step_property(property: str, value: Any, *_, args: Collection[str] | None = None, **__)[source]#

Step a player property (e.g. volume, time_pos etc.). See https://www.mplayerhq.hu/DOCS/tech/slave.txt for a full list of the available steppable properties

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

Stop the playback

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

Toggle the subtitles visibility

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

Volume down by (default: 10)%

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

Volume up by (default: 10)%

wait_stop(timeout=None)#

Wait until a stop event is received.

class platypush.plugins.media.mplayer.MplayerStatus(state: PlayerState = PlayerState.STOP, filename: str | None = None, path: str | None = None, title: str | None = None, duration: float | None = None, position: float | None = None, percent_pos: float | None = None, fullscreen: bool | None = None, mute: bool | None = None, pause: bool | None = None, volume: float | None = None, volume_max: float | None = None, seekable: bool | None = None, url: str | None = None)[source]#

Bases: object

MPlayer status object

__init__(state: PlayerState = PlayerState.STOP, filename: str | None = None, path: str | None = None, title: str | None = None, duration: float | None = None, position: float | None = None, percent_pos: float | None = None, fullscreen: bool | None = None, mute: bool | None = None, pause: bool | None = None, volume: float | None = None, volume_max: float | None = None, seekable: bool | None = None, url: str | None = None) → None#