Documents List ...
GeeXboX Wiki Documentation Base ...
Booting on Mac ...
Enabling Post-Processing Effects ...
Building the GeeXboX ...
MPlayer Documentation ...
Using the installer ...
GeeXboX installed on dual boot Linux ...
Editing TV Configuration ...
Editing Network Configuration ...
Editing WiFi configuration ...
Using a gateway to access to the Internet and play streaming media ...
Booting from PXE using NFS shares ...
Firmware auto-loader ...
UPnP File Sharing ...
DVB cards Support ...
DVD Navigation Menus ...
Network streaming ...
GeeXboX Wiki Documentation Base ...
The GeeXboX team provides you a wiki (collaborative documentation web space) in order to help you using the GeeXboX distribution. The overall goal of this Wiki is to provide to the newcomers the necessary help to start dealing with GeeXboX. There you can find many tips for optimizing your GeeXboX system or even some special configuration needed for reluctant hardware stuff.
The GeeXboX Wiki also features a developer section that will help everyone who intend to add new packages to the distribution, explaining how to create patches and help the core team with development issues.
As every wiki in the world, it depends on user feedback to be fullfilled. Save and share your knowledge.
Booting on Mac ...
Booting from CD on a Mac is very easy: just hold the 'c' key at boot time. Same goes for network boot, but with the 'n' key instead.
Now, if you want to use a Mac as a GeeXboX only computer, it's a pain to have to hold a key at every boot. The solution is then to setup the boot-device open-firmware variable. There's at least two easy ways to do it:
* from a MacOSX shell, you can use the following command:
sudo nvram boot-device='cd:,\\:tbxi'
note that you can also display variables content with:
nvram -p
* directly from the open-firmware prompt (by pressing command-option-O-F at boot time):
setenv boot-device cd:,\\:tbxi
note that you can also display variables content with:
printenv
Some of the possible boot-devices are :
* cd:,\\:tbxi for CDROM boot
* hd:,\\:tbxi for harddisk boot
* enet:, for network boot
Enabling Post-Processing Effects ...
Post-Processing is a software way to get a smoother and more accurate render of your videos. It however consumes a lot of CPU time to magnify pictures but, as a result, it looks far better. Using MPlayer internal filters, GeeXboX lets you make horizontal and vertical deblocking, deringing and auto luminance to enhance your image. By default, post-processing is disabled to avoid lagging on small configurations. You can enable it simply by editing the /etc/mplayer/mplayer.conf file :
# Set Post Processing (h deblock, v deblock, dering, auto luminance)
# Consumes CPU power, disabled for low configs, uncomment to enable it.
#vf=pp=hb:a/vb:a/dr:a/al:a
Building the GeeXboX ...
First, you have to be root (the building scripts need to mount the boot disk image in loopback).
Then you can build the iso with :
make
Or you can directly burn this iso with :
make burn
When done, you can save disk space by cleaning the build tree :
make clean
or by doing a full cleaning, even removing downloaded sources :
make distclean
There's also more advanced commands if you want hack around the GeeXboX :
scripts/get package # download the package
scripts/unpack package # unpack and prepare the package
scripts/build package # build the package
scripts/install package # install the package with the $INSTALL prefix
scripts/clean package # clean the package source tree
If you've made a hacked version of the GeeXboX, you can easily build a small tar.gz for it with :
make dist
or a full tar (containing all sources) with :
make fulldist
or even, create the ISO generator package thanks to :
make generator
The only thing you will have to worry about is the GeeXboX configuration file.
MPlayer Documentation ...
The GeeXboX uses MPlayer. As this player is one of the most powerful media players, it can be started in several different ways. In the GeeXboX, two files are used to control MPlayer's options :
* ./packages/MPlayer/menu_lang.conf
* ./packages/MPlayer/mplayer.conf
The menu_lang.conf is used to generate the OSD Menu. You may have to modify it if you wish to add or remove items from the menu, or to change the items captions to fit your needs.
The mplayer.conf is related to MPlayer's lauching options. The default config file contains some of the following lines :
vo=vesa:vidix,vesa # Video Output driver (Use VidiX if available, VESA otherwise)
ao=alsa # Audio Output driver
alang=en,fr # DVD Audio language : try first one then go to second if first does not exists and so on ...
mixer-channel=Master # Device to be controlled by volume keys
framedrop=yes # When set to 'yes', MPlayer may skip decoding some frames if the video plays too slowly
vsync=yes # Activate Vertical Synchronization
fs=yes # Enable Fullscreen (need more CPU)
zoom=yes #Enable Zoom - modify aspect ratio (need more CPU)
menu=yes # Display OSD Menu
double=yes # Enable Double Buffering
fixed-vo=yes # Use a fixe image ratio
nocolorkey=yes # Deactivate the Colorkey
cache=1500 # Cache Size (in kB)
idx=yes # Let MPlayer rebuild a file with broken headers
lircconf=/etc/lirc # Path to LIRC configuration file
subfont-text-scale=3 # OSD Fonts Size
screenw=800 # Screen Width
screenh=600 # Screen Height
More documentation about MPlayer and its configuration files may be found at MPlayer's Documentation.
Using the installer ...
GeeXboX maybe is a LiveCD but it can also be installed on disk (only on x86_32 for now). Then, you're able to quickly and easily install the system on any IDE/SATA hard disk, SD Card, Compact Flash or USB keys (check that your motherboard's BIOS support boot from USB-HDD). You can install GeeXboX on a new disk (standalone partition) or on an empty partition from your current disk. All you need is a partition with at least 128 MB of disk storage.
Installation is not at all difficult, simply booting on the GeeXboX CDROM. At the IsoLinux prompt menu, just choose the installation item. The GeeXboX will now load on a menu for disk install.
Just follow the instructions and choose the hard disk on which you want GeeXboX to be installed. When you're done, you'll get a cfdisk screen which will let you partition your disk. Use the arrows to go to any partition representing Free Space and hit the New button. Then, you go choose the type of partition you want. Many filesystems are currently supported: FAT 16/32 and EXT2/3 (choose FAT16/32 only if you want to see and edit your disk from Windows). If you intend to boot from this partition, don't forget to use the Flags menu to set the bootable flag to your partition. Finish with Commit and then Quit
Choose whether ot not you want your partition to be formatted (recommanded). The GeeXboX installer will autodetect the kind of filesystem you've choosed before and format it accordingly. If you've decided to use EXT filesystem, it is recommended to format it in EXT3 for better data integrity.
Then, the installer asks you whether you want a bootloader to be installed or not (in case of removable devices, bootloader installation is automatically forced). A bootloader is software that lets you boot from a partition. GeeXboX comes with GRUB bootloader.
If you already have a bootloader on your disk, there's no need to install a new one, but you'll have to add boot arguments to it by hand to boot GeeXboX from it. Otherwise, if you have no other operating system on this disk or if you have a computer with a Microsoft Windows system, that doesn't allow multiboot, it is recommended to accept installing the bootloader. The GeeXboX installer will scan your disk for existing operating systems and create a multiboot that let you choose whether you want to be your former OS or boot GeeXboX. When done, you should be able to boot GeeXboX from hard disk just like any other system.
The next steps are optional. The GeeXboX installer propose you to configure the system the way you can have done it using the ISO generator. This is a post-install tool (also available as boot option, after installation), called configurator, that allows you to tweak many system configuration parameters.
If you really like GeeXboX and use it frequently, it would be a really good idea to install it on a hard disk. Indeed, the system can be seen as a new drive on Windows (if you'd choose to install on a FAT partition) or Linux and hence, it can be easily modified to fit your needs (changing MPlayer's configuration file, supported remote, network configuration ...) without having to regenerate the ISO and burn a CD.
GeeXboX installed on dual boot Linux ...
If you already have a Linux OS installed on your system, you might just want to add a GeeXboX entry to your existing bootloader. This allow you to install GeeXboX very easily.
From GeeXboX CD, simply copy the GEEXBOX folder into your Linux / partition (we suppose it to be /dev/sda1 here). Modify the /boot/grub/menu.lst file to add:
title GeeXboX
root (hd0,1)
kernel /GEEXBOX/boot/vmlinuz root=/dev/ram0 rw rdinit=linuxrc boot=UUID=$my_uuid lang=en keymap=qwerty splash ...
initrd /GEEXBOX/boot/initrd.gz
quiet
Just take are about two things:
- the field root (hd0,1) is to be adapted according to the rest of your GRUB's configuration.
- the $my_uuid value is the unique ID of your partition. Check within your GRUB config file, which value is set for other OS on the same partition or use ls -l /dev/disk/by-uuid/ to see which uuid matches your partition.
Editing TV Configuration ...
GeeXboX now supports TV inputs and tuners. Unfortunately, not all cards are supported. For the supported ones, the system tries to autodetect the card and the tuner. In some cases, autodetection may fail, resulting in an ugly distorted picture. That's why you can force the settings and skip the autodetection attempt. Please modify the /etc/tvsettings as described :
Please use the AUTO parameter if you want to keep autodetection active, or replace it by the number of your card and tuner types, according to the previous URL. Please be careful : in order to force the card and tuner types, you have to know the EXACT SPECIFICATIONS of your hardware.
Once done, you should be able to use the TV inputs (Composite and S-VHS) of your TV card. In the same way, you can use the tuner to watch TV. For that, you will have to define the region you belong to and the frequency of the TV channels you want to watch. Once again, simply edit the /etc/tvsettings file :
# TV Channels
# Syntax : CHAN="Channel Frequency:Channel Title"
# Example:
* #CHAN="29:France 2"
* #CHAN="K08:Canal +"
# TV Channels List
# Available : france, europe-east, europe-west, us-bcast, us-cable
* CHANLIST=france
Please be careful when editing channels and simply use the same syntax as described above and TV channels should be present in the main menu.
Editing Network Configuration ...
GeeXboX 0.90-4 and above come with network support for most Ethernet cards (not all of them, unfortunately) and Samba (Windows shares) support. GeeXboX is running a DHCP client which is trying to autoconfigure your network adapter. If you do not have a DHCP server on your network, you'll have to modify the /etc/network file which contains the following lines :
* HOST="" # GeeXboX IP ("" for DHCP)
* SMB_USER="SHARE" # User Login ("" for none)
* SMB_PWD="" # User Password ("" for none)
You can easily modify the IP and Samba Login and Password. On boot, the GeeXboX checks for remote computers from a common domain and tries to automount the Samba Windows shares. Be sure that all of your computers are on the same domain/subnet in order to mount all the shares.
Editing WiFi configuration ...
If you are a lucky owner of a Linux-compatible WiFi card, you will be pleased to know that the 0.97 release comes with support for it. By default, GeeXboX tries to autodetect your network settings. If you have both traditional NIC and WiFi cards, only the latter will be set up. One again, you may have to modify the /etc/network file in order to match your network's settings. In this case, 4 lines are related to wireless cards :
* PHY_TYPE="auto" # Network physical type (auto|ethernet|wifi)
* WIFI_MODE="managed" # Wifi working mode (managed|ad-hoc)
* WIFI_WEP="" # Wifi WEP key
* WIFI_ESSID="any" # Wifi SSID
These lines let you configure most of the settings. You can enable autodetection, or even force the use of ethernet or WiFi adapters. In the same way, this lets you choose between the managed and the ad-hoc mode and lets you define your WEP key and SSID.
Using a gateway to access to the Internet and play streaming ...
With the 0.97 release, GeeXboX now supports access to the Internet. Of course, there's no support for a direct connection to the Internet (no dial-up modem support and there never will be). If you've got a connection to the Internet, you may share it with your multimedia box, using a router or a gateway. For this, simply define the gateway IP address in the /etc/network file.
* GATEWAY="" # Gateway IP ("" for DHCP or no internet connection)
If you have a DHCP server, you don't even have to bother with these settings :p So GeeXboX is now fully able to play live videos, sounds or streaming, regardless of the contents. You simply have to put in a playlist file which contains the URL of the streams that you want to play (like Web-Radios for example ...).
Booting from PXE using NFS shares ...
GeeXboX 0.96 and above comes with NFS shares support, and lets you boot from the network with a diskless station using the PXE boot method. To achieve this you will need :
* a DHCP server
* a TFTP server
* a NFS server
* a PXE capable station :-)
Using a GNU/Linux system :
First, configure your DHCP server to send PXE boot information. Here is an example using ISC DHCP :
allow booting;
allow bootp;
subnet 192.168.0.0 netmask 255.255.255.0 {
range 192.168.0.128 192.168.0.192;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.0.255;
next-server 192.168.0.1;
filename "/tftpboot/GEEXBOX/boot/pxelinux.0";
}
The next-server option is the address of the TFTP server. Then, configure your TFTP server (such as atftpd) to serve the /tftpboot directory and copy a full GEEXBOX tree into this directory. For example, you can copy the contents of a GeeXboX CD from Linux WITH THE CDROM TRANSPARENT DECOMPRESSION ENABLED !! (to verify this, look at the sbin/init file in the GeeXboX tree and verify that it does not contain garbage). If you've built the GeeXboX yourself from sources, you can also generate the GEEXBOX tree with make pxe.
Then you should edit the file /tftpboot/GEEXBOX/boot/pxelinux.cfg/default to set nfsroot to the right NFS path to the GEEXBOX tree.
Finally set up your NFS to export the GEEXBOX tree with a /etc/exports that contains something like this :
/tftpboot/GEEXBOX (ro)
and a /etc/hosts.allow which contains something like :
ALL: ALL
That should do the trick. Boot your PXE station and see what happens ...
Using a Microsoft Windows system :
In order to boot in PXE mode from a Windows host, you'll need the following software :
* An TFTP and a DHCP Server (for example tftpd32 ).
* An NFS Server (for example Allegro NFS server ).
* A computer supporting PXE boot mode.
Download and uncompress (no need to install) the tftpd32 folder somewhere on your disk. In this example, lets assume it is : C:\tftpd32
Copy the complete GEEXBOX tree in the same directory (C:\tftpd32\GEEXBOX)
Start tftpd32 :
- Choose the C:\tftpd32 folder for "current directory".
- Choose the interface (network card) to be used in "server interface". In the example here it's 192.168.0.1
- Go in "setting" and make sure DHCP server is checked (enabled)
- In the "DHCP server" tab, fill in all the box using the following example (Please refer to some documentation about DHCP all around the net in order to understand) :
* IP starting pool : 192.168.0.10
* Size of pool : 10
* Boot file : ./GEEXBOX/boot/pxelinux.0
* WINS/DNS server : 192.168.0.254
* Default router : 192.168.0.254
* Mask : 255.255.255.0
* Domain name : mydomain.net
- Click "save" to apply modifications.
First part is done, you can now boot the client computer (the one starting GeeXboX), and will see it loading until the logo appears. After a while it'll freeze because your NFS server is not set yet.
Install "Allegro NFS server" and fill in the boxes following these settings :
Exports tab :
* Add a "new name" : and call it "/tftpboot/GEEXBOX"
* In "path" just below : choose "C:\tftp32\GEEXBOX" folder
* In "allowed host list" , choose "all"
* "Read write", and "read only user list", choose "root" and "everyone" (if you want some log just check all in the last tab)
Apply settings.
Don't forget to modify the file : C:\tftp32\GEEXBOX\boot\pxelinux.cfg\default and change the IP address "192.168.0.2" to "192.168.0.1" (or the one you've previously setup).
Just start the client computer and now GeeXboX should be running fine.
Firmware auto-loader ...
GeeXboX supports many free drivers but unfortunately some of them may require an additionnal proprietary firmware (non-free and so not included in GeeXboX ISO) to work properly. The firmware is a binary file that is uploaded to the device (PCI or USB) when the driver is loaded. For each driver, the firmware has to be a specific file with a pre-determined name.
If you have reluctant hardware that require additionnal firmware (in most of the cases, it only concerns WiFi and DVB cards), you'll need to check on the Internet for your Linux driver page to see how to check the firmware file. Most of the time, you'll get a direct download link. Sometimes, you'll need to extract it from your Windows drivers archive that was shipped with your hardware.
Once you get the firmware file, simply put it into the /firmware directory. You can put in as many firmwares as you want, and GeeXboX will automatically find them and use them with the right drivers if needed. The only thing you then have to take care is to have the good firmwares file and to generate a new ISO.
Please note that you can also use the GeeXboX ISO generator to automatically grab firmwares for you. You can select all of the extra binary firmware files you want the generator to add for you. Simply note that this feature will require you to have an Internet access when using the GeeXboX generator.
UPnP File Sharing ...
UPnP stands for Universal Plug And Play and is a network protocol aiming at providing the autodiscovery of devices and services of your Home Network. The UPnP A/V (for Audio/Video) norms defines several profiles for devices to easily share multimedia files and lets them being played. The UPnP Media Server profiles represent all of the devices that are able to share files to devices implementing the UPnP Media Player or UPnP Media Renderer profiles.
The GeeXboX embeds a UPnP Control Point software that is able to auto-discover all UPnP Media Servers from your Home network and it simply mounts their contents to a dedicated mount point (/mnt/UPnP).
This way, you just have to share contents using a compliant UPnP Media Server software and they'll be automatically accessible from GeeXboX. For more info about UPnP and some media servers usage, please go to our Wiki UPnP page.
DVB cards Support ...
GeeXboX has a support for various types of DVB cards (Terrestrial, Cable, ATSC and Satellite) either in PCI or USB. Please note that for now, only one DVB adapter is usable at a time.
Some DVB devices (especially USB ones) may require an external proprietary firmware to be loaded in the mean time as the driver to be usable. You may have a look at the LinuxTV DVB Wiki to see if your card requires one or not and if so, which one it is.
Some firmwares can be fetched directly from the LinuxTV website, otherwise may be included in the Windows drivers archive. See the GeeXboX firmware loader documentation to see how to get them loaded for you.
For each card, the list of channels is available through the MPlayer's open menu. Nevertheless, there's no way to auto-discover these channels.
Thus, adding the list of DVB channels to GeeXboX can be done in several ways :
- using an existing channel list : MPlayer needs to have a working channels.conf file to use DVB. This file can be generated through the tilities provided by the dvb-apps package. Simply use a Linux box that has a DVB card configured, download the linuxtv-dvb-apps tarball, compile it and create the config file using the scan executable, in zap format (which is the default as of dvb-apps 1.1.0). For example, for a DVB-S (Satellite) card using Astra-19.2E as the provider :
wget
tar jxvf linuxtv-dvb-apps-1.1.0.tar.bz2
cd linuxtv-dvb-apps-1.1.0/util/scan
make
./scan -x 0 dvb-s/Astra-19.2E > channels.conf
The -x 0 flag is here to restrict the scan to Free To Air channels only. Please always do so, as MPlayer do not support encrypted DVB channels.
According to your type of DVB card, choose either a file from the dvb-s, dvb-c, dvb-t or atsc directories and ask for a scan.
Then, simply copy the channels.conf file you've just created to the /etc/mplayer directory in the GeeXboX generator tree, and rebuild away.
- using an existing transponder list : the procedure is highly similar to the one defined just before but with no scan. This time, the scan will be done at GeeXboX boot but this way, you do no more require another Linux system to generate the channels.conf file.
To do so, you simpy have to check at the LinuxTV CVS .
According to your DVB card type (S/T/C/ATSC), check for the good directory and grab the transponder frequency list that fit your needs. Then simply rename the file to dvb.conf and copy it to /etc. Then, rebuild a new ISO using the generator.
At bootup, if GeeXboX detects a valid transponder file in /etc/dvb.conf, it will be used to scan for DVB channels and will generate the /etc/mplayer/channels.conf file by itself.
WARNING : Scanning can be slow according to the number of devices to be scanned and will be done each time you boot GeeXboX if using it as a LiveCD. It is highly recommended that you do it once only, then copy the generated /etc/mplayer/channels.conf file somewhere else and rebuild an ISO using generator, following the first method or to install it on disk.
- using installator : this is for sure the easiest solution but requires you to install GeeXboX to disk. During the installation process, if a valid DVB device is recognized by the system, the installator script will ask you if you want to scan for DVB channels.
The installator contains the complete list of transponders frequencies. That way, you just have to select your DVB device type and the transponder file you want to use for GeeXboX to scan. The channels.conf file will then be automatically generated.
DVD Navigation Menus ...
GeeXboX allows 2 DVD playback mode:
- Direct movie playback (default).
- DVD Navigation Menu support (fairly experimental).
The first one can be safely trusted for playing any kind of DVD. Once inserted, the disc is automatically detected and MPlayer tries to play the title it consider as the movie one. The major advantage is that all copyright, advertisement and menu parts are skipped to allow a direct playback. However, in some situations (like DVDs with enhanced menus or most of the series DVD, containing multiple titles to be played) this method is inaccurate and you'll not be able to watch your DVD correctly.
The second one, while still experimental (but has really good chances to works fine) supports the regular DVD Navigation Menus and let you control your DVD the same way you'll do it using a regular commercial DVD player.
You can use the GeeXboX options menu to switch between the DVD playback methods, according to the DVD disc you're trying to watch.
You can also make use of the GeeXboX ISO generator to select the default DVD playback method you want.
Network streaming ...
GeeXboX now gives you the possibility to add some SHOUTcast Radio/TV official playlist as easily as personal playlists (local and remote).
SHOUTcast activation is set in "GEEXBOX/etc/network" config file. As SHOUTcast TV sometimes may contain pornographic and subscription-only streams, you can define a "black list" and a "white list" to allow/deny any streams you choose (default keywords for "black list" are : "adult xxx porn ESS SWCTV SWPTV Subscription"). The black/white lists are case-insensitive.
The "GEEXBOX/etc/netstream" config file can be set to create local and remote playlists (some examples are located in this file). "Remote playlists" refer to "Extended M3U" files.
For French users only:
You can get "FreeboxTV" thanks to this file, using the following process:
- uncomment EXTM3U ad hoc entry.
