Gmerlin Users Guide

1 Basics
1.1 Introduction
1.2 Installation
1.2.1 Requirements
1.2.2 Compilation
2 General usage information
2.1 Configuration data
2.2 GUI
2.3 Remote control
3 Applications
3.1 Player
3.1.1 Media tree
3.1.2 The main window
3.1.3 The video window
3.2 Transcoder
3.3 Alsamixer
4 Get involved

1 Basics

1.1 Introduction

This manual should help you to get familiar with gmerlin software. The gmerlin software is quite modular, because it consists of multiple packages, most of which can be used independently. In this document, it is assumed, that you have all packages installed (See Installation below).

1.2 Installation

1.2.1 Requirements

For compiling x264, you need nasm (yasm on x86_64). They are included in most distributions. Required libraries can be installed from source or from binary packages. In the latter case, you must install the development packages (e.g. libfoo-devel-1.2.3-4.i386.rpm) also. This is what you need:

Alsa It's the recommended audio architecture
esoundOnly needed if neither Alsa nor OSS work for you.
flac For en-/decoding flac files (Optional).
gtk-2.4.xThis is needed for compiling the GUI applications. Without it you'll get just the core library, which won't be of much use.
libjpegFor reading and writing single JPEG images (strongly recommended)
libpngFor reading and writing single PNG images (strongly recommended). Also for decoding png encoded Quicktime and AVI files
libtiff For reading and writing single TIFF images (Optional)
libxmlRequired. All kinds of configuration files as well as the media tree are xml based.
vorbisNeeded for en-/decoding Vorbis files. Also required for the theora encoding.
libmusicbrainz Needed for getting Audio CD metadata using musicbrainz
libcddb Needed for getting Audio CD metadata from CDDB servers
libsmbclient For loading smb:// URLs (optional).

From now on, there are 2 ways to proceed:

libcdio Neccessary for the VCD and Audio CD plugins. You need the latest CVS version or the one in the gmerlin-dependencies package.
faad2Needed for MPEG-4 audio support (mp4, aac files). The latest official faad-2.0 won't play some streams. The current CVS version or the rpms from freshrpms should be ok.
faacNeeded for MPEG-4 audio encoding (.aac files) and for AAC encoding via libquicktime.
FFmpegMany other codecs, strongly recommended. You should get a sufficiently new version from ffmpeg CVS and use --enable-shared when calling configure. The second best option is probably the ffmpeg_acl tarball in the gmerlin-dependencies package. Install before libquicktime.
lameFor encoding mp3s. Install before libquicktime.
libmadFor playing MPEG-1/2 audio (e.g. for mp3)
libdvdread for playing DVDs. Gmerlins method of accessing DVD drives doesn't differ much from others. Thus, DVD playback howtos found in the web apply for gmerlin as well.
x264 For H.264 encoding. Must be installed before libquicktime.
libmpeg2For decoding MPEG-1/2 Video (like .mpg files and DVD video)
liba52For playing AC3 (aka DVD audio) streams.
liba52For playing AC3 (aka DVD audio) streams.
libmusepack For playing musepack files (optional).
libtheora For en-/decoding theora video (optional).
libspeex For en-/decoding Speex streams (optional).
libquicktime Optional, for the libquicktime based encoding and decoding plugins. Mostly necessary if you want to encode video. For decoding Quicktime, gmerlin_avdecoder is a lot better. This should be installed as the seconds last one before mjpegtools.
mjpegtools Optional for en-/decoding yuv4mpeg streams and for encoding high quality MPEG video using mpeg2enc and friends. This should be installed as the last one.

1.2.2 Compilation and installation

If you downloaded a release, make sure, that you have the latest version of all packages. Alternatively, you can download the latest gmerlin-all-in-one package. It contains all source packages together with optional scripts to build and install them. Check the included README file.

We always try to be compatible ther GNU build system. This means, thas all gmerlin packages are compiled using the usual ./configure; make; su; make install prodecure. Type ./configure --help to see the supported options.

The order is the following:

1.2.3 Binary codecs

These must be downloaded from the MPlayer codec page. Download the file essential-YYYYMMDD.tar.bz2, where YYYYMMDD is some date. Unpack the .tar.bz2 and move the included files to /usr/lib/codecs. At this location, the DLLs will also be found by other players.

2 General usage information

2.1 Configuration data

They are saved in the directory ~/.gmerlin, which has subdirectories for all applications. The directory "generic" stores common configuration data for applications, which have no config dialog. Plugins used by these programs can be configured with the gmerlin_plugincfg application. If a program misbehaves, especially after a version upgrade, delete the file ~/.gmerlin/application_dir/config.xml, where application_dir corresponds to the application. Normally, this shouldn't be necessary

All applications except gmerlin_visualizer have their own configuration data. This means, that changes made to plugin configurations are not shared between these applications. Most applications have a configuration dialog, which lets you change some global settings. Then, there is a plugin dialog, which lets you select and configure plugins. It might be a bit tricky to find out if a special option can be set via the the plugin dialog or via the global config dialog. The general rule is: All features, which are supported independently from any plugins, are configured in the global dialog. You can expect them to be present on every gmerlin installation of the same version. The plugin dialog changes depending on what plugins are installed. That's the reason, why they are separated.

2.2 GUI

