FILE LIST:

SPECGRAM.EXE executable program for PAS 16 sound cards
SBSPEC.EXE   executable program for Soundblaster sound cards
SPECGRAM.TXT (you are reading it)
SPECGRAM.INI Initialization file for SPECGRAM.EXE/SBSPEC.EXE
UVBE50BD.ZIP Archive containing a universal VESA driver.


!!!!! MOST IMPORTANT: INSTALLING VESA SUPPORT FOR YOUR VIDEO CARD !!!!!

The SPECGRAM programs require VESA mode support to be installed on your 
video card, because the graphics are done using a VESA 800x600x256 color 
graphics mode.  (Note: The VESA video mode standards are not related to 
VESA local bus standard other than that they were created by the group.  
You do NOT need a VESA local bus video card to have VESA video mode support.)
Some newer video cards support the VESA video modes directly in the BIOS, 
however most cards require running a TSR program to provide this support.  
Check the drivers that came with your video card for such a program (for ATI 
cards, it is VVESA.COM).  If you cannot find a VESA driver among your video 
drivers, check with your video card manufacturer to get a driver.  Many of 
these drivers have been made public domain, and are available from a variety 
of sources.  For example, I have an ATI card, and found the latest VESA 
driver available via FTP from ATI's FTP server (atitech.ca).  There are also 
archives of the publicly available VESA drivers available via FTP or from 
Compuserve.  Three such archives are vesadriv.zip, vesadrv2.zip, and 
vesadr.zip.  One FTP site where these are available is 
ftp.cs.umn.edu/.archive0/X/R5contrib.

If you are unable to locate a VESA driver for your particular card, there is 
a VESA driver which supports many video cards included here in the file 
UVBE50BD.ZIP.  Note: The universal VESA driver contained in UVBE50BD.ZIP 
(UniVBE) is Copyright (C) 1992-94 SciTech Software, and is a shareware 
product requiring separate registration if you continue to use it.

SPECGRAM.EXE:

SPECGRAM.EXE is a program for the ProAudio Spectrum/Studio 16 sound cards.
It samples the input, performs an FFT, and graphs the output in the form
of a spectrogram.  A spectrogram is a form of time-frequency plot, a 3D
plot where one axis is time, the second is frequency, and the vertical
axis is the signal level at the the specific time and frequency.  In this
case, the X axis of the display is time, the Y axis is frequency, and the 
vertical axis is shown as varying colors.

INI file and command line options provide the user with the ability to 
select linear/log frequency and amplitude scales as well as sampling rates, 
length of the FFT, and windowing functions.  Most of these settings can 
also be set while the program is running, and the new settings saved to 
the INI file.  Refer to the Runtime Options, below.

SBSPEC.EXE:

SBSPEC.EXE is the same as SPECGRAM.EXE, except it uses the SoundBlaster
for audio input.  The program searches for an environment variable called
BLASTER, and derives the Soundblaster address, IRQ, and DMA from it.  If
this variable is not set, it will default to address 220h, INT 5, DMA 1.  
If you do not have a SET BLASTER=A220 I5 D1 in your AUTOEXEC.BAT file and 
do not use these default values, you will need to add this before SBSPEC
will run.  Note: This version is not nearly as good as the PAS version
because it only samples 8-bits, and therefore does not have a very good 
signal-to-noise ratio.  Also, the older Soundblasters were only capable of 
sampling up to 12kHz.  Newer Soundblaster models can sample at 44.1kHz or
more.   If anyone has developed some code for recording 16 bit waveform 
data from a Soundblaster card, I would really like to hear from you.  
It would be great to add 16-bit Soundblaster support to this program.

COMPATABILITY:

This program has been tested on the following sound cards:
- ProAudio Studio (specgram)
- Logitech Soundman (specgram)
- Soundblaster 16 (sbspec)
- Soundblaster (sbspec)
- Sound Galaxy 16 NX (sbspec)
- GUS MAX (sbspec with SBOS)

RUNNING UNDER WINDOWS:

Don't.  Actually, it may not be that bad, but some Windows video drivers may
be confused when an application uses 470k (800x600x8) of video memory.  
Typical results will be characters not appearing on the display, and bitmaps 
appearing as black rectangles.  Usually the fonts can be restored by 
displaying lots of varied text so that the font caches get cleared.  

I also have had problems running the PAS version under Windows with the 
latest PAS drivers (MVSOUND version 3.23 or 3.24).  There seems to be a bug 
in this MVSOUND driver.  If you have problems running under Windows you can 
try reverting back to an earlier version of the drivers.

Both the Soundblaster and the PAS version of the program have been 
successfully run under Windows but no guarantees are given.

COMMAND LINE OPTIONS:

-Snumber sets the sampling rate.
-Fnumber sets the length of the FFT.
-W0 selects a Hamming window.  (offset sine) <--default
-W1 selects a Hanning window.  (sine)
-W2 selects a Blackman window. (two sines)
-W3[,alpha] selects a Gaussian window.
-W4 selects a Welch window.    (quadratic)
-W5 selects a Parzen window.   (triangular)
-W6 selects a Rectangular window.
-Wfilename saves the windowing function to the specified file.
-? or -H displays this message.

