stations.list
=============

A Station is a transmitter of video content. Here is the TiVo schema for
a station:

# Tribune Media has it's own ID for each station.
TmsId|string||optional||base
# Long name of the station.
Name|string||single||base
# Mnemonic or FCC-recognized call sign for the station.
CallSign|string||single||base
City|string||optional||base
State|string||optional||base
ZipCode|string||optional||base
Country|string||optional||base
# Network, cable, or breadcasting group with which the station is affiliated.
Affiliation|string||optional||base
# City and state of the market a broadcast station resides in.
DmaName|string||optional||base
# Numeric ranking of city and state of the market a broadcast station
# resides in.
DmaNum|int||optional||base
FccChannelNum|int||optional||base

Here is an example station from the stations.list file:

[Ten-Can]
version=8
affiliation=Ten Network
city=Canberra
country=Australia
doguidedata=True
name=Ten Capital Canberra
serverid=7260007
state=AC
parser=Oguide
urlparams_ebroadcast=10Cap&state=Canberra&fta=1
urlparams_yahoo=86157
urlparams_oguide=Canberra,10

The serverid and version form the unique record-id and the version of this
record in the headend. Each station needs a unique serverid. Other mandatory
fields are the callsign (e.g [Ten-Can]) and the name. Optional fields are
tmsid, city, state, zipcode, country, affiliation, dmaname, dmanum and
fccchannelnum.

Wktivoguide uses the parser and urlparams_xxx fields to determine what
fetch mechanisms exist and their parameters. The parser field is a list
of comma-separated values, e.g parser=Oguide,D1,Ebroadcast. For each
parser, there must be an all-lowercase urlparams_xxx field.

QUESTION: Can someone explain the tmsid, dmanum and fccchannelnum parameters
and how they are picked?

Channels
========

A channel is the receiving point of a station. Here is the TiVo schema:

TmsHeadendId|string||optional||base
Station|object|Station|single|dependency|base
#This is the Channel Number
Number|int||single||base
ServiceTier|enum|ServiceTier|optional||base
ABChannel|enum|ABChannel|optional||base
Signal|enum|Signal|optional||base
# should we surf this channel? (only used by setup)
Surf|int||optional||base
# should we record from this channel? (only used by setup) 
Record|int||optional||base
# is this channel one of the viewer's "favorites"?
Favorite|int||optional||base
# input source channel is mapped to
SourceIndex|int||optional||base

The most important fields here are the pointer to the originating
Station, and the channel Number. This information is kept as a series
of lines in the *.lnup files, for example:

channel: 2 ABC-Qld
channel: 7 Seven-Qld
channel: 9 Nine-Qld
channel: 10 Ten-Qld
channel: 41 SBS-Qld

where we use the station's name and not its unique id to tie channel and
station together. These fields in the original schema are not included
in the headend: Signal, Surf, Record, Favorite, SourceIndex.

Lineups: *.lnup files
=====================

A lineup is a collection of channels. Here is the TiVo schema:

Name|string||single||base
Type|enum|LineupType|single||base
Channel|object|Channel|multi|dependency|base

Each lineup can contain multiple channels and a single name. Here is a
full *.lnup file:

provider: 04003 Foxtel Cable - Queensland - Foxtel Analog Cable
version: 8
lineuptype: Cable
use CableSat/Foxtel_Analog_Cable.lnup
channel: 2 ABC-Qld
channel: 7 Seven-Qld
channel: 9 Nine-Qld
channel: 10 Ten-Qld
channel: 41 SBS-Qld

The provider line holds 4 fields:
lineup-id (5-digits) lineup name - community - second name.
If the second name is missing, the lineup name is used instead. If the
community is missing, the lineuptype value is used instead.
The lineup-id is unique for each lineup, and the version must be incremented
if the lineup file changes. The lineuptype can be one of Antenna, Cable,
Digital or Satellite. A "use" line allows channels from other files to be
added into the lineup: in the file above, the channels that are in
Foxtel_Analog_Cable.lnup will be added to the list of channels.

Headends: *.head files
======================

A headend is a collection of lineups, which are a collection of channels
that get their programs from matching stations. Here is the TiVo schema:

# A unique identifier assigned by Tribune
TmsHeadendId|string||single||base
CommunityName|string||optional||base
CountyName|string||optional||base
State|string||optional||base
# All of the zip codes covered by this headend
PostalCode|string||multi||base
Name|string||single||base
TimeZone|enum|TimeZone|optional||base
# A list of all the lineups available on this headend.
Lineup|object|Lineup|multi|dependency|base
# A list of the encryption keys currently in use for this headend
EncryptionKeys|string||multi||base
# Physical location of headend
Location|string||optional||base
# Subobject - city/postal code combination
CityPostalCode|object|CityPostalCode|multi||base

Here is an example *.head file. The [default] section holds most of the
fields:

[default]
version=8
state=QL
country=Australia
headendcode=provider
community=Brisbane
timezone=7
zipcode=04000
postalcode=04000
conflictskip=1
lineups=Brisbane_Analog_FTA.lnup,Digital_FTA.lnup,Foxtel_Analog_Cable.lnup,Foxte
l_Digital_Cable.lnup,Optus_Cable.lnup

[stations]
format=none

The postalcode is the headend-id for each headend, and version numbers
must increment as before. The zipcode is the 5-digit postcode which the
user enters as their region identifier during Guided Setup.

The TmsHeadendId is derived from the unique postalcode. The mandatory
fields are version, zipcode, postalcode and lineups.

The lineups field lists the lineups in the headend. The filenames are
relative to the directory where the headend file lives.