This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version. See the file COPYING for more information.

Written by:		Dave Pickles
Project homepage	http://projects.vdr-developer.org/projects/vdrtva


Description:

TV-Anytime is the name given to a set of technologies which aim to simplify the
process of recording and replaying broadcast content. The standards are
published by ETSI and are available without cost from www.etsi.org.  The main
standard is ETSI TS 102 323.

In the UK a subset of the TV-Anytime specification is broadcast on the DTV
service under the trade name "FreeView Plus". This plugin is written for the UK
version, has been tested on New Zealand DVB-S and is believed to be compatible
with the NorDig standard used in Scandanavian countries plus Eire. It should
also work with the full specification (untested).

TV-Anytime data is contained in Content Reference Identifiers (CRIDs). The
syntax of a CRID is described in RFC 4078; it is a URI-compliant string of the
form:

	crid://<DNS name>/<data>

in which <DNS name> is a registered internet domain name (RFC 1034) and <data>
is a free-format string. The <DNS Name> section relates to the content provider
(TV channel or company), and the <data> section to the programme.

CRIDs are transmitted in the EIT as Content Identifier Descriptors, with
descriptor ID 0x76. To save bandwith only the <data> section is sent, the <DNS
Name> part is taken from the Default Authority Descriptor in the SDT, and the
crid:// is assumed.

A programme may have up to three CRIDs in its EPG entry. One identifies the
specific item of content which is being broadcast, while another identifies a
series of programmes which this item belongs to. The third type includes the
CRIDs of 'suggested' events which the viewer might be interested in. In FreeView
Plus these CRIDs have crid_type values 0x31 0x32 and 0x33 respectively
(TV-Anytime uses values 0x01 - 0x03).

To give an example, the programme "Torchwood" broadcast on channel BBC2 at 21:00
on 2008-01-16 had item CRID '54BXLC' and series CRID 'KCJ00C'. When the same
programme was repeated the following day on channel BBC3, the item CRID remained
the same but the series CRID was 'KCJ12C'. Meanwhile the episode broadcast on
BBC2 one week later on 2008-01-24 had CRID '54BXLD' but the same series as the
previous week. Hence it is possible for a PVR to record an entire series by
using the series CRID, or to find an alternative broadcast for an individual
item if there is a clash with another recording.


Operation:

The use of the 'Accurate Recording' feature is described in README-vps.

The plugin captures CRID data continuously, beginning 5 minutes after VDR
startup. A maintenance task runs every 24 hours at a time set by the '-u'
parameter or in VDR's OSD (default 03:00) which:

- Checks for new manually-created timers and adds series links for them.

- Checks each series link to see if any new events have been added to the EPG in
  the same series. If so then timers are added for them.

- Checks for timer clashes and suggests possible alternative recording times
  (unless the -n flag is set).

- Checks that the event being recorded by each timer is the same as when the
  timer was set (ie that the EPG has not changed in the meantime)

- Flags any split events (eg a long programme with a news summary in the
  middle). At present a manual check is needed that all parts of the programme
  are set to be recorded.

- Optionally sends a mail report listing new timers which have been
  automatically created, any timer clash warnings, and a complete list of timers
  and any suggestions for them.

The plugin takes the following parameters:

  -l n     --lifetime=n         Lifetime of new timers (default 99)
  -m addr  --mailaddr=addr      Address to send mail report
  -n       --nocheck            Do not check for timer collisions
  -p n     --priority=n         Priority of new timers (default 99)
  -s n     --serieslifetime=n   Days to remember a series after the last event
                                (default 30)
  -u HH:MM --updatetime=HH:MM   Time to update series links (default 03:00)

The plugin logs activity through the VDR syslog, unless the -m parameter is set
in which case only errors go to syslog and a report is emailed to the given 
address daily.

The plugin has an SVDRP interface which is mainly used for debugging, but could
be used to interface with other applications. The commands are:

DELL <sCrid>	Delete a series link and any timers by series CRID

LLOG		Print the pending log report

LSTL		Print the series links list

LSTS		Print the 'suggested' events list

LSTT		Print the list of timers with suggestions for each event

LSTY		Print the CRIDs for each event

LSTZ		Print the Default Authority data for each channel

STOP		Start and stop CRID data capture
STRT

UPDT		Trigger an update of the series links.


OSD

The plugin adds an entry to the VDR Main Menu called "Series Links". This shows 
the title of the first programme in the series and the date (DD.MM) of the most
recent timer - if the series is still running this date will usually be in the 
future. From this menu you can view further information on a selected series, or
delete a series together with any remaining timers.

The configuration settings described above can also be set using the "Setup" 
menu in the OSD.


Files

The plugin stores details of series links in the file links.data which is in the
VIDEODIR/plugins/vdrtva directory. Entries in this file have the format:

<scrid>;<modtime>;<icrids>;<path>;<title>;<channel>

scrid	The series CRID.
modtime	The start time of the latest event in this series.
icrids	The CRIDS of the events in the series, separated by colons.
path	The subdirectory to store recordings in this series, taken from the first 
	timer, or the string (NULL) if no subdirectory was given.
title	The title of the first event in the series.
channel The channel name of the first recorded event in the series.


Points to remember:

- Not all channels on UK Freeview have CRIDs in the EPG. Some radio channels
  have item CRIDs but none have series CRIDs.

- Different programme providers have different ideas of what constitutes a
  'series'.

- The timer creation process is very simplistic; it doesn't check for timer
  clashes, and selects the first physical entry in the EPG (which may not be
  the prime broadcast of the programme).

- A series link is created for every timer whether you want one or not.

- This plugin has not been tested with multiple tuner cards or with mixed DVB-T
  and DVB-S setups. It will try to collect CRID data from the Primary DVB device.

- The 'suggested' events list may have CRIDs which do not appear in the events
  list.

The plugin is compatible with VDR version >= 1.7.19.

Although I use this software day-to-day on my VDR installation, this is
Beta-quality code - USE AT YOUR OWN RISK!!