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

originally written by: Andreas <andreas.regel@powarman.de>
(Some parts of the plugin's source are based on the analogtv plugin by
Andreas Kool.)

Since the ivtv driver API changed in ivtv >= 0.8 a lot of API calls are no
longer existent/working. Unfortunally the author does no longer maintain this
plugin (see http://www.vdr-portal.de/board/thread.php?threadid=48772).

This INOFFICIAL version allows to use the plugin with newer ivtv versions,
but it is completely without any warranty and still very experimental:

-Adapted to ivtv driver 0.8 by "Wirbel" Winfried Koehler 
 <w_koehl@gmx.de>
-Further development in 2006/2007 by "Dr. Seltsam" Martin Dauskardt
 (martin.dauskardt@gmx.de) and Andreas Schäfers  (andreas_schaefers@gmx.de).

See the file HISTORY for changes.
See the file COPYING for license information.


Description:
------------

This plugin uses a Hauppauge PVR card as an input device. All cards
supported by the ivtv or pvrusb2 driver should work. This version of the plugin
requires ivtv driver version 1.0 or higher. You need very current versions of
videodev.h and videodev2.h in /usr/include/linux to get the plugin compiled 

channels.conf (old channel syntax)
--------------------------
Take the channels.conf_oldsyntax.example in example dir as a reference for your
own channels.conf. You can also take a channels.conf from the analogtv plugin
and modify parameter, teletext and CA values. It is important to have the
following values for the channels:
 Source ID: 'C'
 Video PID: 301
 Audio PID: 300
 Teletext PID: 305
 CA identifier: A1

for example:
RTL:217250:C0:C:0:301:300:305:A1:12003:1:1089:0
       |   |       |   |   |  |    |   |   |
       |   |       |   |   |  |    |   |   --> Transport Stream ID
       |   |       |   |   |  |    |   --> Network ID
       |   |       |   |   |  |    --> Service ID
       |   |       |   |   |  --> CA identifier
       |   |       |   |   --> Teletext PID
       |   |       |   --> Audio PID
       |   |       --> Video PID (set to 0 for radio stations, but see below)
       |   --> Parameters (see below)
       --> Frequency

Parameters:
With a frequency higher than 10000 kHz the tuner input of the PVR card is used.
The number of the tuner input should be detected automatically during startup
of the plugin. If this doesn't work you can specify it by setting the "C"
parameter of the channel entry to the right value. You also have to specify
this value if you want to use another input of the PVR card:
  C0   - Input 0   //in most cases this is the TV tuner
  C12  - Input 1   //e.g. PVRUSB2 Composite
  C23  - Input 2   //e.g  PVRUSB2 S-Video
  C34  - Input 3
  C45  - Input 4
  C56  - Input 5
  C67  - Input 6
  C78  - Input 7
  C89  - Input 8
  C999 - Input 9

Not all inputs are available on all cards and with every ivtv driver version.
Try different settings to find the right input for Composite/FBAS and S-Video.

The video norm can be chosen in a similar way using the "I" parameter:
  I0   - NTSC
  I1   - SECAM
  I999 - PAL
With no "I" parameter, PAL is used.

If you need more information configuring your channels.conf, please read this:
(links to other languages than german are available)

- http://www.vdr-wiki.de/wiki/index.php/Channels.conf
- http://www.vdr-wiki.de/wiki/index.php/Vdr(5)
- http://www.vdr-wiki.de/wiki/index.php/W_pvrscan
- http://www.vdr-wiki.de/wiki/index.php/Wirbelscan-plugin

channels.conf (new channel syntax)
--------------------------
pvrinput now supports a new syntax using the Source Identifier 'P', similar to the one from the iptv-plugin.
Take the channels.conf_newsyntax.example in example dir as a reference for your
own channels.conf.

 Source ID: 'P'
 Video PID: 301 for TV, 0 for Radio
 Audio PID: 300
 Teletext PID: 305 (or 0 if not needed)

for example:
RTL:217250:PVRINPUT|TV:P:0:301:300:305:0:12003:1:1089:0
|      |   |           |    |   |   |  |    |   |   |
|      |   |           |    |   |   |  |    |   |   --> Transport Stream ID
|      |   |           |    |   |   |  |    |   --> Network ID
|      |   |           |    |   |   |  |    --> Service ID, the combination of SID, NID, TID has to be unique.
|      |   |           |    |   |   |  --> CA identifier, should be 0
|      |   |           |    |   |   --> Teletext PID
|      |   |           |    |   --> Audio PID
|      |   |           |     --> Video PID (set to 0 for radio stations)
|      |   |           --> Source 'P'
|      |   --> Parameters (see below)
|      --> Frequency (1 for external inputs)
--> Channel Name (your choice..)

Parameter Description:
Each Parameter is separated with "|" (vertical bar)

* First Parameter: always "PVRINPUT" (uppercase!). Otherwise pvrinput will ignore this channel.
* Second Parameter: always one of the following identifiers (uppercase!):
  *   "TV"               -> a normal tv channel
  *   "RADIO"            -> a radio channel. frequency should be this case 87500..108000 and vpid = 0
  *   "COMPOSITE0"       -> external input, composite in number 0
  *   "COMPOSITE1"
  *   "COMPOSITE2"
  *   "COMPOSITE3"
  *   "COMPOSITE4"
  *   "SVIDEO0"          -> external input, S-Video input number 0
  *   "SVIDEO1"
  *   "SVIDEO2"
  *   "SVIDEO3"

NOTE: * Some cards will have SVIDEO0 and COMPOSITE0 as first external input, while
      other cards may start with SVIDEO1 and COMPOSITE1. This depends on driver and hardware (ivtv, pvrusb2).
      * for all channels with external video inputs, frequency should be 1.

* Third and Fourth Parameters: THESE PARAMETERS ARE *OPTIONAL*. One of the following identifiers, uppercase:
  *   "PAL"              -> specify PAL channel, this is default.
  *   "SECAM"            -> specify Secam channel. default is PAL
  *   "NTSC"             -> specify NTSC channel. default is PAL
  *   "CARD0"            -> specify one video device (here: /dev/video0) which should receive this channel
  *   "CARD1"                all other devices will not switch to this channel. Useful for external video inputs.
  *   "CARD2"                CARD0 is /dev/video0, CARD1 is /dev/video1 and so on. Be aware, that
  *   "CARD3"                a full-featured DVB card or other video devices might also have a /dev/videoXX.
  *   "CARD4"                
  *   "CARD5"                NOTE: if not specified *all* pvrinput devices will try to receive this channel.
  *   "CARD6"
  *   "CARD7"

NOTE: /dev/video0../dev/video7 supported only.

OSD main menu
-------------
There is a small OSD window for setting up the picture parameters (brightness0,
contrast, saturation, hue). It can be reached from the main menu. Use the
Up/Down keys to switch between the parameters and Left/Right to change a
value. Press Ok to save the settings and close the window. Menu/Back just
closes the window without saving the values.

Radio
-----
The PVR150, PVR350, PVR500(first device only), PVRUSB2 and obviously some
versions of PVR250 have a built-in radio tuner.
The pvrinput-plugins detects a radio channel if it has a frequency of 
87.5MHz .. 108 MHz (channels.conf: 87500 .. 108000).
VPID should be set to 0.

VPID=301 is (only) necessary if the PVR350 is used as output device
(pvr350-plugin). With missing video, you won`t hear anything.
Workaround: Set VPID 301 for radio channels. Due to a driver bug this may
lead to a green screen on radio channels when using an older ivtv driver
version (fixed in v4l-dvb hg in October 2007) or when using the PVRUSB2
(see "pvrusb2 & radio").

Because the radio audio volume level is much lower, you can set radio and TV
audio volume separately for TV and FM radio.

When using radio channels, the driver sets the video stream blank. To avoid
large files, you can set the video bitrate separately. Default value is 1/4
of the driver`s default video bitrate:
1/4 of 6 MB/s = 1,5 MB/s
A radio recording with a length of 2 minute may have 120 MB (8 MBit/s)
or only 12 MB (1,5 MB/s).


vdr-1.6.x
---------
vdr-1.6.x needs to be patched to work with pvrinput. See folder patches.
You have two possibilties:

1. Using a channel syntax which is similar like the one from iptv.
   If your vdr version is already patched for the iptv-plugin, you 
   don`t need the patch vdr-1.6.0-pluginparam.patch. Otherwise apply it.

and/or

2. Using the same channel syntax like before in vdr 1.4
   While vdr 1.4 doesn`t need to be patched, you now need 
   vdr-1.6.0-pvrinput.diff (if you have a newer extension patch,
   it may already be included there)


There also seems to be a bug in vdr 1.6.0-1. You should comment out an isyslog
call in vdr.c:

static void SignalHandler(int signum)
{
//  isyslog("caught signal %d", signum);

It looks like that isyslog is not threadsafe here. This is fixed in the
VDR maintenance patch 1.6.0-2.

vdr-1.7.0/1.7.1
---------------
use the vdr-1.7.0-pluginparam.patch (see "vdr-1.6.x" for more details).
It is currently tested with vdr-1.7.0 and vdr-1.7.1 using a dvb-api-wrapper-patch.
Be aware that due to big changes in vdr-1.7.1 your output device might not
work properly. 

vdr-1.4.7
---------
If you want to use the old channel syntax, no patch is necessary.

You can also use the new channel syntax, if vdr is patched for the iptv-plugin
(vdr-1.4.7-pluginparam.patch)


**new***: support for pvrusb2 devices
--------------------------------------
The plugin detects for each PVR device if it is controlled by ivtv or pvrusb2
and uses the appropriate commands. Due to driver bugs detection of the default
values may be wrong. Check the plugin settings and adjust if necessary (see 
"Encoder Settings" below). It is especially important to set the Audio sampling
rate to 48 KHz.

pvrusb2 & radio
---------------
If you use a PVR350 for decoding (VPID = 301, see above) you will notice a
green screen when switching to PVRUSB2 radio. This is caused by a wrong use of
a bitmask in the pvrusb2 driver. Unfortunately the maintainer doesn`t want to
fix it. If you prefer a black screen instead of green, you could patch the
driver (pvrusb2-encoder.c):
from

  pvr2_encoder_vcmd(hdw,CX2341X_ENC_MUTE_VIDEO,1,
                    hdw->input_val == PVR2_CVAL_INPUT_RADIO ? 1 : 0);

to

 pvr2_encoder_vcmd(hdw,CX2341X_ENC_MUTE_VIDEO,1,
                   hdw->input_val == PVR2_CVAL_INPUT_RADIO ? 0x00808001 : 0);

This patch is also included in the pvrusb2-patches
(see folder patches/pvrusb2-driver)

pvrusb2 & channel switching
----------------------------
Unlike newer ivtv drivers, the pvrusb2 driver allows channel and input
switching without stopping the encoder. Channel switching is faster, but you
may recognize short audio/video interferences.

If you set "PVRUSB2 Stop On Change" to "yes" the encoder will be stopped on
every channel switch by closing the device and will restart by re-opening
the device. This makes channel switching a bit slower, but much smoother.
Unfortunately it happens randomly that you get a blank screen.

You may also found messages like this in dmesg:

pvrusb2: ***WARNING*** device's encoder appears to be stuck (status=0x00000003)
pvrusb2: Encoder command: 0x81
pvrusb2: Giving up on command.  This is normally recovered by the driver.

This is probably related to the above mentioned problem. Sometimes the cx23416
stops talking to the driver.  The driver recovers by reloading its
firmware. It only ever happens when streaming is started, probably after
a channel switch when "PVRUSB2 Stop On Change" is set to yes.

In the folder patches/pvrusb2-driver you can find two different patches
(depending on your kernel/driver version). You won`t get rid of the syslog
messages, but the patch should help to avoid delays and black screens when
switching channels 

Note:
If you use the default setting (PVRUSB2 Stop On Change" = no) there should
be no problem, and you don`t need to patch the driver.

pvrusb2 & osdteletext
----------------------
The pvrusb2 driver does not support sliced vbi, so the osdteletext-plugin
won`t work.

bilingual broadcastings
-----------------------
The driver default audio mode is stereo. According to 
http://v4l2spec.bytesex.org/spec/r12342.htm#TUNER-AUDMODE
it is now necessary to set the audio mode to  V4L2_TUNER_MODE_LANG1_LANG2,
otherwise you will only get the first language.
The default mode of the plugin is V4L2_TUNER_MODE_LANG1_LANG2
(bilingual), which should be well for all broadcastings.
MythTV also uses this mode.

If you use a PVR350 for playback with the pvr350-plugin, you need version
2008-05-17 or higher to be able to select the languages. Starting with that
version, the pvr350-plugin supports SetAudioChannel() and GetAudioChannel().

switching between different PVR devices
---------------------------------------
At least with vdr 1.6.0, you can use the femon plugin and switch with 
the "Left" and "Right" keys between the cards. This is useful if you want
to start a recording from an extern input. With femon you can choose the
card that is actually connected to an extern video source.
(Note: if you use the new channel syntax, you can configure the card in 
the channels.conf)

Encoder settings
----------------
The plugin calls the driver for its default values and sets them. Due to a
driver bug, this can lead to wrong values. It was fixed in v4l-dvb hg in
July 2008. Have a look at  http://www.gossamer-threads.com/lists/ivtv/devel/38637.
Obviously there are still problems with the pvrusb2 driver.

It is recommended to check the settings. These are the default values:

pvrinput.AspectRatio = 1			//4:3
pvrinput.AudioBitrate = 10			//224 kBit/s
pvrinput.AudioSampling = 1			//48 KHz
pvrinput.AudioVolumeFM = 65535			//95%
pvrinput.AudioVolumeTV = 62258			//100%
pvrinput.BitrateMode = 0			//VBR
pvrinput.Brightness = 128			//50%
pvrinput.Contrast = 64				//50%
pvrinput.FilterChromaMedianBottom = 0		//Chroma Median Filter Bottom = 0
pvrinput.FilterChromaMedianTop = 255		//Chroma Median Filter Top = 255
pvrinput.FilterChromaSpatialType = 1		//Chroma Spatial Filter Type = 1D horizontal
pvrinput.FilterLumaMedianBottom = 0		//Luma Median Filter Bottom = 0
pvrinput.FilterLumaMedianTop = 255		//Luma Median Filter Top = 255
pvrinput.FilterLumaSpatialType = 1		//Luma Spatial Filter Type = 1D horizontal
pvrinput.FilterMedianType = 0			//Median Filter Type = off
pvrinput.FilterSpatial = 0			//Strength Spatial Filter = 0
pvrinput.FilterSpatialMode = 0			//Mode Spatial Video Filter = manual
pvrinput.FilterTemporal = 8			//Strength Temporal Video Filter = 8
pvrinput.FilterTemporalMode = 0			//Mode Temporal Video Filter = manual
pvrinput.HideMainMenuEntry = 1			//yes (hide main menu entry)
pvrinput.Hue = 0				//50%
pvrinput.LogLevel = 3				//errors and (some) messages
pvrinput.Pvrusb2StopOnChange = 0		//don`t stop pvrusb2 encoder for channel switch
pvrinput.Saturation = 64			//50%
pvrinput.SliceVBI = 1				//only for ivtv-based cards: yes (slice VBI teletext)
pvrinput.TunerAudioMode = 4			//bilingual
pvrinput.UseOnlyCard = 8			//use all cards
pvrinput.VideoBitrateFM = 1500			//1,5 MBit/s for radio channels with VPID 301 
pvrinput.VideoBitrateTV = 6000			//6 MBit/s

Using filters may increase the picture quality, but the default value of 8 for the temporal
filter may cause ghosting effects. If this is the case, try smaller values.

Force the plugin to use a certain card
--------------------------------------
By default the plugin will detect and use all supported cards. For testing
purposes it may be useful to test the behaviour of a certain card. This could
be done by using the new channel syntax with the CARD parameter, but there is
also an easier way by using the PvrSetup.UseOnlyCard value. A value of 0 to 7
will force the plugin to use only /dev/videoX, while x is the value of 
PvrSetup.UseOnlyCard. "PvrSetup.UseOnlyCard = 8" means that all detected
devices will be used.
Note: Don`t change vdr`s setup.conf while vdr is running, it won`t take effect
and will be overwritten by vdr when vdr terminates.
To allow setting PvrSetup.UseOnlyCard while vdr is running there is an OSD menu
entry. By default it is not visible to avoid confusion of a common user. To use
this feature just uncomment "//#define PVR_DEBUG" in menu.c before compiling
the plugin.