home-assistant.io/source/_components/media_player.kodi.markdown

layout	title	description	date	sidebar	comments	sharing	footer	logo	ha_category	featured	ha_release	ha_iot_class
page	Kodi	Instructions on how to integrate Kodi into Home Assistant.	2015-06-22 11:00	true	false	true	true	kodi.png	Media Player	true	pre 0.7	Local Push

The kodi platform allows you to control a Kodi multimedia system from Home Assistant.

The preferred way to set up the Kodi platform is by enabling the discovery component which requires enabled web interface on your Kodi installation.

{% linkable_title Configuration %}

In case the discovery does not work, or you need specific configuration variables, you can add the following to your configuration.yaml file:

# Example configuration.yaml entry
media_player:
  - platform: kodi
    host: 192.168.0.123

{% configuration %} host: description: The host name or address of the device that is running XBMC/Kodi. required: true type: string port: description: The HTTP port number. required: false type: integer default: 8080 tcp_port: description: The TCP port number. Used for WebSocket connections to Kodi. required: false type: integer default: 9090 name: description: The name of the device used in the frontend. required: false type: string proxy_ssl: description: Connect to Kodi with HTTPS and WSS. Useful if Kodi is behind an SSL proxy. required: false type: boolean default: false username: description: The XBMC/Kodi HTTP username. required: false type: string password: description: The XBMC/Kodi HTTP password. required: false type: string turn_on_action: description: Home Assistant script sequence to call when turning on. required: false type: list turn_off_action: description: Home Assistant script sequence to call when turning off. required: false type: list enable_websocket: description: Enable websocket connections to Kodi via the TCP port. The WebSocket connection allows Kodi to push updates to Home Assistant and removes the need for Home Assistant to poll. If websockets don't work on your installation this can be set to false. required: false type: boolean default: true timeout: description: Set timeout for connections to Kodi. Defaults to 5 seconds. required: false type: integer default: 5 {% endconfiguration %}

{% linkable_title Services %}

{% linkable_title Service kodi_add_to_playlist %}

Add music to the default playlist (i.e. playlistid=0).

Service data attribute	Optional	Description
entity_id	no	Name(s) of the Kodi entities where to add the media.
media_type	yes	Media type identifier. It must be one of SONG or ALBUM.
media_id	no	Unique Id of the media entry to add (songid or albumid). If not defined, media_name and artist_name are needed to search the Kodi music library.
media_name	no	Optional media name for filtering media. Can be 'ALL' when media_type is 'ALBUM' and artist_name is specified, to add all songs from one artist.
artist_name	no	Optional artist name for filtering media.

{% linkable_title Service media_player/kodi_set_shuffle %}

Service data attribute	Optional	Description
entity_id	yes	Target a specific media player. It must be of type kodi.
shuffle_on	no	True/false for shuffle on/off.

{% linkable_title Service kodi_call_method %}

Call a Kodi JSONRPC API method with optional parameters. Results of the Kodi API call will be redirected in a Home Assistant event: kodi_call_method_result.

Service data attribute	Optional	Description
entity_id	no	Name(s) of the Kodi entities where to run the API method.
method	yes	Name of the Kodi JSONRPC API method to be called.
any other parameter	no	Optional parameters for the Kodi API call.

{% linkable_title Event triggering %}

When calling the kodi_call_method service, if the Kodi JSONRPC API returns data, when received by Home Assistant it will fire a kodi_call_method_result event on the event bus with the following event_data:

entity_id: "<Kodi media_player entity_id>"
result_ok: <boolean>
input: <input parameters of the service call>
result: <data received from the Kodi API>

{% linkable_title Kodi turn on/off samples %}

With the turn_on_action and turn_off_action parameters you can run any combination of Home Assistant actions to turn on/off your Kodi instance. Here are a few examples of this usage, including the migration instructions for the old turn_off_action list of options.

Turn on Kodi with Wake on LAN

With this configuration, when calling media_player/turn_on on the Kodi device, a magic packet will be sent to the specified MAC address. To use this service, first you need to config the wake_on_lan component in Home Assistant, which is achieved simply by adding wake_on_lan: to your configuration.yaml.

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_on_action:
      - service: wake_on_lan.send_magic_packet
        data:
          mac: aa:bb:cc:dd:ee:ff
          broadcast_address: 192.168.255.255

Turn off Kodi with API calls

Here are the equivalent ways to configure each of the old options to turn off Kodi (quit, hibernate, suspend, reboot, or shutdown):

• Quit method (before was turn_off_action: quit)

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_off_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: Application.Quit

• Hibernate method (before was turn_off_action: hibernate)

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_off_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: System.Hibernate

• Suspend method (before was turn_off_action: suspend)

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_off_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: System.Suspend

• Reboot method (before was turn_off_action: reboot)

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_off_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: System.Reboot

• Shutdown method (before was turn_off_action: shutdown)

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_off_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: System.Shutdown

Turn on and off the TV with the Kodi JSON-CEC Add-on

For Kodi devices running 24/7 attached to a CEC capable TV (OSMC / OpenElec and systems alike running in Rasperry Pi's, for example), this configuration enables the optimal way to turn on/off the attached TV from Home Assistant while Kodi is always active and ready:

media_player:
  - platform: kodi
    host: 192.168.0.123
    turn_on_action:
      service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: Addons.ExecuteAddon
        addonid: script.json-cec
        params:
          command: activate
    turn_off_action:
    - service: media_player.media_stop
      data:
        entity_id: media_player.kodi
    - service: media_player.kodi_call_method
      data:
        entity_id: media_player.kodi
        method: Addons.ExecuteAddon
        addonid: script.json-cec
        params:
          command: standby

This example and the following requires to have the [script.json-cec](https://github.com/joshjowen/script.json-cec) plugin installed on your kodi player. It'll also expose the endpoints standby, toggle and activate without authentication on your kodi player. Use this with caution.

{% linkable_title Kodi services samples %}

Simple script to turn on the PVR in some channel as a time function

{% raw %}

script:
  play_kodi_pvr:
    alias: Turn on the silly box
    sequence:
      - alias: TV on
        service: media_player.turn_on
        data:
          entity_id: media_player.kodi
      - alias: Play TV channel
        service: media_player.play_media
        data_template:
          entity_id: media_player.kodi
          media_content_type: "CHANNEL"
          media_content_id: >
            {% if (now().hour < 14) or ((now().hour == 14) and (now().minute < 50)) %}
              10
            {% elif (now().hour < 16) %}
              15
            {% elif (now().hour < 20) %}
              2
            {% elif (now().hour == 20) and (now().minute < 50) %}
              10
            {% elif (now().hour == 20) or ((now().hour == 21) and (now().minute < 15)) %}
              15
            {% else %}
              10
            {% endif %}

{% endraw %}

Trigger a Kodi video library update

script:
  update_library:
    alias: Update Kodi Library
    sequence:
      - alias: Call Kodi update
        service: media_player.kodi_call_method
        data:
          entity_id: media_player.kodi
          method: VideoLibrary.Scan

For a more complex usage of the kodi_call_method service, with event triggering of Kodi API results, you can have a look at this example