Skip to content

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.

  • One file per upload, .xml, up to 20 MB.
  • The root element must be <tv>.
  • Vidori reads six things: the id of each <channel>, its <display-name>, and, for each <programme>, the channel, start and stop attributes 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.

Only elements directly under <tv> are read.

Element or attributeWhat 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.

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, 202612010600 and 20261201060000 are all accepted. A missing hour, minute or second counts as 00.
  • 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 +0100 and 20261201060000+0100 mean 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.

Vidori keeps one title and one description per language.

  • The lang attribute is the language of that title or description, for example en or es. Capital letters are treated as lowercase.
  • A title or description without lang is 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.

An XMLTV file can hold the programs of many channels. Vidori imports the programs of one channel, picked in this order:

  1. The channel you pick, when the file has several channels and Vidori asks.
  2. The channel from your last upload, when the new file contains the same channel id. The admin panel shows it as XMLTV channel id.
  3. 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.

LimitValue
File size20 MB
Programs per upload5,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.

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).

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 warningWhat it means
with a time that couldn't be readstart 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 titleThe program has no <title> with text.
with no end timeThe program has no stop and is the last program, so there is no next start to end it at.
that ended before they startedstop is at or before start.
that started at the same time as the next oneThe next program starts at the same time, so this one would last no time at all.
beyond the limit of 5000 programs per uploadThe 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.

WarningWhat it means
N programs overlapped the next one and were shortenedA 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 shortenedA 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.

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.

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>