XMMS - X Multimedia System (c)1998-1999

Peter Alm, Thomas Nilsson, Olle Hallnas


TABLE OF CONTENTS
*****************

1. Disclaimer
2. Installation
   2.1 Basic Installation
   2.2 Borderless Installation
   2.3 Skin Installation
3. Documentation
   3.1 Controlling XMMS
       3.1.1 Key bindings
   3.2 Playlist Editor
   3.3 Equalizer
   3.4 Menu
   3.5 Preferences
4. Command Line Options
5. Features
   5.1 Supported Features
   5.2 Yet To Do
6. Obtaining XMMS
7. Misc
   7.1 Shoutcast support
   7.2 Tips and tricks
8. Bugs
9. Contact Emails




1. Disclaimer
-------------

We are not liable for any damage caused by the use of this program.

XMMS is NOT a port of windows95's winamp. We just borrowed the GUI! :)


2. Installation
---------------

These libraries are needed to compile XMMS.

gtk/glib 1.2.2 or better.
ftp://ftp.gtk.org/pub/gtk/v1.2/

For libc5 users, you also need to obtain,

gnu gettext 0.10 (use configure --with-gnu-gettext)
ftp://prep.ai.mit.edu/pub/gnu/gettext/gettext-0.10.tar.gz

linuxthreads 0.71
http://www.xmms.org/files/linuxthreads.tar.gz 

Thread safe Xlibs (atleast aware)
http://www.xmms.org/files/XFree86-3.3-libs.tar.gz (thread aware)

If you want XMMS to play mod/s3m/med and formats supported by mikmod
visit http://www.multimania.com/miodrag/mikmod/index.html and get the
latest version of libmikmod and install it before running ./configure
on XMMS.

For the openGL plugin you'll need Mesa 3.0 or better.
http://www.mesa3d.org/

And if you own a 3dfx card you'll need glide as well.
Voodoo1: http://www.3dfx.com/view.asp?IOID=107
Voodoo2: http://www.3dfx.com/view.asp?IOID=106
Voodoo3/Banshee: http://www.3dfxgamers.com/view.asp?IOID=31

2.1 Basic Installation
----------------------

cd xmms-source
./configure
make
make install

This will put the binary in /usr/local/bin and plugins in 
/usr/local/lib/xmms/ 

2.2 Borderless Installation
---------------------------

As far as I know most WM's accepts GTK decoration hints so it will not have borders. 
But some WM's can't handle this so you have to set in manually.

Afterstep 1.0 ~/.steprc
Style "XMMS_Player" NoTitle, NoHandles 
Style "XMMS_Playlist" NoTitle, NoHandles
Style "XMMS_Equalizer" NoTitle, NoHandles

Afterstep 1.4 ~/GNUstep/Library/AfterStep/database
Style "XMMS_Player" NoTitle, NoHandles
Style "XMMS_Playlist" NoTitle, NoHandles
Style "XMMS_Equalizer" NoTitle, NoHandles

Fvwm's ~/.fvwm95rc
Style "XMMS_Player" NoTitle 
Style "XMMS_Playlist" NoTitle
Style "XMMS_Equalizer" NoTitle

2.3 Skin Installation
---------------------

XMMS will create a drawer called ~/.xmms/Skins/ in which you
just unarchive the skins the same way as you do for winamp.

However, you don't need to unarchive them since XMMS supports
archived skins. Both .zip and .tgz (.tar.gz) archived skins
are supported. Just copy the archive to one of the skin path's
and XMMS will take care of the rest.

In order to support zipped skins you will need to download unzip.
ftp://sunsite.unc.edu/pub/Linux/utils/compress/unzip-5.31.tar.gz

If you do not wish to have unzip in your path, then set the variable
UNZIPCMD to the directory in which you keep the unzip command.

Use ALT+S when using XMMS to bring up the skin selector. XMMS
will remeber which skin you had loaded when you start XMMS the
next time. (saved in ~/.xmms/config) in the skin selector you
have an option to use random skin on play, this will pick a
random skin on song change.

XMMS looks for skins in these directories:

