TOC
1. Introduction
2. Getting the source code
3. Basic Installation
4. VDR, OSCam and libdvbcsa compatibility
5. Plugin and OSCam setup
6. Commandline options
7. Note for a plugin developers
8. Fast ECM

-----------------------------------------------------------------------------
1. Introduction
-----------------------------------------------------------------------------

DVBAPI plugin for VDR

  The plugin allows connect VDR to OScam. It creates a software CAM in VDR,
and communicates with OSCam over camd.socket (using 'dvbapi' module).
This way it pass decryption requests to OSCam and obtains back keys which
are needed for CSA stream decryption. Decryption of the stream is done using
DeCSA libraries (FFdecsa or libdvbcsa).

Refer to INSTALL/README for installation and usage procedure
Refer to FAQ for frequently asked questions

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.

Latest version available at: https://github.com/manio/vdr-plugin-dvbapi

-----------------------------------------------------------------------------
2. Getting the source code
-----------------------------------------------------------------------------

You will have to grab the source code of course. First install the git
package provided by your distribution. Then from a terminal, type:

   $ cd /usr/local/src/vdr/PLUGINS/src
   $ git clone https://github.com/manio/vdr-plugin-dvbapi.git
   $ ln -s vdr-plugin-dvbapi dvbapi

-----------------------------------------------------------------------------
3. Basic Installation
-----------------------------------------------------------------------------

For sample installation instructions refer to INSTALL file.

-----------------------------------------------------------------------------
4. VDR, OSCam and libdvbcsa compatibility
-----------------------------------------------------------------------------

VDR:
The plugin is tested with the current stable VDR 2.8.3. It needs at least
VDR 2.3.3, which introduced the MasterSlot CAM API the plugin uses; the first
stable VDR with it is 2.4.0.

OSCam:
You need OSCam svn rev >= 11534 with the 'dvbapi' module enabled.

FFdecsa and libdvbcsa:
The plugin descrambles with FFdecsa by default, which is part of the plugin
and supports iCAM. To use libdvbcsa instead (see INSTALL), install one of:

  - https://code.videolan.org/videolan/libdvbcsa
    The VideoLAN reference implementation. Its git master (not in a release
    yet) supports iCAM with dvbcsa_bs_key_set_ecm(): build the plugin with
    "make LIBDVBCSA_NEW=1". The faster bitslice engine of glenvt18's fork
    is being merged into it; until that work is complete, it is slower than
    the fork.

  - https://github.com/glenvt18/libdvbcsa
    A fork with a much faster engine (SSSE3, AVX2, NEON), but without iCAM
    support: build the plugin with "make LIBDVBCSA=1". iCAM channels cannot
    be descrambled with it.

*** NOTE FOR OLDER VDR VERSIONS:
    If you are using VDR older than 2.3.3 then you need an older plugin
    version:
    - version 2.2.4 is the last plugin revision that will work for you.
    If you are using older VDR stable versions or developer version older
    then 2.1.4 then you need:
    - version 1.0.6 is the last plugin revision that will work for you;
    you also need OSCam svn rev >= 7314 and <= 9854 in this case.

*** NOTE FOR OLDER OSCAM VERSIONS:
    If you are using older OSCam svn versions older then 11534 then you
    also need an older plugin version:
    - version 2.2.5 is the last plugin revision that will work for you.

-----------------------------------------------------------------------------
5. Plugin and OSCam setup
-----------------------------------------------------------------------------

Current version of the plugin has a feature which allows connect to OSCam
via TCP socket. This way OSCam instead of doing filering on demux device,
is doing the requests over the network and the plugin is doing filering on
data provided by VDR. All communication with OSCam is done over one single
TCP socket. This allows directly connect to remote OSCam host with card
readers if it is on different host then VDR is running at.
This is currently the default (and recommended) plugin mode.
It will also help to using the plugin in cases where there is no physical
hardware the OSCam could use, eg the SAT>IP devices running on VDR.

To enable this mode it is needed to set listening port on OSCam server and
also host and port in this plugin options. Required minimal OSCam version
for this mode to work is svn rev 9580.
Let's assume that you want to use the port 2000 for communication on host
192.168.0.1 in your LAN.

