This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Olivier DJIAN <odjosc@free.fr>

Project's homepage:          http://www.panczyk.eu/vdr

Latest version available at: http://www.panczyk.eu/vdr

See the file COPYING for license information.


Restrictions :
==============

This plugin was only tested with sessions contaning only one subsession using MP2T codec. I have no idea if it works with more.


Requirements :
==============

This plugin needs LIVE555 Streaming Media library to work. You can get it from :

      http://www.live555.com/

    Download liveMedia source code, built then install the library on your system

NB: at the date of writing this document, the library provided by the DEBIAN-etch package (liblivemedia-dev) doesn't work with this plugin so please build it from the source code.

EPG feature (Electronic Program Guide) is optional. If you want to use it, you need the following extra components :

  - xmltv software
  - additional libraries (libs AND headers) :
      libxml++ (version 2.6 or later)
      glib (version 2.6 or later)
      glibmm (version 2.4 or later)

If you installed your VDR-box from DEBIAN distro, you can get these libraries from the following packages :
    apt-get install libxml++2.6-2 libxml++2.6-dev
    apt-get install libglib2.0-0 libglib2.0-dev
    apt-get install libglibmm-2.4-1c2a libglibmm-2.4-dev


Installation :
==============

This plugin was written for VDR 1.4.x and only tested with those releases but it should work with previous one.

1- As said above, liveMedia library is mandatory and should be correctly installed on your system. If you built it from source code, please pay attention to where you put the different files. The makefile provided in the FreeboxTv plugin tarball assumes liveMedia include files and directories are located under /usr/include (default path if you install from your distro packet). If you used let's say /usr/local as prefix when building the library, you'll have to adapt the FreeboxTv Makefile accordingly (INCLUDES variable).

2- Like any other VDR plugin, extract FreeboxTv source code from the tarball in the <YOUR_VDR_HOME>/PLUGINS/src directory. Then create a freeboxtv symbolic link pointing to that directory.

3- Go to <YOUR_VDR_HOME>
  Create or edit Make.config file and add the following lines :
      LIBS += -L/usr/local/lib/liveMedia \
            -lBasicUsageEnvironment  -lgroupsock  -lliveMedia  -lUsageEnvironment

Here again, pay attention to where you installed the libraries you built from source code. You may need to change the above -L directive to fit your configuration.

3bis - If you don't need EPG feature (activated by default), please comment the following line in plugin's Makefile then jump directly to step 4 : 
    FREEBOXTV_EPG = 1

  Otherwise, you have to add the following declaration to LIBS line in general VDR's Make.config file (the same line you changed in step 3 above) :
     -lglibmm-2.4 -lxml2 -lxml++-2.6

Depending on your configuration, you may need to add a proper -L directive or change release number in the related libraries names. 

4- Then :
      make plugins
      make
  Next, install the newly generated files as usual.


Configuration :
==============

Here is the "tricky" part of the thing ;-)
For now, configuration files are not managed via VDR plugin setup menu so you have to do this "by hand".

1- First you have to add channel definitions to your channels.conf. The correct syntax is described in VDR documentation (man 5 vdr). As Freebox isn't a device getting his DVB stream thru the air, frequencies and various transmission parameters are meaningless for it. However you must provide "fake" ones to satisfy the VDR channel file parser. To simplify, I suggest you use the same values in each line for fields Frequency, Parameters, Srate, Conditional access, SID, NID, RID.

Of course VPID, APID and TPID (if any) must have valid values. Getting those values is probably the most difficult task to build a correct channels.conf for this plugin as there isn't currently any automatic way to get them from incoming stream. You may try to obtain them from a mediaplayer able to deal with RTSP streams - e.g. VLC (http://www.videolan.org/) for example.

The most important field is TID (as named in VDR documentation) because it makes the link with the second FreeboxTv configuration file and is used to uniquely identify a channel (VDR channel ID). You can choose whatever value you want provided each channel has a different one. It's probably a good idea to map it to channel number or some distinctive part of the URL.

