1. Dependencies
  2. Installation
  3. Usage
  4. Configuration
  5. Controls
  6. Problems


oxine depends on a number of external libraries to support it in some of the more complicated tasks it has to perform. Please make sure to install the following libraries before you start compiling oxine.

Libraries marked as mandatory must be installed. It is suggested that you also install libraries marked as optional to improve oxine's overall experience.

Depending on the distribution you are using it may be necessary to not only install the library, but to also install the associated development packages. For Ubuntu this would mean that you would need to install liblircclient0 and liblircclient-dev.

Library Description Status
X.org You will need to install the X or X.org development files. mandatory
xine-lib This library provides the core functionality of oxine. Everything that has to do with video and audio playback depends on this piece of software. mandatory
gettext This library is used to provide internationalization. Without it translating oxine to your favorite language cannot work. mandatory
LIRC This library is necessary if you wish to use a remote control with oxine. optional

This library is necessary if you wish to display thumbnail or cover images. Although it is also possible to use ImageMagick for this purpose the higher speed of gdk-pixbuf (around factor 10 compared to ImageMagick) makes it the better choic.

Because gdk-puxbuf does not provide a method for reducing the number of colors in an image and because the OSD of xine-lib only support 256 colors oxine has to do the color reduction. This leads to a slightly worse image-quality than when using ImageMagick.

If image quality is important to you and the time needed to display an image is not relevant, please run

./configure --disable-gdkpixbuf <other options>
ImageMagick This library is necessary if you wish to display thumbnail or cover images and do not have gdk-pixbuf installed. If you wish to rotate images this library must be installed. optional
libcurl This library is necessary if you wish to enable oxine to download files via a network. This is needed e.g. for shoutcast support. optional
libcdio This library is used to identify ISO image files. Without it oxine will not know what to do with these files as it cannot know if it's looking at a DVD image, a VCD image or something else. optional
libiso9660 This library is actually a part of libcdio. Some distributions (e.g. Debian, Ubuntu) distribute it as a separate package. optional
libmetar This library is necessary if you wish to use the weather functionality. If you wish to use the weather functionality you will also have to install libcurl. optional

This library is recommended if you wish to use a joystick to control oxine. It makes the job of reading input from the joystick much easier and gives better results than when using the raw joystick interface.

There is a bug in versions of libjsw ≤ 1.5.5 that may cause oxine to crash if no joystick is attached. This bug has been fixed in 1.5.6 and may be fixed in earlier versions by some distributions (e.g. Ubuntu) as well. If oxine crashes when starting up please either disable libjsw by running

./configure --without-jsw <other options>

or install version 1.5.6 of the library.

These libraries are used to provide support for automatically detecting when new media such as CDROMs, DVDs or external harddrives are inserted. optional
libavahi-client Avahi is a system which facilitates service discovery on a local network. This means that you can plug your laptop or computer into a network and instantly be able to view other people who you can chat with, find printers to print to or find files being shared. oxine uses this library to find available Apple Airport Express in the local network. optional
libexif The Exchangeable image file format (EXIF) specifies a number of metadata tags for digital images. This library is used to read this metadata information from image files. oxine currently only displays the date and time an image was created but this could easily be changed to include more information. optional

Apart from the libraries oxine also depends on a number of command line programs.

Program Description Status
These tools are used by oxine to mount and unmount volumes. These tools are available on all linux base systems. mandatory
These tools are necessary if you want to mount and unmount volumes recognized by HAL. If these tools are available mount and umount will not be used. optional
eject This tool is necessary if you wish to eject drives (e.g. CDROM-drives). If this tool is not available oxine will try to eject the drives using the ioctl command. optional
cdparanoia This tool is necessary if you wish to extract audio CDs. optional
At least one of these tools is necessary to compress the extracted audio files. It is possible to choose what encoder to use in oxine's configuration menu. optional
dd This is needed if you wish to create DVD and VCD images. This tool is available on most linux base systems. optional


The installation is quite straight forward. Make sure that you have installed the latest version of xine-lib. At least version 1.0 is required. Then download and unpack oxine source tarball, change to the directory created and type

./configure --prefix=/some/path
make install

If you checked oxine out of SVN you must first create the configure script yourself. The tools autoconf and automake are needed for this to work. To run type

./autogen.sh --prefix=/some/path
make install

When building oxine a number of it's feature may be enabled or disabled. Most features are enabled by default. Only a small subset of features is not enabled by default. This is because these features (e.g. support for VDR or Apple Airport Express) are only interesting to a few users.

The following parameters may be used to configure oxine at build time. They may be passed to the scripts configure or autogen.sh:

