2025.3.4
首页 ▸ Integrations ▸

Kodi

kodi 平台允许您从 Home Assistant 控制 Kodi 多媒体系统。

设置 Kodi 平台的首选方式是通过发现，这需要您的 Kodi 安装启用 Web 界面。

目前在 Home Assistant 中支持以下设备类型：

配置

要将 Kodi integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

Kodi 可以被 Home Assistant 自动发现。如果发现了实例， 它将显示为 已发现。您可以立即进行设置。

手动配置步骤

如果没有自动发现，请不要担心！您可以设置一个 手动集成条目：

如果您之前通过 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 配置了 Kodi，建议将其删除，并通过 UI 进行配置。 如果您不删除，您的配置将被导入，但存在以下限制：

  • 您的开关动作将不会被导入。此功能现在可以通过设备触发器实现。
  • 您可能会有重复的实体。
  • Kodi 必须在 Home Assistant 首次加载时处于打开状态，以便配置能够被导入。

开关

您可以通过自动化自定义开关动作。只需使用相关的 Kodi 设备触发器，您的自动化将被调用以执行 turn_on 或 turn_off 序列；请参见 Kodi 开关样本 部分以获取可使用的脚本。

这些自动化可以通过 UI 配置（有关自动化，请参见 设备触发器）。如果您更喜欢 YAML，您需要从 UI 自动化编辑器中获取设备 ID。自动化将如下所示：

automation:
  - alias: "Kodi: 开启"
    triggers:
      - trigger: device
        device_id: !secret kodi_device_id
        domain: kodi
        entity_id: media_player.kodi
        type: turn_on
    actions:
      - action: script.kodi_turn_on

  - alias: "Kodi: 关闭"
    triggers:
      - trigger: device
        device_id: !secret kodi_device_id
        domain: kodi
        entity_id: media_player.kodi
        type: turn_off
    actions:
      - action: script.kodi_turn_off

动作

动作 kodi.add_to_playlist

将音乐添加到默认播放列表（即 playlistid=0）。

数据属性 可选 描述
entity_id 否 要添加媒体的 Kodi 实体名称。
media_type 是 媒体类型标识符。必须是 SONG 或 ALBUM 之一。
media_id 否 要添加的媒体条目的唯一 ID（songid 或 albumid）。如果未定义，则需要 media_name 和 artist_name 来搜索 Kodi 音乐库。
media_name 否 过滤媒体的可选媒体名称。当 media_type 为 ALBUM 且指定 artist_name 时，可以为 ‘ALL’，以添加一个艺术家的所有歌曲。
artist_name 否 过滤媒体的可选艺术家名称。

动作 kodi.call_method

调用带有可选参数的 Kodi JSON-RPC API 方法。Kodi API 调用的结果将在 Home Assistant 事件中重定向：kodi_call_method_result。

数据属性 可选 描述
entity_id 否 要运行 API 方法的 Kodi 实体名称。
method 是 要调用的 Kodi JSON-RPC API 方法的名称。
任何其他参数 否 Kodi API 调用的可选参数。

事件触发

调用 kodi.call_method 动作时，如果 Kodi JSON-RPC API 返回数据，当 Home Assistant 接收到数据时，将在事件总线上触发 kodi_call_method_result 事件，包含以下 event_data：

entity_id: "<Kodi media_player entity_id>"
result_ok: <boolean>
input: <动作输入参数>
result: <从 Kodi API 接收到的数据>

Kodi 开关样本

以下脚本可以在自动化中使用，用于打开/关闭您的 Kodi 实例；请参见 开关。您还可以直接在自动化中使用这些序列，而无需创建脚本。

使用局域网唤醒打开 Kodi

通过此配置，当对 Kodi 设备调用 media_player/turn_on 时，将向指定 MAC 地址发送 魔术数据包。要使用此操作，首先需要在 Home Assistant 中配置 wake_on_lan 集成，这只需在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中添加 wake_on_lan:。

script:
  turn_on_kodi_with_wol:
    sequence:
      - action: wake_on_lan.send_magic_packet
        data:
          mac: aa:bb:cc:dd:ee:ff
          broadcast_address: 192.168.255.255

使用 API 调用关闭 Kodi

以下是配置每个旧选项以关闭 Kodi（quit、hibernate、suspend、reboot 或 shutdown）的等效方法：

  • 退出 方法
script:
  kodi_quit:
    sequence:
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: Application.Quit
  • 休眠 方法
script:
  kodi_hibernate:
    sequence:
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: System.Hibernate
  • 挂起 方法
script:
  kodi_suspend:
    sequence:
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: System.Suspend
  • 重启 方法
script:
  kodi_reboot:
    sequence:
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: System.Reboot
  • 关机 方法
script:
  kodi_shutdown:
    sequence:
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: System.Shutdown

使用 Kodi JSON-CEC 插件打开和关闭电视

对于 24/7 运行并连接到 CEC 兼容电视的 Kodi 设备（例如运行 OSMC / OpenElec 和 Raspberry Pi 系统），此配置使得从 Home Assistant 中打开/关闭连接的电视成为可能，同时 Kodi 始终保持活动状态并准备就绪：

script:
  turn_on_kodi_with_cec:
  sequence:
    - action: kodi.call_method
      target:
        entity_id: media_player.kodi
      data:
        method: Addons.ExecuteAddon
        addonid: script.json-cec
        params:
          command: activate

  turn_off_kodi_with_cec:
    sequence:
      - action: media_player.media_stop
        target:
          entity_id: media_player.kodi
      - action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: Addons.ExecuteAddon
          addonid: script.json-cec
          params:
            command: standby

