openhab-addons/bundles/org.openhab.binding.xmltv/README.md

XmlTV Binding

XMLTV is an XML based file format for describing TV listings. This format is often used by Home Theater software to produce their Electronic Program Guide (http://wiki.xmltv.org/index.php/Main_Page)

The norm allows to separate program display from its building. The building of the XMLTV file itself is taken in charge by so called "grabbers" (http://wiki.xmltv.org/index.php/HowtoUseGrabbers).

Some websites provides updated XMLTV files than can be directly downloaded.

Here is a sample for France : https://www.xmltv.fr/

This binding takes an XMLTV file as input and creates a thing for each channel contained in it. XmlTV channels are called Media Channels in this binding in order to avoid messing with openHAB Channels.

For each thing, you will be able to get information regarding the current program and the next to come.

Supported Things

Discovery

Once the XmlTV bridge to a file is created, you can add all known channels by searching new things.

Binding Configuration

Configuration Parameter	Required	Description	Default
filePath	X	Full path (including filename) to an Xml TV file
refresh	X	XMLTV file reload interval in hours	24h
encoding	X	XMLTV file encoding	UTF8

Thing Configuration

Configuration Parameter	Required	Description	Default
channelId	X	Id of the channel as presented in the XmlTV file
offset	X	Offset applied to program times (forward or backward (minutes)	0
refresh	X	Refresh interval in seconds	60

Channels

Channel Type ID	Item Type	Description
iconUrl	String	Channel Icon URL
icon	Image	Icon of the channel

Current program (currentprog) Channels Group

Channel Type ID	Item Type	Description
progStart	DateTime	Program Start Time
progEnd	DateTime	Program End Time
progTitle	String	Program Title
progCategory	String	Program Category
progIconUrl	String	URL to an image of the program
icon	Image	Icon of the program
elapsedTime	Number:Time	Current time of currently playing program
remainingTime	Number:Time	Time remaining until end of the program
progress	Number:Dimensionless	Relative progression of the current program

Next program (nextprog) Channels Group

Channel Type ID	Item Type	Description
progStart	DateTime	Program Start Time
timeLeft	Number:Time	Time left before program start
progEnd	DateTime	Program End Time
progTitle	String	Program Title
progCategory	String	Program Category
progIconUrl	String	URL to an image of the program
icon	Image	Icon of the program

Full Example

xmltv.things

Bridge xmltv:xmltvfile:france "XmlTV" @ "TV" [filePath="/etc/openhab2/scripts/tvguide.xml"]
{
    Thing channel france2 "France 2" @ "TV" [channelId="C4.api.telerama.fr", offset=0, refresh=60]
}

xmltv.items

String france2_title "Titre" {channel="xmltv:channel:france:france2:currentprog#progTitle"}