We try to make this as consistent as possible across the applications. In many windows, you'll see context sensitive menus when you right click somewhere. Furthermore, tooltips are enabled in all programs by default. You can, however, switch them off if they bother you. Many dialogs behave exactly the same in all applications, because they share a lot of code.

2.3 Remote control

The player and the transcoder are remotely controllable by the commandline programs gmerlin_remote and gmerlin_transcoder_remote respectively. Call them with -help as argument to see the options. The remote servers listen at ports starting with 10101 by default. You can change these via environment variables:

GMERLIN_PLAYER_REMOTE_PORT Port for the player remote, default 10101.
GMERLIN_TRANSCODER_REMOTE_PORT Port for the transcoder remote, default 10102.

By default, remote enabled applications will listen on the localhost (127.0.0.1) only. If you want to control your gmerlin applications from other computers too, enable it in their config dialogs.

Remote commands can be used to launch gmerlin and/or open files, urls and devices. They allow seamless integration of gmerlin into existing desktop systems. Finally there is a script gmerlin_launcher. It can be used as a Mime handler by filenamagers and webbrowsers. If gmerlin_launcher is called with a file or URL as argument, it will launch a gmerlin player if neccessary, add the location to the Incoming album and start playing it.

3 Applications

3.1 Player

Type gmerlin with any number of files or URLs to start this. If you omit any commandline arguments, the GUI will come.

3.1.1 Media tree

The media tree can be used to store and organize your media collection. It consists of virtual folders called albums. You can create albums, subalbums and move stuff between them like you want. The media files always stay at the same place in the filesystem. The albums can be either in own windows (Windowed mode) or as tabs in the tree window (Tabbed mode). The tree- and album windows remember their screen positions.

You can create your own albums by right clicking onto the parent album in the tree and select Album->New. Whenever you doubleclick a track, it will be played immediately. In addition to the regular albums, there are a number of special albums:

Adding tracks to the media tree can happen in multiple ways: Drag and Drop is supported: When dragging albums, they are always moved. When dragging tracks, the default action is move. If you hold the Ctrl-Key before you start dragging, the tracks will be copied.

If you close the currently played album during playback, the player will stop after the current track is finished. You can then select another album by doubleclicking a track inside it.

Inside the album, you have the following shortcuts:

Global commands
CTRL+GPop up current album and goto current track
CTRL+PPop up plugin configuration dialog
CTRL+OPop up preferences dialog
Navigation
UP/DOWNMove the cursor one track up/down
PAGEUP/PAGEDOWNMove the cursor one page up/down
MousewheelScroll
Selecting
Shift+UP/DOWNMove the cursor one track up/down and select track
Shift+PAGEUP/PAGEDOWNMove the cursor one page up/down and select tracks
Ctrl+UP/DOWNMove the cursor one track up/down and unselect track
Ctrl+PAGEUP/PAGEDOWNMove the cursor one page up/down and unselect tracks
Edit
Ctrl+CCopy selected tracks to clipboard
Ctrl+XCut selected tracks to clipboard
Ctrl+VPaste tracks from clipboard at the current cursor position
Favourites
F10Copy selected tracks to favourites

3.1.2 The main window

It's a usual player window, with self explanatory buttons. The menu button will show the main menu of the player. It lets you configure plugins and other global settings, show other windows, launch other applications and so on.

3.1.3 The video window

This comes only when gmerlin has to show some video or still images. The X11 plugin has special functions: You can zoom or squeeze the image to make your favourite tradeoff between aspect ratio distortion, black borders or cropped images.

You have the following shortcuts:

Global commands
CTRL+GPop up current album and goto current track
CTRL+PPop up plugin configuration dialog
CTRL+OPop up preferences dialog
Navigation
PAGEUPPrevious track
PAGEDOWNNext track
LEFSeek back
RIGHTSeek forward
MousewheelSeek
0 (Zero)Seek to start of the track
Zoom/Squeeze
CTRL+PLUSIncrease aspect ratio (squeeze)
CTRL-MINUSDecrease aspect ratio (squeeze)
CTRL-MousewheelIn-/Decrease aspect ratio (squeeze)
ALT-PLUSIncrease zoom factor
ALT-MINUSDecrease zoom factor
ALT-MousewheelIn-/Decrease zoom factor
POS1Reset zoom and squeeze
Volume control
UPIncrease volume
DOWNDecrease volume
Brightness, Saturation, Contrast
bDecrease brightness
BIncrease brightness
sDecrease saturation
SIncrease saturation
cDecrease contrast
CIncrease contrast
Player control
SPACEToggle play/pause
Fullscreen
TABToggle between fullscreen and windowed mode

3.2 Transcoder

Type gmerlin_transcoder to start this. It has only one window, which contains the tasklist. A tasklist stores ALL information necessary to transcode the track. This includes codec settings, bitrates etc. You can load and save tasklists, the current tasklist is remembered. Using the right-click-menu, you can change the encoding plugins for tracks, with the configure button at the lower toolbar, you can configure each track. New tracks can be added: The upper toolbar controls global things. Here you can select and configure plugins as defaults for newly added tracks. Moreover, you can load/save tasklists, start/stop transcoding, set some global options and track defaults and quit the program.

3.3 Alsamixer

This was written because available programs often don't support the full range of soundcard settings. By right clicking on a control, you can: All window configurations and coordinates are remembered. The actual mixer settings are NOT remembered, since this is done globally by the startup scripts.

4 Get involved

Contribution to gmerlin can happen at several skill levels: