XMLTV - User contributions [en]

LineupProposal2

2009-08-18T11:25:31Z

Benb: /* Stations */ Examples

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

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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.

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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:16:59Z

Benb: /* 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 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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:15:06Z

Benb: /* 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 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.

= 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 ("supplement").

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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:13:53Z

Benb: /* 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 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.

= 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 ("supplement").

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:11:49Z

Benb: /* 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 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.

= 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 ("supplement").

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:10:51Z

Benb: /* 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 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.

= 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 ("supplement").

The presets and long/short names are a matter of judgment, and to be decided on by the grabber author, XMLTV project or similar. The only consideration should be how users (TV watchers) would like to see/use it.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T11:08:44Z

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

= 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 ("supplement").

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T10:55:30Z

Benb: /* Analog EU */

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T10:54:53Z

Benb: /* Analog EU */ cni in hex

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T10:51:52Z

Benb: /* Stations */

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T10:44:08Z

Benb: /* Stations */

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. 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 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T10:43:23Z

Benb: /* Stations */

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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'. The "spam"-channels get 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 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-18T06:46:42Z

Benb:

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

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.

= 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:37:06Z

Benb: /* Stations */

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

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 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 RFC2838 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 [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:35:31Z

Benb: /* Definition */

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

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 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 RFC2838 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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:33:05Z

Benb: /* Structure */

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

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 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 RFC2838 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 and <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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:27:34Z

Benb: author

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

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:
# Identify a channel (which we found during scan) as a certain station (by its RFC2838 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 and <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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:21:59Z

Benb: /* Definition */

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:
# Identify a channel (which we found during scan) as a certain station (by its RFC2838 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 and <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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:21:34Z

Benb: /* Definition */ Each element only once.

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

= Definition =

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

Unless mentioned otherwise, each element underneath and <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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:19:08Z

Benb: /* DVB Channels */

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). 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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal2

2009-08-17T23:18:25Z

Benb: /* DVB Channels */

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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). So, ideally, there should only be one DVB service name for the same station, no matter which DVB transport medium or location.

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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal

2009-08-17T23:14:48Z

Benb: /* Analog TV */ Fix header

== Lineup Proposal ==

Proposal by [[User:MattiasHolmlund|Mattias Holmlund]].

(There is an alternate proposal on [[LineupProposal2]]).

This page describes my proposal for a new capability for grabbers that I call "lineups". It has not yet been decided on and no grabber implements it.

The problem as I see it is that we need a way for applications such as MythTV to connect the channels that it can find on a videosource (a TV-card for example) to the xmltvids that it gets from the xmltv grabber. Each channel contained in an xmltv-file can be a part of several different lineups. This means that we need to be able to supply several different mappings for one channel. The mapping for a channel will also differ depending on which lineup the user has selected. Therefore, I think we need to have the lineup information separate from the channel-section of the xmltv-file. Note that the lineup information can in some cases contain mappings for channels that the grabber does not have schedule data for.

Furthermore, I don't think we need to include the lineup information every time the grabber downloads schedules data. The PVR application will typically need lineup-information after a channel scan or when it detects that something has changed in the lineup via other means (changed service-name in an mpeg-stream etc.) The lineup-information will for at least some grabbers not come from the same source as the data. I would guess that at least some of the grabbers would fetch the lineup-data from community-run sites, and I think we can save a lot of bandwidth for these sites if we only download lineup-data when the PVR application really needs it.

The mapping from tuning data to xmltvid is different for different providers. However, it is also different depending on the type of videosource. For analog TV, the mapping can be expressed as a frequency to xmltvid mapping. For DVB-T, several channels can share a single frequency (multiplex) and it is pretty easy to scan all frequencies, so there we can use the provider-name and service-name inside the MPEG-stream and map it to an xmltvid instead. For IP-TV, we can map a url for the stream to the xmltvid. For IP Multicast-TV we map a multicast IP address and port-number to the xmltvid.

These mappings can be described in lineups. A lineup contains a set of channels that a customer can order from his provider. I would propose that lineups are not included in the xmltv-format and that they are instead described in separate xml-files. We can write the DTD as a part of the xmltv-project, but it should be separate from the current xmltv dtd.

