Since version 0.99, a number of changes were introduced in MP2Audio. 

So, what's new in this version? Well, just about everything with the
interface, and nothing at all with the DSP player. The appearance of
the GEM interface is very much the same as the last version. One
button has been replaced, namely the count direction button which now
contains a lambda symbol, to symbolize the integrated script language
which now controls large parts of the player. The language is called
Shoe, and is written by Fredrik Noring. It's contructed to be a small
and easily extendable LISP like language. 

Large parts of the C code has been replaced by Shoe functions or
combinations of Shoe functions. All buttons and control keys are
controlled via Shoe. This means that you can map the control keys and 
buttons to any function you like. It is not possible to change the
icons on the buttons right now, but this might be implemented in a 
later version.

The mp2audio.sho file has also replaced the configure file that was
previously used. With this alpha version, not all configure functions 
have been implemented in Shoe yet. You can't set which clock to use, 
automatic detection will always be used. Time slice and buffer size
is constant, unless you recompile the program, of course. If you ask
me nicely, I might recompile a new version with the values you want, 
if you're not happy with the current values. 

Right now, the program _needs_ the mp2audio.sho to be in the same 
directory as the program file, or no mappings of the buttons and keys
are made, and you can't do anything but to end the program. This will
change later, and the basic functions will be mapped by the program
itself. 

When you start the program, with the mp2audio.sho file included in this
package, it will behave very much like the previous versions. By pressing
control+j you will enter Jukebox mode. In this mode, when you load a song
it is pushed into a play list, and by pressing the play button, it will
play the first song on the list. Following presses on the load or play
button will not stop the current song, but only push the new selected
song onto the play list. To change to next song, press the next button. 
This will start playing the first song in the play list, and remove it
from the list at the same time. The previous button hasn't been mapped
in Jukebox mode. 

I suggest that you read through the mp2audio.sho file and try to figure
out as much as possible what it does. I'll try to list the most common
Shoe functions here, but I'll probably miss some of them.

When you press the lambda button, a console window will pop up. This is
a very simple line editor with a history list. When you enter expressions
you can break lines at any place a normal space would have been inserted.
Since LISP, and therefore also Shoe, contains a lot of parantheses, these
might be difficult to keep track of. The console prints the number of
unclosed parantheses as a number before the prompt. Expressions will be
evaluated when the parantheses are in balance. 

Shoe uses lists for most thing. These are written as:
  (element1 element2 element3)
where the elements can be numbers, symbols or lists.
Functions are used by writing a list with the function name as the first
element and its arguments as the following ones. Exemple:
  (+ 1 2 3)

Numbers are only integers. Symbols may not begin with a number.
For the following examples, assume that "test" is a list containing
three elements, a, b and c, like this:
	> test
	(a b c)

True and false values are represented as #t and #f respectively.

Values inside "" are quotes, which means the value should not be evaluated.

Shoe internal functions:

+	Add the arguments.
-	Subract the arguments three and forward from the first.
/	Divide the first argument with the arguments three- multiplicated
	with each other.
*	Multiply all arguments.
%	Give the rest of a division, i.e. modulo.

car	Return the first element or a list.
	> (car test)
	a

cdr	Return the list that remains if the first element is removed.
	> (cdr test)
	(b c)

if	If expression is true, do the true-statement, otherwise do the
	false-statement.
	> (if expression true-statement false-statement)
	[result of true- or false-statement]

cons	Put an element in the first position of a list.
	> (cons "q" test)
	(q a b c)

define	Define a new function. Functions can only do one expression now,
	but with the "begin" statement, several can be used.
	> (define fac (n)
	1> (if (< n 1) 1
	2>   (* n (fac (- n 1)))))
	fac
	
	This means the function 'fac' has been defined and it takes one
	argument, n. Use the function like this:
	> (fac 5)
	120
	
begin	Combine several statements, evaluate them all in order, and return
	the value of the last one.
	> (begin (fac 2) (fac 3))
	6
	
equal	Returns #t if both arguments are equal and #f otherwise.

