gamp ncurses MPEG audio decoder, version 1.1.0

Russ Burdick <wburdick@cs.umn.edu> 1999-2001

1. Introduction

gamp is Graphical AMP. It started out as an ncurses front end built onto
Tomislav Uzelac's amp mp3 player and was recently rewritten as a pure
frontend to sajber jukebox compatible players, such as amp and mpg123. It
is designed to be a true alternative to x windows mp3 players. As such it
incorperates a playlist editor, play, pause, stop, prev, next options.
work is in progress on fast forward, and rewind functions. more ideas as
they come. at present this program has been tested only under linux on
both the redhat and debian distributions. please feel free to drop me a
line with any suggestions, comments, or bug reports.

begining with version 0.2.0 gamp now includes elements of id3ren by Robert
Alto <badcrc@tscnet.com>. i borrowed some of the functions from his id3
renamer which are used in reading id3 tags from mp3s. further information
on this program can be found at http://tscnet.com/pages/badcrc/apps/id3ren/

the present webpage for gamp can be found at
http://www.cs.umn.edu/~wburdick/gamp/. i may put up a domain for it in the
future, but right now my cs account is adequate and i dont have to worry
much about bandwidth.

2. Installation

gamp requires that you have some sort of curses package present on your
system, including a development package (if such exists). on linux
systems you'll probably be looking for ncurses and ncurses-devel. on bsd
i think you've got curses, but dont quote me on that. the Makefile will
try to find the curses headers in a few standard locations, so if you
try and build and it dies saying something like 'cant find curses.h',
you're either missing the devel portion of curses for your system or
you're using some strange installation i havent delt with and i'd like
to hear about it. gamp also requires pthreads (or c_r on bsd), but
that's a pretty standard part of any installation so you shouldnt have
any trouble there.

In order to use gamp you also need to have a compatible backend player.
Any player which can act as a backend for the Sajber Jukebox will work as
i've used the same control mechanisms. The sajber jukebox itself requires
you to have QT installed, which could be a problem, especially on other
unicies which dont have QT. amp-0.7.6 has support for acting as a backend
for the sajber jukebox, but development on it seems to have stopped in
1997 and efforts to contact the author have been unsuccessful.
additionally, rewind doesnt work with amp (it actually fast forwrds) and
the backend doesnt pass song info back to the player so remaining time is
unavailable and some other song info is missing. The best option, and the
one I use, is mpg123 compiled with sajber jukebox support. both amp and
the sajber jukebox should compile 'out of the box' with no additional
work. there are a couple of simple steps to getting mpg123 to compile as a
sajber backend.

-obtain the latest version of mpg123 from http://mpg123.com. as of this
 writing the current version is mpg123-0.59r.
-expand the tar.gz archive for mpg123-0.59r. you will need to copy two
 files from this distribution into the mpg123-0.59r tree. assuming you've
 decompressed both mpg123 and gamp in the same place you should be able to
 do the following:

	cp gamp-1.1.0/controldata.h gamp-1.1.0/audio.h mpg123-0.59r/jukebox/

now you can enter the mpg123 directory

	cd mpg123-0.59r

and build it as a sajber player

	make linux-sajber

which should work great on linux, but on FreeBSD you'll need to

	make freebsd-sajber

i'd like to hope that the linux build will work on any linux and the
freebsd build will work on any bsd, but i'm not sure. if you try this on
something other than linux/freebsd, please let me know so i can make a
note here.

one note with respect to mpg123-0.59r: there is a very small bug in
control_sajber.c. change line 144 from:

	mode = MODE_STOPPED;
to
	mode = MODE_PAUSED;

or else the rewind function will not work. i've sent email about this to
the author and expect that it will be included in future releases.

-once one of the above has completed you should have a sajberplay binary
 in the current directory. you'll need to put this somewhere in your
 path.

-now on to the good stuff, building and installing gamp. you'll want to:

	./configure
	make

(note for the bsd folks: you'll need GNU make to build this, so substitute
'make' for 'gmake' throughout. if someone wants to submit a patch to the
Makefile so that it'll build with both regular and GNU make, i'd be more
than happy to incorporate this.)

-at this point you can optionally strip symbols from the binary to
 reduce its size via:

	make strip

-finally, to install (you may need to be root):

	make install

-optionally, you can then run 'gamp -s' or 'gamp --setup' to have it
create your ~/.gamp/ directory and put a default config and logo file
there. this distribution also includes a sample configuration for both
sajberplay (mpg123) and amp as well as the default and 4 other possible
logos for your player. take your pick. if you come up with new logos,
please send them to me so that they can be included in future releases! 16
lines by 78 columns is the 'default' area you have to work with for a
standard xterm/console. i'd prefer to keep the logos limited to this size.
be creative!

3. Running:

You can use this program by simply typing 'gamp'. There are several
command line arguments which are documented in the COMMANDS file included
with this archive, the gamp(1) man page, and via 'gamp -h'.

4. Feedback

Send in your patches, opinions, bugreports, suggestions; anything related
to this program. You can also send me unlimited amounts of money, bawls,
pengin reds, mountain dew, pepsi, whatever.

5. Legal

This software can be used freely for any purpose. It can be distributed
freely, as long as it is not sold commercially without permission from
Russ Burdick <wburdick@cs.umn.edu>. However, including this software
on CD_ROMs containing other free software is explicitly permitted even 
when a modest distribution fee is charged for the CD, as long as this
software is not a primary selling argument for the CD.

/* This license is itself copied from Tatu Ylonen's ssh package. It does 
 * not mention being copyrighted itself :)
 * --- also borrowed from amp's readme for my use - russ.
 */

THERE IS NO WARRANTY FOR THIS PROGRAM - whatsoever. You use it entirely at
your risk, and neither Russ Burdick, nor anyone else will be liable for
any damages that might occur to your computer, software, etc. in
consequence of you using this freeware program.

Russ Burdick
<wburdick@cs.umn.edu>

6. Non-Linux OS Help

i've tried to make this compatible with as many operating systems as
possible, so if you need to do anything other than the simple
'./configure; make; make install' listed above, let me know so that i can
incorporate these changes and make it easier for everyone else.