Editor

xmltv.dtd

<!-- DTD for TV listings

This file is extended to support Android TV Input Framework and static
video contents. You can find the original file at:
http://xmltv.cvs.sourceforge.net/viewvc/xmltv/xmltv/xmltv.dtd

This is a DTD to represent a TV listing.  It doesn't explicitly group
programmes by day or by channel, instead broadcast time and channel
are attributes of the 'programme' element.  Optionally, data about the
TV channels used can be stored in 'channel' elements.

Data about a TV programme are stored in the subelements of element
'programme', but metadata such as when it will be broadcast are stored
as attributes.

Many of the details have a 'lang' attribute so that you can
store them in multiple languages or have mixed languages in a single
listing.  This 'lang' should be the two-letter code such as 'en' or
'fr_FR'.  Or you can just leave it out and let your reader take a
guess.

Unless otherwise specified, an element containing CDATA must have some
text if it is written.

An example XML file for this DTD might look like this:

<tv generator-info-name="my listings generator">
  <channel id="3sat.de">
    <display-name lang="de">3SAT</display-name>
  </channel>
  <channel id="das-erste.de">
    <display-name lang="de">ARD</display-name>
    <display-name lang="de">Das Erste</display-name>
  </channel>

This describes two channels and then a programme broadcast on one of
the channels, then some more programmes.  Almost everything in the DTD
is optional, so you can write files which are much simpler than this
example.

All dates and times in this DTD follow the same format, loosely based
on ISO 8601.  They can be 'YYYYMMDDhhmmss' or some initial
substring, for example if you only know the year and month you can
have 'YYYYMM'.  You can also append a timezone to the end; if no
explicit timezone is given, UTC is assumed.  Examples:
'200007281733 BST', '200209', '19880523083000 +0300'.  (BST == +0100.)

Unless specified otherwise, textual element content may not contain
newlines - this is to make it easy to convert into line-oriented
formats, and to avoid the question of what exactly a newline would
mean in the middle of someone's name or whatever.  Leading and
trailing whitespace in element content is not significant.

At present versions of this DTD correspond to releases of the 'xmltv'
package, which is a set of programs to generate and manipulate files
conforming to this DTD.  Written by Ed Avis (ed@membled.com) and
Gottfried Szing, thanks to others for suggestions.

$Id: xmltv.dtd,v 1.47 2014/05/02 07:27:51 bilbo_uk Exp $

-->

<!-- The root element, tv.

Date should be the date when the listings were originally produced in
whatever format; if you're converting data from another source, then
use the date given by that source.  The date when the conversion
itself was done is not important.

To indicate the source of the listings, there are three attributes you
can define:

'source-info-url' is a URL describing the data source in
some human-readable form.  So if you are getting your listings from
SAT.1, you might set this to the URL of a page explaining how to
subscribe to their feed.  If you are getting them from a website, the
URL might be the index of the site or at least of the TV listings
section.

'source-info-name' is the link text for that URL; it should
generally be the human-readable name of your listings supplier.
Sometimes the link text might be printed without the link itself, in
hardcopy listings for example.

'source-data-url' is where the actual data is grabbed from.  This
should link directly to the machine-readable data files if possible,
but it's not rigorously defined what 'actual data' means.  If you are
parsing the data from human-readable pages, then it's more appropriate
to link to them with the source-info stuff and omit this attribute.

To publicize your wonderful program which generated this file, you can
use 'generator-info-name' (preferably in the form 'progname/version')
and 'generator-info-url' (a link to more info about the program).
-->
<!ELEMENT tv (channel*, programme*)>
<!ATTLIST tv date   CDATA #IMPLIED
             source-info-url     CDATA #IMPLIED
             source-info-name    CDATA #IMPLIED
             source-data-url     CDATA #IMPLIED
             generator-info-name CDATA #IMPLIED
             generator-info-url  CDATA #IMPLIED >

<!-- channel - details of a channel

Each 'programme' element (see below) should have an attribute
'channel' giving the channel on which it is broadcast.  If you want to
provide more detail about channels, you can give some 'channel'
elements before listing the programmes.  The 'id' attribute of the
channel should match what is given in the 'channel' attribute of the
programme.

