Revision as of 23:13, 17 August 2009

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 RCF2838-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 XMLTV XML format.

This is an alternative to LineupProposal.

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 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:

1. Identify a channel (which we found during scan) as a certain station (by its RFC2838 ID).
2. 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.

Definition

Example file (for Germany, DVB-S Astra 19.2°)

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=""/>
  <group>oeff-rechtl</group>
  <commercial-free>true</commercial-free>
</station>

rfc2838id (mandatory)

The globally unique ID of the station, per RFC2838. 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.

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. Ideally <= 5 characters. Ideally, only characters A-Z, 0-9 and space are used.

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

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 or sort channels. You can assign a common string as group 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 "news".

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). 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 XDS 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. Compare Zapping API docs. The list of station IDs is at ETSI TR 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