INI File options: 

These options override the program defaults, but are overridden by the 
options specified on the command line.

Sample rate: 44100          - same as -Snumber
	This sets the sampling rate, in Hz.  For Soundblaster cards, if
	you set this value too high, the frequency scale will not be correct
	because the sampling will not occur at the requested value.  For 
	example, the Soundblaster section on my PAS16 can only sample at
	up to 12000 Hz, so it is pointless to use a value higher than this.
	The newer versions of the Soundblater cards can handle sampling up
	to (and possibly beyond) 44.1kHz.
FFT length: 1024            - same as -Fnumber
	Number of samples used for each FFT.  The pixels displayed on the 
	screen will be half of this number due to the nature of the FFT, 
	so a 1024-point FFT will show up as 512 pixels high on the display.
Pixel height: 1
	This factor multiplies the FFT length to increase the height of the
	displayed data.  For example, if you specify a 256 point FFT, and have
	a pixel height of 1, the display will be 128 pixels high.  However, if
	you specify a pixel height of 4, the display will be stretched to 512
	pixels.
Accel factor: 1
	This factor accelerates the display by plotting multiple FFTs per 
	buffer.  The amount of acceleration possible depends on the speed of 
	your computer and the sampling rate.  On my 486DX/33 with a 12kHz 
	sampling rate and 1024-point FFT I can get an acceleration factor of 
	4.  The accel factor setting is displayed in the header information.  
	After 100 FFTs have been calculated and plotted, the actual 
	acceleration rate is listed in parentheses after the setting.  The 
	initially displayed actual value may be a little off since it not 
	much averaging is involved.  If you let the program run for a few 
	seconds, and then toggle help mode on/off, the number will be updated 
	with a more accurate value.  The longer you let the program run, the 
	more accurate this value will get.  
	The actual value display is reset each time you change a parameter 
	which effects it.
Window function: 0          - same as -Wnumber
	0 selects a Hamming window.  (offset sine) <--default
	1 selects a Hanning window.  (sine)
	2 selects a Blackman window. (two sines)
	3 selects a Gaussian window.
	4 selects a Welch window.    (quadratic)
	5 selects a Parzen window.   (triangular)
	6 selects a Rectangular window.
Log mode: 0
	Any non-zero value here will use a log-scaling method for the color
	display.
Log scale base: 8
Log scale factor: 20
	Scaling factors used in the log-scaling mode.  Increasing the log 
	scale base will result in pushing more low-level sounds (and noise) 
	to black.  Increasing the log scale factor will cause the display to 
	be brighter.
Linear scale factor: 4
	Scaling factor used in the linear-scaling (log-mode=0) mode.  
	Increasing this value will cause the display to be brighter.
DB/octave gain: 0
	This selection causes the scaling factors to be frequency dependent.
	Accepted values are 0, 6, and 12.  0dB/octave gives a flat frequency
	response.  6dB/octave causes, for example, a 1kHz signal with 
	amplitude 1 and a 2kHz signal with amplitude 0.5 to show up equally 
	bright.  In 12dB/octave mode, the 2kHz signal would show up twice as 
	bright as the 1kHz signal.  This is useful since harmonic signals 
	generally decrease as 1/f (-6dB/octave) or as 1/(f*f) (-12dB/octave).  
	With these options, the higher harmonics can be more clearly seen.
Embossed mode: 0
	Any non-zero value here will select embossed mode.  It gives sort of 
	a 3-D texture to the spectrogram.  This mode only looks good with one
	of the black-to-white palettes selected.
Palette: 0
	0 selects HSV (blue-cyan-green-yellow-red)
	1 selects Threshold (same as HSV, but with a black background)
	2 selects Cool (cyan-magenta)
	3 selects Hot (black-red-yellow-white)
	4 selects White (black-white)
	5 selects Bone (black-offwhite)
	6 selects Copper (black-brown)
Stereo: 0
	This option is only available on PAS cards.
	Any non-zero value here will enable stereo mode, with a spectogram 
	displayed for each channel, Left and Right (or Sum, Difference 
	as set next...)
Stereo L-R: 0
	This option is only available on PAS cards.
	Any non-zero value will switch the stereo mode into Sum/Difference
	mode.  The lower spectrogram will display the summed Left and Right
	channels.  The upper spectrogram will display the difference between
	the Left and Right channels.

RUNTIME OPTIONS:

While the program is running, the following commands may be used:

'X','Q',<ESC> : Exit from the program
'F' :           Change the FFT length
'A' :           Change the accel factor
'R' :           Change the sampling rate
'W' :           Toggle windowing function
'P' :           Change the palette
'L' :           Toggle between logarithmic (dB) and linear amplitude scales
'D' :           Toggle L/R (normal) and (L+R)/(L-R) (difference) stereo modes
'E','M' :       Toggle Embossed/Amplitude modes
'G' :           Save the screen as a GIF file
'S' :           Save the current setup to an INI file
'H','?' :       Toggle the help screen on/off
'0','6','1,'2': Select 0/6/12 db/octave gain
'<' and '>' :   Change the external jack input level (PAS only)
'[' and ']' :   Change the microphone input level (PAS only)
'{' and '}' :   Change the internal jack (CD) input level (PAS only)
<u/d arrows> :  Increase/decrease the amplitude scale
<l/r arrows> :  Change the base level for log amplitude scales
<space> :       Freeze the display.  Another <space> will continue.