Important

此示例及以下示例需要在您的 Kodi 播放器上安装 script.json-cec 插件。它还将在您的 Kodi 播放器上无身份验证地公开 standby、toggle 和 activate 端点。使用此功能时请小心。

Kodi 动作样本

简单脚本以时间函数打开某个频道的 PVR 

script:
  play_kodi_pvr:
    alias: "打开傻瓜箱"
    sequence:
      - alias: "电视开启"
        action: media_player.turn_on
        target:
          entity_id: media_player.kodi
      - alias: "播放电视频道"
        action: media_player.play_media
        target:
          entity_id: media_player.kodi
        data:
          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 %}

简单脚本以播放智能播放列表 

script:
  play_kodi_smp:
    alias: "打开带随机消防员山姆剧集的傻瓜箱"
    sequence:
      - alias: "电视开启"
        action: media_player.turn_on
        target:
          entity_id: media_player.kodi
      - action: media_player.play_media
        target:
          entity_id: media_player.kodi
        data:
          media_content_type: DIRECTORY
          media_content_id: special://profile/playlists/video/feuerwehrmann_sam.xsp

触发 Kodi 视频库更新 

script:
  update_library:
    alias: "更新 Kodi 库"
    sequence:
      - alias: "调用 Kodi 更新"
        action: kodi.call_method
        target:
          entity_id: media_player.kodi
        data:
          method: VideoLibrary.Scan

通知

kodi 通知平台允许您从 Home Assistant 向您的 Kodi 多媒体系统发送消息。

要将 Kodi 添加到您的安装中，请在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中添加以下内容：

# 示例 configuration.yaml 条目
notify:
  - platform: kodi
    name: NOTIFIER_NAME
    host: IP_ADDRESS

Configuration Variables

Looking for your configuration file?
name string (Optional)

前端显示的名称。通知器将绑定到 notify.NOTIFIER_NAME 操作。

host string Required

运行 Kodi 的设备的主机名或地址。

port integer (Optional, default: 8080)

HTTP 端口号。

proxy_ssl boolean (Optional, default: false)

以 HTTPS 连接到 Kodi。如果 Kodi 处于 SSL 代理后面，这很有用。

username string (Optional)

XBMC/Kodi HTTP 用户名。

password string (Optional)

XBMC/Kodi HTTP 密码。

脚本示例 

kodi_notification:
  sequence:
  - action: notify.NOTIFIER_NAME
    data:
      title: "Home Assistant"
      message: "来自 Home Assistant 的消息！"
      data:
        displaytime: 20000
        icon: "warning"

消息变量

Configuration Variables

Looking for your configuration file?
title string (Optional)

显示在消息上的标题。

message string Required

要显示的消息。

data map (Optional)

配置消息属性

icon string (Optional, default: info)

Kodi 附带 3 个默认图标：info、warning 和 error，图像的 URL 也是有效的。

displaytime integer (Optional, default: 10000 ms)

消息在屏幕上显示的时间长度（以毫秒为单位）。

要使用通知，请参见 入门自动化页面。

按键事件

键盘/遥控器的按键可以在 Kodi 中被重写，并配置为向 Home Assistant 发送事件，然后可以在自动化中使用，例如，调整电视/接收器的音量。

可以使用 Kodi keymap XML 或从 Kodi GUI 中使用 Keymap Editor 插件 重写按键。

下面是使用 XML 的 Kodi keymap 配置示例，它将重写 volume_up/volume_down 按钮，转而向 HomeAssistant 发送事件：

<keymap>
  <global>
    <keyboard>
      <volume_up>NotifyAll("KodiLivingroom", "OnKeyPress", {"key":"volume_up"})</volume_up>
      <volume_down>NotifyAll("KodiLivingroom", "OnKeyPress", {"key":"volume_down"})</volume_down>
    </keyboard>
  </global>
</keymap>

"KodiLivingroom" 可以设置为任何值，并将在事件数据中作为 "sender" 出现。 "OnKeyPress" 是在 Home Assistant 中识别事件所需的，请勿更改。 {"key":"volume_up"} 可以包含任何 JSON，它将出现在事件数据中的 "data" 键下，通常用于识别按下了哪个键。

有关可能的键盘键名称，请参见： https://kodi.wiki/view/List_of_keynames 有关其他操作，请参见： https://kodi.wiki/view/Keymap#Keynames

对于上述示例，当按下音量增加键时，Home Assistant 中将触发如下事件：

event_type: kodi_keypress
data:
  type: keypress
  device_id: 72e5g0ay5621f5d719qd8cydj943421a
  entity_id: media_player.kodi_livingroom
  sender: KodiLivingroom
  data:
    key: volume_up

以下是使用该事件来调整接收器音量的自动化示例：

alias: Kodi 按键事件
mode: parallel
max: 10
triggers:
  - trigger: event
    event_type: kodi_keypress
    event_data:
      entity_id: media_player.kodi_livingroom
actions:
  - choose:
      - conditions:
          - condition: template
            value_template: "{{trigger.event.data.data.key=='volume_up'}}"
        sequence:
          - action: media_player.volume_up
            target:
              entity_id: media_player.receiver
      - conditions:
          - condition: template
            value_template: "{{trigger.event.data.data.key=='volume_down'}}"
        sequence:
          - action: media_player.volume_down
            target:
              entity_id: media_player.receiver