A sample lineup could look like this:

<xmltv-lineup type="DVB-T">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

Note that there is a display-name for each channel even though this display-name can be found in the xmltv-file. The reason for this is that we might not have data for all channels, and then the user will at least have a display-name.

The grabber shall support two new command-line options: --lineup and --list-lineups. They are used as follows:

First, the application lets the user configure the grabber just as before. During the configuration, the grabber asks the user questions so it can learn which lineups the user has access to. How this is done is up to the grabber, but typically the user will be able to choose between a set of lineups somehow. The user shall be able to select several lineups at once. If a user chooses one or more lineups, it will probably not make sense to ask the user which channels he wants to download data for, since this is given by which lineups he has chosen.

When the configuration is done, the application can ask the user which lineups the user has chosen with the --list-lineups parameter:

$ tv_grab_se_swedb --list-lineups
stockholm.fri.boxer.se|DVB-T|Boxer Fri Stockholm
total.canalplus.se|DVB-S|Canal+ Total

The application can then ask for detailed information about each lineup with the --lineup parameter:

$ tv_grab_se_swedb --lineup stockholm.fri.boxer.se
<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

== Lineup types ==

We need to define the lineup-format for all available types of TV-sources and preferably radio as well.

=== List ===

The simplest type of lineup is the "list". This only contains a list of channels with a display-name and an optional preferred-preset. It is useful in cases when we don't have any other information available. It cannot be used to map channels to xmltvids, but it can be used to select a set of channels that you want to receive data for.

<xmltv-lineup type="list" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

The preferred-preset field tells the application which "button on the remote" this channel should preferably be connected to. This field is optional.

All other lineup-types are extensions of the list-type.

=== DVB-T ===

For DVB-T, it is fairly easy for an application to scan all available frequencies and find all channels. Therefore, we don't need to include the frequencies in the lineup. Instead, we only include enough information to allow the application to uniquely identify each channel. Each channel in a DVB-T stream is identified by a provider-name and a service-name, so we can use these.

<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2</service-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

One advantage of not including the frequencies is that the number of different lineups decreases. This is because several different regions can use the exact same lineup even though they use different frequencies. In Sweden for example, we have roughly 50 different transmitters operating on different frequencies, but the country is only divided into five different regions for lineups.

I think that DVB-S and DVB-C can use the same format and possibly also ATSC. So we might want to call the lineup-type DTV instead.

=== Analog TV ===

For analog TV we have to use the frequency to identify the channel since there is no other channel identifier available.

Should we use frequenzies (in Hz) or frequency numbers? Do the channel numbers mean the same frequency in all countries? How about Analog Cable?

<xmltv-lineup type="Analog" id="chateau.latresne.33.fr">
<display-name lang="fr">33 - Latresne - Chateau d'Eau</display-name>

<channel id="france2.fr">
<display-name lang="fr">France 2</display-name>
<preferred-preset>2</preferred-preset>
<frequency-number>31</frequency-number>
</channel>

<channel id="france3.fr">
<display-name lang="fr">France 3</display-name>
<preferred-preset>3</preferred-preset>
<frequency-number>34</frequency-number>
</channel>
</xmltv-lineup>

=== IP TV ===

Identify each channel with a url such as rtsp://...

=== IP Multicast TV ===

Identify each channel with an IP multicast address and a port-number.

=== STB ===

In some countries, it is common with computers that get their video signal from an STB (Set-Top Box) and to change the channel, you have to tell the STB to change to a different preset.

<xmltv-lineup type="STB" id="stb.stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<preset>1</preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
<preset>2</preset>
</channel>
</xmltv-lineup>

Note the difference between preferred-preset and preset here. preset is the number that you have to tune the STB to to receive the channel. preferred-preset is the channel number that the user will likely prefer to have the channel mapped to on the remote to his computer. These two fields will likely contain the same value, but they are separate.

LineupProposal2

2009-08-17T23:13:33Z

Benb: /* IPTV channels */

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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''

LineupProposal

2009-08-17T23:13:10Z

Benb: /* STB */ Fix header

== Lineup Proposal ==

Proposal by [[User:MattiasHolmlund|Mattias Holmlund]].

