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

Initial versions by:         Roland Praml
Further development by:      The Softdevice Team
                             Stefan Lucke, Torgeir Veimo, Martin Wache

Project's homepage:          http://softdevice.berlios.de


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

This plugin is a MPEG2 decoder.
It can be used as an output device for the vdr. Possible output devices are
Xv, DirectFB, Vidix or a framebuffer.


Requirements:
-------------

- libavcodec (i took the one shipped with ffmpeg 0.4.8)
- libavformat (also included in ffmpeg)
  It is recommended that after building ffmpeg you do:
  make install
  make installlib
  By this it is guaranteed that all libraries _and_ headers
  get installed.

- ALSA

And one of the following:
- DirectFB compatible VGA-Card
- DirectFB (I use cvs, 0.9.20 should work also)
- DFB++ (I use cvs, 0.9.20 should work also)

 OR
- Vidix compatible VGA-Card
- Vidix-library

 OR
- XV compatible VGA-Card

 OR
- A strong CPU and a Framebuffer with 16 bit

Typically a CPU with around 1 GHz gives you smooth playback for
all accelerated video out methods (all except framebuffer).

Installation:
-------------

This plugin is written for VDR 1.2.x, VDR 1.3.x and VDR 1.4.x

As usual, unpack the plugin and make a link in the
./VDR/PLUGINS/src directory

By default you should "cd" to softdevice directory and run "./configure" .
This will generate config.h and config.mak files, which will guide make.
Available parameters of configure are listed by "./configure --help" .

Users of vdr-1.2.x have to disable build of shm-out by:
./configure --disable-shm

To get rid of these generated files a "make dist-clean" should be done.

Without running configure, you'll have to modify the Makefile to your needs.
Comment out all ouput methods that you don't plan to use
( put a "#"-sign in at the start of the line ). Adjust the path to libavcodec
in the Makefile, and disable all other features you don't want.

If you don't plan to use Xv,set up a framebuffer on /dev/fb0

recommened resolution: 768x576
16bit with Framebuffer output
32bit with DFB/Vidix output

Start vdr with -P "softdevice -vo [your prefered output method]:"
Example:
- vdr -P "softdevice -vo xv:" for X11/Xv
- vdr -P "softdevice -vo dfb:" for DirectFB


If you compiled softdevice with option USE_SUBPLUGINS (the default from
Makefile) and you start vdr with option -L PATH or --lib=PATH , you'll have to
specify that pathname to softdevice too via option -L PATH.


To get a full list of options try "vdr -h"

Set the PrimaryDVB value to the last device if you own a FF-Card.

Note that we strongly recommend to use Xv, DirectFB or Vidix for output.
Framebuffer mode is not well maintained and  _completly_ unaccelerated.


AC3 pass through:
-----------------
For using AC3 pass through, you have to specify the IEC958 device name of
your sound card. Which device to use, can be checked with ac3play.
For my system, ac3play works with: "ac3play -C -D 0,1 AC3_FILE_NAME"

So my vdr call with parameter list for softdevice looks like:
-P "softdevice -ao alsa:pcm=default#ac3=hw:0,1# -vo dfb:mgatv"

Notice the trailing '#' of the last alsa subparameter.

AC3 pass through is mainly based on the code of ac3play-0.5.2f, so
many thanks to the authors of that program.


Shared Memory Client/Server
---------------------------