Typically, all the channels used in a particular TV listing will be
included and then the programmes using those channels.  But it's
entirely optional to include channel details - you can just leave out
channel elements or provide only some of them.  It is also okay to
give just channels and no programmes, if you just want to describe
what TV channels are available in a certain area.

Each channel has one id attribute, which must be unique and should
preferably be in the form suggested by RFC2838 (the 'broadcast'
element of the grammar in that RFC, in other words, a DNS-like name
but without any URI scheme).  Then one or more display names which are
shown to the user.  You might want a different display name for
different languages, but also you can have more than one name for the
same language.  Names listed earlier are considered 'more canonical'.

Since the display name is just there as a way for humans to refer to
the channel, it's acceptable to just put the channel number if it's
fairly universal among viewers of the channel.  But remember that this
isn't an official statement of what channel number has been
allocated, and the same number might be used for a different channel
somewhere else.

The ordering of channel elements makes no difference to the meaning of
the file, since they are looked up by id and not by their position.
However it makes things like diffing easier if you write the channel
elements sorted by ASCII order of their ids.

The repeat-programs attribute is introduced to simulate a live channel.
If "true", the programs in the XML document are scheduled sequentially
in a loop. Program and advertisement start and end times will be shifted
as necessary for looping content. This is Android TV specific.

Attribute introduced by Android TV: repeat-programs.
Child elements introduced by Android TV: display-number, app-link, advertisement.
-->
<!ELEMENT channel (display-name+, display-number, icon*, url*, app-link?, advertisement?)>
<!ATTLIST channel id              CDATA #REQUIRED
                  repeat-programs CDATA #IMPLIED >

