media.kodi

Platypush documentation

media.kodi#

Description#

Plugin to interact with a Kodi media player instance

Configuration#

media.kodi:
  # [Optional]
  # Base URL for the Kodi JSON RPC API (default:
  # http://localhost:8080/jsonrpc). You need to make sure that the RPC
  # API is enabled on your Kodi instance - you can enable it from the
  # settings.
  # rpc_url: http://localhost:8080/jsonrpc  # type=str

  # [Optional]
  # Kodi JSON RPC websocket port, used to receive player events
  # websocket_port: 9090  # type=int

  # [Optional]
  # Kodi username (optional)
  # username:   # type=str | None

  # [Optional]
  # Kodi password (optional)
  # password:   # type=str | None

  # [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=str | Iterable[str | dict] | Dict[str, str | dict] | None

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

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

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

  # [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=str | None

  # [Optional]
  # Select the preferred audio format for
  # YouTube videos downloaded only for audio. Default: ``bestaudio``.
  # youtube_audio_format: ba  # type=str | None

  # [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=str | None

  # [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=Sequence[str] | None

  # [Optional]
  # Optional configuration to expose this
  #   media plugin as a Chromecast receiver on the LAN. The HTTP backend
  #   must be configured, and the ``chromecast-receiver`` extra must be
  #   installed:
  #
  # .. code-block:: bash
  #
  #   pip install platypush[chromecast-receiver]
  #
  # Example configuration:
  #
  # .. code-block:: yaml
  #
  #   media.mpv:
  #       chromecast_receiver:
  #           enabled: true
  #           device_name: Living Room Platypush
  #           host: 192.168.1.50
  #           port: 8009
  #           model_name: Platypush
  #           manufacturer: Platypush
  #           allowed_networks:
  #               - 192.168.0.0/16
  #               - 10.0.0.0/8
  #           status_interval: 1.0
  #           dial:
  #               # To enable the DIAL protocol
  #               enabled: true
  # chromecast_receiver:   # type=Dict[str, Any] | None

  # [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=float | None

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=float | None

  # [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 kodi-json

Alpine

apk add py3-kodi

Arch Linux

pacman -S python-kodi-json

Actions#

Module reference#

class platypush.plugins.media.kodi.MediaKodiPlugin(rpc_url: str = 'http://localhost:8080/jsonrpc', websocket_port: int = 9090, username: str | None = None, password: str | None = None, **kwargs)[source]#

Bases: MediaPlugin

Plugin to interact with a Kodi media player instance

__init__(rpc_url: str = 'http://localhost:8080/jsonrpc', websocket_port: int = 9090, username: str | None = None, password: str | None = None, **kwargs)[source]#
Parameters:

  • rpc_url – Base URL for the Kodi JSON RPC API (default: http://localhost:8080/jsonrpc). You need to make sure that the RPC API is enabled on your Kodi instance - you can enable it from the settings.

  • websocket_port – Kodi JSON RPC websocket port, used to receive player events

  • username – Kodi username (optional)

  • password – Kodi password (optional)

add_to_queue(resource: str | dict, index: int | None = None)#

Add a media item to the playback queue.

Parameters:

  • resource – Media URL or media item dictionary to queue.

  • index – Optional zero-based position where the item should be inserted. If not specified, the item is appended to the end of the queue.

Returns:

The item that was added to the queue.

back(offset=30, player_id=None, **_)[source]#

Move the player execution backward by delta_seconds

Parameters:

  • offset (float) – Backward seek duration (default: 30 seconds)

  • player_id – ID of the target player (default: configured/current player).

back_btn(**_)[source]#

Simulate a back input event

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

clean_audio_library(**_)[source]#

Clean the audio library

clean_video_library(**_)[source]#

Clean the video library

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

clear_queue()#

Clear the playback queue.

Returns:

The number of items that were removed.

down(**_)[source]#

Simulate a down input event

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.

forward(offset=30, player_id=None, **_)[source]#

Move the player execution forward by delta_seconds

Parameters:

  • offset (float) – Forward seek duration (default: 30 seconds)

  • player_id – ID of the target player (default: configured/current player).

fullscreen(**_)[source]#

Set/unset fullscreen mode

get_active_players()[source]#

Get the list of active players

get_albums(**_)[source]#

Get the list of albums in the audio library

get_artists(**_)[source]#

Get the list of artists in the audio library

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_movies(**_)[source]#

Get the list of movies on the Kodi server

get_queue()#

Get the items currently in the playback queue.

Returns:

List of queued media items.

get_songs(**_)[source]#

Get the list of songs in the audio library

is_muted(**_)[source]#

Return the muted status of the application

left(**_)[source]#

Simulate a left input event

move_queue_item(from_index: int, to_index: int)#

Change the position of an item in the playback queue.

Parameters:

  • from_index – Current zero-based index of the item.

  • to_index – New zero-based index for the item.

Returns:

The updated queue.

mute(**_)[source]#

Mute/unmute the application

next(*args, **kwargs)#

Play the next item in the queue or the player-specific playlist.

notify(title, message, **_)[source]#

Send a notification to the Kodi UI

pause(player_id=None, **_)[source]#

Play/pause the current media

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, **kwargs)[source]#

Open and play the specified file or URL

Parameters:

resource – URL or path to the media to be played

pop_queue()#

Remove and return the next item from the front of the playback queue.

Returns:

The removed queue item, or None if the queue is empty.

quit(**_)[source]#

Quit the application

remove_queue_item(index: int)#

Remove an item from the playback queue by its index.

Parameters:

index – Zero-based index of the item to remove.

Returns:

The removed queue item.

repeat(player_id=None, repeat=None, **_)[source]#

Set/unset repeat mode

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

right(**_)[source]#

Simulate a right input event

scan_audio_library(**_)[source]#

Scan the audio library

scan_video_library(**_)[source]#

Scan the video library

search(query: str, types: Iterable[str] | None = None, queue_results: bool = False, autoplay: bool = False, timeout: float = 60, limit: int | None = None, page_token: str | None = None) → Dict[str, Any]#

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)

  • limit – Maximum number of results per source per page (default: 25).

  • page_token – Opaque pagination token returned by a previous search call as next_page_token. Pass it to retrieve the next page of results.

Returns:

A dictionary with results (list of media items) and next_page_token (string or null when there are no more pages).

seek(position, player_id=None, **_)[source]#

Move to the specified time position in seconds

Parameters:

  • position (float) – Seek time in seconds

  • player_id – ID of the target player (default: configured/current player).

select(**_)[source]#

Simulate a select input event

send_text(text, **_)[source]#

Simulate a send_text input event

Parameters:

text (str) – Text to send

set_position(position, player_id=None, *args, **kwargs)[source]#

Move to the specified time position in seconds

Parameters:

  • position (float) – Seek time in seconds

  • player_id – ID of the target player (default: configured/current player).

set_volume(volume, **_)[source]#

Set the application volume

Parameters:

volume (int) – Volume to set between 0 and 100

shuffle(player_id=None, shuffle=None, **_)[source]#

Set/unset shuffle mode

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"
}
stop(player_id=None, **_)[source]#

Stop the current media

up(**_)[source]#

Simulate an up input event

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

Volume down (default: -10%)

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

Volume up (default: +10%)

Platypush documentation