There is now an experimental client/server model in the softdevice. To use
it compile the softdevice with SHM_SUPPORT enabled and start it using
"-vo shm:". The softdevice will then start with the decoding suspended until
a client connects to the shared memory. For now there is only an Xv client.
To start the Xv client simply type "ShmClient", and a window will open
from which you can use Vdr just like you are used to from the Xv-out will open up. When
this window is closed the Softdevice will automatically suspend the decoding.
It is possible to make a client for the other video-out methods too, but
I found the Xv-Client the most usefull for combined desktop/vdr machines :-)
The softdevice doesn't always remove the shared memory segment which is
used for comunication with the client, if you have troubles with that (or
you get an error message that the client/server can't connect to the shm ctl)
you can remove the shared memory segment with "ipcrm". First you have to
find out the shared memory id, type the command "ipcs" and look for the
key "0x0000162" the shared memory id is next to it. Them remove the
shared memory segment with "ipcrm shm shared_memory_id".
There is currently one limitation to the ShmClient: it has no access to the
SetupStore, this means that some settings, for example hue, contrast and others
are not available.

OSD setup options:
------------------
  Cropping:

    CropMode:
      Output methods: X11-XV, DirectFB, vidix
      Possible Values: none, 4:3, 16:9, 14:9
      This option selects either the 4:3, 16:9, 14:9 or no specific
      area of current video stream. No specific area value will choose
      the video stream as is.

    CropModeToggleKey:
      Output methods: X11-XV, DirectFB
      Possible Values: USERx (x = 1 .. 9)
      You may specify a vdr USERx key of your remote to cycle throu
      CropModes.

    Zoom factor:
      Output methods: X11-XV, DirectFB, vidix
      Possible Values: 0 .. 128
      Zoom calculation: 1 + (value² / 1024) with maximum result 17

    Zoom area shift:
      Output methods: X11-XV, DirectFB, vidix
      Possible Values: -100 .. 100
      Value measured in %, shifts the zoomed out part left / up (with
      negative numbers) or right / down (with positive numbers). All zoom
      specific values are not stored in vdr's setup.conf file.

    Crop lines / columns:
      Output methods: X11-XV, DirectFB
      By this you may replace video line from top, bottom, left and right
      with black lines. It may be usfull, if there is some time code
      information or some WSS information is present in the viewable
      area (shown as white dots). Changing these values does not effect
      displayed aspect ratio.

    Expand lines /columns:
      Output methods: X11-XV, DirectFB, vidix
      Intention of this option is similar to crop lines. The advantage
      is the you don't get black lines instead of unwanted content.
      The disadvantage is that changing these values effects displayed
      aspect ratio.

  Post processing:

  Video out:
    Output methods : X11-XV
    The following subselections are available if the driver of
    current video card supports it:

    Brightness, Contrast, Hue, Saturation:
      Possible Values: 0 .. 100
      Center and default value of all is 50.

  Xv startup aspect
    Output methods : X11-XV
    Possible values: 4:3 normal, 16:9 wide
    You may choose the startup window aspect for next time starting
    vdr. It either in 4:3 format with video size of 768x576 or a
    in 16:9 format with size of 1024x576 .

  Screen aspect
    Possible values: default, 5:4, 4:3, 16:9, 16:10

  OSD alpha blending
    Output methods : X11-XV, Vidix
    Possible values: pseudo, software

  Buffer mode
    Possible values: safe, good seeking, HDTV

  Playback
    Possible values: playing, suspended

  A/V Delay
    Possible values: 0 .. 250

  AC3 Mode
    Possible values: Stereo (2CH), 5.1 S/P-DIF,
                     5.1 Analog (4CH), 5.1 Analog (6CH)
    This specifies what should be done when we get AC3 audio frames.
    When set to 5.1 S/P-DIF no software decoding is done. AC3 frames
    are passed directly from your sound card to your audio processing
    equipment.
    If you choose any of (xCH) modes, it depends on the capabilities of
    the decoding libary for getting any output. We request a 2, 4 or 6
    channel downmix of the AC3 data. If your libary (ffmpeg) does not
    support downmixing, you'll get silence. In such a situation you'll
    have to select an other audio track/channel of your selected source.

  Sync Mode
    Possible values: usleep, rtc, sig
    The method for syncing video output to audio output is determined by
    this option.

  Pixel Format
    Output methods : DirectFB, Vidix
    Possible Values: YV12, I420, YUY2

  Use StretchBlit
    Output methods : DirectFB
    Possible Values: off, on

  Hide main menu entry
    Possible values: yes, no
    When set to yes, softdevice setup menu is not shown in vdr's main
    menu. Softdevice developers usually set this to no, normal end user
    tend to set this to yes. If softdevice setup menu is hidden, it is
    still accessible via vdr -> setup -> plugins -> softdevice .

Problems/todo:
--------------
What does NOT work:
- Other depths than 16/15 bit framebuffer are not supported. (in FB-mode)

The code in the plugin is based on parts of:
- mplayer
- mpeg2dec
- alsa
- ac3play-0.5.2f

Many thanks to:
- Andre Neumann
- Antti Seppälä
- Colin Paton
- Herbert Attenberger
- Holger Waechtler
- Konrad Naumann
- Laurence Abbott
- Luca Olivetti
- Lucian Muresan
- Malcolm Caldwell
- Marko Mäkelä
- Martin Wache
- Nicolas Huillard
- Roland Praml
- Rolf Ahrenberg
- Stefan Lucke
- Thomas Günter
- Torgeir Veimo
- Vadim Catana