(There is an alternate proposal on [[LineupProposal2]]).

This page describes my proposal for a new capability for grabbers that I call "lineups". It has not yet been decided on and no grabber implements it.

The problem as I see it is that we need a way for applications such as MythTV to connect the channels that it can find on a videosource (a TV-card for example) to the xmltvids that it gets from the xmltv grabber. Each channel contained in an xmltv-file can be a part of several different lineups. This means that we need to be able to supply several different mappings for one channel. The mapping for a channel will also differ depending on which lineup the user has selected. Therefore, I think we need to have the lineup information separate from the channel-section of the xmltv-file. Note that the lineup information can in some cases contain mappings for channels that the grabber does not have schedule data for.

Furthermore, I don't think we need to include the lineup information every time the grabber downloads schedules data. The PVR application will typically need lineup-information after a channel scan or when it detects that something has changed in the lineup via other means (changed service-name in an mpeg-stream etc.) The lineup-information will for at least some grabbers not come from the same source as the data. I would guess that at least some of the grabbers would fetch the lineup-data from community-run sites, and I think we can save a lot of bandwidth for these sites if we only download lineup-data when the PVR application really needs it.

The mapping from tuning data to xmltvid is different for different providers. However, it is also different depending on the type of videosource. For analog TV, the mapping can be expressed as a frequency to xmltvid mapping. For DVB-T, several channels can share a single frequency (multiplex) and it is pretty easy to scan all frequencies, so there we can use the provider-name and service-name inside the MPEG-stream and map it to an xmltvid instead. For IP-TV, we can map a url for the stream to the xmltvid. For IP Multicast-TV we map a multicast IP address and port-number to the xmltvid.

These mappings can be described in lineups. A lineup contains a set of channels that a customer can order from his provider. I would propose that lineups are not included in the xmltv-format and that they are instead described in separate xml-files. We can write the DTD as a part of the xmltv-project, but it should be separate from the current xmltv dtd.

A sample lineup could look like this:

<xmltv-lineup type="DVB-T">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

Note that there is a display-name for each channel even though this display-name can be found in the xmltv-file. The reason for this is that we might not have data for all channels, and then the user will at least have a display-name.

The grabber shall support two new command-line options: --lineup and --list-lineups. They are used as follows:

First, the application lets the user configure the grabber just as before. During the configuration, the grabber asks the user questions so it can learn which lineups the user has access to. How this is done is up to the grabber, but typically the user will be able to choose between a set of lineups somehow. The user shall be able to select several lineups at once. If a user chooses one or more lineups, it will probably not make sense to ask the user which channels he wants to download data for, since this is given by which lineups he has chosen.

When the configuration is done, the application can ask the user which lineups the user has chosen with the --list-lineups parameter:

$ tv_grab_se_swedb --list-lineups
stockholm.fri.boxer.se|DVB-T|Boxer Fri Stockholm
total.canalplus.se|DVB-S|Canal+ Total

The application can then ask for detailed information about each lineup with the --lineup parameter:

$ tv_grab_se_swedb --lineup stockholm.fri.boxer.se
<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

== Lineup types ==

We need to define the lineup-format for all available types of TV-sources and preferably radio as well.

=== List ===

The simplest type of lineup is the "list". This only contains a list of channels with a display-name and an optional preferred-preset. It is useful in cases when we don't have any other information available. It cannot be used to map channels to xmltvids, but it can be used to select a set of channels that you want to receive data for.

<xmltv-lineup type="list" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

The preferred-preset field tells the application which "button on the remote" this channel should preferably be connected to. This field is optional.

All other lineup-types are extensions of the list-type.

=== DVB-T ===

For DVB-T, it is fairly easy for an application to scan all available frequencies and find all channels. Therefore, we don't need to include the frequencies in the lineup. Instead, we only include enough information to allow the application to uniquely identify each channel. Each channel in a DVB-T stream is identified by a provider-name and a service-name, so we can use these.

<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2</service-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

One advantage of not including the frequencies is that the number of different lineups decreases. This is because several different regions can use the exact same lineup even though they use different frequencies. In Sweden for example, we have roughly 50 different transmitters operating on different frequencies, but the country is only divided into five different regions for lineups.

I think that DVB-S and DVB-C can use the same format and possibly also ATSC. So we might want to call the lineup-type DTV instead.
Analog TV

For analog TV we have to use the frequency to identify the channel since there is no other channel identifier available.

Should we use frequenzies (in Hz) or frequency numbers? Do the channel numbers mean the same frequency in all countries? How about Analog Cable?

<xmltv-lineup type="Analog" id="chateau.latresne.33.fr">
<display-name lang="fr">33 - Latresne - Chateau d'Eau</display-name>

<channel id="france2.fr">
<display-name lang="fr">France 2</display-name>
<preferred-preset>2</preferred-preset>
<frequency-number>31</frequency-number>
</channel>

<channel id="france3.fr">
<display-name lang="fr">France 3</display-name>
<preferred-preset>3</preferred-preset>
<frequency-number>34</frequency-number>
</channel>
</xmltv-lineup>

=== IP TV ===

Identify each channel with a url such as rtsp://...

=== IP Multicast TV ===

Identify each channel with an IP multicast address and a port-number.

=== STB ===

In some countries, it is common with computers that get their video signal from an STB (Set-Top Box) and to change the channel, you have to tell the STB to change to a different preset.

<xmltv-lineup type="STB" id="stb.stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<preset>1</preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
<preset>2</preset>
</channel>
</xmltv-lineup>

Note the difference between preferred-preset and preset here. preset is the number that you have to tune the STB to to receive the channel. preferred-preset is the channel number that the user will likely prefer to have the channel mapped to on the remote to his computer. These two fields will likely contain the same value, but they are separate.

LineupProposal2

2009-08-17T23:11:44Z

Benb: Link other proposal.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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>rtp://....</iptv-url>
</iptv-channel>

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

Where to fetch the media stream.

''TODO''

LineupProposal

2009-08-17T23:09:43Z

Benb: /* Lineup Proposal */ link my proposal 2

== Lineup Proposal ==

Proposal by [[User:MattiasHolmlund|Mattias Holmlund]].

(There is an alternate proposal on [[LineupProposal2]]).

This page describes my proposal for a new capability for grabbers that I call "lineups". It has not yet been decided on and no grabber implements it.

The problem as I see it is that we need a way for applications such as MythTV to connect the channels that it can find on a videosource (a TV-card for example) to the xmltvids that it gets from the xmltv grabber. Each channel contained in an xmltv-file can be a part of several different lineups. This means that we need to be able to supply several different mappings for one channel. The mapping for a channel will also differ depending on which lineup the user has selected. Therefore, I think we need to have the lineup information separate from the channel-section of the xmltv-file. Note that the lineup information can in some cases contain mappings for channels that the grabber does not have schedule data for.

Furthermore, I don't think we need to include the lineup information every time the grabber downloads schedules data. The PVR application will typically need lineup-information after a channel scan or when it detects that something has changed in the lineup via other means (changed service-name in an mpeg-stream etc.) The lineup-information will for at least some grabbers not come from the same source as the data. I would guess that at least some of the grabbers would fetch the lineup-data from community-run sites, and I think we can save a lot of bandwidth for these sites if we only download lineup-data when the PVR application really needs it.

The mapping from tuning data to xmltvid is different for different providers. However, it is also different depending on the type of videosource. For analog TV, the mapping can be expressed as a frequency to xmltvid mapping. For DVB-T, several channels can share a single frequency (multiplex) and it is pretty easy to scan all frequencies, so there we can use the provider-name and service-name inside the MPEG-stream and map it to an xmltvid instead. For IP-TV, we can map a url for the stream to the xmltvid. For IP Multicast-TV we map a multicast IP address and port-number to the xmltvid.

These mappings can be described in lineups. A lineup contains a set of channels that a customer can order from his provider. I would propose that lineups are not included in the xmltv-format and that they are instead described in separate xml-files. We can write the DTD as a part of the xmltv-project, but it should be separate from the current xmltv dtd.

A sample lineup could look like this:

<xmltv-lineup type="DVB-T">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

Note that there is a display-name for each channel even though this display-name can be found in the xmltv-file. The reason for this is that we might not have data for all channels, and then the user will at least have a display-name.