/usr/local/share/xmms/Skins
/usr/share/xmms/Skins
~/.xmms/Skins

or you can set the variable SKINSDIR to another location of your
choice.

for bash:
export SKINSDIR=/path/to/Skins:/more/paths/to/other/locations/of/Skins

for csh:
setenv SKINSDIR=/path/to/Skins:/more/paths/to/other/locations/of/Skins


3. Documentation
----------------

This file or http://www.xmms.org/doc.html

3.1 Controlling XMMS
--------------------

When you start up XMMS, you will get a console very similar to that of
WinAMP.  

- On the top is the window title bar. To the right you will see 3 buttons,
   Left button will minimize XMMS.
   Middle button will make XMMS only display the title bar.
   Right button will end the XMMS session.

- The area in the upper left part displays the following:
   - Play state: Paused, Stopped, or Playing
   - Time elapsed in the current song or if you click on it, the reversed.
   - Spectrum analyzer of the sound being played. Right mouse click will bring up
     the Visualization menu. Left mousebutton will change the analyzer to an
     oscilliscop and/or none. 

- To the right of the Spectrum analyzer is the title of the file being played.
  This also contains the length of the song being played, as well as it's
  position in the [unsorted] playlist. Right clicking in this window will
  bring up a new meny with some more options that are self explaining.

- In the left part of the Spectrum analyzer you'll have letters (atleast if you use the
  default skin) O A I D V   left mouse clicking on these will open up menus or preform
  actions.
  O : Options menu
  A : Always on top
  I : File info box                      
  D : Doublesize mode
  V : Visualization menu

- Underneath the track title are the following static informational data:
   - bitrate in KBps (usually 128 or 112)
   - Sample Rate in KHz (usually 44)
   - Stereo or Mono channel mixing

- Underneath the informational data are a few controls you can play with:
   - The first slider controls the volume
   - The second slider controls the balance between speakers
   - The button marked "EQ" loads up the graphic equalizer
   - The button marked "PL" loads up the playlist editor
   - The LARGE slidebar moves from left to right as the song plays. You can
     drag this to jump to another location in the current file.

- On the bottom of the console are the standard buttons you would see on a CD
  player: Previous track, Play, Pause, Stop, Next track, eject, shuffle and repeat.

   - The eject button doesn't REALLY eject, of course. :) It opens up the
     file requester. The File Requester builds a playlist for the current
     XMMS session. You can use it to load files, add files to the list, or
     load all mp3s in a directory.

   - The shuffle button randomizes the sequence of the playlist.
   
   - The repeat button when enabled makes the playlist loop when it reaches the
     end of the playlist.


3.1.1 Key bindings
------------------

Main window:
  z = last song
  x = play
  c = pause
  v = stop
  b = next song
  l = play file (brings up the filerequester)
  j = jump to file (in the existing playlist)
  r = repeat
  s = shuffle
  
  Control + l = Play location (url)
  Control + p = Preferences dialog
  Control + v = Visualation plugin dialog
  Control + r = Time remaining
  Control + a = Always on top (works with gnome and windows maker)
  Control + w = Winshade mode
  Control + d = Doublesize mode
  Control + e = Easy move
  Control + j = Jump to time
  Control + z = Start of list
  Control + n = No Playlist Advance

  Shift + Control + w = Playlist winshade mode

  Alt + w = Hide/show mainwindow
  Alt + e = Hide/show playlistwindow
  Alt + g = Hide/show Equalizer
  Alt + s = Skinselecting window

  Arrow key up    = Volume up 2%
  Arrow key down  = Volume down 2%
  Arrow key right = Skip 5 seconds forward in song
  Arrow key left  = Skip 5 seconds back in song

Playlist window: (mostly same as main window exept arrow keys)
  Arrow key up    = up one step in playlist
  Arrow key down  = down one step in playlist

  del key   = delete song from playlist
  page up   = up one page in playlist
  page down = down one page in playlist
  home key  = first page in playlist
  end key   = last page in playlist
  enter     = play selected song
  
Equalizer shade mode: (mostly same as main window)
  Arrow key up    = Volume up 2%
  Arrow key down  = Volume down 2%
  Arrow key right = Balance 4% to right
  Arrow key left  = Balance 4% to left
   
  
