vdr-plugin-iptv/README

This is an IPTV plugin for the Video Disk Recorder (VDR).

Written by:                  Rolf Ahrenberg
                             < R o l f . A h r e n b e r g @ s c i . f i >

                             Antti Seppälä
                             <a j h s e p p a @ n i k s u l a . h u t . f i >

Project's homepage:          http://www.saunalahti.fi/~rahrenbe/vdr/iptv/

Latest version available at: http://www.saunalahti.fi/~rahrenbe/vdr/iptv/

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

Requirements:

An IPTV patched VDR-1.5.10 (or later) setup and DVB compatible MPEG1/2
network video streams.

Description:

This plugin integrates multicast IPTV transport streams seamlessly into
VDR. You can use any IPTV channel like any other normal DVB channel for
live viewing, recording, etc. The plugin also features full section
filtering capabilities which allow for example EIT information to be
extracted from the incoming stream.

Currently the IPTV plugin supports both multicast UDP/RTP and unicast
HTTP MPEG1/2 transport streams. Also a file input method is supported,
but a file delay must be selected individually to prevent VDR's transfer
buffer over/underflow. Therefore the file input should be considered
as a testing feature only.

Installation:

cd /put/your/path/here/VDR/PLUGINS/src
tar -xzf /put/your/path/here/vdr-iptv-X.Y.Z.tgz
ln -s iptv-X.Y.Z iptv
cd /put/your/path/here/VDR
patch -p1 < PLUGINS/src/iptv/patches/vdr-X.Y.Z-pluginparam.patch
cp sources.conf /path/to/vdrconf/
cp -R PLUGINS/src/iptv/iptv /path/to/vdrconf/plugins/
make
make plugins
./vdr -P iptv

Setup menu:

- TS buffer size [MB] = 2          Defines ringbuffer size for transport
                                   stream in MB.
                                   Valid range: 1...4
- TS buffer prefill ratio [%] = 0  Defines prefill ratio for transport
                                   stream ringbuffer before data is
                                   transferred to VDR.
                                   The valid range: 0...40
- Use section filtering = 1        Defines whether section filtering shall
                                   be used.
                                   Valid range: 0...1
- Scan Sid automatically = 1       Defines whether service id shall be
                                   scanned automatically. Requires section
                                   filtering.
                                   Valid range: 0...1
- Disable filters = 0              Certain section filters might cause some
                                   unwanted behaviour to VDR such as time
                                   being falsely synchronized etc. This
                                   option allows creation of blacklists of
                                   ill-behaving filters. If this option is
                                   set to a non-zero value, the menu page
                                   will contain that many "Disable filter"
                                   options which allow you to disable the
                                   individual section filters.
                                   Valid range: 0...7
- [Red:Channels]                   Opens IPTV channel editor.
- [Blue:Info]                      Opens IPTV information/statistics menu.

Channel editor menu:

- Because of the different nature and content the VDR channel editor is not
  best suited for editing of IPTV channels. Therefore an alternative editor
  is provided which allows more IPTV centric editing of channel information.
  An IPTV channel editor is accessible via "Setup -> Plugins -> IPTV" and
  pressing the Red button. The channel editor is functionally similar to
  VDR's built-in channel editor.

Information menu:

- [Red:General]                    Opens the general information page.
- [Green:Pids]                     Opens the pid statistics page.
- [Yellow:Filters]                 Opens the section filter statistics page.
- [Blue:Bits/bytes]                Toggles between bits and bytes mode.

Configuration:

- channels.conf

  TV4;IPTV:4:IPTV|EXT|iptvstream.sh|0:P:0:0:680:0:0:4:0:0:0
  TV3;IPTV:3:IPTV|FILE|/video/stream.ts|5:P:0:514:670:2321:0:3:0:0:0
  TV2;IPTV:2:IPTV|HTTP|127.0.0.1/TS/2|3000:P:0:513:660:2321:0:2:0:0:0
  TV1;IPTV:1:IPTV|UDP|127.0.0.1|1234:P:0:512:650:2321:0:1:0:0:0
           ^ ^    ^   ^         ^    ^
           | |    |   |         |    Source type ("P")
           | |    |   |         IP Port Number, File delay (ms), Script parameter
           | |    |   IP Address, File location, Script location
           | |    Protocol ("UDP", "HTTP", "FILE", "EXT")
           | Plugin ID ("IPTV")
           Unique enumeration

- UDP multicast rules for iptables firewall

  # Multicast UDP -packets
  iptables -A INPUT -i eth0 -p udp -d 224.0.0.0/4 --dport 1234 -j ACCEPT

  # IGMP required by multicasts
  iptables -A INPUT -i eth0 -p igmp -d 224.0.0.0/4 -j ACCEPT

External streaming:

- Starting from version 0.0.2 IPTV plugin features support for external
  streaming applications. What this means in short is that with proper helper
  applications and configuration the plugin is able to display streams not 
  originally in MPEG1/2 TS format.

- To add an externally received channel, add an EXT entry to channels.conf.
  Specify a script name as the location parameter. This script is executed
  from plugin configuration directory when VDR tunes to the specified
  channel. The port parameter in channels.conf is passed to the script and
  can be used to select for example between different URLs.

- When EXT channel is opened IPTV plugin opens an UDP listening port on the
  local host. The script executing is then responsible for supplying IPTV
  plugin with MPEG2 TS data in UDP format to the opened port. The data will
  then be processed by VDR as usual. The opened listening port can be
  specified in plugin configuration.

- IPTV plugin includes an example script which uses VLC media player for
  receiving streams, transcoding and handing the result to IPTV plugin. IPTV
  was tested with VLC version 0.8.6c

Notes:

- Working EIT requires correct Nid/Tid/Sid values as the NIT filter cannot
  determine the type (satellite/cable/terrestrial) of the IPTV transport
  stream.

- The following section filters are recommended to be disabled:
  "NIT (0x40)", "SDT (0x42)", "TDT (0x70)"

- The EXT protocol listens UDP packets from localhost. The default listen
  port base number is 4321 and it can be configured via a commandline
  switch. The port range is defined by the number of IPTV devices (max. 8).

- The EXT protocol scripts must be located in the config directory of the
  plugin.

Acknowledgements:

- The IPTV section filtering code is derived from Linux kernel.