./configure --help
  --disable-hal           do not activate HAL support
  --disable-extractor     do not activate ripping support
  --disable-exif          do not activate EXIF support
  --disable-gdkpixbuf     do not activate gdk-pixbuf support
  --disable-lirc          do not activate LIRC support
  --disable-joystick      do not activate joystick support
  --disable-weather       do not activate weather support
  --disable-shoutcast     do not activate SHOUTcast support
  --disable-youtube       do not activate YouTube support
  --enable-vdr            enable support for Video Disc Recorder (VDR)
  --enable-aex            enable support for Apple Airport Express (AEX)
  --enable-debug          enable support for debugging
  --without-curl          Turn off CURL support.
  --without-imagemagick   Turn off ImageMagick support.
  --without-jsw           Turn off libjsw support.

Users who want to help debug oxine should add --enable-debug to the options they pass to configure or autogen.sh. This enables debug messages that often make it easier to find out what goes wrong.


There exist a number of command line options oxine accepts. These can be used to change the standard behaviour of oxine (e.g. what configuration file or what log file to use).

It is also possible to deactivate certain features that were enabled at build time but are not needed by the user.

The following command line options are known to oxine:

Usage: oxine [OPTIONS] [MRL]

  -c, --config <filename>      Use non-standard configuration file.
  -v, --version                Display version.
      --verbose=<level>        Set verbosity level. Default is 0.
  -l, --logfile <filename>     Set the log filename.
  -V, --video-driver <drv>     Select video driver by ID.
                               Available drivers:
                               auto xv xshm sdl
  -A, --audio-driver <drv>     Select audio driver by ID.
                               Available drivers:
                               alsa esd file none
  -X, --xineramascreen=<num>   Sets the screen on which the fullscreen window                               
                               will be shown.
  -F, --no-fullscreen          Do no start in fullscreen mode.
  -L, --no-lirc                Do not use remote control (LIRC).
  -J, --no-joystick            Do not use joystick support.
  -W, --no-weather             Do not automaticaly retrieve weather information.
  -H, --no-hal-dbus            Do not use HAL/ DBUS to monitor removable drives.

Depending on how you configured oxine at build time some of the above options may not be available. If you for example configured oxine without weather support the command line option --no-weather will not be available.


There are two location where oxine keeps it's configuration files. One is in $PREFIX/share/oxine/ ($PREFIX is the installation prefix where you installed oxine. This will usually be /usr/ or /usr/local/) and the other is $HOME/.oxine/ ($HOME is your home directory).

Especially the file $HOME/.oxine/config is important. This is where all configuration values are saved by oxine. This file will be created the first time you run oxine.

oxine's configuration can be changed by editing the configuration file directly or by selecting "Edit Settings" from the oxine main menu.

The following sections describe various issues that need to be addressed before oxine is fully functional.

Please read the ChangeLog when updating oxine. As the program is still alpha configuration and feature may change between releases.


oxine comes with one standard skin. This skin (oxinetic) is in english and for 4:3 monitors only.

Skins in your favorite language and skins for 16:9 monitors can be downloaded from the oxine subversion repository by running

svn co https://oxine.svn.sourceforge.net/svnroot/oxine/trunk/oxine-skins

The skins in that directory can be installed by running

./install.sh <skinname>

If a skin is missing in your favorite language or resolution please file a support request telling us what language and resolution (4:3 or 16:9) you need.

Once you've installed other skins the skin to use can be selected via the 'User Interface' section of the configuration menu or by changing the following configuration key:

# Skin to use
# { oxinetic  default  oxinetic-de  oxinetic-de-hdtv }, default: 1

Removable Media

If you wish to use a CDROM or DVD drive please make sure the correct devices are set in the configuration file. The following configuration keys are relevant:

# device used for DVD playback
# string, default: /dev/dvd

# device used for CD audio
# string, default: /dev/cdrom

# CD-ROM drive used for VCD when none given
# string, default:

Remote Control

To control oxine with a remote control the library LIRC must be installed and correctly configured.

The names of the oxine LIRC commands were choosen to be descriptive rather than to fit to a specific remote control. This means that nearly all remote controls will not work out of the box.

There are two options to fix this:

What you should not do is modify $PREFIX/share/oxine/lircrc directly, as this will be overwritten whenever oxine is reinstalled.

If you use LIRC, make sure that you don't have the irxevent daemon running. Otherwise oxine may get all LIRC events twice which is quite annoying.

Main Menu

Starting with version 0.6 it is possible to configure oxine's main menu.

