media.chromecast

media.chromecast#

Description#

Plugin to control Chromecast devices.

Configuration#

media.chromecast:
  # [Optional]
  # Default Chromecast to cast to if no name is specified.
  # chromecast:   # type=Optional[str]

  # [Optional]
  # How often the plugin should poll for new/removed
  # Chromecast devices (default: 30 seconds).
  # poll_interval: 30  # type=float

  # [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[width<=?1080][ext=mp4]+ba[ext=m4a]/bv+ba  # type=Optional[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]
  # Additional arguments to pass to the youtube-dl
  # executable. Default: None.
  # ytdl_args: ('--use-postprocessor', 'FFmpegCopyStream', '--ppa', 'CopyStream:"-c:v libx264 -preset veryfast -crf 28 +faststart -c:a aac"')  # type=Optional[Sequence[str]]

  # [Optional]
  # Use youtube-dl to download the media if we are dealing
  # with formats compatible with youtube-dl/yt-dlp. Disable this option
  # if you experience issues with the media playback on the Chromecast,
  # such as media with no video, no audio or both. This option will
  # disable muxing+transcoding over the HTTP server and will stream the
  # URL directly to the Chromecast.
  # use_ytdl: True  # type=bool

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

Alpine

apk add py3-pychromecast

Debian

apt install python3-pychromecast

Fedora

yum install python-chromecast

Actions#

Module reference#

class platypush.plugins.media.chromecast.MediaChromecastPlugin(chromecast: str | None = None, poll_interval: float = 30, youtube_format: str | None = 'bv[width<=?1080][ext=mp4]+ba[ext=m4a]/bv+ba', merge_output_format: str = 'mp4', ytdl_args: Sequence[str] | None = ('--use-postprocessor', 'FFmpegCopyStream', '--ppa', 'CopyStream:"-c:v libx264 -preset veryfast -crf 28 +faststart -c:a aac"'), use_ytdl: bool = True, **kwargs)[source]#

Bases: MediaPlugin, RunnablePlugin

Plugin to control Chromecast devices.

__init__(chromecast: str | None = None, poll_interval: float = 30, youtube_format: str | None = 'bv[width<=?1080][ext=mp4]+ba[ext=m4a]/bv+ba', merge_output_format: str = 'mp4', ytdl_args: Sequence[str] | None = ('--use-postprocessor', 'FFmpegCopyStream', '--ppa', 'CopyStream:"-c:v libx264 -preset veryfast -crf 28 +faststart -c:a aac"'), use_ytdl: bool = True, **kwargs)[source]#
Parameters:

  • chromecast – Default Chromecast to cast to if no name is specified.

  • poll_interval – How often the plugin should poll for new/removed Chromecast devices (default: 30 seconds).

  • use_ytdl – Use youtube-dl to download the media if we are dealing with formats compatible with youtube-dl/yt-dlp. Disable this option if you experience issues with the media playback on the Chromecast, such as media with no video, no audio or both. This option will disable muxing+transcoding over the HTTP server and will stream the URL directly to the Chromecast.

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

disconnect(chromecast: str | None = None, timeout: float | None = None)[source]#

Disconnect a Chromecast and wait for it to terminate

Parameters:

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

  • timeout – Number of seconds to wait for disconnection (default: None: block until termination).

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.

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.

join(chromecast: str | None = None, timeout: float | None = None)[source]#

Blocks the thread until the Chromecast connection is terminated.

Parameters:

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

  • timeout – Number of seconds to wait for disconnection (default: None: block until termination).

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

Alias for play().

main()[source]#

Implementation of the main loop of the plugin.

mute(chromecast: str | None = None)[source]#

Toggle the mute status on the Chromecast

Parameters:

chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

next()#

Play the next item in the queue

pause(*_, chromecast: str | None = None, **__)[source]#

Pause the current media on the Chromecast.

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, *_, content_type: str | None = None, chromecast: str | None = None, title: str | None = None, image_url: str | None = None, autoplay: bool = True, current_time: int = 0, stream_type: str = 'BUFFERED', subtitles: str | None = None, subtitles_lang: str = 'en-US', subtitles_mime: str = 'text/vtt', subtitle_id: int = 1, youtube_format: str | None = None, use_ytdl: bool | None = None, **kwargs)[source]#

