		   wavplay-1.3.tar.gz
	        Wed Sep 16 17:47:00 1998
		  Warren W. Gay VE3WWG

There are still issues in wavplay regarding certain legal, but unusually
formatted wav  files  that  it  does not handle correctly.  This will be
fixed in GnuWave at a later date.


================
COMMON PITFALLS:
================

Many emails I get are related to the following user errors:

	1. The user never installed the release patches. At this time
	   there are no patches for release 1.3, but if you do
	   experience problems, please check to see if patches
	   have been released by the time you read this. You can
	   also check www.tripod.com/~ve3wwg for pointers to
	   software and patches.

	2. If you are installing the X component xltwavplay, which
	   is entirely optional, then make sure that you've first
	   installed X, its libraries and its include files. Second,
	   make sure you have MOTIF or LessTif installed correctly.
	   These are major sources of user problems.

	3. If you are compiling xltwavplay, then make sure you go
	   over the Makefile. There are a number of places where
	   directories and linking options may need to change based
	   upon your X/MOTIF/LessTif installation.

	4. Keep in mind, that if you are using LessTif, that the
	   LessTif effort is still in progress. While I have tried
	   to make xltwavplay function as best as I can, there were
	   still weaknesses in the File Selection dialog for example.
	   These are problems that will be fixed by later releases
	   of LessTif, or if you have purchased MOTIF.


===============================
SOUND GLITCHES AND LIMITATIONS:
===============================

The  wavplay-1.0  release  was  compiled  without  any  of the real time
benefits that can be had under LINUX. It was suggested that I add a call
to sched_setscheduler()  to incorporate LINUX real time scheduling. This
has  will  be  done,  provided  that you configure SCHED_PRIORITY in the
Makefile (by default this is configured with a real time priority of 9).

The  sched_setscheduler()  call  should  work  quite  well in giving the
wavplay  server  (only)  the necessary  system  priority  to  play sound
samples  without  gaps  or  glitches.  If  a  busy  system  still causes
playing/recording to  glitch then  you  may  want to use a higher valued
SCHED_PRIORITY value (assuming you have other real time tasks running on
your system). This real time scheduling, should improve your recordings.


============
SETUID ROOT:
============

In order to call sched_setscheduler() with a SCHED_PRIORITY of more than
0 (to be useful), you must have root privileges. This is because you are
gaining  improved scheduling privileges this way. Running any program as
root has its security drawbacks.  I have endeavoured to only run as root
long   enough    to    process    the   command   line   options,   call
sched_setscheduler() and  then  switch back to the natural userid.  This
allows  the  program  to call sched_setscheduler(), but prevents it from
being  able  to  overwrite any file (record mode), or to access any file
(play  mode)  that it  might  otherwise be  able to  do, if the  program
continued to run as root.

If  running a program setuid root bothers you, or presents too much of a
security  risk,  then  comment  out  the  SCHED_PRIORITY  entry  in  the
Makefile.

As a further precaution, you will be required to do a 'make setuid_root'
after  the  initial  install,  if  you HAVE choosen to use the real time
scheduling feature. By  doing  so  you assume all of the risk associated
with  any  possible  security breach of running wavplay as a setuid root
program. The software is provided ASIS, and I assume no risk whatsoever.


=======================================
THE PAUSE BUTTON SEEMS TO LOSE SAMPLES:
=======================================

If  you  PLAY  a  wav file and then press PAUSE in xltwavplay, expect to
lose a bunch of samples.  The reason is fairly simple: serveral KB worth
of  samples  are  shoved  into the /dev/dsp buffers to keep it well fed,
since if it gets starved you'll hear glitches in the sound.

To stop almost immediately, much of that queued data is dumped.  So when
you resume with PLAY, you'll often notice that some sound was lost.

In  recent  kernels,  you are asked to specify how large the DSP buffers
should  be when configuring it for compile.  Using large buffers insures
fewer  problems  with  gaps  in the sound during heavy system loads. The
downside  of  this means that you'll  have  less immediate control (when
pressing PAUSE).  You  might prefer smaller buffers, with the small risk
that  you may  occaisionally  hear gaps in your sound playing under busy
system conditions. The trade-off is entirely your choice.


=========================
YOU WANT TO REPORT A BUG:
=========================

Please give me something to work with when you submit a problem.

If  it doesn't compile, get the error message text and forward it to me.
If you're  using X, the use the mouse to copy the text of the screen and
pasted  that  into the  message to me.  Please do not describe a compile
error in your own words.

Runtime  errors  from xltwavplay can be had by starting it from an xterm
session, since  many  messages go to stderr.  Use the usual UNIX command
line  or X Window techniques to extract those messages, and forward them
in the email.

For catching compile errors, try something like:

	$ make 2>&1 | tee errors.out

To force a remake, try:

	$ make clobber all 2>&1 | tee errors.out

This  allows  you  to  see  the  messages  in real time, and capture the
messages to file errors.out as well.  Include the contents of errors.out
in your message to me please.

Also please describe something about your system:

	LINUX Kernel Version? (important)
	CPU type? (if you think it matters)
	Amount of memory?
	Video card (if you think it matters)
	What sound card type? (important)
	
also:
	whether or not the system is a laptop (ie. PCMCIA etc.)

Please describe your C compiler tools:

	GCC --version
	Version of the C libraries (if you can tell me this)

These are good places to start when reporting a bug.

Please send all bug reports and correspondance to:

	Warren W. Gay VE3WWG
	ve3wwg@vaxxine.com

Please  distinguish  between  the  programs  wavplay and xltwavplay when
reporting  problems. Note  also, if the problem is with only certain wav
files,  or wav  files  from  a certain  tool,  then please remember that
wavplay does  not  properly process all legal variations of wav files at
this time (to be addressed with GnuWave).

If  wavplay  won't  play  or  record at all, then make sure you have the
sound  card  installed  correctly.  Ask  yourself,  does  this work from
DOS/Windows ok? If not, then perhaps that's a place to start.  If that's
ruled  out,  then make sure your kernel has sound driver support.  Newer
kernels may require you to LOAD the module to support the sound driver.

Also  make  sure you have specified the I/O ports, IRQs and DMA channels
correctly when configuring your kernel.

Make  sure  your  special  device  file is available and has permissions
(/dev/dsp on my system).

Last,  but  not  least, some of you out there are running very old LINUX
kernels.  While I have nothing against vintage code, I must suggest that
the  sound card  support has changed a lot since 0.xx versions of LINUX.
Please  consider upgrading  ASAP  if you're running something older than
1.2.13.

Send correspondance to:
 
 	Warren W. Gay VE3WWG
	ve3wwg@vaxxine.com
	www.tripod.com/~ve3wwg

End BUGS.
