				X11AMP for Linux

				   (c)1998

				  Mikael 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 Console Overview
   3.2 Playlist Editor
   3.3 Equalizer
4. Command Line Options
5. Features
   5.1 Supported Features
   5.2 Yet To Do
6. Obtaining X11AMP
7. Misc
   7.1 Shoutcast support
   7.2 Tips and tricks
8. Bugs
9. Contact Emails




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

This version is considered an -BETA- release.  This means it may not be
stable.  You have been warned.  We are not liable for any damage caused by
the use of this program.

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


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

These libraries are needed to compile x11amp!!

gtk/glib 1.1.12 or better.
get it here: ftp://ftp.gtk.org/pub/gtk/v1.1/

For you libc5 users you'll need these extra things.

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

linuxthreads 0.71
get it here: http://www.x11amp.bz.nu/files/linuxthreads.tar.gz 

Thread safe Xlibs! dunno where to find them or if this work.. drop me
an email about it.. Crocodile@x11amp.bz.nu

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

cd x11ampsource
./configure
make
make install
This will put the binary in /usr/local/bin and in/outplugins in 
/usr/local/share/x11amp/ 

x11amp will hopefully load *grin*

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.
do this for x11amp just add this: 

Afterstep 1.0 ~/.steprc
Style "x11amp" Icon x11amp.xpm, NoTitle, NoHandles 

Afterstep 1.4 ~/GNUstep/Library/AfterStep/database
Style "x11amp" Icon x11amp.xpm, NoTitle, NoHandles

Fvwm's ~/.fvwm95rc
Style "x11amp" NoTitle 

The poblem here is that all GTK windows will also be borderless :(

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

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

Or don't unarchive them, x11amp supports zipped skins..
just copy the skin.zip to a Skin path and boom of you go!
note: you will need unzip ftp://sunsite.unc.edu/pub/Linux/utils/compress/unzip-5.31.tar.gz
to get this to work! If you don't keep unzip in your path then you can set a
variable called UNZIPCMD to the tight path.

Use ALT+S when using x11amp to bring up the skin selector. X11Amp
will remeber which skin you had loaded when you start X11Amp the
next time. (saved in ~/.x11amp/config)

You can also have global skins in /usr/local/share/x11amp/Skins or 
/usr/share/x11amp/Skins if you are not happy with this just set the 
SKINSDIR variable to another location of your choice eg.

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

good idea here is SKINSDIR=/dos/programs/winamp/skins if you have windows 
and winamp with skins installed :)

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

This file or http://www.x11amp.bz.nu/doc.html

3.1 Console Overview
--------------------

When you start up X11Amp, 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 X11Amp.
   Middle button will make X11Amp only display the title bar.
   Right button will end the X11Amp session.

- There is a window in the upper left that shows 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. *NOTE* oscilliscop and/or none not yet working! 

- To the Right of the Spectrum analyzer is the title of the mp3 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. I will describe them here:
  O : Options menu
  A : Always on top
  I : File info box                           <--- screenshots
  D : Doublesize mode
  V : Visualization menu

- Underneath the track title are the following static informational data:
   - MP3 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 described later
     in more detail
   - The button marked "PL" loads up the playlist editor described later in
     more detail
   - The LARGE slidebar moves from left to right as the song plays. You can
     drag this to jump to another location in the current mp3 file.

- On the bottom of the console are the standard buttons you'd see on a CD
  player: Back 1 track, Play, Pause, Stop, Forward 1 track, and eject.

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

   - The shuffle button does just that; it randomizes the sequence of the
     playlist.

- By hitting the key combination alt+s you'll bring the skin selector up and 
  can choose a skin to use, choosing the (none) skin will make x11amp use the
  built in skin.

- You also have key control.. these are:
  z = last song
  x = play
  c = pause
  v = stop
  b = next song
  n = eject
*NOTE* key controls don't work yet

3.2 Playlist editor
-------------------

To access the Playlist editor, select the button labeled "PL" on the right
side of the X11Amp 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
	    url       : will let you add an url for streaming 
	    dir       : will let you pick a directory (recursive) 

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

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

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

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

Just like in windows, 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 specify files in the command line e.g
./x11amp file1.mp3 file2.mp3 file3.mp3 or wildcard ./x11amp *.mp3

If you do this while X11Amp is running, it will remove the current selection
of mp3 files and play the one(s) from the command line. This is useful if 
you are using Midnight Commander like I do :)

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

To access the Equalizer, select the button labeled "EQ" on the right
side of the X11Amp 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 ~/.x11amp/config when you close x11amp.


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


x11amp --help will produce:

Usage: x11amp [options] [files] ...

Options:
--------

-h, --help              Display this text and exit.
-n, --session           Select X11Amp 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
-v, --version           Print version number and exit.

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

5.1 Supported Features
----------------------

Seeking in files
Volume/Balance 
Shuffle play 
Repeat play 
Timer Elapsed/Timer Remaining
Plug-in system
Double Size option
GTK Requesters (with themesupport)
Autoremove borders if the WM has support for it
Wildcard select from commandline
Playlist editor
Equalizer
Spectrum Analyzer
Oscilliscope
Skins (The same skins as winamp)
Streaming (shoutcast)

5.2 Yet To Do
-------------

Wharf (afterstep) version! 
YOU tell us


6. Obtaining X11Amp
-------------------

How do I get it?

Get the latest version from the web  http://www.x11amp.bz.nu or FTP
ftp://ftp.x11amp.org/x11amp/

Want some skins made by linux users? goto http://www.x11amp.bz.nu/skins.html


7. Misc
-------

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

To make netscape use x11amp 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: x11amp %s
hit the OK button and off you go!


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

X11Amp 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 "x11amp" x11amp -r
Key     Menu    A       N       Exec "x11amp" x11amp -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/x11amp/playlists/)
and I really hate browsing to that dir with the playlistbrowser so I start x11amp like this.
make a bash script file looking like this:

--------------------------------------
#!/bin/sh
cd /usr/local/share/x11amp/playlists/
if [ "" = "$1" ]; then
       /usr/local/bin/x11amp
else
/usr/local/bin/x11amp "$1"
fi
--------------------------------------
now you can keep all you playlists in /usr/local/share/x11amp/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      Mikael Alm      (psy@x11amp.bz.nu)
Graphics         Thomas Nilsson  (fatal@x11amp.bz.nu)
Everything else  Olle Hallnas    (crocodile@x11amp.bz.nu)