Cast media to an available Chromecast device.

Parameters:

  • resource – Media to cast

  • content_type – Content type as a MIME type string

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

  • title – Optional title

  • image_url – URL of the image to use for the thumbnail

  • autoplay – Set it to false if you don’t want the content to start playing immediately (default: true)

  • current_time – Time to start the playback in seconds (default: 0)

  • stream_type – Type of stream to cast. Can be BUFFERED (default), LIVE or UNKNOWN

  • subtitles – URL of the subtitles to be shown

  • subtitles_lang – Subtitles language (default: en-US)

  • subtitles_mime – Subtitles MIME type (default: text/vtt)

  • subtitle_id – ID of the subtitles to be loaded (default: 1)

  • youtube_format – Override the default YouTube format.

  • use_ytdl – Override the default use_ytdl setting for this call.

quit(chromecast: str | None = None)[source]#

Exits the current app on the Chromecast

Parameters:

chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

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)

set_volume(volume: float, chromecast: str | None = None)[source]#

Set the Chromecast volume

Parameters:

  • volume – Volume to be set, between 0 and 100.

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

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(chromecast: str | None = None)[source]#
Returns:

The status of a Chromecast (if chromecast is specified) or all the discovered/available Chromecasts. Format:

{
  "type": "cast",  // Can be "cast" or "audio"
  "name": "Living Room TV",
  "manufacturer": "Google Inc.",
  "model_name": "Chromecast",
  "uuid": "f812afac-80ff-11ee-84dc-001500e8f607",
  "address": "192.168.1.2",
  "port": 8009,
  "status": {
    "app": {
      "id": "CC1AD845",
      "name": "Default Media Receiver"
    },
    "is_active_input": false,
    "is_stand_by": true,
    "is_idle": true,
    "namespaces": [
      "urn:x-cast:com.google.cast.cac",
      "urn:x-cast:com.google.cast.debugoverlay",
      "urn:x-cast:com.google.cast.media"
    ],
    "volume": 100,
    "muted": false,
    "adjusted_current_time": 14.22972,
    "album_artist": null,
    "album_name": null,
    "artist": null,
    "url": "https://some/video.mp4",
    "content_type": "video/mp4",
    "current_subtitle_tracks": [],
    "position": 1.411891,
    "duration": 253.376145,
    "episode": null,
    "idle_reason": null,
    "images": [
      [
        "https://some/image.jpg",
        null,
        null
      ]
    ],
    "last_updated": "2023-11-12T02:03:33.888843",
    "media_custom_data": {},
    "media_is_generic": true,
    "media_is_movie": false,
    "media_is_musictrack": false,
    "media_is_photo": false,
    "media_is_tvshow": false,
    "media_metadata": {
      "title": "Some media",
      "thumb": "https://some/image.jpg",
      "images": [
        {
          "url": "https://some/image.jpg"
        }
      ],
      "metadataType": 0
    },
    "media_session_id": 1,
    "metadata_type": 0,
    "playback_rate": 1,
    "player_is_idle": false,
    "player_is_paused": false,
    "player_is_playing": true,
    "state": "play",
    "season": null,
    "series_title": null,
    "stream_type": "BUFFERED",
    "stream_type_is_buffered": true,
    "stream_type_is_live": false,
    "subtitle_tracks": [],
    "supported_media_commands": 12303,
    "supports_pause": true,
    "supports_queue_next": false,
    "supports_queue_prev": false,
    "seekable": true,
    "supports_skip_backward": false,
    "supports_skip_forward": false,
    "supports_stream_mute": true,
    "supports_stream_volume": true,
    "title": "Some media",
    "track": null
  }
}

stop(*_, chromecast: str | None = None, **__)[source]#

Stop the plugin.

voldown(chromecast: str | None = None, step: float = 10, **_)[source]#

Turn down the Chromecast volume by 10% or step.

Parameters:

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

  • step – Volume decrement between 0 and 100 (default: 10%).

volup(chromecast: str | None = None, step: float = 10, **_)[source]#

Turn up the Chromecast volume by 10% or step.

Parameters:

  • chromecast – Chromecast to cast to. If none is specified, then the default configured Chromecast will be used.

  • step – Volume increment between 0 and 100 (default: 10%).

wait_stop(timeout=None)#

Wait until a stop event is received.