mirror of
https://github.com/openhab/openhab-addons.git
synced 2025-01-10 15:11:59 +01:00
239 lines
158 KiB
Markdown
239 lines
158 KiB
Markdown
# Kodi Binding
|
|
|
|
[Kodi](https://kodi.tv) (formerly known as XBMC) is an free and open source (GPL) software media center for playing videos, music, pictures, games, and more.
|
|
Kodi runs on Linux, OS X, BSD, Windows, iOS, and Android.
|
|
It allows users to play and view most videos, music, podcasts, and other digital media files from local and network storage media and the internet.
|
|
|
|
The Kodi Binding integrates Kodi media center support with openHAB, allowing both controlling the player as well as retrieving player status data like the currently played movie title.
|
|
|
|
The Kodi binding is the successor to the openHAB 1.x xbmc binding.
|
|
|
|
## Preparation
|
|
|
|
In order to allow Kodi to be controlled through this binding, you need to enable the Kodi application remote control feature.
|
|
Please enable "Allow remote control from applications on this/other systems" in the Kodi settings menu under:
|
|
|
|
* Settings ➔ Services ➔ Control ➔
|
|
* Allow remote control from applications on **this** systems
|
|
* Allow remote control from applications on **other** systems
|
|
|
|
To make use of the auto-discovery feature, you additionally need to enable "Allow control of Kodi via UPnP" in the Kodi settings menu.
|
|
|
|
* Settings ➔ Services ➔ UPnP / DLNA ➔ Allow remote control via UPnP
|
|
|
|
## Supported Things
|
|
|
|
This binding provides only one thing type: The Kodi media center.
|
|
Create one Kodi thing per Kodi instance available in your home automation system.
|
|
|
|
All Kodi devices are registered as an audio sink in openHAB.
|
|
|
|
## Discovery
|
|
|
|
The binding supports auto-discovery for available and prepared (see above) instances of the Kodi media center on your local network.
|
|
Auto-discovery is enabled by default.
|
|
To disable it, you can add the following line to `<openHAB-conf>/services/runtime.cfg`:
|
|
|
|
```
|
|
discovery.kodi:background=false
|
|
```
|
|
|
|
## Binding Configuration
|
|
|
|
The following configuration options are available for the Kodi binding:
|
|
|
|
| Parameter | Name | Description | Required |
|
|
|---------------|--------------|----------------------------------------------------------------------------|----------|
|
|
| `callbackUrl` | Callback URL | URL to use for playing notification sounds, e.g. `http://192.168.0.2:8080` | no |
|
|
|
|
### Thing Configuration
|
|
|
|
The Kodi thing requires the IP address of the device hosting your Kodi media center instance, the TCP port to access it (default: `9090`) and the HTTP port to build URLs to the Kodi webinterface for downloading thumbnail and fanart images (default: `8080`).
|
|
You optionally can define a `httpUser` and a `httpPassword` parameter if the access to your Kodi webinterface is protected.
|
|
The IP address will be found by the auto-discovery feature.
|
|
You can use the `notificationVolume` property for setting a default volume (in %) as well as a `notificationTimeout` (in s) to be used to play notifications.
|
|
|
|
A manual setup through a `things/kodi.things` file could look like this:
|
|
|
|
```
|
|
Thing kodi:kodi:myKodi "Kodi" @ "Living Room" [ipAddress="192.168.1.100", port=9090, httpPort=8080]
|
|
```
|
|
|
|
## Channels
|
|
|
|
The Kodi thing supports the following channels:
|
|
|
|
| Channel Type ID | Item Type | Description |
|
|
|-----------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| mute | Switch | Mute/unmute your playback |
|
|
| volume | Dimmer | Read or control the volume of your playback |
|
|
| control | Player | Control the Kodi player, e.g. `PLAY`, `PAUSE`, `NEXT`, `PREVIOUS`, `FASTFORWARD`, `REWIND` |
|
|
| stop | Switch | Write `ON` to this channel: Stops the Kodi player. If this channel is `ON`, the player is stopped, otherwise Kodi is in another state (see control channel) |
|
|
| title | String | Title of the currently played song/movie/tv episode |
|
|
| originaltitle | String | Title of the currently played song/movie/tv episode in local language |
|
|
| showtitle | String | Title of the currently played tv-show; empty for other types |
|
|
| album | String | Album name of the currently played song |
|
|
| artist | String | Artist name of the currently played song or director of the currently played movie |
|
|
| playuri | String | Plays the file with the provided URI. The URI can be amended by `#timestamp=<s>` where `s` is position in seconds at which the video should be started. |
|
|
| playfavorite | String | Plays or opens the favorite with the provided title (channel's state options contains available favorites) |
|
|
| pvr-open-tv | String | Opens the PVR TV channel with the provided name (channel's state options contains available PVR TV channels) |
|
|
| pvr-open-radio | String | Opens the PVR Radio channel with the provided name (channel's state options contains available PVR Radio channels) |
|
|
| pvr-channel | String | Title of the currently played PVR channel |
|
|
| shownotification | String | Shows the provided notification message on the screen |
|
|
| input | String | Sends a key stroke to Kodi to navigate in the UI. Valid commands are: `Back`, `ContextMenu`, `Down`, `Home`, `Info`, `Left`, `Right`, `Select`, `ShowCodec`, `ShowOSD`, `ShowPlayerProcessInfo` and `Up`. `ExecuteAction` and `SendText` should be used with the dedicated channels `inputaction` and `inputtext`. |
|
|
| inputtext | String | Sends a generic input (unicode) text to Kodi. |
|
|
| inputaction | String | Sends a predefined action to Kodi to control the UI and/or perform other tasks. Valid commands are: `left`, `right`, `up`, `down`, `pageup`, `pagedown`, `select`, `highlight`, `parentdir`, `parentfolder`, `back`, `menu`, `previousmenu`, `info`, `pause`, `stop`, `skipnext`, `skipprevious`, `fullscreen`, `aspectratio`, `stepforward`, `stepback`, `bigstepforward`, `bigstepback`, `chapterorbigstepforward`, `chapterorbigstepback`, `osd`, `showsubtitles`, `nextsubtitle`, `cyclesubtitle`, `playerdebug`, `codecinfo`, `playerprocessinfo`, `nextpicture`, `previouspicture`, `zoomout`, `zoomin`, `playlist`, `queue`, `zoomnormal`, `zoomlevel1`, `zoomlevel2`, `zoomlevel3`, `zoomlevel4`, `zoomlevel5`, `zoomlevel6`, `zoomlevel7`, `zoomlevel8`, `zoomlevel9`, `nextcalibration`, `resetcalibration`, `analogmove`, `analogmovex`, `analogmovey`, `rotate`, `rotateccw`, `close`, `subtitledelayminus`, `subtitledelay`, `subtitledelayplus`, `audiodelayminus`, `audiodelay`, `audiodelayplus`, `subtitleshiftup`, `subtitleshiftdown`, `subtitlealign`, `audionextlanguage`, `verticalshiftup`, `verticalshiftdown`, `nextresolution`, `audiotoggledigital`, `number0`, `number1`, `number2`, `number3`, `number4`, `number5`, `number6`, `number7`, `number8`, `number9`, `smallstepback`, `fastforward`, `rewind`, `play`, `playpause`, `switchplayer`, `delete`, `copy`, `move`, `screenshot`, `rename`, `togglewatched`, `scanitem`, `reloadkeymaps`, `volumeup`, `volumedown`, `mute`, `backspace`, `scrollup`, `scrolldown`, `analogfastforward`, `analogrewind`, `moveitemup`, `moveitemdown`, `contextmenu`, `shift`, `symbols`, `cursorleft`, `cursorright`, `showtime`, `analogseekforward`, `analogseekback`, `showpreset`, `nextpreset`, `previouspreset`, `lockpreset`, `randompreset`, `increasevisrating`, `decreasevisrating`, `showvideomenu`, `enter`, `increaserating`, `decreaserating`, `setrating`, `togglefullscreen`, `nextscene`, `previousscene`, `nextletter`, `prevletter`, `jumpsms2`, `jumpsms3`, `jumpsms4`, `jumpsms5`, `jumpsms6`, `jumpsms7`, `jumpsms8`, `jumpsms9`, `filter`, `filterclear`, `filtersms2`, `filtersms3`, `filtersms4`, `filtersms5`, `filtersms6`, `filtersms7`, `filtersms8`, `filtersms9`, `firstpage`, `lastpage`, `guiprofile`, `red`, `green`, `yellow`, `blue`, `increasepar`, `decreasepar`, `volampup`, `volampdown`, `volumeamplification`, `createbookmark`, `createepisodebookmark`, `settingsreset`, `settingslevelchange`, `stereomode`, `nextstereomode`, `previousstereomode`, `togglestereomode`, `stereomodetomono`, `channelup`, `channeldown`, `previouschannelgroup`, `nextchannelgroup`, `playpvr`, `playpvrtv`, `playpvrradio`, `record`, `togglecommskip`, `showtimerrule`, `leftclick`, `rightclick`, `middleclick`, `doubleclick`, `longclick`, `wheelup`, `wheeldown`, `mousedrag`, `mousemove`, `tap`, `longpress`, `pangesture`, `zoomgesture`, `rotategesture`, `swipeleft`, `swiperight`, `swipeup`, `swipedown`, `error`, `noop`. |
|
|
| systemcommand | String | This channel allows to send system commands to `Shutdown`, `Suspend`, `Hibernate`, `Reboot` or `Quit` Kodi (channel's state options contains available system commands) |
|
|
| mediatype | String | The media type of the current file. Valid return values are: `unknown`, `channel`, `episode`, `movie`, `musicvideo`, `picture`, `radio`, `song`, `video` |
|
|
| mediaid | Number | The media_id in database of Kodi |
|
|
| mediafile | String | Full path and file name of the current file |
|
|
| uniqueid-imdb | String | IMDB link ID of currently playing media **(Advanced)** |
|
|
| uniqueid-tmdb | String | TheMovieDB link ID of currently playing media **(Advanced)** |
|
|
| uniqueid-douban | String | Douban link ID of currently playing media **(Advanced)** |
|
|
| uniqueid-imdbtvshow | String | IMDB link ID of the season of currently playing tv episode **(Advanced)** |
|
|
| uniqueid-tmdbtvshow | String | IMDB link ID of the season of currently playing tv episode **(Advanced)** |
|
|
| uniqueid-tmdbepisode | String | IMDB link ID of single episode of currently playing tv episode **(Advanced)** |
|
|
| season | Number | Season number if currently playing tv episode |
|
|
| episode | Number | Episode number if currently playing tv episode |
|
|
| genreList | String | A comma-separated list of genres of the current file |
|
|
| thumbnail | Image | The URL to the thumbnail of the current file |
|
|
| fanart | Image | The URL to the fanart of the current file |
|
|
| playnotification | String | Plays the notification sound by a given URI |
|
|
| subtitle-enabled | Switch | Display/hidden subtitle |
|
|
| subtitle-index | Number | Set or get subtitle index of currently playing media |
|
|
| subtitle-language | String | Display subtitle language of currently playing media |
|
|
| subtitle-name | String | Display subtitle title of currently playing media |
|
|
| audio-index | Number | Audio stream index of currently playing media |
|
|
| audio-codec | String | Audio codec of currently playing media **(Advanced)** |
|
|
| audio-language | String | Display language of currently playing audio stream **(Advanced)** |
|
|
| audio-name | String | Display title of currently playing audio stream **(Advanced)** |
|
|
| audio-channels | Number | Display channels of currently playing audio stream **(Advanced)** |
|
|
| video-codec | String | Video codec of currently playing media **(Advanced)** |
|
|
| video-index | Number | Index of currently playing multi stream video **(Advanced)** |
|
|
| video-height | Number | Height of currently playing video **(Advanced)** |
|
|
| video-weight | Number | Width of currently playing video **(Advanced)** |
|
|
| currenttime | Number:Time | Current time of currently playing media |
|
|
| currenttimepercentage | Number:Dimensionless | Current time of currently playing media |
|
|
| duration | Number:Time | Length of currently playing media |
|
|
| rating | Number | rating of currently playing media **(Advanced)** |
|
|
| mpaa | String | MPAA rating of currently playing media **(Advanced)** |
|
|
| userrating | Number | personal rating of currently playing media **(Advanced)** |
|
|
| profile | String | Current profile **(Advanced)** |
|
|
|
|
Kodi things are extensible by channels of type `shownotification`, so that different notification pop-ups can be configured for different use cases.
|
|
|
|
|
|
### Channel Configuration
|
|
|
|
**group** The PVR channels can be put into user-defined PVR channel groups.
|
|
There are two default PVR channel groups.
|
|
One for PVR TV channels and one for PVR radio channels.
|
|
The default labels are "All channels" (in German systems "Alle Kanäle").
|
|
You have to adjust this configuration to use the `pvr-open-tv` and `pvr-open-radio` channels properly.
|
|
You can optionally configure an user-defined PVR channel group.
|
|
The PVR channels from Kodi will be populated during runtime into the state options of the `pvr-open-tv` and `pvr-open-radio` channels.
|
|
|
|
**shownotification** The `shownotification` channel type has three configuration parameters through which it can be customized:
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-------------|---------|---------|------------------------------------------------------------------------|
|
|
| title | Text | openHAB | Title of the notification |
|
|
| displayTime | Integer | 5000 | Time the notification is shown (in ms) |
|
|
| icon | Text | | Icon to use (e.g. "alarm"). One of the openHAB icons (as listed [here](https://www.openhab.org/docs/configuration/iconsets/classic/)). |
|
|
|
|
## Audio Support
|
|
|
|
All Kodi instances are registered as an audio sink in the framework.
|
|
Audio streams are sent to the `playnotification` channel and will change the volume of the audio sink using the `notificationVolume` defined in the properties for the thing, not the `volume`.
|
|
|
|
URL audio streams (e.g. an Internet radio stream) are an exception and do not get sent to the `playnotification` channel.
|
|
Instead, these will be sent to the `playuri` channel.
|
|
|
|
## Full Example
|
|
|
|
A manual setup through a `things/kodi.things` file could look like this:
|
|
|
|
```java
|
|
Thing kodi:kodi:myKodi "Kodi" @ "Living Room" [ipAddress="192.168.1.100", port=9090] {
|
|
Channels:
|
|
Type pvr-open-tv : pvr-open-tv [
|
|
group="All channels"
|
|
]
|
|
Type shownotification : error-notification [
|
|
title="openHAB - Error",
|
|
icon="error"
|
|
]
|
|
Type shownotification : weather-notification [
|
|
title="openHAB - Weather",
|
|
icon="sun_clouds"
|
|
]
|
|
}
|
|
```
|
|
|
|
### Item Configuration
|
|
|
|
demo.items
|
|
|
|
```java
|
|
Switch myKodi_mute "Mute" { channel="kodi:kodi:myKodi:mute" }
|
|
Dimmer myKodi_volume "Volume [%d]" { channel="kodi:kodi:myKodi:volume" }
|
|
Player myKodi_control "Control" { channel="kodi:kodi:myKodi:control" }
|
|
Switch myKodi_stop "Stop" { channel="kodi:kodi:myKodi:stop" }
|
|
String myKodi_title "Title [%s]" { channel="kodi:kodi:myKodi:title" }
|
|
String myKodi_showtitle "Show title [%s]" { channel="kodi:kodi:myKodi:showtitle" }
|
|
String myKodi_album "Album [%s]" { channel="kodi:kodi:myKodi:album" }
|
|
String myKodi_artist "Artist [%s]" { channel="kodi:kodi:myKodi:artist" }
|
|
String myKodi_playuri "Play URI" { channel="kodi:kodi:myKodi:playuri" }
|
|
String myKodi_playfavorite "Play favorite" { channel="kodi:kodi:myKodi:playfavorite" }
|
|
String myKodi_pvropentv "Play PVR TV channel" { channel="kodi:kodi:myKodi:pvr-open-tv" }
|
|
String myKodi_pvropenradio "Play PVR Radio channel" { channel="kodi:kodi:myKodi:pvr-open-radio" }
|
|
String myKodi_pvrchannel "PVR channel [%s]" { channel="kodi:kodi:myKodi:pvr-channel" }
|
|
String myKodi_notification "Notification" { channel="kodi:kodi:myKodi:shownotification" }
|
|
String myKodi_error-notification "Error Notification" { channel="kodi:kodi:myKodi:error-notification" }
|
|
String myKodi_weather-notification "Weather Notification" { channel="kodi:kodi:myKodi:weather-notification" }
|
|
String myKodi_input "Input" { channel="kodi:kodi:myKodi:input" }
|
|
String myKodi_inputtext "Inputtext" { channel="kodi:kodi:myKodi:inputtext" }
|
|
String myKodi_systemcommand "Systemcommand" { channel="kodi:kodi:myKodi:systemcommand" }
|
|
String myKodi_mediatype "Mediatype [%s]" { channel="kodi:kodi:myKodi:mediatype" }
|
|
String myKodi_genrelist "Genres [%s]" { channel="kodi:kodi:myKodi:genreList" }
|
|
Image myKodi_thumbnail { channel="kodi:kodi:myKodi:thumbnail" }
|
|
Image myKodi_fanart { channel="kodi:kodi:myKodi:fanart" }
|
|
Number:Time myKodi_currenttime "Current Time [%d %unit%]" { channel="kodi:kodi:myKodi:currenttime" }
|
|
Number:Dimensionless myKodi_ctp "Current Time [%d %unit%]" { channel="kodi:kodi:myKodi:currenttimepercentage" }
|
|
Number:Time myKodi_duration "Duration [%d %unit%]" { channel="kodi:kodi:myKodi:duration" }
|
|
String myKodi_playnotification "Play notification URI" { channel="kodi:kodi:myKodi:playnotification" }
|
|
```
|
|
|
|
### Sitemap Configuration
|
|
|
|
demo.sitemap
|
|
|
|
```perl
|
|
sitemap demo label="myKodi"
|
|
{
|
|
Frame label="myKodi" {
|
|
Switch item=myKodi_mute
|
|
Slider item=myKodi_volume
|
|
Selection item=myKodi_control mappings=[PLAY='Play', PAUSE='Pause', NEXT='Next', PREVIOUS='Previous', FASTFORWARD='Fastforward', REWIND='Rewind']
|
|
Default item=myKodi_control
|
|
Switch item=myKodi_stop
|
|
Text item=myKodi_title
|
|
Text item=myKodi_showtitle
|
|
Text item=myKodi_album
|
|
Text item=myKodi_artist
|
|
Selection item=myKodi_pvropentv
|
|
Selection item=myKodi_pvropenchannel
|
|
Text item=myKodi_pvrchannel
|
|
Selection item=myKodi_input mappings=[Up='Up', Down='Down', Left='Left', Right='Right', Select='Select', Back='Back', Home='Home', ContextMenu='ContextMenu', Info='Info']
|
|
Selection item=myKodi_systemcommand
|
|
Text item=myKodi_mediatype
|
|
Text item=myKodi_genrelist
|
|
Image item=myKodi_thumbnail
|
|
Image item=myKodi_fanart
|
|
Text item=myKodi_currenttime
|
|
Text item=myKodi_ctp
|
|
Text item=myKodi_duration
|
|
}
|
|
}
|
|
```
|