3.2 Playlist editor
-------------------

To access the Playlist editor, select the button labeled "PL" on the right
side of the XMMS console.

This will bring up the actual playlist window, here you'll fins 5 buttons.
All of these buttons can be held down to bring up an extra menu.
From left to right:

file +    : will add a file to current playlist, held down mode you'll have 2 extra options
dir       : will let you pick a directory (recursive) 
url       : will let you add an url for streaming 

file -    : will delete the highlighted file, held down mode you'll have 3 more options
crop      : delete all files exept the highlighted in the list
all       : delete all files in the list
misc      : *** NOT FUNCTIONAL ***

sel all   : select all files in current playlist, held down mode you'll have 2 extra options
sel zero  : select none
inv sel   : ivert you selection

misc opts : held down you'll have 2 extra options
fileinfo  : as it say, fileinfo :P
sort      : release button on this will bring up another menu with sort options 

load list : will let you pick a playlist to load, held down you'll have 2 extra options
save      : will let you save your playlist
new       : will empty the playlist and let you create a new playlist

If you want to select/deselect files in the filrequester/playlisteditor use CTRL for files
and SHIFT key for blocks of files. You can also browse the PL using the cursorkeys and enter
to select song. Pressing the delete button will remove the song from the playlist. 
If your mouse is equipped with a mousewheel, you can use this to scroll up and down.

3.3. Equalizer
--------------

To access the Equalizer, select the button labeled "EQ" on the right
side of the Xmms console.

That will bring up the Equalizer window. it looks like an equlizer on a stereo and
behaves like one as well. Press the button labeld ON to enable the use of the
equalizer, once you turned it on you use it as a normal equalizer. EQ presets will
be saved in ~/.xmms/config when you close xmms. You can also have your own
presets for diffrent song using the "Preset" button, xmms can also
import/export from winamp's preset files!

3.4. Menu
---------

There are several menu hotspots on the xmms window. One place is at the left hand side of the visual 
window described in sections 3.1 If you click the right mouse button in the main window, the menus
will also pop up (same as clicking the button on the top left corner).

3.5. Preferences
----------------

Use the menu to open Options/Preferences or use the shortkey ctrl+p to bring the preference dialog up.
In here you'll find 3 tabs Audio I/O, Plugins and Options.

Audio I/O:

You'll find 2 diffrent types of plugins here.. Input plugins and Output plugins.
To make changes to any of the Input plugins highlight the one you want to change by clicking on it's
name and hit Input plugin's configure button, you also have an about button that will tell you
a little about the selected plugin and you made it if this information is available.
xmms comes with 4 Input plugins as default (if your system makes all 4 of them) these are

CD audio Player
MikMod Player
MPEG Layer 1/2/3 Player
Wave Player
id software cin player

Configure options for these plugin are diffrent so let's see if we can enlight you a bit here :)

CD audio Player:
In here you have 3 tabs Devices, Volume and CD info. Device you'll enter the device the CDROM drive is 
connected to. Directory is where you want to browse to see the audio tracks. Let's say you have a CDROM 
drive connected to /dev/hdb just type that in Device option and where you usually mounts the drive in 
Directory. insert an audio CD and select open file and browse to the dir you normally mount data CD's 
you'll find the audio tracks you want to listen to. The Volume tab just let you choose what volume 
control you would like to use for the CDROM drive. CD info tab is for CDDB support, it uses freecddb
databse to get the info of the CD.

MikMod Player:
This plugin will only be built if you have libmikmod (http://www.multimania.com/miodrag/mikmod/index.html)
3.1.6 or better installed before you run "configure" in the xmms source tree. If you like to change anything
that has todo with mikmod formats playing hit configure and you'll have 2 tabs with Quality and Options
for mikmod driver. Most people want to leave these untouched :)

