XMMS - X Multimedia System (c)1998-2000

Peter Alm, Thomas Nilsson, Olle Hallnas


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

1. Disclaimer
2. Installation
   2.1 Basic Installation
   2.2 Border less 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 Email




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/libc5/linuxthreads.tar.gz 

Thread safe Xlibs (at least aware)
http://www.xmms.org/files/libc5/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 Border less 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

CTWM's ~/.ctwmrc
NoTitle and NoBorder sections:
NoTitle {     
    "xmms" 
}

NoBorder {
    "xmms"  
}

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 remember 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:

<prefix>/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/documentation.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 mouse button will change the
     analyzer to an oscilloscope 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 menu with some more options that are self explaining.

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

- Underneath the track title are the following static informational data:
   - bit rate 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 slide bar 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 = previous song
  x = play
  c = pause
  v = stop
  b = next song
  l = play file (brings up the file requester)
  j = jump to file (in the existing playlist)
  r = repeat
  s = shuffle
  
  Control + l = Play location (url)
  Control + p = Preferences dialog
  Control + v = Visualization plugin dialog
  Control + r = Time remaining
  Control + a = Always on top (works with gnome and windows maker)
  Control + w = Winshade mode
  Control + d = Double size 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 = Skin selecting 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 except 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 except 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   : invert 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/playlist editor use
CTRL for files and SHIFT key for blocks of files. You can also browse the
PL using the cursor keys and enter to select song. Pressing the delete button
will remove the song from the playlist. If your mouse is equipped with a
mouse wheel, 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 equalizer on a stereo
and behaves like one as well. Press the button labeled 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 different song using the "Preset" button, XMMS can
also import/export from WinAmp's preset files!

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

There are several menu hot spots 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 Short Cut Key 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 different 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 different so let's see if we can
enlighten 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 database 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 to do 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 to do 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 size 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 interesting 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 buffer 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 except the OpenGL plugins that
will run in full screen mode (ESC key to exit full screen) but you can configure
the OpenGL plugin to work in window mode as well. The OpenGL plugin has some
key bindings 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
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 file selector, 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 map3'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" alphabetical, as is sounds :)

Use Real time priority when available, This works only if XMMS is run as 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 option 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 frame rates. 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 track number in the playlist.

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

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

Snap window are "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 File formats
-------------------------

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
Oscilloscope
Timer Elapsed/Timer Remaining
Plug-in system Output/Input/Effect/General/Visualization
Equalizer
Double Size option
WinAmp 2.0 skin support (can use wsz files)
GTK Requesters (with theme support)
Streaming/Shoutcast(1.0/1.1)/Icecast support
Auto remove 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/previous songs, those 
things can be binded to a key. I use AfterStep and the useless window keys 
for this. Here is an example 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, don't blame us if
  locate don't 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 playlist browser 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 Email's
-----------------

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