The grabber shall support two new command-line options: --lineup and --list-lineups. They are used as follows:

First, the application lets the user configure the grabber just as before. During the configuration, the grabber asks the user questions so it can learn which lineups the user has access to. How this is done is up to the grabber, but typically the user will be able to choose between a set of lineups somehow. The user shall be able to select several lineups at once. If a user chooses one or more lineups, it will probably not make sense to ask the user which channels he wants to download data for, since this is given by which lineups he has chosen.

When the configuration is done, the application can ask the user which lineups the user has chosen with the --list-lineups parameter:

$ tv_grab_se_swedb --list-lineups
stockholm.fri.boxer.se|DVB-T|Boxer Fri Stockholm
total.canalplus.se|DVB-S|Canal+ Total

The application can then ask for detailed information about each lineup with the --lineup parameter:

$ tv_grab_se_swedb --lineup stockholm.fri.boxer.se
<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2 ABC</service-name>
</channel>
</xmltv-lineup>

== Lineup types ==

We need to define the lineup-format for all available types of TV-sources and preferably radio as well.

=== List ===

The simplest type of lineup is the "list". This only contains a list of channels with a display-name and an optional preferred-preset. It is useful in cases when we don't have any other information available. It cannot be used to map channels to xmltvids, but it can be used to select a set of channels that you want to receive data for.

<xmltv-lineup type="list" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

The preferred-preset field tells the application which "button on the remote" this channel should preferably be connected to. This field is optional.

All other lineup-types are extensions of the list-type.

=== DVB-T ===

For DVB-T, it is fairly easy for an application to scan all available frequencies and find all channels. Therefore, we don't need to include the frequencies in the lineup. Instead, we only include enough information to allow the application to uniquely identify each channel. Each channel in a DVB-T stream is identified by a provider-name and a service-name, so we can use these.

<xmltv-lineup type="DVB-T" id="stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT1</service-name>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<provider-name>Sveriges Television</provider-name>
<service-name>SVT2</service-name>
<preferred-preset>2</preferred-preset>
</channel>
</xmltv-lineup>

One advantage of not including the frequencies is that the number of different lineups decreases. This is because several different regions can use the exact same lineup even though they use different frequencies. In Sweden for example, we have roughly 50 different transmitters operating on different frequencies, but the country is only divided into five different regions for lineups.

I think that DVB-S and DVB-C can use the same format and possibly also ATSC. So we might want to call the lineup-type DTV instead.
Analog TV

For analog TV we have to use the frequency to identify the channel since there is no other channel identifier available.

Should we use frequenzies (in Hz) or frequency numbers? Do the channel numbers mean the same frequency in all countries? How about Analog Cable?

<xmltv-lineup type="Analog" id="chateau.latresne.33.fr">
<display-name lang="fr">33 - Latresne - Chateau d'Eau</display-name>

<channel id="france2.fr">
<display-name lang="fr">France 2</display-name>
<preferred-preset>2</preferred-preset>
<frequency-number>31</frequency-number>
</channel>

<channel id="france3.fr">
<display-name lang="fr">France 3</display-name>
<preferred-preset>3</preferred-preset>
<frequency-number>34</frequency-number>
</channel>
</xmltv-lineup>

=== IP TV ===

Identify each channel with a url such as rtsp://...

=== IP Multicast TV ===

Identify each channel with an IP multicast address and a port-number.
STB

In some countries, it is common with computers that get their video signal from an STB (Set-Top Box) and to change the channel, you have to tell the STB to change to a different preset.

<xmltv-lineup type="STB" id="stb.stockholm.fri.boxer.se">
<display-name lang="sv">Boxer Fri Stockholm</display-name>

<channel id="svt1.svt.se">
<display-name lang="sv">SVT 1</display-name>
<preferred-preset>1</preferred-preset>
<preset>1</preset>
</channel>

<channel id="svt2.svt.se">
<display-name lang="sv">SVT 2</display-name>
<preferred-preset>2</preferred-preset>
<preset>2</preset>
</channel>
</xmltv-lineup>

Note the difference between preferred-preset and preset here. preset is the number that you have to tune the STB to to receive the channel. preferred-preset is the channel number that the user will likely prefer to have the channel mapped to on the remote to his computer. These two fields will likely contain the same value, but they are separate.

