XMLTV File Reference
A channel’s EPG is uploaded as an XMLTV file: an .xml file that lists the programs of one or more channels. This page lists what Vidori reads from the file, what it ignores, and what happens to programs it can’t use.
At a glance
Section titled “At a glance”- One file per upload,
.xml, up to 20 MB. - The root element must be
<tv>. - Vidori reads six things: the
idof each<channel>, its<display-name>, and, for each<programme>, thechannel,startandstopattributes and the<title>and<desc>elements. - Everything else is ignored, including
<rating>. - Up to 5,000 programs are imported per upload.
- Programs that have already ended are left out. A file whose programs have all ended is rejected.
Elements Vidori reads
Section titled “Elements Vidori reads”Only elements directly under <tv> are read.
| Element or attribute | What Vidori does with it |
|---|---|
<tv> | The root element. Any other root element is rejected. |
<channel id="…"> | Declares a channel. The id is how the file refers to that channel. |
<display-name> inside <channel> | The channel’s name. The first one with text is shown next to the id when you are asked to choose a channel. |
<programme channel="…"> | One program. The channel attribute says which channel it belongs to. A <programme> with no channel attribute is ignored. |
start on <programme> | When the program starts. See Times. |
stop on <programme> | When the program ends. See Times. Without it, the program ends when the next one starts. |
<title lang="…"> | The program’s title in one language. A program needs at least one title. See Languages. |
<desc lang="…"> | The program’s description in one language. Optional. |
Extra spaces and line breaks inside a title or description are collapsed into single spaces, and an empty <title> or <desc> counts as missing.
What Vidori ignores
Section titled “What Vidori ignores”Every other element and attribute in the file is ignored, and so is any channel you don’t import. That includes:
<rating>: programs imported from a file have no age rating. See Parental controls.<category>,<icon>,<sub-title>,<episode-num>and any other element inside<programme>.- The programs of the other channels in the file.
A <!DOCTYPE tv SYSTEM "xmltv.dtd"> line at the top of the file is fine. A file that declares its own XML entities is rejected.
start and stop use the XMLTV time format:
YYYYMMDDhhmmss ±hhmm- Everything after the date is optional:
20261201,202612010600and20261201060000are all accepted. A missing hour, minute or second counts as00. - The offset (
+0000,-0500,+0530) says which time zone the time is in. It can be written with or without a space before it:20261201060000 +0100and20261201060000+0100mean the same. - Without an offset, the time is read as UTC, and the result shows a warning. Include the offset in every time.
- A time that doesn’t fit this format, or has an offset that isn’t a real one, can’t be read, and the program is skipped.
The admin panel shows every time in your account’s time zone (Settings → General → Timezone) and names the zone after the time, so you can check what you uploaded.
Languages
Section titled “Languages”Vidori keeps one title and one description per language.
- The
langattribute is the language of that title or description, for exampleenores. Capital letters are treated as lowercase. - A title or description without
langis stored in your account’s default language (Settings → Languages → Default Language). - If a language appears twice in one program, the first one is used.
- If a program has no title in your default language, its first title is also stored as the default language, so the program always has a title there. The same goes for descriptions.
Several channels in one file
Section titled “Several channels in one file”An XMLTV file can hold the programs of many channels. Vidori imports the programs of one channel, picked in this order:
- The channel you pick, when the file has several channels and Vidori asks.
- The channel from your last upload, when the new file contains the same channel
id. The admin panel shows it as XMLTV channel id. - The file’s only channel, when the file has just one.
If none of these applies, the admin panel lists the channels in the file and asks Which one is this channel? Nothing is imported until you choose. A channel counts as being in the file when a <channel> element or any <programme> names its id.
After a successful import, the chosen id is remembered for the channel, so you can upload a new file for it without choosing again.
Limits
Section titled “Limits”| Limit | Value |
|---|---|
| File size | 20 MB |
| Programs per upload | 5,000. If the file has more, the earliest are kept and the rest are skipped. |
Programs that have already ended don’t count toward the 5,000.
Skipped and trimmed programs
Section titled “Skipped and trimmed programs”Vidori imports every program it can use and tells you about the rest in the warnings under Imported. A program can be skipped (not imported) or trimmed (imported, with its start or end changed).
Skipped
Section titled “Skipped”Vidori sums the skipped programs into one warning, for example 2 programs were skipped: 1 with no title, 1 with no end time. It lists only the reasons that apply:
| Reason in the warning | What it means |
|---|---|
with a time that couldn't be read | start is missing, or start or stop doesn’t match the time format. A missing stop isn’t a reason: the program ends when the next one starts. |
with no title | The program has no <title> with text. |
with no end time | The program has no stop and is the last program, so there is no next start to end it at. |
that ended before they started | stop is at or before start. |
that started at the same time as the next one | The next program starts at the same time, so this one would last no time at all. |
beyond the limit of 5000 programs per upload | The file has more than 5,000 programs that haven’t ended. The earliest 5,000 are kept. |
Programs are put in order by start time first, so the file doesn’t have to be sorted.
Trimmed
Section titled “Trimmed”| Warning | What it means |
|---|---|
N programs overlapped the next one and were shortened | A program ends after the next one starts. Vidori ends it when the next one starts. |
N programs started before the end of the programs already aired and were shortened | A program starts before the last program that has already ended on this channel. Vidori moves its start to that end, so the schedule never overlaps what already aired. |
A warning for exactly one program uses the singular: 1 program overlapped the next one and was shortened.
Left out without a warning
Section titled “Left out without a warning”A program that has already ended is left out, and no warning is shown. It isn’t counted as skipped. If every program in the file has already ended, the whole file is rejected with Every program in the file for channel <channel id> has already ended.
Example
Section titled “Example”This file has one channel and three programs. The first program has its title and description in two languages. The file imports with no warnings:
<?xml version="1.0" encoding="UTF-8"?><tv> <channel id="example-news"> <display-name>Example News</display-name> </channel> <programme start="20261201060000 +0000" stop="20261201090000 +0000" channel="example-news"> <title lang="en">Morning News</title> <title lang="es">Noticias de la mañana</title> <desc lang="en">The day's headlines.</desc> <desc lang="es">Los titulares del día.</desc> </programme> <programme start="20261201090000 +0000" stop="20261201100000 +0000" channel="example-news"> <title lang="en">Business Hour</title> </programme> <programme start="20261201100000 +0000" stop="20261201110000 +0000" channel="example-news"> <title lang="en">Weather</title> </programme></tv>