# Kodi Binding
Kodi (opens new window) (formerly known as XBMC) is a 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. |
| inputbuttonevent | String | Send a button press event. The parameter can have the format "<button>", "<button>;<keymap>" or "<button>;<keymap>;<holdtime>". For details see https://kodi.wiki/view/JSON-RPC_API/v12#Input.ButtonEvent (opens new window) |
| inputrequested | Switch | Indicates whether Kodi is currently asking the user for input |
| screensaver | Switch | Current state of the Screensaver |
| 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 (opens new window)). |
# 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:
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
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
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
}
}