LineupProposal2

2009-08-17T23:07:11Z

Benb: Main Page/lineupproposal2.html moved to LineupProposal2

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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>rtp://....</iptv-url>
</iptv-channel>

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

Where to fetch the media stream.

''TODO''

Main Page/lineupproposal2.html

2009-08-17T23:07:11Z

Benb: Main Page/lineupproposal2.html moved to LineupProposal2

#REDIRECT [[LineupProposal2]]

LineupProposal2

2009-08-17T23:04:25Z

Benb: /* Analog EU */

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW 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>rtp://....</iptv-url>
</iptv-channel>

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T23:03:34Z

Benb: /* Analog EU */

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]

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

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T23:00:35Z

Benb: /* XML structure */

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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="http://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:59:28Z

Benb: /* XML structure */

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:57:33Z

Benb: /* Structure */

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.

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

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:56:35Z

Benb: /* Structure */

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.

= 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 several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:54:31Z

Benb: /* Structure */

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.

= 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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:54:07Z

Benb: /* Structure */

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.

= Structure =

This format used "channel" different 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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:53:45Z

Benb: /* Structure */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes and what see in your TV guide.
* 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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:52:39Z

Benb: /* IPTV channels */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

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

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:52:15Z

Benb: /* IPTV channels */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

'''url''' (mandatory)

Where to fetch the media stream.

''TODO''

LineupProposal2

2009-08-17T22:51:56Z

Benb: /* Definition */ IPTV

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

== IPTV channels ==

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

'''url''' (mandatory)

Where to receive the media stream.

''TODO''

LineupProposal2

2009-08-17T22:42:03Z

Benb: /* Definition */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory)

The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:40:02Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:39:29Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [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.
Compare [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:38:30Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:38:01Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [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 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:36:51Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [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 provides regional tuning data. 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:36:22Z

Benb: /* Analog US */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 [http://en.wikipedia.org/wiki/Extended_Data_Services XDS] [http://www.ce.org/Standards/browseByCommittee_2523.asp Standard].

Other countries don't maintain official (nor 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 provides regional tuning data. 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:35:19Z

Benb: /* Stations */

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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'''
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)

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 <http://en.wikipedia.org/wiki/Extended_Data_Services> <http://www.ce.org/Standards/browseByCommittee_2523.asp>.

Other countries don't maintain official (nor 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 provides regional tuning data. 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:32:27Z

Benb: /* Definition */ Example file

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

[http://www.bucksch.org/1/projects/various/xmltv/lineup.de.xml 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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.

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

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 <http://en.wikipedia.org/wiki/Extended_Data_Services> <http://www.ce.org/Standards/browseByCommittee_2523.asp>.

Other countries don't maintain official (nor 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 provides regional tuning data. 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.

LineupProposal2

2009-08-17T22:27:50Z

Benb: /* Analog channels */ rfc2838id

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.

= Structure =

This format used "channel" different 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 the XMLTV file content describes.
* A "channel" is a technical means to transmit the station's broadcast.
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: BBC1.

It is very common for one station to be transmitted on many different channels, sometimes several received by the same TV system (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 RFC2838 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.

= Definition =

== 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 network="1" service="28006" transport="1079"/>
...
</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://dummy.invalid/zdf.gif"/>
<group>oeff-rechtl</group>
<commercial-free>true</commercial-free>
</station>

'''rfc2838id''' (mandatory):
The globally unique ID of the station, per [http://www.apps.ietf.org/rfc/rfc2838.html 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.

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

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 <http://en.wikipedia.org/wiki/Extended_Data_Services> <http://www.ce.org/Standards/browseByCommittee_2523.asp>.

Other countries don't maintain official (nor 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 provides regional tuning data. 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 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 [http://zapping.sourceforge.net/doc/libzvbi/structvbi__network.html#o5 Zapping API docs].
The list of station IDs is at [http://pda.etsi.org/pda/home.asp?wki_id=E7d9DkZdLL09830%27Y3uW ETSI TR 101 231]
Note that there's also a Teletext packet 8/30 format 2, which is different, therefore the complicated element name.