The default menu file is located in $PREFIX/share/oxine/mainmenu.xml. This file should not be changed as it will be overwritten whenever oxine is reinstalled. Instead you should copy this file to $HOME/.oxine/mainmenu.xml and modify it there. The file must follow the syntax as described in $PREFIX/share/oxine/DTD/menu.dtd

The default menu file contains a complete set of permitted parameters and some examples.


When selecting "Listen to Music", "Watch Films" or "View Images" the user enters the file selection dialogs. The main difference between the three is what files are displayed. When selecting "Listen to Music" only audio files are displayed while selecting "Watch Films" will only display video files and "View Images" will only display image files.

To customize the entries the user sees when first entering these dialogs mediamarks files may be created in $HOME/.oxine/ called:


For an example of how these files might look please have a look at $PREFIX/share/oxine/mediamarks_example.xml. These files must follow the syntax defined in the mediamarks document type definition.

Shutdown Dialog

When pressing the "Shutdown" button in the main menu oxine displays a dialog asking the user what he wishes to do. If the user specifies the necessary commands

# shell command (reboot)
# string, default: /sbin/reboot

# shell command (power off)
# string, default: /sbin/poweroff

# shell command (standby)
# string, default:

in the configuration file, the user can also choose to shutdown or reboot the computer or to switch the computer to standby mode.

If the configuration key

# ask before leaving oxine
# bool, default: 1

is set to 0 this dialog will not be displayed.

Thumbnail Images

There are three ways to make oxine display thumbnail images in the filelist and the playback menu:

  1. If you place an image in a directory oxine will show that image whenever that directory is opened in the filelist menu or a file from that directory is being played in the playback menu. The image may have any name. If a file called title.jpg, title.png or title.gif exists oxine will display that.
  2. You may also add a thumbnail link to an entry in a mediamarks file:
        <mrl href="dvd:/home/public/lotr.iso" />
        <title>[Lord Of The Rings (ISO)]</title>
        <thumbnail href="/home/public/lotr.png" />
  3. You may add a '.directory' file to a directory that contains an entry 'Icon':
    [Desktop Entry]

For thumbnails to work you must have ImageMagick installed on your computer.

Video Disc Recorder

Starting with version 0.6 oxine can be used with Klaus Schmidinger's Video Disc Recorder via the vdr-plugin-xine.

Support for VDR is not enabled by default. To enable it you must run

./configure --enable-vdr <other options>

As soon as you've got VDR and vdr-plugin-xine up and running, oxine should work with it without any further problems. To use VDR please change the configuration key

# type of television
# { Analogue Television  Digital Television  Video Disc Recorder }, default: 1
television.type:Video Disc Recorder

to 'Video Disc Recorder'.

Apple Airport Express

Using the xine-lib audio output plugin for the Apple Airport Express which can be downloaded from the oxine subversion repository by running

svn co https://oxine.svn.sourceforge.net/svnroot/oxine/trunk/xine-aex

it is possible to output audio on any Apple Airport Express available on the local network.

If you have the AVAHI client library installed (see above) oxine will automatically find any available Apple Airport Express and make them available in the settings menu.

At the moment it is only possible to output audio via one Apple Airport Express or via the normal sound card.

Password protection

Directories on local discs can be password protected by placing a file .password inside that directory.

The .password file must contain exactly one password. The password may be in clear text or (as in /etc/shadow/) encrypted.

Due to some limitations of oxine's widget toolset the directory is not entered at once after providing the password. The user must double click on the directory again to enter.

Please note, that this does not protect the directory in any meaningful way. Anyone with direct access to the filesystem will not care at all about the .password file. This is only good enough to keep kids (depending on the kids) out of some directories.

Audio CD extractor

The audio CD extractor support three different output format:

  1. Lossless (FLAC)
  2. Lossy (OGG)
  3. Lossy (MP3)

By setting the following configuration keys it is possible to pass extra parameters to the programs doing the actual encoding:

# FLAC encoder (flac) parameters
# string, default: 

# MP3 encoder (lame) parameters
# string, default: 

# OGG encoder (oggenc) parameters
# string, default: 

Another configuration key does the same thing for the program doing the ripping (cdparanoia):

# CD extractor (cdparanoia) parameters
# string, default: 

If for example you want the FLAC encoder (flac) to use the higest level of compression you might want to set:

# FLAC encoder (flac) parameters
# string, default: 

DVD and video CD extractor

By default the command dd is used to copy complete images of DVD's and video CD's to disc. As this may not work for all discs other programs can be specified by changing the following configuration keys:

# DVD extractor command
# string, default: /bin/dd if=%s of=%s
#extractor.dvd.command:/bin/dd if=%s of=%s