MPEG Layer 1/2/3 Player:
Here you can set options that has todo with the mpg123 driver. Decoder options is mostly used
if you have a crappy soundcard :).. Streaming tab deals with shoutcast/icecast streamings.
You can change buffer sice and prebuffering stuff as well as setting up proxy connection
and save the streams you listen to on to the harddrive. If you save streams to HD it will
be named "radio station name".mp3 In the title tab you have options to set id3 tag strings
that xmms displays in the main window. Also you'll find an option to have this plugin 
recognizing files by content rather than filename extension.

Wave Player:
This can not be altered yet. plays wavfiles.

id software cin player:
This can not be altered yet. plays quake II movie format.

Output Plugins are:

OSS Driver 1.0:
This is the general plugin for output stream to the soundcard. Configuring this plugin has some
intresting options. First you will see Devices, in here you can change the soundcard you are using
if you have 2 soundcards most people do not want to change these settings but just leave them at default.
Buffering is the size of buffert xmms will have loaded into the memory.

eSound Output Plugin 1.0:
This plugin will only be built if you have eSound 0.2.8 (http://www.tux.org/~ricdude/EsounD.html) or
better installed before you run the "configure" in the xmms source tree. The tabs in here are Server
that let you choose a remote server using eSound to play the music on. Also you'll find Buffering tab
that is the same as for the OSS Driver 1.0.

Disk Writer Plugin 1.0:

This plugin let's you save music that the input plugins can handle as wav. 
The only option here is Path: just type the path where you want to save the wav files and that's it.

Effect/General Plugins:

You'll have 2 more plugin types here, Effect plugins that are used to alter the sound and
General plugins that can be used to control xmms.

Visualization Plugins:

Here you can find some eye candy plugins :) also included is an OpenGL plugin. Most plugins in here will 
run in window mode exept the OpenGL plugins that will run in fullscreen mode (esc key to exit fullscreen)
but you can configure the OpenGL plugin to work in window mode as well. The OpenGL plugin has some keybinds
that are useful in fullscreenmode, z x c v b as described in main window, on top of that you can use the
arrow keys to move the x and z axis's and q+w for y axis. Enter will reset to default settings.


Options:

Here you have some general options for xmms and these are:

Read info on "Demand" and on "load"

Reverse file order in fileselector, like it sounds :)

Allow multiple instances, if you select this you need to restart xmms for changes to take effect
it will let you load more then 1 copy of xmms.

Convert %20 to space, good when you download mp3's in netscape.. some has %20 instead of space.

Convert underscore to space, same as the %20 but for "_" instead.

Dim titlebar when inactive, makes the titlebar look as it was active all the time.

Sort "jump to file" aplhabetical, as is sounds :)

Use Realtime priority when available, This works only if xmms is runned by root or is setuid as root.
This will get xmms the cpu it needs all the time and it won't be easy to get it to skip..
You won't be able to use the diskwriter plugin with this ption enabled.

Pause between song for X seconds, this will let you choose a pause for X seconds before XMMS plays 
the next song.

Use "\" as a directory delimiter, this is useful for winamp .m3u files where "\" is directory delimiter
and not like in linux/unix with "/"

Enable DGA access when available. DGA access is a way for plugins to be able to write directly to the
graphic cards video memory which results in much higher framrates. There are some bugs in some X servers
that make XMMS crash on startup. If you enable this option, if this happens, change the line 
enable_dga = TRUE to enable_dga = FALSE in your ~/.xmms/config file.

Always show clutterbar, will show/not show the OAIDV displayed on the left side of visual window.

Save window positions, saves main windows position on the screen instead of letting the WM choose location.

Show numbers in playlist, will display the internal tracknumber in the playlist.

Save playlist position, save the playlist position like the main one.

Equalizer doublesize linked, if you uncheck this box the EQ will always be in normal size.

Snap window ar "x" pixels, how many pixels from the windows before they "snap" together.

Smooth title scroll, makes the title scroll go smoother.

Mouse Wheel adjust Volume by (%), this let you define how much in % volume will increase/decrease
when you use the wheel mouse in XMMS mainwindow.

And finally you can choose a font for the playlist window. 

4. Command Line Options
-----------------------

xmms --help will produce:

Usage: xmms [options] [files] ...

Options:
--------

