View source

This is a proposal by [http://www.bucksch.org Ben Bucksch] and used by a TV system created by him. This is an alternative to [[LineupProposal]].

= Purpose =

During setup of a TV (recording) system, it is not only necessary to find channels by a channel scan, but also to properly name and sort the channels, and to assign the [[RFC 2838]]-IDs, which associate the station to schedule information from XMLTV. This file format provides this information.

It is separate from the scheduling (programme) information in the [[XMLTVFormat|XMLTV XML format]].

= Source =

This file shall be (if so decided by XMLTV project) provided by the grabber, when called with a commandline flag <code>--list-channels</code> (or similar). The grabber may compile the file from information from the grabber source, or via a static list, or (usually) a mix of both.

The file may also be retrieved from other sources, e.g. web service which just lists satellite channels, or from a static location provided by the vendor of the TV system, or from the XMLTV web server (http://supplement.xmltv.org).

The presets and long/short names are a matter of judgment, and to be decided on by the grabber author (assuming he's unbiased), XMLTV project or similar. The only consideration should be how users (TV watchers) would like to see/use it. If the grabber source or station networks happen to provide presets, but they are not ideal in the way users would want it, the commercial interests are to be ignored and manually managed preset lists should be used.

= Structure =

This format uses the term "channel" differently from the XMLTV DTD.
* A "station" is defined by the programmes, the content of the media. E.g. "BBC 1" is a station, and it airs the BBC news show at 8 PM. This is what you see in your TV guide and what the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast. This is how you receive the actual video and audio.
E.g. The DVB-T channel in Cologne on frequency 129050000 Hz, with service ID 1802, is a channel, and the analog PAL channel E51 in Cologne is a different channel. But both may transmit the same station: ZDF.

It is very common for one station to be transmitted on many different channels, sometimes even several of them received by the same TV/computer (e.g. one via DVB-T and one via DVB-C or DVB-S).
Similarly, there are stations which are transmitted as HDTV and as SD, with the same content (apart from technical quality) - these are also different channels for the same station.

We separate the problem into two parts:
# Identify a channel (which we found during scan) as a certain station (by its [[RFC 2838]] ID).
# Get metadata about a station, like long and short display names, logo, and the default preset number.

The <*-channel> elements do the first, the <station> elements do the latter.

= Example =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml Example file] (for Germany, DVB-S Astra 19.2°)

= Definition =

Unless mentioned otherwise, each element underneath <station> and <*-channel> may appear only once. Applications should ignore additional elements of the same tag name and use the first. Of course, <station> and <*-channel> may appear several times.

== XML structure ==

 <lineup>
   <stations>
     <station rfc2838id="zdf.de">
       <long-name>ZDF</long-name>
       ...
     </station>
     <station rfc2838id="1.bbc.co.uk">
      ...
     </station>
     ...
   </stations>
   <channels>
     <dvb-channel rfc2838id="zdf.de">
       <dvb-id service="28006" transport="1079" network="1" />
       ...
     </dvb-channel>
     <dvb-channel rfc2838id="1.bbc.co.uk">
       <dvb-id service="2" transport="28" network="1" />
       ...
     </dvb-channel>
     ...
     <analog-channel rfc2838id="1.bbc.co.uk">
       <cni tt-8-30-1="0x447F" />
     </analog-channel>
     ...
   </channels>
 </lineup>

''TODO'' better word for "lineup"? At least define what the word "lineup" means.

== Stations ==

 <station rfc2838id="zdf.de">
   <long-name>ZDF</long-name>
   <short-name>ZDF</short-name>
   <preset>2</preset>
   <logo url="http://example.com /zdf.gif"/>
   <group>oeff-rechtl</group>
   <commercial-free>true</commercial-free>
 </station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [[RFC 2838]]. It must follow the rules in the RFC, and the should match ID used by the XMLTV grabbers for the country of the station.

This links the station to the XMLTV data, and also links the <station> to the <*-channel> elements within this document.

Each rfc2838id must only appear in one <station> element in a document, i.e. there must not be two <station>s with the same rfc2838id. (There may be several <*-channel> elements with the same rfc2838id, though.)

'''Long name''' (mandatory)

The display name of the station, as shown to the user - long version.
This is not necessarily the official legal name of the station, but a name that people find nice in unambiguously identifying the station.
Should be used in places in the UI where display space is not short.

It should be no longer than 30-50 characters. Spaces are allowed. May contain UTF characters.

Examples: "National Geographic", "BBC 1" (same as short name), "Sky Entertainment 1"

'''Short name''' (mandatory)

The display name of the station, as shown to the user - short version.
A name that people find nice in unambiguously identifying the station, but at the same time short.
To be used in places in the UI where display space is short.

Must not be longer than 10 characters (hard limit). Spaces are allowed.<br>
Ideally <= 5 characters. Ideally, only characters A-Z, 0-9 and space are used.

Examples: "BBC 1", "NatGeo", "Sky Entert"

'''preset''' (optional)

The number that the user keys in on the remote control to change to this station.
Also used for sorting channels, where channels are listed. This allows
* to put the most important channels first
* to adhere to local conventions, e.g. BBC1 is expected on button 1 in the UK, while German users expect ARD on 1 and ZDF on 2.
* to create a logical order (e.g. news stations together, kids stations together, or a certain pay-TV bouquet together).

This is also useful for satellite users (e.g. Astra in Europe) which receive >1000 channels, but 98% of them are essentially 'spam'. The "spam"-channels should have no preset.

This element may be omitted, in which case the channel is to be put ''after'' the channels with a preset.

This element only gives a default preset. A user should be able to easily change it at will (in a configuration/setup program), and the user's choice must be preserved over the choice here.
''TODO'' what to do when the presets here are re-arranged, and a new channel has the same preset that the user assigned to another channel? Find first free channel after the assigned one? Can get complicated, esp. on the next change after that.

'''group''' (optional)

This is another way to sort channels. You can assign a common string to a set of channels, to reflect that they are in some way related and could be displayed together.

E.g. you may mark all Canal+ pay-TV stations as group "Canal+", or all news stations as group "news" and all cartoon stations as group "kids". There can (currently) only be one group per station, so if Canal+ broadcasts cartoon stations, decide for either "Canal+" or "kids".

The group name may or may not be displayed to the user, and may not have any effect at all.

'''logo''' (optional)

The attribute '''url''' (mandatory) contains the URL (http: or file:) to a PNG, JPEG or GIF image of the station's logo.

The attribute '''res''' (optional) contains the size of the image in pixels, in form width "x" height, e.g. "64x48".

The element <logo> may be included several times, to include several logos of different sizes/resolutions.

'''commercial-free''' (optional)

boolean: "true" or "false". Whether the station has advertisement in the content. Advertisements may be
* between programmes (e.g. only before and after movies, not during the movie)
* in the middle of the programmes (e.g. an interruption for 30 seconds every 10 minutes or for 5 minutes every 40 minutes)
* on top of the programme (e.g. while the movie is running, there is an overlay text or icon or sound, which advertises for a product, service or for another show on the same station).
* part of the programme (e.g. sponsoring, product placement etc.)

It is up to the data source to make an (unbiased) judgment decision which stations are considered commercial-free. For example, you may label stations which have advertisements only between movies, and include the full teaser and end credits of the movie still as "commercial-free". You may also not count the airing of a Hollywood movie as product placement, but a pure home shopping station as non-stop advertisement.

== DVB Channels ==

 <dvb-channel rfc2838id="zdf.de">
   <dvb-name provider="ZDFvision" service="ZDF"/>
   <dvb-id service="28006" transport="1079" network="1" />
   <encrypted>false</encrypted>
 </dvb-channel>


'''rfc2838id''' (mandatory)

The ID of the station, see <station>. Allows to link the channel to the <station>.

Several <dvb-channel> or <*-channel> elements with the same rfc2838id are allowed and intended. In fact, that's why <station> and <*-channel> are separate.

'''dvb-id''' (optional)

The "'''service''' ID", "'''transport''' ID" (also called "transponder ID") and "original '''network''' ID" (in decimal numbers), as transmitted on the DVB stream in the PAT, SDT and NIT.

All of service, transport and network must be given, they are only valid as a triple. An application should not use only the serviceID, but the whole triple, to identify a channel, as the same service ID (e.g. 2) may be used for entirely different channels/stations on different transponders.

This is the preferred way to identify a DVB channel. However, it may differ for each DVB-T and DVB-C region/broadcaster, so that's why dvb-name is provided as fallback way to identify the channel.

'''dvb-name''' (optional)

The "'''service''' name" and "'''provider''' name" strings, as transmitted on the DVB stream in the SDT.

It should be unique per station (modulo HD), i.e. should be the same on DVB-T, DVB-C and DVB-S (in the same country / station cover area). So, ideally, there should only be one DVB service name for the same station, no matter which DVB transport medium or location, making identification easy and our list short.

However, in practice, some operators / cable head stations mess up and use e.g. "ZDFinfo" vs. "ZDF info" vs. "ZDFinfokanal" for the same station. In this case, include several <dvb-channel> elements, with all variations, all pointing to the same rfc2838id, but only one <station>.

The provider name is optional, but should be included when known. An application may chose to ignore the provider name, depending on experiences.

'''encrypted''' (optional)

The channel is scrambled and can only be used if the user has a specific descrambler and appropriate smart card. This is used for
* Pay-TV
* some cable systems
* to limit the geographical coverage (e.g. to Austria, to block German viewers, to reduce movie license costs).

If the channel is scrambled, this element is mandatory and must contain the text "true", otherwise it can either be omitted or contain "false".

== Analog channels ==

=== Analog US ===

 <analog-channel rfc2838id="1.bbc.co.uk">
   <fcc-callsign>BBC1</fcc-callsign>
   <frequency number="E51" system="NTSC-M" />
 </analog-channel> 

'''rfc2838id''' (mandatory)

See <dvb-channel>

'''fcc-callsign''' (optional)

For the US, where the FCC assigns a unique identifier with up to 5 characters. It is transmitted on the air via [http://en.wikipedia.org/wiki/Extended_Data_Services XDS] [http://www.ce.org/Standards/browseByCommittee_2523.asp Standard].

Other countries don't maintain official (not even unofficial) callsigns. Do not use this element for other identification schemes than the FCC-assigned US callsigns.

'''frequency''' (optional)

Mainly (but not exclusively) for the US, where Schedule Direct and other grabbers provide regional tuning data. For the user's (or application's) convenience. Only provide this information, if you know it is applicable (tunable) for this user, e.g. after having asked him about his physical location and/or reception method.

The '''system''' (mandatory) is the television system, including the tuning tables, e.g. "NTSC-M" or "PAL-G".
The '''number''' is the channel number in the tuning tables, e.g. "5" or "54". It may contain letters, e.g. "E51" or "S05" for extended and special channels, which have been added later to the VHF or UHF spectrum. Length <= 5 characters.

=== Analog EU ===

 <analog-channel rfc2838id="1.bbc.co.uk">
   <cni tt-8-30-1="0x447F" />
 </analog-channel>

'''cni tt-8-30-1''' (optional)

For the EU, where a numerical CNI of the station is transmitted in Teletext packet 8/30 format 1. In hex, with preceding "0x".

Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://tech.ebu.ch/publications/PDC-VPS ETSI TS 101 231]

Note that there's also a Teletext packet 8/30 format 2, which is also a station ID, but different numbers, therefore the complicated element name.

== IPTV channels ==

 <iptv-channel rfc2838id="1.bbc.co.uk">
   <iptv-url>rtsp://....</iptv-url>
 </iptv-channel>

'''iptv-url''' (mandatory)

Where to fetch the media stream.

''TODO''