# VCD extractor command
# string, default: /bin/dd if=%s of=%s
#extractor.vcd.command:/bin/dd if=%s of=%s

If for example you wish to use mplayer to extract DVD's you might want to set:

# DVD extractor command
# string, default: /bin/dd if=%s of=%s
extractor.dvd.command:mplayer dvd:// -dvd-device %s -dumpstream -dumpfile %s

The first %s of the commands is replaced with the device name (e.g. /dev/dvd). The second %s is replaced with the output filename. Please note, that it is not possible to change the order of device name and filename in the command.


oxine can be controlled using a keyboard, a mouse or a remote control (using LIRC).

The names of the LIRC commands were choosen to be descriptive rather than to fit to a specific remote control. On most systems it will be necessary to change these names to the command names of the remote control used (see remote control).

Menu Navigation

Action Keyboard Remote control
navigate the menus arrow keys up, down, left, right
next widget Tab next_widget
previous widget Shift-Tab prev_widget
(de)select items in a list Space select
activate items or buttons Enter activate
go back/ up one level Esc, Backspace back

Direct Menu Access

Action Keyboard Remote control
show the help menu F1 menu_help
show the settings menu F2 menu_settings
show the playback menu F3 menu_playback
start television playback F4 television
show the main menu F5 menu_main
show the music menu F6 menu_music
show the video menu F7 menu_video
show the image menu F8 menu_image
show the playlist menu F9 menu_playlist
show the weather menu F10 menu_weather


Action Keyboard Remote control
leave the program Ctrl + q quit
show the shutdown dialog q shutdown
eject a removable volume e eject
save configuration/ playlist Ctrl + s save
toggle fullscreen mode f toggle_fullscreen
show/ hide onscreen display o show_osd

Playback Control

Action Keyboard Remote control
adjust volume v / V, + / - volume [+/-]
seek in stream Ctrl + Alt +
arrow right/ left
skip [+/-]
adjust speed Ctrl +
arrow up/ down
speed [+/-]
fast forward/ rewind Ctrl +
arrow right/ left
stop s stop
toggle mute/ unmute m toggle_mute
toggle pause/ play Space toggle_pause_play
toggle playmode M toggle_playmode
toggle aspect ratio a toggle_aspect_ratio
toggle deinterlace i toggle_deinterlace
change audio channel x / X audio_channel [+/-]
adjust audio offset c / C audio_offset [+/-]
change subtitle channel r / R spu_channel [+/-]
adjust subtitle offset t / T spu_offset [+/-]
adjust zoom factor Z / z zoom [+/-]
adjust x-zoom factor Ctrl + Z / z zoom_x [+/-]
adjust y-zoom factor Alt + Z / z zoom_y [+/-]
reset zoom factor Ctrl + Alt + Z / z zoom_reset


Action Keyboard Remote control
previous entry Ctrl + page up prev
next entry Ctrl + page down next


Action Keyboard Remote control
previous image Ctrl + page up prev
next image Ctrl + page down next
rotate clockwise Ctrl + r rotate_right
rotate clockwise Ctrl + F5 red
rotate counter-clockwise Ctrl + l rotate_left
rotate counter-clockwise Ctrl + F8 blue


Action Keyboard Remote control
previous chapter Ctrl + page up prev
next chapter Ctrl + page down next
escape from the menu Ctrl + F1 menu1
go to the title menu Ctrl + F2 menu2
go to the root menu Ctrl + F3 menu3
go to the subtitle menu Ctrl + F4 menu4
go to the audio menu Ctrl + F5 menu5
go to the angle menu Ctrl + F6 menu6
go to the chapter menu Ctrl + F7 menu7


Action Keyboard Remote control
previous channel Ctrl + page up prev
next channel Ctrl + page down next

Video Disc Recorder

Action Keyboard Remote control
previous channel Ctrl + page up prev
next channel Ctrl + page down next
show main menu Ctrl + F1 menu1
show channel menu Ctrl + F2 menu2
show schedule menu Ctrl + F3 menu3
show recordings menu Ctrl + F4 menu4
depends on the location (see OSD) Ctrl + F5 red
depends on the location (see OSD) Ctrl + F6 green
depends on the location (see OSD) Ctrl + F7 yellow
depends on the location (see OSD) Ctrl + F8 blue


If you have trouble doing something with oxine please try to do the same thing with xine before reporting it as a bug. If it doesn't work in xine it will normally not work in oxine. This is not true the other way around as many things implemented in xine have not been added to oxine yet.

If you do find a bug please report it to the issue tracker, send a mail to the oxine-devel mailing list or directly to one of the developers. Good patches are very welcome.