dxr3Player - DVD player for Linux/DXR3 dxr3player
Status: Beta
Brought to you by:
ivaradi
Menu
▾
▴
Tree [b1a57e] default tip / History
ivaradi
convert-repo
vi
Read Me
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
- liba52: 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.
-M <file>
<file> should be an MPEG-2 file (or FIFO) in DVD VOB format
which will be played back by the program instead of a DVD.
-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
"DATADIR/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.
-F
The default behaviour of the fast forward/backward keys
is to increase/decrease the speed of the playback. In other
words the fast forward key progresses through this sequence:
fast backward speed 3 -> fast backward speed 2 ->
fast backward speed 1 -> normal playback ->
fast forward speed 1 -> fast forward speed 2 ->
fast forward speed 3
The fast backward key goes through this sequence in reverse
order.
If this switch is given, however, a keypress in the opposite
direction will keep the speed, but change the direction.
For example, if currently we are fast forwarding at speed 2,
pressing the fast backward key will switch to fast
rewind at speed 2.
-c
If given, dxr3player will close the DVD tray when it quits
and the tray is open.
-n <deviceNumber>
Use the DXR3 board with the given device number.
-p
Shrink non-menu subtitles to fit into the middle 16:9 portion of
the screen if a 16:9 movie is played in a display mode of 16:9.
This actually only shifts the subtitles up or down.
-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.
-g <level>
Determine the cases when empty audio data is written to the DXR3
board if the placyback is stopped for some reason. <level> can
be one of:
0: empty audio data is never written
1: empty audio data is written if the playback is stopped to
switch to fast forward/backward
2: empty audio data is written if the playback is stopped to
switch to fast forward/backward or to jump a chapter
3: empty audio data is always written if the playback is stopped
-H <hacks>
Enables various "hacks" to tweak the behaviour of the program.
<hacks> is a string of one or more of the following characters:
1, 2, f: VOBUs are read only up to the first, second reference
picture or entirely, respectively, when fast
forwarding/backwarding.
VOBUs are about 0.5 second long units of the DVD, and when
fast forwarding/backwarding, only one frame, the so-called
I-frame is displayed from each VOBU. The beginning of the
VOBU contains information about the position of the first,
second and third reference frames.
In almost all cases the I-frame is the first reference
picture in the VOBU, but a few DVDs were found where
we need to read up to the third one, which is the current
default. With this switch you can change this. For example,
if you have a slow machine you might want to use "-H 1"
to avoid reading any unnecessary data.
b: If using a DXR3 board, video data will be buffered before
sending to the board.
Some DVDs were found where audio and video got out of
sync. The exact reason is unknown, but it is suspected,
that the way the video data is broken up into sectors
confuses the board.
-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
Shift+T, Alt+T go to the next/previous title track
Space pause/unpause playback
> fast forward
< fast backward
` (backtick) 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
[, ] decrease/increase brightness
;, ' [DXR3] decrease/increase contrast
., / [DXR3] decrease/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 liblirc_client 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
PREVIOUS_TITLE go to the previous title track
NEXT_TITLE go to the next title track
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 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
