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.

License:
--------

    This is a output plugin for Klaus Schmidinger's vdr.
    Copyright (C) 2007  Roland Praml,
                        Stefan Lucke, Torgeir Veimo, Martin Wache

    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.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

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.3.x and VDR 1.4.x .
VDR must be at version 1.3.7 or greater!

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


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.

Commandline arguments:
----------------------
Complete list of suitable options is available when vdr is called with
option "-h" for help. Subarguments of each output method can be combined.

 -vo METHOD{:SUBARGUMENTS}
     Specify desired output method. Possible values:
     dfb      Output via DirectFB.
              Available subarguments:
              mgatv           TV-out for Martoy cards.
              viatv           TV-out for other cards (from Via, ??).
              cle266          Enable Via hardware decoding support.
              triple          Use triple buffering for output.

     dummy    Use a dummy device for video out.

     fb       Output via framebuffer.

     shm      Output via shared memory. You'll need a special client
              ShmClient for video viewing.

     vidix    Output via vidix.

     xv       Output via X11-Xv.
              Available subarguments:
              full            Startup in fullscreen mode.
              max-area        Use maximum available area for video source.
              use-defaults    Reset video out options to default values found
                              at startup. Usually we use those values from
                              previous run.
              aspect=wide     Startup with an initial aspect ratio of 16:9.
                              Video window size will be 1024x576.
              aspect=normal   Startup with an initial aspect ratio of 4:3.
                              Video window size will be 768x576.

 -ao METHOD{:SUBARGUMENTS}
    Specify desired output method. Possible values:
    dummy     no output at all.
    alsa      normal audio output via alsa
              Availavble subarguments:
              mixer           Use alsa mixer for volume control. By default,
                              volume control is done via software scaling.

              Devicename subarguments must be terminated by '#'.

              pcm=DEVICE      Device name for audio PCM out.
              ac3=DEVICE      Device name for AC3 pass through.

    Example:
    -ao alsa:mixer:pcm=default#ac3=hw:0,2#

ALSA audio device names:
------------------------
In most cases it is enough to use the alsa default device name "default".
In case of several installed cards, the exact name could be specified
like "hw:0,0". If this still does not fit your needs (ac3 analog out,
redirecting/remapping logical channels to physical ones, ..), you may
specify for each number of channels some special action, as we try
to open device CH1, CH2, CH3, CH4, CH5, CH6 according to current number
of channels. As fallback mode, we still try to open specified pcm device
name which defaults to "default" :-) .

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, vidix
    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
    For correct scaling operations, you'll have to specify geometry
    of your output device.
    - When using some sort of TV-out, you should choose either 4:3 or 16:9.
    - With LCD monitors, you should specify the geometry of the native
      resolution. That is for example in case of 1280x1024 monitor: 5:4 (even
      it is driven by a 1024x768 signal).
    - When default is used, we assume a geometry which is derived from the
      assumption that your monitor operates in square pixel mode.

  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ä
- Artur Skawina
- Chris Elsworth
- Colin Paton
- Herbert Attenberger
- Holger Waechtler
- Konrad Naumann
- Laurence Abbott
- Luca Olivetti
- Lucian Muresan
- Malcolm Caldwell
- Marko Mäkelä
- Martin Wache
- Matthias Schwarzott
- Nicolas Huillard
- Petri Hintukainen
- Prakash Punnoor
- Roland Praml
- Rolf Ahrenberg
- Stefan Lucke
- Thomas Günter
- Torgeir Veimo
- Vadim Catana