eval	Evaluate a statement.
	> (eval test)
	#ERR.
	
	Bad example, but it tries to use (a b c) as a function call, with
	'a' being the function name and 'b' and 'c' as its arguments.

sort	Sort a list in alphabetical increasing order.
	> (sort (cons "q" test))
	(a b c q)
	

MP2AUDIO specific functions:

pwd	Return the current directory in a list.
	> (pwd)
	d:\mp2\jarre\

cd	Change the current directory, relative, or absolute and return the
	new directory.
	> (cd "zoolook")
	d:\mp2\jarre\zoolook

ls	Return the files in the current directory as a list. An argument
	may be used to 'ls', and is the search mask, e.g. "*.mp?".
	> (ls)
	(. .. 02diva.mp2 01ethni.mp2)
	> (ls "*.mp2")
	(02diva.mp2 01ethni.mp2)

	'ls' does not sort the files in alphabetical order, but only list
	them as they appear on the disk. To sort, use the 'sort' function:
	> (sort (ls "*.mp2"))
	(01ethni.mp2 02diva.mp2)

mp2-dsp-load   Returns the load of the DSP decoder. Two values are 
               provided: current load and average load. 0 means
               that the decoder is totally idle. 100 means that
               the decoder is busy all the time, which is not a
               very good thing.

mp2-external-clock?  Returns the external clock frequencies. It
                     supports dual clocks with both 44.1 and 48KHz. 
                     The returned value is a list of two values, 
                     the frequencies of each clock respectively. If
                     there isn't a dual clock available, it will 
                     give the same fequencies for both values. If
                     an external clock is not found, both values will
                     be zero (0).
                     
mp2-external-clock   Set the clock frequencies. This is mainly for
                     testing purposes, and in case the automatic
                     clock detection would fail. The parameter should
                     be a list with two values, corresponding to the
                     values described in the above function. 

mp2-play		Play the loaded song, if any.
mp2-stop		Stop the currently playing song.
mp2-pause		Pause or unpause the current song.
mp2-load		Load a song with the filename as argument.
mp2-fast-forward	Fast forward the currently playing song.
mp2-loop		Set loop or not loop the current song.
mp2-window-info		Open the Info window.
mp2-window-console	Open the Console window.
mp2-select		Open a fileselector and return the choosen name
			or #f if none was choosen.

mp2-countdown		Toggle counting direction of time. If argument #t
			or #f are given, set the direction accordingly.
mp2-display-time	Toggle (or set) if the time should be displayed
			in the title of the main window.
mp2-title		Set the title of the main window.
mp2-subtitle		Set the subtitle of the main window. This is where
			the song name of the current song is usually written.

mp2-type		Return a list of information about the loaded song.
mp2-play-time		Return the amount of seconds that has been played.

The following are functions that is being called by the program
if the respective button is being pressed down:

mp2-icon-play
mp2-icon-stop
mp2-icon-pause
mp2-icon-load
mp2-icon-next
mp2-icon-previous
mp2-icon-fast-forward
mp2-icon-loop
mp2-icon-info
mp2-icon-console

control-key-?	Replace the '?' with any letter, a-z or A-Z, and that
		function is called when control+? key is pressed. Capital
		control-key functions are called when shift is also pressed.

mp2-hook-finitum	This function is called when the current song has
			finished playing.

mp2-hook-loaditum	This function is called when a song has been loaded.
			It is only called if the MPEG file is valid.

mp2-hook-dragumdroppum	This function is called when the user has either
			entered a filename at the command line, dragged a
			file to the program, or in MultiTOS dragged a file
			to any of the windows belonging to the program.
			Running Thing or another desktop that supports the
			VA-protocol, this function is also called when a
			filename is sent to the already started program.


The following functions return #t or #f depending on states of the player:

mp2-play?
mp2-pause?
mp2-loaded?
mp2-loop?


The file mp2audio.sho contains some other common LISP functions, such as
'cond', 'list', 'assoc', 'member', boolean operations and more. Have a look
at the file.


Tomas Berndtsson <tomas@nocrew.org>
