dxr3Player
                            ==========

dxr3Player is a lightweight, command-line DVD player primarily for
Linux and the DXR3 (aka Hollywood+) MPEG-2 decoder boards. It supports
all major DVD features, including: menus, navigation, fast forward and
backward playback, subtitles and camera angle changes. The player is
very conservative on memory usage and tries very hard (and mostly
succeeds) to keep video and audio in sync.

While originally written for the DXR3 decoder board, dxr3Player can
also play DVD using the following other configurations:

- any X Window System display using the Simple DirectMedia Layer (SDL) 
  library.

- Via EPIA-M motherboards equipped with the Unichrome (CLE266) video
  adapter and MPEG-2 decoder. This support is provided by a driver 
  built in dxr3Player. This is an almost completely user-space driver,
  with optional kernel support for smooth frame flipping. It is 
  experimental, and has never run on a motherboard other than that
  of the author (an EPIA MII 10000 with revision 17 of the Unichrome IC). 
  Its compilation is also non-trivial as of now. See more details below.

The project is hosted at Sourceforge:

        http://dxr3player.sourceforge.net

The software includes the following libraries from MPlayer, which
are mostly modified copies of other libraries (thanks:)):

- libmpdvdkit: to read DVDs
- liab52: to decode AC-3 audio streams