<!ELEMENT display-name (#PCDATA)>
<!ATTLIST display-name lang CDATA #IMPLIED>

<!ELEMENT display-number (#PCDATA)>

<!-- A URL where you can find out more about the element that contains
it (programme or channel).  This might be the official site, or a fan
page, whatever you like really.

If multiple url elements are given, the most authoritative or official
(which might conflict...) sites should be listed first.
-->
<!ELEMENT url (#PCDATA)>

<!-- The app-link allows channel input sources to provide activity links
from their live channel programming to another activity. This enables
content providers to increase user engagement by offering the viewer
other content or actions. This is Android TV specific.

'color' is the accent color of the app link template for this channel.
This is primarily used for the background color of the text box in the
template.

'intent-uri' is the intent URI of the app link for this channel. It
should be created using Intent.toUri(int) with Intent.URI_INTENT_SCHEME
(See https://developer.android.com/reference/android/media/tv/TvContract
.Channels.html#COLUMN_APP_LINK_INTENT_URI). The intent is launched when
the user clicks the corresponding app link for the current channel.

'poster-uri' is the URI for the poster art used as the background of the
app link template for this channel.

'text' is the text of the app link template for this channel.

Child elements introduced by Android TV: color, intent-uri, poster-uri,
text.
 -->
<!ELEMENT app-link (icon?)>
<!ATTLIST app-link color      CDATA #IMPLIED
                   intent-uri CDATA #IMPLIED
                   poster-uri CDATA #IMPLIED
                   text       CDATA #IMPLIED >

<!-- programme - details of a single programme transmission

A show will be exactly the same whether it is broadcast at 18:00 or
19:00, and on whichever channel.  Technical details like broadcast
time don't affect the content of the programme itself, so they are
included as attributes of this element.  Start time and channel are
the two that you must include.

Sometimes VCR programming systems like PDC or VPS have their own
notion of 'start time' which is different from the actual start time,
so there are attributes for that.  In practice, stop time will usually
be the start time of the next programme, but if you can get it more
accurate, good for you.  Similarly, you can specify a code for
Gemstar's Showview or VideoPlus programming systems.

TV listings sometimes have the problem of listing two or more
programmes in the same timeslot, such as 'News; Weather'.  We call
this a 'clump' of programmes, and the 'clumpidx' attribute
differentiates between two programmes sharing the same timeslot and
channel.  In this case News would have clumpidx="0/2" and Weather
would have clumpidx="1/2".  If you don't have this problem, be
thankful!

It's intended that start time and stop time, when both are present,
make a half-closed interval: a programme is considered to be
broadcasting _at_ its start time but to stop just before its stop
time.  In this way a programme from 11:00 to 12:00 does not overlap
with another programme from 12:00 to 13:00, not even for a moment.
Nor is there any gap between the two.

To do: Some means of indicating breaks between programmes on the same
channel.  The 'channel' attribute references the 'id' of a channel
element, but the DTD doesn't give a way to specify this constraint.
Perhaps there is some better XML syntax we could use for that.

'video-src' is the video URL for the given program. This can be
omitted if the XML will be used only for the program guide update.
This is Android TV specific.

'video-type' is the video type. Should be one of "HTTP_PROGRESSIVE",
"HLS", and "MPEG-DASH". This can be omitted if the XML will be used
only for the program guide update. This is Android TV specific.

Note that the XML validator in Android Studio requires the ordering
of elements to be aligned with the ordering in dtd. If you see errors
on 'programme' element, please double check the ordering of child
elements in programme.

Attributes introduced by Android TV: video-src, video-type.
Child elements introduced by Android TV: advertisement
-->
<!ELEMENT programme (title+, sub-title*, desc*, credits?, date?,
                     category*, keyword*, language?, orig-language?,
                     length?, icon*, url*, country*, episode-num*,
                     video?, audio?, previously-shown?, premiere?,
                     last-chance?, new?, subtitles*, rating*,
                     star-rating*, review*, advertisement* )>
<!ATTLIST programme start     CDATA #REQUIRED
                    stop      CDATA #IMPLIED
                    pdc-start CDATA #IMPLIED
                    vps-start CDATA #IMPLIED
                    showview  CDATA #IMPLIED
                    videoplus CDATA #IMPLIED
                    channel   CDATA #REQUIRED
                    clumpidx  CDATA "0/1"
                    video-src CDATA #IMPLIED
                    video-type CDATA #IMPLIED >

<!ELEMENT title (#PCDATA)>
<!ATTLIST title lang CDATA #IMPLIED>

<!ELEMENT sub-title (#PCDATA)>
<!ATTLIST sub-title lang CDATA #IMPLIED>

<!-- Description of the programme or episode.

Unlike other elements, long bits of whitespace here are treated as
equivalent to a single space and newlines are permitted, so you can
break lines and write a pretty-looking paragraph if you wish.
-->
<!ELEMENT desc (#PCDATA)>
<!ATTLIST desc lang CDATA #IMPLIED>

<!-- Credits for the programme.

People are listed in decreasing order of importance; so for example
the starring actors appear first followed by the smaller parts.  As
with other parts of this file format, not mentioning a particular
actor (for example) does not imply that he _didn't_ star in the film -
so normally you'd list only the few most important people.

Adapter can be either somebody who adapted a work for television, or
somebody who did the translation from another language.  Maybe these
should be separate, but if so how would 'translator' fit in with the
'language' element?
-->
<!ELEMENT credits (director*, actor*, writer*, adapter*, producer*,
                   composer*, editor*, presenter*, commentator*, 
                   guest* )>
<!ELEMENT director    (#PCDATA)>
<!ELEMENT actor       (#PCDATA)>
<!ATTLIST actor role  CDATA #IMPLIED>
<!ELEMENT writer      (#PCDATA)>
<!ELEMENT adapter     (#PCDATA)>
<!ELEMENT producer    (#PCDATA)>
<!ELEMENT composer    (#PCDATA)>
<!ELEMENT editor      (#PCDATA)>
<!ELEMENT presenter   (#PCDATA)>
<!ELEMENT commentator (#PCDATA)>
<!ELEMENT guest       (#PCDATA)>

<!ELEMENT date (#PCDATA)>

<!ELEMENT category (#PCDATA)>
<!ATTLIST category lang CDATA #IMPLIED>

<!ELEMENT keyword (#PCDATA)>
<!ATTLIST keyword lang CDATA #IMPLIED>

<!-- The language the programme will be broadcast in.  This does not
include the language of any subtitles, but it is affected by dubbing
into a different language.  For example, if a French film is dubbed
into English, language=en and orig-language=fr.

There are two ways to specify the language.  You can use the
two-letter codes such as en or fr, or you can give a name such as
'English' or 'Deutsch'.  In the latter case you might want to use the
'lang' attribute, for example

<language lang="fr">Allemand</language>
-->
<!ELEMENT language (#PCDATA)>
<!ATTLIST language lang CDATA #IMPLIED>

<!ELEMENT orig-language (#PCDATA)>
<!ATTLIST orig-language lang CDATA #IMPLIED>

<!ELEMENT length (#PCDATA)>
<!ATTLIST length units (seconds | minutes | hours) #REQUIRED>

<!-- An icon associated with the element that contains it.
src: uri of image
width, height: (optional) dimensions of image

These dimensions are pixel dimensions for the time being, eventually
this will change to be more like HTML's 'img'.
-->
<!ELEMENT icon EMPTY>
<!ATTLIST icon src         CDATA #REQUIRED
               width       CDATA #IMPLIED
               height      CDATA #IMPLIED>

<!ELEMENT value (#PCDATA)>

<!-- A country where the programme was made or one of the countries in
a joint production.  You can give the name of a country, in which case
you might want to specify the language in which this name is written,
or you can give a two-letter uppercase country code, in which case the
lang attribute should not be given.  For example,

<country lang="en">Italy</country>
<country>GB</country>
-->
<!ELEMENT country (#PCDATA)>
<!ATTLIST country lang CDATA #IMPLIED>

<!-- Episode number

Not the title of the episode, its number or ID.  There are several
ways of numbering episodes, so the 'system' attribute lets you specify
which you mean.

There are two predefined numbering systems, 'xmltv_ns' and
'onscreen'.

xmltv_ns: This is intended to be a general way to number episodes and
parts of multi-part episodes.  It is three numbers separated by dots,
the first is the series or season, the second the episode number
within that series, and the third the part number, if the programme is
part of a two-parter.  All these numbers are indexed from zero, and
they can be given in the form 'X/Y' to show series X out of Y series
made, or episode X out of Y episodes in this series, or part X of a
Y-part episode.  If any of these aren't known they can be omitted.
You can put spaces whereever you like to make things easier to read.

(NB 'part number' is not used when a whole programme is split in two
for purely scheduling reasons; it's intended for cases where there
really is a 'Part One' and 'Part Two'.  The format doesn't currently
have a way to represent a whole programme that happens to be split
across two or more timeslots.)

Some examples will make things clearer.  The first episode of the
second series is '1.0.0/1' .  If it were a two-part episode, then the
first half would be '1.0.0/2' and the second half '1.0.1/2'.  If you
know that an episode is from the first season, but you don't know
which episode it is or whether it is part of a multiparter, you could
give the episode-num as '0..'.  Here the second and third numbers have
been omitted.  If you know that this is the first part of a three-part
episode, which is the last episode of the first series of thirteen,
its number would be '0 . 12/13 . 0/3'.  The series number is just '0'
because you don't know how many series there are in total - perhaps
the show is still being made!

The other predefined system, onscreen, is to simply copy what the
programme makers write in the credits - 'Episode #FFEE' would
translate to '#FFEE'.

You are encouraged to use one of these two if possible; if xmltv_ns is
not general enough for your needs, let me know.  But if you want, you
can use your own system and give the 'system' attribute as a URL
describing the system you use.

Systems proposed in 2013 to refer to common metadatabases in a
common way:
'themoviedb.org' with the content 'movie/1234' to refer to a movie,
'thetvdb.com' with the content 'series/123456' to refer to a series,
'thetvdb.com' with the content 'episode/123456' to refer to one episode
of a series and 'imdb.com' with the content 'title/tt123455' to refer to
a movie, series or episode.

-->
<!ELEMENT episode-num (#PCDATA)>
<!ATTLIST episode-num system CDATA "onscreen">

<!-- Video details: the subelements describe the picture quality as
follows:

present: whether this programme has a picture (no, in the
case of radio stations broadcast on TV or 'Blue'), legal values are
'yes' or 'no'.  Obviously if the value is 'no', the other elements are
meaningless.

colour: 'yes' for colour, 'no' for black-and-white.

aspect: The horizontal:vertical aspect ratio, eg '4:3' or '16:9'.

quality: information on the quality, eg 'HDTV', '800x600'.

-->
<!ELEMENT video (present?, colour?, aspect?, quality?)>
<!ELEMENT present (#PCDATA)>
<!ELEMENT colour (#PCDATA)>
<!ELEMENT aspect (#PCDATA)>
<!ELEMENT quality (#PCDATA)>

<!-- Audio details, similar to video details above.

present: whether this programme has any sound at all, 'yes' or 'no'.

stereo: Description of the stereo-ness of the sound.  Legal values
are currently 'mono','stereo','dolby','dolby digital','bilingual' 
and 'surround'. 'bilingual' in this case refers to a single audio 
stream where the left and right channels contain monophonic audio
in different languages.  Other values may be added later.

-->
<!ELEMENT audio (present?, stereo?)>
<!ELEMENT stereo (#PCDATA)>

<!-- When and where the programme was last shown, if known.  Normally
in TV listings 'repeat' means 'previously shown on this channel', but
if you don't know what channel the old screening was on (but do know
that it happened) then you can omit the 'channel' attribute.
Similarly you can omit the 'start' attribute if you don't know when
the previous transmission was (though you can of course give just the
year, etc.).

The absence of this element does not say for certain that the
programme is brand new and has never been screened anywhere before.
-->
<!ELEMENT previously-shown EMPTY>
<!ATTLIST previously-shown start   CDATA #IMPLIED
                           channel CDATA #IMPLIED >

<!-- 'Premiere'.  Different channels have different meanings for this
word - sometimes it means a film has never before been seen on TV in
that country, but other channels use it to mean 'the first showing of
this film on our channel in the current run'.  It might have been
shown before, but now they have paid for another set of showings,
which makes the first in that set count as a premiere!

So this element doesn't have a clear meaning, just use it to represent
where 'premiere' would appear in a printed TV listing.  You can use
the content of the element to explain exactly what is meant, for
example:

<premiere lang="en">
  First showing on national terrestrial TV
</premiere>

The textual content is a 'paragraph' as for <desc>.  If you don't want
to give an explanation, just write empty content:

<!-- Last-chance.  In a way this is the opposite of premiere.  Some
channels buy the rights to show a movie a certain number of times, and
the first may be flagged 'premiere', the last as 'last showing'.

For symmetry with premiere, you may use the element content to give a
'paragraph' describing exactly what is meant - it's unlikely to be the
last showing ever!  Otherwise, explicitly put empty content:

<last-chance />
-->
<!ELEMENT last-chance (#PCDATA)>
<!ATTLIST last-chance lang CDATA #IMPLIED>

<!-- New.  This is the first screened programme from a new show that
has never been shown on television before - if not worldwide then at
least never before in this country.  After the first episode or
programme has been shown, subsequent ones are no longer 'new'.
Similarly the second series of an established programme is not 'new'.

Note that this does not mean 'new season' or 'new episode' of an
existing show.  You can express part of that using the episode-num
stuff.
-->
<!ELEMENT new EMPTY>

<!ELEMENT subtitles (language?)>
<!ATTLIST subtitles type (teletext | onscreen | deaf-signed) #IMPLIED>

<!ELEMENT rating (value, icon*)>
<!ATTLIST rating system CDATA #IMPLIED>

<!ELEMENT star-rating (value, icon*)>
<!ATTLIST star-rating system CDATA #IMPLIED>

<!ELEMENT review (#PCDATA)>
<!ATTLIST review type     (text | url) #REQUIRED
                 source   CDATA        #IMPLIED
                 reviewer CDATA        #IMPLIED
                 lang     CDATA        #IMPLIED>

<!-- Advertisement. This is Android TV specific element to support advertisement insertion in
program. A programme may have multiple advertisements.

'start' and 'stop' is the start/end time of advertisement.The time of advertisement cannot overlap
with another advertisement.

'type' is a require attributes for advertisement type.

Child elements introduced by Android TV: request-url.
-->
<!ELEMENT advertisement (request-url)>
<!ATTLIST advertisement start CDATA #IMPLIED
                        stop  CDATA #IMPLIED
                        type  CDATA #REQUIRED>

<!-- URL for requesting advertisement from providers. Since many request URLs contain special
characters (such as ampersand) which violate the XML encode schema, <![CDATA[]]> is recommended to
avoid XML parser misinterpreting. For example:

<request-url><![CDATA[https://example.com?sz=640x480&impl=s&gdfp_req=1]]></request-url>

If there is no special characters or they are properly handled by escaping, <![CDATA[]]> is not
required.
-->
<!ELEMENT request-url (#PCDATA)>