2- CAUTION : starting from 0.0.2 FreeboxTv plugin's release, all configuration files are located in :
      <YOUR_VDR_CONFIG_DIRECTORY>/plugins/freeboxtv/

Next you have to create the following file
      <YOUR_VDR_CONFIG_DIRECTORY>/plugins/freeboxtv/channels.conf.freebox

Each line represents the triplet NID/XMLTV identifier/URL for one stream and has the form :
      <NID>:<XMLTV_Channel_ID>:<URL>

To every defined NID must correspond one and exactly one line with the same NID in channels.conf.

For example :
If we have the following line in channels.conf :
  France 2:219000:C12D0M64B8T8G32Y0:T:27500:163:1912:35:0:1:1:1201:0

We have a line like this in channels.conf.freebox :
  1201:C2.telepoche.com:rtsp://mafreebox.freebox.fr/freeboxtv/stream?id=201

NB: you can notice in the previous example I used 1201 as NID. My personal  definition strategy is that I choose NID = 1000 + (URL stream id).
This choice is purely arbitrary and you may take another one. Once again, VPID (163), APID (1912) and TPID (35) are valid values.

3- To get EPG on FreeboxTv device, you have to configure xmltv software. I won't tell here how it works, nor will I describe his principles. Please visit http://xmltv.org/wiki/ for more information. Depending on the channels of interest for you, you have to choose the appropriate xmltv grabber and use whatever mean you want to make it run on a regular basis (crontab, VDR command hooks, ...). From here, I'll use the french grabber in my examples (tv_grab_fr) but you may transpose all the explanations with the one you need.

On first launch, your grabber will ask you which channel you want. Answering the questions, you'll get a tv_grab_fr.conf file in your ~/.xmltv directory. The next step is to analyze this file to know which identifier you have to put in your channels.conf.freebox file. In France for example, each identifier has the form Cxxx.telepoche.com where xxx is a number following the "channel" keyword in tv_grab_fr.conf file. Here are some examples with french channels :

    In tv_grab_fr.conf                   Identifier in channels.freebox.xmltv
    channel 2 france 2            ->              C2.telepoche.com
    channel 40 ab1                ->              C40.telepoche.com

So the corresponding channels.conf.freebox file looks like this :

   1201:C2.telepoche.com:rtsp://mafreebox.freebox.fr/freeboxtv/stream?id=201
   1211:C40.telepoche.com:rtsp://mafreebox.freebox.fr/freeboxtv/stream?id=211


Once channels.conf.freebox file is correctly configured, you have to make the following command run on a regular basis :

    tv_grab_fr --day 2 --slow --output <YOUR_VDR_CONFIG_DIRECTORY>/plugins/freeboxtv/xmltv.freebox
 
You may change the value after --day keyword but be aware that it will take a longer time to get the whole information.

NB: Even if you don't activate EPG feature, you have to put some (dumb) value in the second field of your  channels.conf.freebox file. However this value won't be interpreted.

Two templates and a xmltv configuration file sample are provided in the examples directory :
  channels.conf-template can be merged to your channels.conf file (in VDR config directory)
  channels.conf.freebox can be copied to <YOUR_VDR_CONFIG_DIRECTORY>/plugins/freeboxtv
  tv_grab_fr.conf can be copied to directory ~/.xmltv

Please note that at the writing date of this doc, those files are valid for Free ISP suscribers 


Usage :
=======

As usual, just add -P freeboxtv to you vdr command line.

Client port number selection (local port on your VDR box) :
Starting from 0.0.3 release, you can select on which port RTSP server will deliver the video stream to your box. This feature is useful for network security reasons, specially for whose who are behind a firewall and may only open the needed port.

To configure it, please use VDR setup : 
  Menu -> Setup -> Plugins -> Freeboxtv

Here you can enter whatever value you want for "Client Port Number".
NB : a 0 value means you let RTSP server choose the port number for you.

Enjoy !

