path: root/README

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

Written by:                  Petri Hintukainen <phintuka@users.sourceforge.net>

Project's homepage:          http://www.sourceforge.net/projects/xineliboutput

Latest version available at: http://prdownloads.sourceforge.net/xineliboutput/


See the file COPYING for license information.


Description

  X11 and Linux framebuffer front-end for VDR.
  Plugin displays video and OSD in X/Xv/XvMC window,
  Linux framebuffer/DirectFB/vidixfb or DXR3 card.

  Support for local and remote frontends.

  Built-in image and media player supports playback of most known 
  media files (avi/mp3/divx/jpeg/...), DVDs and radio/video streams
  (http, rtsp, ...) directly from VDR.


Requirements

  - vdr-1.4.0 or later
    (vdr is required only at server side)
  - xine-lib 1.1.1 or later
    (xine-lib is not required for server in network-only usage)
  - Enough CPU power and memory to decode streams
    (PII 400Mhz + 64M should be enough with Xv or DirectFB)

  Optional:

  - X server with Composite and Xrender extensions,
    compositing window manager or composite manager (xcompmgr).
    (Required for HUD OSD to blend high-quality OSD using graphics hardware)
  - libextractor 0.5.20 or later (http://libextractor.sourceforge.net).
    (used for media file metadata extraction in media player)

WARNING

  Remote (network) mode should be used only in firewalled 
  environment; it gives anyone full control to VDR !

  Full access is allowed to all hosts listed in svdrphosts.conf.

  Multicast streaming can flood your internet connection and/or
  wireless LAN. If there is no router (or intelligent switch ?)
  all multicast packets will be broadcasted to all network links.
  This will flood slow network links:
    - Internet connection if outgoing bandwith is < 10 Mbit/s
    - Wireless LAN (11 or 54 Mbit/s).
  By default multicast TTL is set to 1 so multicast packets should
  be stopped to first router regardless of network configuration.


Public CVS

  Latest fixes are available from sourceforge.net public CVS
  (http://sourceforge.net/cvs/?group_id=160063).

  CVS checkout command:
  cvs -d:pserver:anonymous@xineliboutput.cvs.sourceforge.net:/cvsroot/xineliboutput co vdr-xineliboutput


Buildtime options

  X11 and xine-lib are detected by Makefile.
  It is possible to override auto-detection by adding
  following definitions to VDR's Make.config:

    enable/disable building of X11 frontends:
      XINELIBOUTPUT_X11 = 1
      XINELIBOUTPUT_X11 = 0

    enable/disable framebuffer frontends:
      XINELIBOUTPUT_FB = 1
      XINELIBOUTPUT_FB = 0

    enable/disable xine (input)plugin:
      XINELIBOUTPUT_XINEPLUGIN = 1
      XINELIBOUTPUT_XINEPLUGIN = 0

  or changing corresponding lines in plugin's Makefile.

  It is possible to compile only remote frontends with command 
  "make frontends". Building frontends is possible without VDR.
  Only xine-lib (and corresponding development package or headers)
  are required.


Installing - IMPORTANT

  XINE'S DYNAMIC LIBRARIES AND FRONTEND EXECUTABLES ARE NOT
  INSTALLED AUTOMATICALLY.

  It is important to copy required libraries to right place
  either by hand or by executing "make install" in plugin's
  source directory.
  Installing binaries and libraries usually requires root
  permissions.

  PLUGIN WILL NOT WORK UNLESS ALL FILES HAVE BEEN INSTALLED !

  To be able to use remote frontends each client's IP address
  must be defined in VDR's svdrphosts.conf.
  Full access is allowed to all hosts listed in svdrphosts.conf.
  Connections from any other hosts are rejected.


Usage examples (VDR plugin)

  If no arguments are given, both X11 and framebuffer frontends are tried.
  First working frontend is used with best available video driver.
  Complete list of available command-line arguments can be obtained
  with "vdr --help".

  Only local frontend, X11/Xv video, alsa audio:
    vdr -P"xineliboutput --local=sxfe --video=xv --audio=alsa --remote=none"

  Only local frontend, (slow) X11 video, oss audio:
    vdr -P"xineliboutput --local=sxfe --video=xshm --audio=oss --remote=none"

  Only local frontend, DirectFB: 
    vdr -P"xineliboutput --local=fbfe --video=DirectFB --remote=none"

  Only remote frontend(s):
    vdr -P"xineliboutput --local=none --remote=37890"

  Local and remote frontends:
    vdr -P"xineliboutput --local=sxfe --remote=37890"
  or
    vdr -P"xineliboutput --local=fbfe --remote=37890"


Using remote frontends

  Two remote frontends are included, vdr-fbfe for framebuffer and 
  vdr-sxfe for X11.
  Complete list of available command-line arguments can be obtained
  with "vdr-??fe --help".

  Frontend should find server automatically (from local subnet) 
  and negoate best available transport. If frontend does not
  find server (or specific transport should be used), mrl must
  be given on command line.

  Examples:

    Search for VDR (xineliboutput) server, connect to it and
    negoatite best available transport. Use best available audio 
    and video driver.
      vdr-fbfe
    or
      vdr-sxfe

    Connect to 192.168.1.3 default port and negoate best available transport
       vdr-fbfe xvdr://192.168.1.3

    Connect to 192.168.2.100, port 12550 and use TCP transport
       vdr-fbfe xvdr+tcp://192.168.2.100:12550

    Automatically search for VDR server and use UDP transport
        vdr-fbfe xvdr+udp:
      or
        vdr-fbfe --udp

  Available transports for video/audio 
      pipe  Use local pipe; server and front-end must be running in 
            same machine
      rtp   Use RTP/UDP multicast for data and TCP for control. 
            Multiple frontends can receive same stream.
      udp   Use UDP unicast for data and TCP for control.
      tcp   Use TCP protocol for control and data. Both channels 
            use same server port and are opened by client.

  Forwarding lirc keys to server
     Use option --lirc with optional lircd socket name to
     forward LIRC commands from client to server.

  Audio driver
    Use alsa:
      vdr-fbfe --audio alsa
    Use alsa (and specific card/sub-device):
      vdr-fbfe --audio alsa:plughw:1,1

  Video driver (and display / device):
    With X11 frontend (vdr-sxfe):
        vdr-sxfe --video [xshm | xv | xvmc | xxmc | vidix |
                          XDirectFB | opengl | sdl | none [:display]]
      Examples:
        --video xv
        --video xvmc:127.0.0.1:1.0

    With framebuffer frontend (vdr-fbfe):
        --video [fb | DirectFB | sdl | vidixfb | dxr3 | aadxr3 | none [:fb_device]]
      Examples:
        --video DirectFB
        --video fb:/dev/fb/1
        --video vidixfb
        --video aadxr3

  De-interlacing
    If deinterlacing post plugin options are not given at command line, 
    deinterlacing is controlled by VDR plugin configuration menu settings.

    De-interlacing can also be forced on or off with command-line option --post tvtime.
    Examples:
      vdr-sxfe --post tvtime:method=Linear,cheap_mode=1,pulldown=0,use_progressive_frame_flag=1
      vdr -P"xineliboutput --post=tvtime:method=Linear,cheap_mode=1,pulldown=0,use_progressive_frame_flag=1"
    Disable deinterlacing:
      vdr-sxfe --post tvtime:enable=0


HUD OSD

  HUD OSD implements high-quality OSD using modern graphics hardware.
  OSD is scaled and blended using hardware, so it adds no extra CPU 
  overhead. OSD is always blended to output (display) resolution,
  so it remains sharp and detailed even with low-resolution video.

  HUD OSD must be enabled with command-line option (--hud). Scaling
  options can be configured in xineliboutput plugin setup menu, 
  OSD settings page.

  Requirements:
    - X server with Composite and Xrender extensions.
      Composite extension must be enabled in Xorg config.
    - Composite window manager (compiz, beryl, or properly configured xfce4, metacity, ...)
      or separate composite manager (xcompmgr).
    - Compatible graphics hardware and drivers.
      HUD OSD has been tested with:
        nVidia GF FX5700LE      (driver version 169.09)
        Intel G965 (GMA-X3000)  (driver version 2.2.1, textured XVideo)

        metacity 2.23.2
        xcompmgr 1.1.3

  NOTE: 
    - Drawing video (even without OSD) may be slower when composite 
      extension is enabled.

    - Try to adjust OSD size and offsets to get rid of possible graphical
      corruption.

    - For true HD-resolution OSD VDR needs to be patched.

  HUD OSD was contributed by Antti Seppälä and Rolf Ahrenberg.


Using with xine-ui (xine, fbxine, gxine, ...)

  Examples:
    xine "xvdr://127.0.0.1#nocache;demux:mpeg_block"
    xine "xvdr+tcp://127.0.0.1:37890#nocache;demux:mpeg_block"
    xine "xvdr+udp://127.0.0.1:37890#nocache;demux:mpeg_block"

  "#nocache;demux:mpeg_block" should always be appended to end of mrl.

  Remote mode must be enabled in VDR plugin.

  Some configuration options are not available when using 
  third-party frontends.


Using with other media players (mplayer, vlc, ...)

  Primary device video and audio (without OSD or subtitles) 
  can be streamed from plugin control port to almost any media 
  player using http or rtsp.

  Session Announcement Protocol (SAP) compatible players 
  should detect stream automatically and add it to playlist 
  or bookmarks when RTP transmission is active (tested with vlc).

  Tested players: 

    Linux: mplayer, vlc, xine
    Windows: vlc

  Examples:

    mplayer http://192.168.1.3:37890
    vlc http://192.168.1.3:37890
    vlc rtsp://192.168.1.3:37890
    vlc rtp://@224.0.1.9:37890


Controlling VDR

  With local frontend, vdr-sxfe and vdr-fbfe:

    Keyboard input from console is mapped to VDR keyboard input. 
    If VDR was compiled or configured without keyboard support,
    console keyboard input does not work.

    Keyboard input from X11 window is mapped to XKeySym remote.
    Keys are mapped to VDR keys in remote.conf file. Simple example
    of X11 key mappings is included in examples directory.

    It should be possible to use VDR's remote controller learning
    mode by pressing some key just after VDR has been started.
    Learning mode does not work with remote frontends.

    Keyboard input can be disabled in configuration menu. There
    are separate entries for local and remote frontends.

  With xine-ui:

    Keyboard shortcuts and remote events from xine menus are 
    automatically forwarded to VDR and translated to VDR keys.
    Translation to VDR keys is static and defined in xine_input_vdr.c.


Frontend key bindings

  Esc     Close frontend (vdr-fbfe / fdr-sxfe)
  
  Mouse left button double-click
          Toggle between fullscreen / window mode (vdr-sxfe only)

  Mouse right button click
          Toggle between normal window / always on top /
          borderless window (vdr-sxfe only)

  Close Window
          Close frontend (fdr-sxfe only)


Image viewer key bindings

  Left/Prev       Previous image
  Right/Next      Next image
  Up/Down         Jump 5 images forward/backward
  Yellow          Delete current image
  Back            Return to image list
  Stop/Blue       Exit image viewer
  Play            Start slide show
  Pause           Stop slide show
  FastFwd/FastRew Start slide show; Increase/decrease slide show speed; 
                  Change slideshow direction
  Ok              Toggle replay display mode

Media player key bindings for video files

  Back         Return to file list
  Red          Open playlist if more than one file in the playlist,
               otherwise jump to beginning of file
  Green        Jump 1 min back
  Yellow       Jump 1 min forward
  Stop/Blue    Stop replay
  User7        Random play / normal play
  1, User8     Jump 20 s back
  3, User9     Jump 20 s forward
  2            Move subtitles up
  5            Move subtitles down
  Down/Pause   Pause replay
  Up/Play      Play
  Ok           Toggle replay display mode
  Next         Skip to next file when replaying playlist
  Prev         Skip to previous file when replaying playlist
  FastRew/Left Play slower
  FastFwd/Right Play faster

Media player key bindings for audio files

  Back         Return to file list
  Red          Open playlist
  Green        Jump 1 min back
  Yellow       Jump 1 min forward
  Stop/Blue    Stop replay
  0...9        Use to select a file from the playlist 
               according to its position on the playlist
  Down/Pause   Pause replay
  Up/Play      Play
  Ok           Toggle replay display mode
  Next/Right   Skip to next file
  Prev/Left    Skip to previous file or restart the currently playing file 
               if more than three seconds has been played back already
  FastRew/FastFwd  Play faster/slower
  User7        Random play / normal play

  with VDR < 1.5.15:
    If media file includes multiple subtitles (DVD, .mkv file, ...),
    subtitle language can be selected from xineliboutput plugin menu, 
    "Select subtitle track" key macro or from DVD subtitle menu.
    Preferred subtitle languages can be selected from plugin setup menu.

  with VDR >= 1.5.15:
    If media file includes multiple subtitles (DVD, .mkv file, ...),
    subtitle language can be selected with VDR Subtitle key or from
    DVD subtitle menu.
    Plugin uses VDR's preferred subtitle language settings.

DVD player key bindings

  Up/Down/Left/Right/Ok/Back  DVD menu navigation when DVD menu is active
  Red            Access DVD menu(s)
  Green          Jump 1 min back
  Yellow         Jump 1 min forward
  Stop/Blue/Back Stop replay
  Ok / Info      Toggle replay display mode
  1 / User8      Jump 20 s back  
  3 / User9      Jump 20 s forward
  Pause / Down   Pause replay
  Play / Up      Play
  6 / Next,      Next chapter
  4 / Prev       Previous chapter
  9              Next title
  7              Previous title
  Info           Show progress display
  2              Next subtitle track     (with VDR < 1.5.15)
  5              Previous subtitle track (with VDR < 1.5.15)
  FastRew/FastFwd,
  Left/Right    Play faster/slower


DVD playback

  DVD images

    Media player supports playing DVDs directly from hard disk.
    Found DVD folders are marked with 'D' in media player 
    file list.
    Plugin detects folders as DVDs if there is file 
    Name_Of_DVD/VIDEO_TS/VIDEO_TS.IFO.

    It is also possible to replay DVD as VDR recording by 
    creating empty recording directory and renaming or
    symlinking .VOBs of selected title to 00?.vdr files.
    DVD menus (VTS_??_0.VOB) should _not_ be copied.
    Audio can be selected from main menu just as with normal 
    VDR recordings.
    For seeking it is necessarily to create index.vdr file
    with genindex or similar tool.

  DVD discs

    "Real" DVD discs (accessible from /dev/dvd) can be played 
    from xineliboutput plugin menu.

    In case of remote frontend (vdr-sxfe/vdr-fbfe) DVD drive 
    of _remote client_ is used.

  Audio track can be selected from VDR audio track menu 
  (keys "Menu" + "Green" or "Audio") or from DVD menu.

  with VDR < 1.5.15:
    DVD subtitle language can be selected from xineliboutput plugin 
    menu, from DVD menu, with keys "2" and "5" or from subtitle
    menu (using "Select subtitle track" key macro).
    Preferred subtitle languages can be selected from plugin setup menu.

  with VDR >= 1.5.15:
    DVD subtitle language can be selected with VDR Subtitle key or 
    from DVD subtitle menu.
    Plugin uses VDR's preferred subtitle language settings.


Aspect ratio setting

    default  Aspect ratio is calculated from display resolution.

    4:3      4:3 video is scaled to fill whole window; 
             16:9 video has black bars at top and bottom

    16:9     16:9 video is scaled to fill whole window; 
             4:3 video has black bars at left and right.

    16:10

    auto     4:3 and 16:9 are scaled to fill whole window.
             (useful if TV can "smart scale" 4:3 video to 16:9)


Shortcut key macros

  It is possible to change some settings and execute actions with 
  user-defined key macros and VDR User? keys.

  Supported settings and corresponding key sequences in VDR 
  keymacros.conf format are:

    Start replaying DVD                  (User? @xineliboutput Red 0)
    Start replaying Title 1 from DVD     (User? @xineliboutput Red 1)
    Select subtitle track (VDR <1.5.15)  (User? @xineliboutput Red 2)
    Toggle aspect ratio                  (User? @xineliboutput Red 3)
    Toggle letterbox -> 16:9 cropping    (User? @xineliboutput Red 4)
    Toggle stereo -> 5.1 upmix           (User? @xineliboutput Red 5)
    Toggle 5.1 -> surround downmix       (User? @xineliboutput Red 6)
    Toggle de-interlacing                (User? @xineliboutput Red 7)
    Toggle local frontend on/off         (User? @xineliboutput Red 8)
    Start replaying default playlist or file pointed by symlink 
    $(CONFDIR)/plugins/xineliboutput/default_playlist
                                         (User? @xineliboutput Red 9)
    Increase audio delay                 (User? @xineliboutput Red Up)
    Decrease audio delay                 (User? @xineliboutput Red Down)
    Toggle the video aspect ratio        (User? @xineliboutput Red Right)

  with VDR < 1.5.15:
  Defining "Select subtitle track" macro key enables VDR-style
  subtitle track menu for media player (identical to audio track 
  selection with VDR "Audio" key).


Special frontend control keys

  When frontend is started with --hotkeys command-line option, following
  keyboard and LIRC keys are interpreted by vdr-sxfe/vdr-fbfe:

    Keyboard (console and X11 window)
      f, F         Toggle fullscreen state
      d, D         Toggle deinterlacing

    LIRC
      Fullscreen   Toggle fullscreen state
      Deinterlace  Toggle deinterlacing
      Quit         Close program

  [ this run-time option replaces old build-time options 
    INTERPRET_LIRC_KEYS and XINELIBOUTPUT_FE_FULLSCREEN_TOGGLE ]


Xine-specific settings

  All xine-specific settings can be changed by editing file
  $(HOME)/.xine/config_xineliboutput.

  Default mpeg2 decoder (libmpeg2) can be switched to ffmpeg mpeg2 decoder
  by increasing ffmpeg decoder priority:

     engine.decoder_priorities.ffmpegvideo:1

  (ffmpeg decoder is slower but handles errors better).


Slave mode

  vdr-sxfe and vdr-fbfe implement simple slave mode. Slave mode is 
  activated with command-line option --slave. In slave mode program reads 
  CRLF-terminated commands from standard input instead of using keyboard
  as VDR remote controller. Supported commands are:

  HITK <vdrkey>    Send key press event to VDR
  FULLSCREEN       Toggle fullscreen state
  DEINTERLACE      Toggle deinterlacing
  QUIT             Close program

  Video can be drawn to existing X11 window with vdr-sxfe 
  option --wid=<x_window_id>


Distributed set-up - multiple clients and/or servers

  Simple multi-head setup

  When there is no need to watch different recordings / channels at
  different clients at the same time, just running vdr-[sx/fb]fe at 
  each client is enough. In this case the same video + OSD is mirrored 
  to all clients and all clients control the same (shared) VDR.

  Real multi-user setup

  When there is a need to have multiple independently controlled 
  clients (each with separate video and OSD), running multiple 
  instances of VDR is required.
  It doesn't matter if all VDR instances run at server or at each
  client. However, there are some benefits when running all 
  instances of VDR on the same server:
   - less maintenance: only one installation of VDR and plugins is required
   - posibility to use simpler, diskless clients with less memory
   - Faster cutting / DVD burning / ... as there is no 
     network between VDR and disks
   - no need to export and mount /video to every client
   - overall resource usage is lower
   - ...

  It is preferred to allow recording only at the "master" vdr. 
  Recording the same timer on two VDR instances will most likely
  corrupt the recording. Besides that, doing all recordings directly
  from DVB card (no streamdev in middle) makes things simpler and less
  error prone. It is probably even impossible to do several recordings
  from different transponders using single streamdev instance.

  Timersync plugin disables recording on client VDRs. All timers
  are still visible at each client and timers can be created/modified
  at any client just as with the single VDR setup.
  Timersync plugin synchronizes all timer modifications between VDR instances
  and takes care that all recordings are made by the "master" vdr.
  Still, all kind of autotimer plugins etc. that generate timers 
  should be activated only at server vdr (there shouldn't
  be any reasons to run multiple instances of such plugins).

  Simplified example:  
    (xinelibout and streamdev plugins required)

    Start 3 VDRs at server:

    "Master" VDR: controls all DVB cards, does all recordings, 
                  server for client 1

        vdr -c /etc/vdr \
           -P"xineliboutput --local=none --remote=37890" \
           -Pstreamdev-server

    VDR server for client 2:

        vdr -c /etc/vdr2 \
           -D 10 -p 2102 \
           -P"xineliboutput --local=none --remote=37892" \
           -Pstreamdev-client

    VDR server for client 3

        vdr -c /etc/vdr3 \
           -D 10 -p 2103 \
           -P"xineliboutput --local=none --remote=37894" \
           -Pstreamdev-client

    + all possible other options and plugins.

    - Using -D 10 option for client VDR instances "forces" all DVB 
      cards for master VDR.
    - Each VDR instance must have its own configuration directory (-c option).
    - Each xineliboutput server uses different port
    - Streamdev plugin is used to provide live view for client
      VDR's. It is not required to just watch recordings.
      To correctly configure vdr-streamdev plugin, see 
      streamdev plugin's README.
    - Using suspendoutput plugin with some proper timeout value
      in VDR instances might be good idea - it releases
      streamdev VTP connection and server-side DVB devices
      for other use when the client is not in use.

    Starting clients:

      Client 1:   vdr-sxfe

      Client 2:   vdr-sxfe xvdr://<server ip>:37892

      Client 3:   vdr-sxfe xvdr://<server ip>:37894

    - If RTP is used between vdr and vdr-sxfe, using separate 
      RTP address or port for each xineliboutput server 
      instance might be good idea.


VDR Logo

  The VDR logo was designed by Jan Grell.