On the VDR plugin side you need set the host and the same port of the machine
where the OSCam is listening for input connections.
You can set it in the plugin menu or manually adding the following lines
in the VDR's setup.conf file:
dvbapi.OSCamHost = 192.168.0.1
dvbapi.OSCamPort = 2000

NOTE: If you want to use VDR and OSCam on the same host, then just use
127.0.0.1 as the OSCamHost setting.

The OSCam has to be configured accordingly (oscam.conf file):
[dvbapi]
enabled                       = 1
au                            = 1
pmt_mode                      = 4
listen_port                   = 2000
user                          = vdr
boxtype                       = pc

You also need to properly add the above "vdr" user in OSCam, please refer
the OSCam documentation for details.


The log level parameter of the plugin can be configured either from VDR
menu or manually editing the VDR's setup.conf file (remember to change
the file when VDR is not running).

The parameter line for the plugin is:
dvbapi.LogLevel = 2

The values for the log level are:
  0 - totally disable debug
  1 - only error messages
  2 - information and error messages (default)
  3 - all information including debug

-----------------------------------------------------------------------------
6. Commandline options
-----------------------------------------------------------------------------

Adapter index offset:
---------------------
When you are using the plugin in network mode, single OSCam server is able to
handle more then one VDR dvbapi clients. The problem is the adapter indexes.

Let's assume the following scenario:
  VDR client 1: two DVB adapters (0, 1)
  VDR client 2: two DVB adapters (0, 1)

As every VDR host will number devices from zero, then both requests will come
to OSCam with conflicting adapter indexes, resulting in broken decrypting.

To be able to prevent this conflict (and if you want to connect more then one
dvbapi client to the same OSCam server) you need to add a constant value to
all adapter indexes on one of the above host.

There is a command line option "-o" to set this offset by the plugin when
communicating with the OSCam.

If you want to add eg. value 2 as the adapter index offset, then you need to
run vdr like this:
  vdr -P"dvbapi -o2"

If you do this on "VDR client 2" from the above scenario it will add value 2
to adapter indexes resulting in:
  VDR client 1: two DVB adapters (0, 1)
  VDR client 2: two DVB adapters (2, 3) - added offset 2 to indexes

This way all adapters/clients will be handled correctly by single OSCam.

NOTE: you can set this option permanently in setup.conf, like eg:
dvbapi.AdapterIndexOffset = 2
It is not exposed to the plugin setup as it is an advanced option.

CW expiration:
--------------
A key obtained from OSCam stays in use until OSCam sends the next one. OSCam
sends a CW only when it changes, so a key cannot be judged by its age: an
expiration check would blank channels with a constant CW. The former option
-d (--disable-exp) is still accepted but has no effect.

-----------------------------------------------------------------------------
7. Note for a plugin developers
-----------------------------------------------------------------------------

If you want your device to use a full performance of this dvbapi plugin,
then I strongly recommend that your plugin's device ring buffer to be set
to 5MB of size or more.

You can find the explanation in the following pull requests:
#104
#105

-----------------------------------------------------------------------------
8. Fast ECM
-----------------------------------------------------------------------------

Description:
CW Changes usually come 5 seconds before they are needed (enough time to
decrypt). Some Providers (Sky Germany) are sending CW changes only 600 ms
before it should be used in Data Stream.

When decryption is delayed the new CW arrives to late and the decryption
fails. Fast ECM can hold the data stream up to 2500ms until the CW is
available (odd/even check).
While this works very good for recordings, live video/audio will stop
for a brief moment (but usually only for the first time fastecm kicks in).

VDR compatibility:
Fast ECM needs a 16 MB TS buffer to work well. VDR uses 16 MB since version
2.4.5, so no change is needed there. For older VDR versions change the line
tsBuffer = new cTSBuffer(fd_dvr, MEGABYTE(5), CardIndex() + 1);
in cDvbDevice::OpenDvr() in dvbdevice.c to
tsBuffer = new cTSBuffer(fd_dvr, MEGABYTE(16), CardIndex() + 1);