It relies on the dxr3 (EM8300) drivers developed by the
dxr3 project at Sourceforge (http://dxr3.sourceforge.net)

For SDL-based playback the following libraries are used:

- libSDL itself
- libmpeg2: to decode MPEG video streams

For Unichrome support the information for the driver is taken from
the following sources:

- the DirectFB unichrome driver (http://www.directfb.org)
- Andreas Robinson's MPEG-2 decoder 
- the Unichrome project (http://unichrome.sourceforge.net)
- Via's Unichrome framebuffer driver

Installation
============

See the INSTALL file in this directory.

Usage
=====

    dxr3player [<options>]

Options can contain the following switches:

    -d <dvd>
        Use <dvd> as the default DVD device. If given, the program
        checks if <dvd> is a DVD device, and uses that, if so. 
        Otherwise it tries the following devices:

        - /dev/dvd
        - /dev/hda
        - /dev/hdb
        - /dev/hdc
        - /dev/hdd

        You can also give the path of a DVD image dump, a mounted
        DVD directory or a copy of a DVD directory.

    -l <language>
        Use the given 2-letter language code as the default language.
        This is only an indication to the DVD's "program", and it may 
        choose to not honour it.

    -A <language>|<stream number>
        If a 2-letter language code is given, force the playback of 
        the audio stream for the given language. If a stream number is
        given (between 0 and 7), force the playback of that stream.
        
    -S <language>|<stream number>
        If a 2-letter language code is given, force the playback of 
        the SPU stream for the given language. If a stream number is
        given (between 0 and 31), force the playback of that stream.

    -t 
        Keep the default TV standard (as set in the driver), 
        regardless of how it changes on the DVD.

    -a 
        Keep the default aspect ratio (as set in the driver), 
        regardless of how it changes on the DVD.

    -D pcm|ac3
        Switch the audio output to digital in the given mode:
        
        pcm - digital PCM-only output on SPDIF (AC-3 streams are
              decoded into stereo PCM and output as such)
        ac3 - digital AC3 output on SPDIF (a PCM or MPEG audio track is 
              output as stereo PCM)

        Note, that DTS audio streams are always output on SPDIF, 
        they are not decoded.

    -O
        Use an OSS sound card even for DXR3-based playback.

        Note, that synchronization may be quite imperfect in this
        case.

    -o <offset>
        Set the audio playback offset. If audio is not perfectly in sync
        with video, this option causes it to be played with a fixed
        offset. The offset is according to the clock of the DVD's 
        timestamp, which runs at 90kHz. So, to achieve 1 second *delay*
        in audio, you need to specify 90000; in order to play audio
        1 second *earlier*, <offset> should be -90000.
 
    -r <region>
        Set the region code to <region>. By default, all regions
        are enabled. There are, however, DVDs that don't like it.
        In that case you may set your region with this option.

    -i <directory>
        Look for data files in the given directory. 

        It may contain informational sequences in the "info"
        subdirectory.

        Informational sequences are MPEG-1 or MPEG-2 video files,
        that are played continuously by the program when something 
        other than the playback of a DVD is going on. The files 
        should reside in the directory specified (which defaults to 
        "/usr/lib/dxr3player/info") with the following names:
        
        - trying.mpg: played when there is no DVD in the drive,
          and the application is continuously trying for one.
        - decoding.mpg: played when opening and decoding the disk.
        - ejecting.mpg: played when ejecting the DVD.

        Icons (for the OSD of Unichrome-based playback) can be found 
        in the "icons" subdirectory.

    -j <joystick>
        Use <joystick> as the default joystick device. It defaults 
        to /dev/js0.

    -x
        If given, dxr3player will quit completely when an EXIT
        instruction is executed in the DVDs program.

    -m <microcode>
        Upload microcode to the DXR3 board from the given file.

    -s <size>
        Use a read buffer of <size> sectors. 

        By default the read buffer is 1024 sectors. On a fast 
        machine you may lower this value, which results in lower
        memory consumption and faster camera angle changes
        (to make angle changes "seamless", one cannot flush
        the read buffer). On a slower machine, you may have to 
        increase this value.

    -e 
        Eject DVD after startup.

    -f <scr frequency>
        This option is being deprecated. The player should now
        automatically adapt to the frequency of your DXR3 board.
        However, should you have any synchronization or skipping
        problems, read on, as it may help.

        The audio and video streams on the DVD have timestamps 
        according to a clock running at 90 kHz. The DXR3 also has
        an on-board clock which it uses to play video data. 

        However, audio must be synchronized by the player to this
        clock. Because this clock and the computer's clock are not 
        in sync, the DXR3 clock frequency is perceived by the program
        to be slightly different from 90 kHz. With this argument
        you can specify this frequency in millihertzs (i.e. 
        90kHz would be 90000000). The 'calibrate' utility displays
        the frequency, e.g:

            vi@vi:~/tmp/local/bin$ ./calibrate
            Please wait 60 seconds
            19:56:21: Base SCR: 0, base millis: 1057686981082
            SCR: 5399748, time difference: 60002.000000, freq: 89992.800240

        In this case the program sees a frequency of 89992.800 Hz.
        To use it, you would specify -f 89992800.

    -V
        Print the verbose debug messages too.

    -L <log file name>
        Log also into the given file.         

Note that some switches may not be available depending on
the configuration options. (For example, if you do not
configure joystick support, the -j switch will not be usable.)

Configuration file
------------------

Configuration options can be stored in the configuration file.
Its name is

        $HOME/.dxr3player/config

A sample configuration file with a lot of documentation can be 
found in the "misc" subdirectory of the sources.

An option present on the command-line overrides the corresponding
setting in the configuration file.

Keyboard
--------

Currently the player supports keyboard input in Linux terminals
(Linux character console, xterm, rxvt, gnome-terminal and probably
others too). It does not use termcap, so you may have some problems
with certain terminals.

Some keys have different meaning with a DXR3 board and SDL-based
playback, or may work only with one of those. In such cases,
the mode the meaning is associated with is denoted by [DXR3] 
and/or [SDL].

You can use the following keys:

    Cursor Keys, 
    2, 4, 6, 8          navigate in menus

    Enter, 5            activate the current menu item

    t                   go to "Title" menu

    r                   go to "Root" menu

    R                   go to "Root" menu and try to find it
                        if the current title has not root menu

    s                   go to "Subtitle" menu

    a                   go to "Audio" menu

    n                   go to "Angle" menu

    p                   go to "Part" menu

    Page Up, Shift+P    previous chapter    

    Page Down, Shift+N  next chapter    

    Space               pause/unpause playback

    >                   fast forward

    <                   fast backward

    1                   resume normal playback

    End, e              stop playback and eject DVD

    =, -                increase, decrease audio (AC-3) volume

    v                   reset audio (AC-3) volume to default

    m                   mute/unmute audio (AC-3)

    Shift+A             change to next camera angle

    Shift+L, Alt+L      select the next/previous audio stream
                        This works only if the -A option is not given.

    Shift+S, Alt+S      select the next/previous subtitle stream
                        after the last/before the first one the
                        subtitles will be turned off and then turned
                        back if one of these keys is pressed again
                        This works only if the -S option is not given.

    o                   [DXR3] toggle between VGA overlay and TV output
                        
                        [SDL] toggle between full-screen and windowed mode

    [, ]                decrase/increase brightness

    ;, '                [DXR3] decrase/increase contrast

    ., /                [DXR3] decrase/increase saturation

    z                   save the current position on the DVD

    Z                   restore the position of the current DVD to the
                        saved one

    i                   print status information (for debugging
                        purposes)

    Shift+Q             quit the player

Remote control
--------------

Remote controls are supported using LIRC (http://www.lirc.org).
The liblirclient library is used, meaning that you should
use your ~/.lircrc file for configuring LIRC usage.

Some config strings different meaning with a DXR3 board and 
SDL-based playback, or may work only with one of those. In 
such cases, the mode the meaning is associated with is 
denoted by [DXR3]  and/or [SDL].

The program name ("prog=..." line) should be "dxr3player".
The "config" strings should be one of the following strings:

    UP                  select the button (menu option) 
                        above the current one

    DOWN                select the button (menu option) 
                        below the current one

    LEFT                select the button (menu option) 
                        to the left of the current one

    RIGHT               select the button (menu option) 
                        to the right of the current one

    ACTIVATE            activate the current button (menu option) 

    MENU_TITLE          go the "Title" menu
        
    MENU_ROOT           go to "Root" menu

    MENU_ROOT_FORCED    go to "Root" menu and try to find it
                        if the current title has not root menu

    MENU_SUBPICTURE     go to "Subtitle" menu

    MENU_AUDIO          go to "Audio" menu

    MENU_ANGLE          go to "Angle" menu

    MENU_PART           go to "Part" menu
        
    PREVIOUS_CHAPTER    previous chapter    

    NEXT_CHAPTER        next chapter    

    PAUSE               pause/unpause playback

    PLAY_FAST_FORWARD   fast forward

    PLAY_FAST_BACKWARD  fast backward

    PLAY                resume normal playback

    EJECT               stop playback and eject DVD

    VOLUME_UP           increase audio (AC-3) volume

    VOLUME_DOWN         decrease audio (AC-3) volume

    VOLUME_RESET        reset audio (AC-3) volume to default

    TOGGLE_AUDIO        mute/unmute audio

    INCREASE_BRIGHTNESS increase brightness

    DECREASE_BRIGHTNESS decrease brightness

    INCREASE_CONTRAST   [DXR3] increase contrast

    DECREASE_CONTRAST   [DXR3] decrease contrast

    INCREASE_SATURATION [DXR3] increase saturation

    DECREASE_SATURATION [DXR3] decrease saturation

    CHANGE_ANGLE        change to next camera angle

    NEXT_AUDIO_STREAM   select the next audio stream

    PREVIOUS_AUDIO_STREAM   select the previous audio stream

    NEXT_SPU_STREAM     select the next subtitle stream

    PREVIOUS_SPU_STREAM     select the previous subtitle stream

    TOGGLE_OUTPUT       [DXR3] toggle between normal and VGA overlay mode

                        [SDL] toggle between full screen and windowed mode

    SAVE_DVD_STATE      save the current position on the DVD.

    RESUME_DVD_STATE    restore the position of the current DVD to the
                        saved one.

    QUIT                quit the player

See the file "misc/lircrc.lircemu" for an example for the
LIRC emulator.
    

A rather odd infrared remote control, the eDio IR 401 is also 
supported. It has an IR receiver which plugs into a MIDI port 
(e.g. on your sound card). 

Joystick
--------

It is possible to control dxr3player from a joystick. See 
the sample "config" file for how to configure this.

VGA overlay
-----------

The DXR3 board supports VGA overlay. Currently, dxr3Player
implements full-screen "overlay", i.e. when the whole display
is occupied by the picture. 

You should calibrate the overlay parameters with the 'autocal'
utility found in the 'overlay' subdirectory of the em8300
driver sources. 

Compile with --enable-overlay to add support for this feature.
You should run the application under X (it is needed to get
the resolution from). Make sure that the loopback cable is used,
and your monitor is connected to the DXR3 board. Otherwise the
the program will not run correctly, and may even freeze!

You can switch between output to the TV and the monitor by
pressing the 'o' key.

Notes about SDL mode
--------------------

In SDL mode (i.e. when executing "dxr3player-sdl") the program
outputs video into an X Window System window and sound onto
a sound card with OSS interface. ALSA works too with OSS 
emulation. Audio volume setting affects only AC-3 audio,
as with DXR3. You should normally use a mixer program to 
setup volumes.

By default, the window size is 960x720. It can be changed by
setting one or both of the 'initialWindowWidth' and 
'initialWindowHeight' configuration parameters in the 
configuration file. If the latter parameter is not set, 
it will be 3 / 4th of initialWindowWidth, i.e. the 
aspect ratio will be 4:3. 

If your screen's resolution  does not have an aspect ratio
of 4:3 (e.g. 1280x1024), you may want to reflect it in the
window size (e.g. you can set it to 960x768). 

The window can be resized. Only the new width is taken into
account and the height is adjusted to keep the aspect ratio
determined by the initial window size.

Notes about Unichrome support
-----------------------------

The Unichrome-enabled version of dxr3Player is called
"dxr3player-unichrome". Due to the fact that it uses its
own driver, it does not cooperate with X (with or without
the Unichrome project's driver), so you should run it
standalone. 

It has a simple OSD. This OSD support requires some files
in the data directory (specified by the -i switch):

- the font file: normal.fnt

- the icon files in the "icons" subdirectory:

  audioLanguage.ico
  chapter.ico
  ff1.ico
  ff2.ico
  ff3.ico
  flag_DE.ico
  flag_EN.ico
  flag_HU.ico
  pause.ico
  play.ico
  rew1.ico
  rew2.ico
  rew3.ico
  spuLanguage.ico

The font file can be created by the "convertfont" utility. This
utility is compiled only if FreeType support is enabled. If so,
and a font file is also given, the "normal.fnt" file will be 
created during compilation in the "misc/osd/default" directory. 
A size of 28 pixels is used.

The icon files can be created by the "png2uci" utility. This
utility is compiled only if LibPNG support is turned on. If so,
the icons are created in the "misc/osd/default/icons" directory
during compilation. The .png files are provided.

Run these utilities with no arguments to get a help.

A kernel module is built optionally. It uses the experimental
major number 62. To change it, modify the following line in
"src/lib/unichrome/kernel/uchelper.c":

    #define MAJOR_NR 62

The "/dev/uchelper" device must be created also:

    mknod /dev/uchelper c 62 0

The module created is "uchelper.ko". It has no arguments. If 
it is loaded and the device file is present, dxr3Player will use
it automatically.

Making DVD dumps
================


As an aid to debug problems with the playback of particular
DVDs, a new utility called "dumpdvd" is included. It can be 
used as follows:

    dumpdvd [-d dvdPath] [-p] outFile

It will make a dump into file <outFile>. The other options are
as follows:

    -d <dvdPath>
        The path of the DVD device. This is the same as for dxr3player.

    -p 
        Print the contents in textual format. Useful for debugging only.

You can also make a full dump of a DVD, i.e. dump the complete DVD in
a decoded form for later playback:

    dumpdvd -f [-d dvdPath] [-p] dumpDirectory

The dump will be created in the directory <dumpDirectory>. It must exist
when starting the dump. Such a dumped DVD can be played back by dxr3player
using the -d option:

    dxr3player -d dumpDirectory