This is GSI version 0.6 (28- 5-1998)
====================================
License: CGPL (see the file LICENSE.CGPL for details)

Files are available from:
	http://www.cistron.nl/~wouters


0. Planned changes:
===================
0.9+:
- NAS midi playing (emulation of wave card)
- Pure notes
- echo
- noise filter
- POSIX 1b real time  changes (only when  using  sockets as the server
  can then be started by root at startup (or suid, root access needed,
right?)
- SYSV shared memory
- CD playing commands

0.8:
- Adding ADPCM software (de-) compression (using Sun's PD adpcm code).
- Add security for the socket version: see doc/SECURITY

0.7:
- midi: fix playing/pausing.
- midi: add more sysex decoding.
- midi: multi client negotiation.
- Get the eiffel code working again.
- NAS: add channel playing (now only stack) and adjust volume of
  playing sounds when the PCM volume is adjusted.
- native storage of sounds in memory (16 bit) ?
- Improve AUTO_DSP and USE_BEST_DSP_SETTINGS code in the multi client
  dsp mode setting code.
- midi timing: replace current_midi by current_time.


1. Changes:
===========
0.6 (28- 5-1998) Fixed  some  client  shutdown stuff. Fixed 8 bit AIFF
		 (signed  data, not  unsigned). Decide  file  types on
		 signature   instead  of  extension  (except  for  raw
		 sounds). MSB sending of 16/32 bit  values (x,dx etc).
		 Improved  gsiplay: while  running  the volume  can be
		 adjusted by pressing +/- when it's been compiled with
		 USE_CURSES defined.

0.5 (24- 5-1998) Fixed volume  initialisations  when the master volume
		 is emulated.  Support  for most  simple wav  files (I
		 must  have  lost my  mind,  supporting  this  trash).
		 Simplified the sample  playing code (always 16 bit in
		 the premix  buffer) and with this put in code to play
		 mulaw samples  without decoding  them first to 16 bit
		 as done in 0.4. Added a small  example program to the
		 manpage. Changing DSP settings now works when the DSP
		 hasn't been  released  first (i.e. SND_GRAB_DSP while
		 the DSP is grabbed works). Started separating out the
		 OSS specific  stuff  (mode  setting, mixer) and added
		 code for generic /dev/audio (8kHz mono mulaw). 
		 Changed the license of gsiplay's main.cc from CGPL to
		 public domain. Made gsitest's main.cc public  domain.
		 Separated DSP  mode setting, mixer, file loading code
		 from     gsi_server.c and gsi_interface.c into dsp.c,
		 mixer.c and  load.c    respectively. Started   adding
		 socket code so  multiple  clients can access  the DSP
		 simultaneously. Connecting works. It runs! (old  fork
		 & pipe code is commented out, might be useful later).
		 AIFF/AIFC  file  formats  (Apple)  are  almost  done.
		 Multiple client DSP negotiation code added.

0.4 (29- 4-1998) Software  sound  volume used in all conversions. Midi
		 player  included. Made  code more  readable.  Started
		 work on updating the eiffel and NAS code. Added  code
		 to  play  on  a mulaw  device.  Added  Master  volume
		 emulation if it's not  available in  hardware.  Added
		 code to play mulaw encoded samples. Improved debug.h.

0.3 ( 3- 4-1998) Bugs removed, added updated python script h2e.py
		 Added configuration script

0.2 (29- 3-1998) Full 3d doppler (no propagation delays though) using
		 the newer doppler code I had not included in 0.1

0.1 (10- 3-1998) 2d doppler version.


2. The general sound interface:
===============================
  The mission: To  provide extremely easy access  to the sound  system
for simple  tasks and  still allow  full control  over every detail of
sound playing.  This  is done by allowing  almost all  functions to be
controlled with serially encoded commands,  which has the advantage of
very easy interfacing with other languages  than C (this isn't so easy
, or at the very least messy, with the use  of structs and stuff in eg
NAS). These commands send  only the  minimal information needed  which
will   make it run  well on  a network (need  to change  the pipe to a
socket for network use though). Convenience functions take care of the
'easy access' part  and the special  functions are also quite  easy to
use even though they must be sent as a string. 

  This version should be considered alpha due to various changes  made
recently and the various changes that will take place.

  Also, The NAS and eiffel code must be checked and missing stuff must
be added (in particular all the channel playing commands must be added
as both were  used with a previous version  of the sound  server which
only used the stack). Furthermore, you also need elibc-0.13 to use the
eiffel files (to use pipe functions etc). 


3. Supported hardware interface API's:
======================================
	1. OSS
	2. NAS. The NAS interface must be updated though.
	3. generic /dev/audio  [ Untested, does it work ? ]
Future:
	a. ultrasound project and successor ( http://alsa.jcu.cz/ )
	b. FreeBSD's new driver
	c. Native for SGI's and other OS'es ?


4. Requirements:
================
ANSI C  compiler that doesn't quit  when seeing // style comments,
gmake.

OSS 3.8 or higher for correct synth mixer behaviour on some cards,
e.g. GUS PNP.

For the  eiffel code: elibc (access  to  lowlevel  functions  such  as
select), SmallEiffel (changes for other compilers are probably small).


5. Quickstart:
==============
Type
	'make location'
	'make config'
	'make install.all'
and follow the instructions.


6. Configuration:
=================
	'make config'
This will make a file config.h, which will go into the gsi include dir
so you only enter once
	(1) if you want GUS and OPL3 and other devices compiled in.
	(2) if you want to use NAS or OSS (overriding is possible by
	    doing #undef USE_OSS /#define USE_NAS for example)
	(3) any other system/hardware dependant things.

Adjustment:

possibly  change LINE1  in the  mixer code in  gsi_interface.c for the
synth volume   for   ad1848 cards  (GUS  PNP: LINE1,   others may  use
LINE2/LINE3) , However, this is only needed for OSS 3.5 which is quite
old by now. 


	'make eiffelconfig'

will  make an eiffel class   GSI_CONFIG with all configuration details
from config.h 


7. Installing:
==============
type 'make location' to set install locations.

To install the header and interface files type:
	'make install.header'
[ default location: /usr/local/include/gsi ]

To make the sound server (gsi_server) type:
	'make'

To install the server type:
	'make  install'
[ default location: /usr/local/bin ]
Optionally do a 'make strip' before installing.

To install the man pages gsi.3 and gsi_commands.3 type
	'make install.man'

To install server, header files and man pages in one go type:
	'make install.all'

Finally, you MUST place a line in /etc/services, like this:

gsi_server      9000/tcp                        # Shared 3d sound server

You can change the port number 9000 into any other but if running over
a network, make  sure it's  the same  on both  machines. This  default
number may change to a better value when I implement security.


8. Starting the server:
=======================
/usr/local/bin/gsi_server -loop &


9. Test program:
================
  The 'test'  directory   contains    a program  used to    test   the
server. Have a look at it to see how to  use the commands (also have a
look   at the man   pages)  and the use  of  the  symbolic link to the
interface file. 

The test data:
gsi-sounds-2.tgz :
------------------
  sounds used to test the  conversions from sound speed/bytes/channels
to the DSP's speed/bytes/channels. Use it if you want to change and/or
test that part of the server or  if you want  to use the test program.
marvin.au  (the depressed robot)   is  mulaw encoded, the others   are
linear 8 bit and 16 bit). 

gsi-music-2.tgz :
---------------
  110.au  : A  long music sample   (from Ougenweide's  Sol)  to   test
       doppler/moving (8 bit 11kHz mono)
      (for more information see http://www.emimusic.de/i/content.html) 
  InstantX.mid : (excellent rendition of Mylene Farmer's l'Instant X),
       used to (enjoy myself and)  test the  patch  loading  and  midi
       playing 
  Mission_impossible_movie.mid : (superb midi), ditto 
  Zzunkown.mid : (original music by Nguyen van Lam), ditto. 
  a-quoi-je-sers.mid : another Mylene Farmer midi. Sounds like crap on
       gsi at the moment (not on Cakewalk).

duke3d.zip :
------------
  All music from the game, which are a  good test of the midi playing,
e.g: 
  alienz.mid -- I love this tune. At the  moment it  doesn't  sound as
       good with gsi as it does in the game. Cakewalk handles it a lot
       better. 

gsi-wav-2.tgz :
---------------
  A few assorted .wav's to test the server:
  s_8_22.wav: the  8 bit stereo  22050 Hz  original of the  conversion
          tests in gsi_sounds-2.tgz.
  clarissa.wav: Melissa explains it all. She's great. 8 bit 11kHz mono
  howlb.wav: 16 bit (LSB) stereo 22 kHz


10. Sound player: gsiplay
=========================
gsiplay in the player directory plays raw, .au/.snd, .wav, aiff, aifc,
midi's  and sets volume levels.
	'make install'
installs the program in  /usr/local/bin. Optionally  do a 'make strip'
first.


11. Use in your own programs:
=============================
For the OSS version, make a symlink
	ln -s /usr/local/include/gsi/gsi_interface.c sound.c
and add sound.o as one of the objects to be made.
Alternatively, in one of your files, do
	#include <gsi/gsi_interface.c>

For the NAS interface, replace gsi_interface.c by gsi_nas_interface.c.
When  using NAS, programs also   need   some   include/link  location
directives  for  Solaris  (  -L/usr/X11R6/lib  -R/usr/X11R6/lib
-I/usr/openwin/include IIRC) and -laudio for all OS's.

You  can  also  use the file  sound.c in the  player directory in your
own programs.


  For   eiffel,  inherit    or      instantiate  an     object    from
gsi_interface.e. To use the NAS interface  from eiffel, you'll need to
change  gsi_interface.e and  use gsi_nas_interface.c as  an external C
file at the moment. Note that the eiffel code must be updated.


12. Debug output:
=================
When you've  compiled  with DEBUG  defined (default), the  environment
variable  DEBUG_LEVEL  controls the  amount  of output (0 or undefined
gives no output). See debug.h for more information.



13. Fileformats:
================
The only formats I intend to support at this moment are:
Samples: raw, .au/.snd (+standard wav/aiff/aifc)
Music:   midi

This is enough for  most  applications. Suggestions about  'must have'
formats are welcome though (with justification).


14. Utilities:
==============
  'make utils' makes the utilities in the utils dir.  raw2au: converts
a mono 8  bit raw file  to .au/.snd (i.e. adds  a  header) Comment out
#define  NL in raw2au.c for english  messages. Just enter 'raw2au' and
the  program will ask you  what it needs to   know, or use it directly
like this: 

	raw2au alien_shoots.raw 8000 1 8 "Planetoid sound: alien shot"

which converts a sound   'alien_shoots.raw' to 'alien_shoots.au'  with
header info of speed = 8000Hz, channels = 1, type = 8 bit, description
= "Planetoid sound: alien shot" 


15. More information:
=====================
See the gsi man page for details on  using the system, and information
on things that will be fixed and implemented. 


Please send me any fixes, patches, improvements and suggestions.


Enjoy,

WHS (wouters@cistron.nl)
