				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
4. Command Line Options
5. Features
   5.1 Supported Features
   5.2 Yet To Do
6. Obtaining X11AMP
7. 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
---------------

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

Just make sure x11amp is executeable and copy it to somewhere in the
executable PATH, like /usr/X11R6/bin or /usr/local/bin/ or simmilar, then
just start it in X. If you run x11amp as root or have it SUID root it will
play in realtime mode!

** Warning: If you have a multi user system, please consider that having beta
            products SUID root might be a security risc. We try as hard as we
            can to prevent any types of exploits, but no-one is perfect.


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

As far as I know you can remove the borders in Afterstep and Window Maker. To
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 

Window Maker's ~/GNUstep/Defaults/WMWindowAttributes
x11amp = {
Icon = x11amp.xpm;
NoTitlebar = YES;
NoResizebar = YES;
NoAppIcon = YES;
};


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

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
     (This can be changed to oscilliscope or none by clicking on it)

- 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.

- 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
     ** NOT implemented yet **
   - 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:
  c = last song
  x = play
  c = pause
  v = stop
  b = next song


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

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

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.

The first things you will see are two windows. The one to the left is a file
browser window and the one to the right the playlist(s). Now press the create
playlist button and a requester will popup and let you name your playlist. 
Now you will see ../ at the top of the right window, that indicates that you
are in a playlist and can add mp3(s).  Use the filebrowser at the left and
pick up the mp3(s) you would like to have in your playlist and press the
"done" button. X11Amp will now play your playlist :) Now if you have several
playlists it's real easy to switch between them, just open the playlisteditor
and click on ../ and choose another playlist to play. You can also sort you
playlist by selecting a file in the playlist, and use the arrow buttons located
at the bottom row of the right window. Theese buttons will move the selected
song, or the selected range of songs up/down. 

The playlists are stored in ~/.x11amp/ and they are plain text files which you 
can edit if you need to :)
 
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 :)


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


x11amp --help with produce:

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

Options:
--------

-h, --help              Display this text and exit.
-s, --shuffle           Turn on shuffle play.
-r, --repeat            Turn on repeat play.
-b, --buffer <size>     Set the audio buffer size to <size> kb
-d, --downmix           Downmix stereo mp3's to mono
-o, --resolution <bits> Set playing resolution to <bits>
-z, --nospectrum        Turn off spectrum analyzer
-w, --rew               Skip backwards in playlist and exit
-f, --fwd               Skip forward in playlist and exit


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

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

Nice filerequester 
ADD button in filerequester
Seeking in files
Volume/Balance 
Shuffle play 
Repeat play 
Wildcard select from commandline
Playlist editor
Spectrum Analyzer
Oscilliscope
Skins (The same skins as winamp)


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

Installation scripts for borderless use on different window-managers 
Streaming from the web/ftp 
Wharf (afterstep) version! 
Graphical equalizer
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.bz.nu/x11amp/

Want some skins made by linux users? goto http://www.x11amp.bz.nu/skins.html
Want some skins for winamp uh? goto http://www.layer3.org/software/winampmangled.html


7. 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 -w
Key     Menu    A       N       Exec "x11amp" x11amp -f

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

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


8. Bugs
-------

Some.


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)

