Specgram, a spectrogram display program for DOS, Linux, Linux/X
 
Copyright (C) 1995  Philip VanBaren

This program is free software; with the exception of the soundcard 
sampling routines which are copyright their respective authors, 
you can redistribute it and/or modify it under the terms of the GNU 
General Public License as published by the Free Software Foundation; 
either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Program files:

dos/specgram.exe  DOS executable program for PAS16, SB8, SB16 and VESA/AI
linux/specgram    Linux executable using SVGA display
linux/xspecgram   Linux executable using X-Windows display

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

The DOS version of the SPECGRAM program requires VESA video 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 mach32 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://oak.oakland.edu/SimTel/msdos/graphics/vesadrv2.zip

If you are unable to locate a VESA driver for your particular card, there is 
a VESA driver which supports many video cards available as:
ftp://oak.oakland.edu/SimTel/msdos/graphics/univbe51.zip
Note: The universal VESA driver (UniVBE) is Copyright (C) 1992-94 
SciTech Software, and is a shareware product requiring separate 
registration if you continue to use it.

DOS: specgram.exe

Specgram.exe is a program which performs a Spectrogram time-frequency plot
of the data input from a soundcard.  Soundcards currently supported are
the MediaVision PAS16, Soundblaster 8-bit and compatibles, Soundblaster
16-bit cards, and any card which supports the VESA Audio Interface standard.

The program 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 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 an INI file.  
Refer to the Runtime Options, below.

When using the Soundblaster sampling routines, 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 the program will run.

Note: the older Soundblasters and many compatibles are only capable of 
sampling up to 12kHz.  Newer Soundblaster models can sample at 44.1kHz or
more.  The program will allow you to try the high sampling rates on older
Soundblaster cards, and will not return any error messages.  However, the
display will be incorrect if you exceed your soundcard's limits.

Linux: specgram and xspecgram

The Linux versions of the program have been dynamically linked with ELF
versions of the standard libraries.  The specgram (SVGA display based) 
version uses the SVGALib package for display, and requires that those 
libraries be installed on your system.  The xspecgram (X-Windows based)
program uses the SRGP package for display under X-Windows, so you need 
to have that library installed on your system.  Refer to the 
source/readme.txt file for more information on these libraries.

COMPATABILITY:

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

RUNNING UNDER WINDOWS:

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 driver.

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

I have run both versions under Windows95 without any problems.

COMMAND LINE OPTIONS:

-Cnumber selects the soundcard 
   In DOS: 0=SB8, 1=PAS16, 2=VESA, 3=SB16
   In Linux: 0=AU, 1=DSP
-Ddevice selects the input device (Unix only)
-Odevice selects the output device (Unix only)
-Xdevice selects the Mixer device (Unix only)
-Rnumber sets the sampling rate.
-S selects stereo mode.
-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.

Soundcard: 0                - same as -Cnumber
	This selects the input device.  Valid values are:
        in DOS: 0=SB8, 1=PAS16, 2=VESA, 3=SB16
	in Linux: 0=MULAW (/dev/audio), 1=LINUX (/dev/dsp)
Sample rate: 44100          - same as -Rnumber
	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 PAS16 and SB16 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 PAS16 and SB16 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' :       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
'O' :           Output the display to a GIF file
'S' :           Save the current setup to an INI file
'H','?' :       Toggle the help screen on/off
'G' :           Select 0/6/12 db/octave gain
'<' and '>' :   Change the external jack input level
'[' and ']' :   Change the microphone input level
'{' and '}' :   Change the internal jack (CD) input level
<u/d arrows> :  Increase/decrease the amplitude scale
<l/r arrows> :  Change the base level for log amplitude scales
                Note: in Linux, the arrow keys are input using the
                numerical keypad with numlock turned on.
                This means 8=up, 4=left, 6=right, 2=down.
<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 program will round the rate you enter to the nearest rate that the 
soundcard can handle.

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:

*** Please, don't bother these people with problems you have with my
*** program.  I used some code they they made available on the Internet
*** to provide some of the soundcard support.  However, they did no direct
*** work on this program, and so cannot help you with problems you have
*** with it.  On the other hand, if you are interested in writing programs
*** which support these sound cards, get a copy of their code from the
*** Internet, look it over, and then bother them about it.

The Soundblaster code was written by Heath I. Hunnicutt 
(heathh@cco.caltech.edu).  The source for this code is available via FTP
from: ftp://ftp.inf.tu-dresden.de/pub/ms-dos/sound/program/sb_dsp.zip
and dma_code.zip.  The first file gives the SB8 routines, and the second
file gives the DMA routines.

The Soundblaster-16 code is based on code written by Ethan Brodsky 
(ebrodsky@pobox.com), which is available from:
ftp://oak.oakland.edu/simtel/msdos/sound/sb16snd.zip

The VESA AI code comes from the VESA AI SDK, available via FTP from:
ftp.uwp.edu:/pub/msdos/proaudio/vaisdk.zip
The VESA BIOS extensions for PAS16 cards is available from:
ftp.uwp.edu:/pub/msdos/proaudio/vbeai.zip

The PAS16 libraries come from the MediaVision PAS SDK, available via FTP from:
ftp.uwp.edu:/pub/msdos/proaudio/passdk30.zip
garbo.uwasa.fi:/pc/proaudio/pas-sdk1.arj and pas-sdk2.arj

The SVGALIB libraries were written by Harm Hanemaayer, and are available from
sunsite.unc.edu:/pub/OS/Linux/libs/graphics/svgalib126.tar.gz

The SRGP libraries were written by David Sklar, and are available from
sunsite.unc.edu:/pub/OS/Linux/libs/X/srgp.tar.gz

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 from:
ftp://oak.oakland.edu/SimTel/msdos/c/gifsave.zip.

Thanks to Andrew Veliath and his SVGAFFT program for giving me examples
for doing both audio sampling and SVGA graphics output under Linux, making
it easy to port this program to Linux.

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.

Thanks to Jaime Ramirez Barajas for testing the Soundblaster 16 code.

LEGAL STUFF

Soundblaster is a trademark of Creative Labs.
ProAudio Spectrum and ProAudio Studio are trademarks of Media Vision.

If you have any questions, bug reports, suggestions, or additions to the code,
you can contact me at:

Philip VanBaren
Internet:    phillipv@eecs.umich.edu