-h, --help              Display this text and exit.
-n, --session           Select XMMS session (Default: 0)
-r, --rew               Skip backwards in playlist
-p, --play              Start playing current playlist
-u, --pause             Pause current song
-s, --stop              Stop current song
-f, --fwd               Skip forward in playlist
-e, --enqueue           Don't clear the playlist
-m, --show-main-window  Show the main window
-v, --version           Print version number and exit.

You can specify files on the command line, e.g:
./xmms file1.mp3 file2.mp3 file3.mp3
./xmms *.mp3
./xmms playlist.m3u (note: playlists must be named .m3u)

If you do this while XMMS is running the current playlist
will be cleared and the files/playlist specified on the command
line will be used instead.

To keep the current playlist intact use the -e option.

5. Features
-----------

5.1 Supported Fileformats
-------------------------

MP2 and MP3 streams
WAV/AU samples

module formats:
mod, xm, s3m, med, it
669, amf, dsm, far
gdm, imf, m15, mtm
stm, stx, ult, uni

others:
cin movies, cd audio
shout/icecast


5.2 Supported Features
----------------------

Seeking in files
Volume/Balance
Shuffle play
Repeat play
Playlist editor
Spectrum Analyzer
One Line mode al'a WinShade in WinAmp
Oscilliscope
Timer Elapsed/Timer Remaining
Plug-in system Output/Input/Effect/General/Visualization
Equalizer
Double Size option
Winamp 2.0 skinsupport (can use wsz files)
GTK Requesters (with themesupport)
Streaming/Shoutcast(1.0/1.1)/Icecast support
Autoremove borders if the WM has support for it
Gnome/Afterstep/WindowMaker dock app
Fast jump in playlist
Scroll wheel support
Save to wav option
Saves http streams to HD
HTTP authorization
Plays mpeg layer 1/2/3 also wav and formats supported by mikmod
Compiles and works on other unix's
Proxy authentication support

5.3 Yet To Do
-------------

Icecast streamer plugin
Recording
YOU tell us


6. Obtaining XMMS
-------------------

How do I get it?

Get the latest version from the web  http://www.xmms.org or FTP
ftp://ftp.xmms.org/xmms/

Want some skins made by linux users? goto http://www.xmms.org/skins.html


7. Misc
-------

7.1. Shoutcast support
---------------------

To make netscape use XMMS on http://www.shoutcast.com you just have to load up
netscape and choose view/preferences/Navigator/applications add a new handler
set mimetype: audio/x-scpls
set application: xmms %s
hit the OK button and off you go!

And for http://www.mp3.com

Set mimetype: audio/x-mpegurl
Set suffix: m3u
Set application: xmms %s

7.2. Tips and Tricks
-------------------

If you have a windows partition with winamp installed, a good idea would be to
set the SKINSDIR variable to that dir.



XMMS features some command line options like next/prevoius songs, those 
things can be binded to a key. I use Afterstep and the useless window keys 
for this. Here is an exampel from my .steprc:

Key     Meta_R  A       N       Exec "xmms" xmms -r
Key     Menu    A       N       Exec "xmms" xmms -f

If you want all your mp3's in one playlist an easy way is:
locate .mp3 > /path/to/playlistname

( considering you have a fairly recent updatedb, dont blame us if
  locate dont finds the file you downloaded 3 minutes ago :P )

I like to have my playlists in a special path (in my case /usr/local/share/xmms/playlists/)
and I really hate browsing to that dir with the playlistbrowser so I start XMMS like this.
make a bash script file looking like this:

--------------------------------------
#!/bin/sh
pldir=/usr/local/share/xmms/playlists
binary=/usr/local/bin/xmms
IFS=" "
if [ -x $binary ]
then
        cd $pldir
        $binary "$@"
else
        echo "Couldn't execute $binary!"
fi
--------------------------------------
now you can keep all you playlists in /usr/local/share/xmms/playlists/ if you like :P

8. Bugs
-------

Bugs are usual.. else something is wrong and you better report it as a bug!


9. Contact Emails
-----------------

Programming      Peter Alm       (peter@xmms.org)
Graphics         Thomas Nilsson  (thomas@xmms.org)
Everything else  Olle Hallnas    (olle@xmms.org)