THE WINDOWING FUNCTION:

Several different windowing functions are available.  The windowing function
is a function that is multiplied by the input data to reduce the effects of
the discontinuity at the ends of the data set.  A rectangular window is 
actually no window: all data is passed through.  A Parzen (triangular) window
uses a trianglar weighting: the end points are multiplied by 0, the
middle point by 1, with a linear ramp from 0 to 1 and back to 0 again.
A Welch Window uses a quadratic weighting: the end points are multiplied by
0, the middle points by 1, with a [concave down] quadratic function from 0,
up to 1, and back down to 0 again. To see the shapes of the various windows, 
used the -Wfilename option, and plot the data in the output file.

KNOWN PROBLEMS: (let me know if you find others)

1) The PAS version of the program does not work if the 'device=mvsound.sys'
line in config.sys contains the switch "u" (this switch allows initialization
of the card, but then the driver is unloaded from memory (not a TSR)).
Removing this switch solves the problem.  My config.sys contains the
following line:
   devicehigh=c:\pastudio\mvsound.sys d:5 q:10 s:1,220,1,7 j:1 t:1 v:0

2) The actual sample rates must be integer divisions of the timer frequency,
which is 1.19318 MHz for PAS cards, and 1.0 MHz for Soundblaster cards.  
This means actual sampling rates for PAS cards are:
   91.78kHz, 85.23kHz, 79.55kHz, 74.57kHz, 70.19kHz, 66.29kHz, 62.80kHz,
   59.66kHz, ... , 45.89kHz, 44.19kHz, 42.61kHz, etc.
and the actual sampling rates for Soundblaster cards are:
   45.45kHz, 43.48kHz, 41.67kHz, 40kHz, ... 22.73kHz, 22.22kHz, 21.74kHz, etc.
The displayed sample rates will not reflect actual values unless the command
line option specifies a rate that is an integral division of the timer
frequency.

3) The specified sampling rate may be above what a Soundblaster can handle. 
If this occurs, the Soundblaster will sample at its maximum rate, and the 
frequency axis will not reflect the true frequencies.  Typical 8 bit 
Soundblasters will only handle sampling rates up to 12kHz.  Newer 
Soundblasters can handle sampling rates of at least 44.1kHz, and may be 
able to go beyond this rate.

4) The PAS version of the program may crash under Windows when used with 
the latest PAS drivers (MVSOUND versions 3.23 and 3.24.)  If you have 
problems running under Windows, you can try going back to a previous version 
of the PAS drivers.  Other side effects which may occur depending on the 
drivers installed are that the Windows mixer settings are confused by the 
program.

CREDITS:

The GIF routines were written by Sverre H. Huseby (sverrehu@ifi.uio.no).  
All I did was link then in with my code, and they performed perfectly!  
The source for this code (and more information) is available at many FTP 
sites, under the file name gifsave.zip.

The Soundblaster code was written by Heath I. Hunnicutt (heathh@cco.caltech.edu 
-or- heathh@tybalt.cco.caltech.edu).  The source for this code is also 
available via FTP, but I don't remember where.

I learned all that I know about accessing VESA display modes from a file 
called VESA.DOC compiled by Gary Lorensen of Everex Systems, Inc, and and 
example program provided by Kendall Bennett with one of his VESA driver 
packages.  The VESA.DOC file, available via FTP (just do an archie search 
for vesa.doc), provides an excellent summary of the VESA BIOS calls. 

Thanks to Marko Slyz for his relentless critique of this program.  Because 
of him, the user-friendliness was improved and many extra features have been 
added.

LEGAL STUFF

Soundblaster is a trademark of Creative Labs.
ProAudio Spectrum and ProAudio Studio are trademarks of Media Vision.
The universal VESA driver contained in UVBE50BD.ZIP (UniVBE) is 
  Copyright (C) 1992-94 SciTech Software, and is a shareware product  
  requiring separate registration if you continue to use it.

DISCLAIMER

This program is FREE.  You may use and distribute it as long as credit 
is given to the author, and no modifications are made.
The author hereby disclaims all warranties relating to this software,
whether express or implied, including without limitation any implied
warranties of merchantability or fitness for a particular purpose.
The author will not be liable for any special, incidental,
consequential, indirect or similar damages due to loss of data or
any other reason, even if the author has been advised of the possibility 
of such damages.  The person using the software bears all risk as to the
quality and performance of the software.

OTHER

The source code for a program that this program was based on, which uses
a sound card to create a spectrum analyzer, is available via FTP in the file
FREQ3.ZIP or FREQ3.ARJ.

If you have any questions or bug reports, you can contact me at:

Internet:    phillipv@eecs.umich.edu

Compuserve:  71214,2302

Philip VanBaren
1845 Lake Lila Dr.  Apt. C3
Ann Arbor, MI  48105
