media.gstreamer#

Description#

Plugin to play media over GStreamer.

Configuration#

media.gstreamer:
  # [Optional]
  # GStreamer audio sink (default: ``None``, automatic).
  # sink:   # type=Optional[str]

  # [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 pygobject

Alpine

apk add py3-gst py3-gobject3

Debian

apt install python3-gst-1.0 python3-gi

Fedora

yum install python-gstreamer1 python-gobject

Arch Linux

pacman -S gst-python python-gobject

Actions#

Module reference#

class platypush.plugins.media.gstreamer.MediaGstreamerPlugin(sink: str | None = None, *args, **kwargs)[source]#

Bases: MediaPlugin

Plugin to play media over GStreamer.

__init__(sink: str | None = None, *args, **kwargs)[source]#
Parameters:

sink – GStreamer audio sink (default: None, automatic).

back(offset=60.0)[source]#

Back by (default: 60) 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)#

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.

forward(offset=60.0)[source]#

Forward by (default: 60) 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": "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_volume() float[source]#

Get the volume.

Returns:

Volume value between 0 and 100.

is_playing()[source]#
Returns:

True if it’s playing, False otherwise

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

Load/queue a resource/video to the player (alias for play()).

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 | None = None, **_)[source]#

Play a resource.

Parameters:

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

quit()[source]#

Stop and quit the player (alias for stop())

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) dict[source]#

Seek backward/forward by the specified number of seconds.

Parameters:

position – Number of seconds relative to the current cursor.

set_position(position: float) dict[source]#

Seek backward/forward to the specified absolute position.

Parameters:

position – Stream position in seconds.

Returns:

Player state.

set_volume(volume)[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() dict[source]#

Get the current player state.

stop()[source]#

Stop and quit the player (alias for quit())

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.