CREATING SCROLLING AUDIO SPECTRUM DISPLAYS WITH SPECTRUM.DLL

Spectrum.dll is a Win32 dynamic link library for Win95/98 or WinNT that will create a scrolling audio spectrogram display within your application program.  Spectrum.dll creates a child window of any size and position you specify.  This Spectrum Window can then receive windows messages from your application which direct it to receive audio data from the sound card and begin a scrolling spectrogram display, set any of the spectrum analysis processing and display parameters, or start, stop, or resize the scrolling display.

Spectrum.dll uses the _stdcall calling conventions.

FUNCTION:  Spectrum.dll contains one function

HWND SpectrumWindow (HWND, HINSTANCE, LPSPECTRUMPARAM);

FUNCTION PARAMETERS:

HWND - Handle of the application program window within which the child Spectrum Window is to be opened.

HINSTANCE - Handle to application program instance

LPSPECTRUMPARAM - Pointer to a SPECTRUMPARAM structure in memory

typedef struct  {int xpos; int ypos; int width; int height; int samplespersecond;

int fftsize; float freqres; int lowbandfreq; int highbandfreq; int marker1freq; int marker2freq;

int offsetfreq; int timescale; int avecount; int gain; int ampscale; short scrolldirection;}  SPECTRUMPARAM;

typedef  SPECTRUMPARAM	*LPSPECTRUMPARAM;

SPECTRUMPARAM	SpectrumParam;

xpos = x coordinate of Spectrum Window (relative to parent)

ypos = y coordinate of Spectrum Window (relative to parent)

width = width of Spectrum Window (in pixels)

height = height of Spectrum Window (in pixels)

samplespersecond = audio digital sampling rate.  Must be either 5102, 11025, 22050, or 44100 samples per second.

fftsize = size of FFT used in spectrum analysis.  FFT size is limited to the following powers of two; 512, 1024, 2048, 4096, 8192, 16384.  The highest possible frequency resolution of your spectrogram will be the digital sampling rate divided by this FFT size.

freqres = frequency resolution of spectrum analysis in Hz.  Minimum allowable frequency resolution is samplespersecond/fftsize

lowbandfreq = lower frequency limit of display

highbandfreq = upper frequency limit of display

marker1freq = Display frequency mark #1

marker2freq = Display frequency mark #2

offsetfreq = Cursor offset is useful when scanning or analyzing signals that have been frequency translated.  For example, the audio output signals from an SSB radio receiver can be read as true radio frequency by placing the cursor on the displayed signal.  Cursor offset should be set equal to the zero beat frequency of the radio i.e.  the difference between RF frequency and audio frequency.  Both positive and negative offsets are allowed.  Positive offset should be used with USB (Upper SideBand) and negative offset with LSB (Lower SideBand) radio settings.  For analysis of natural sounds that have not been frequency translated, cursor offset should remain at zero.

timescale = Time scale in milliseconds which corresponds to the time interval between the calculation of each FFT.  To obtain greater time resolution in the spectrogram and faster scrolling speed, choose a smaller value for the time scale.  Each vertical line in the spectrogram display represents the output of one FFT calculation.  The time scale selected determines the length of the time between each FFT and thus the time resolution and scrolling speed of the spectrogram display.

avecount =  The number of sequential spectrum measurements which are averaged together before display.  Averaging is particularly useful in recovering weak periodic signals from a noisy background, but is probably not of much interest in analysis of speech or other rapidly varying signals.  You can choose averaging of one (no averaging) to 128 spectrum measurements.

gain = Signal gain in dB applied to the display.  This can be either a negative value (signal reduction) or a positive value (signal amplification) from -15 dB to +15 dB.  This gain will decrease or increase the spectrum amplitude by a constant factor across the entire frequency band.

ampscale = Amplitude scales for the scrolling spectrogram display.  The 30 dB scale examines a signal range from -30 dB to -60 dB.  The 60 dB scale examines a signal range from 0 dB to -60 dB.  And the 90 dB scale examines a signal range from 0 dB to -90 dB.  The 30 dB scale is most useful for strong audio signals; whereas, the 90 dB scale is most useful for very weak audio signals.

scrolldirection = choice of right-to-left scrolling or top-to-bottom waterfall scrolling.  Set scrolldirection equal to 0 for right-to-left scrolling and equal to 1 for waterfall scrolling.

RETURN VALUE

HWND - Handle of the child Spectrum Window.  This handle will be used in sending Windows messages to Spectrum Window with instructions for spectrum processing and display.

MESSAGES TO CHILD SPECTRUM WINDOW FROM APPLICATION PROGRAM

Once the child Spectrum Window has been created with a call to the dll function

hChildWindow = SpectrumWindow (HWND, HINSTANCE, LPSPECTRUMPARAM), the following windows messages can be sent to hChildWindow to control spectrum analysis and display.

RUNSCAN - Start spectrum analysis and display of audio data from the sound card.  RUNSCAN is sent as a WM_COMMAND message with the address of a SPECTRUMPARAM Structure contained in the lParam variable.

SendMessage (hChildWindow, WM_COMMAND, RUNSCAN, (long)&SpectrumParam);

UPDATE - Update the spectrum analysis and display parameters.  UPDATE is sent as a WM_COMMAND message with the address of a SPECTRUMPARAM structure contained in the lParam variable.

SendMessage (hChildWindow, WM_COMMAND, UPDATE, (long)&SpectrumParam);

GETSPECTRUM - Request a spectrum measurement.  GETSPECTRUM is sent as a WM_COMMAND message with the handle of the window that is to receive the measurement contained in the lparam variable.

SendMessage (hChildWindow, WM_COMMAND, GETSPECTRUM, (long)hWindow);

STOPSCAN - Stop spectrum analysis and display of audio data and freeze the display.   STOPSCAN is sent as a WM_COMMAND message.

SendMessage (hChildWindow, WM_COMMAND, STOPSCAN,  0L);

The child window will return a WM_AUDIOFREE message to the application (parent) window to indicate that audio input has been terminated (see WM_AUDIOFREE below).

CLOSESCAN - Stop spectrum analysis and display of audio data and freeze the display.

SendMessage (hChildWindow, WM_COMMAND, CLOSESCAN,  0L);

The child window will return a WM_AUDIOFREE message to the application (parent) window to indicate that audio input has been terminated (see WM_AUDIOFREE below).

MESSAGES TO APPLICATION (PARENT) WINDOW FROM CHILD SPECTROGRAM WINDOW

WM_READFREQ - The child spectrum window sends a WM_READFREQ message to the parent window when the user clicks the left mouse button over the spectrogram display.  The lParam variable of the WM_READFREQ message contains an audio frequency measurement.

WM_READSPECTRUM - The child spectrum window sends a WM_READSPECTRUM message in response to receipt of a GETSPECTRUM message from the parent window.  The WM_READSPECTRUM message is sent to the window specified in the original GETSPECTRUM message.   The lParam variable of the WM_READSPECTRUM message contains the handle of a global memory block.  Locking this memory block gives you the starting address of a sequence of short integers representing the Decibel (dB) output of the frequency analysis.  The length of the sequence is N/2 where N is the FFT size used in frequency analysis.  The center frequency represented by each of these points is (F/N)*(Count+1/2) where F is sampling rate and Count is the sequence number of the sample (Count ranges from 0 to N/2-1).  It is up to you not to read sequence values beyond N/2.  It is also your responsibility to free the sequence global memory block when it is no longer needed.

WM_AUDIOFREE - The child spectrum window sends a WM_AUDIOFREE message to the parent window when the audio processing from the sound card has been terminated.  This is usually in response to a STOPSCAN or CLOSESCAN message sent from the parent window (see above).  If the lParam variable of the WM_AUDIOFREE message is equal to 0, audio processing has been terminated, but the child spectrum window still exists and can receive additional messages.  If the lParam variable of the WM_AUDIOFREE message is equal to 1, audio processing has been terminated, and the child spectrum window has been closed down and cannot receive further messages.  To restart the spectrum display in this case will first require creation of a new child spectrum window using the dll SpectrumWindow function.

IMPORTANT NOTE:  The application (parent) window must not be closed before audio processing has been terminated.  Before closing the application window, send either a STOPSCAN or CLOSESCAN message to the child spectrum window.  Then wait for the WM_AUDIOFREE return message before closing the application window.  Also, note that the sound card cannot be used for any other purpose while audio processing by the child spectrum window is in process.  If the sound card is needed for another purpose, send either a STOPSCAN or CLOSESCAN message and wait for WM_AUDIOFREE before using the sound card elsewhere.

EXAMPLE PROGRAM

The following files make up a programming example showing the intended use of spectrum.dll.

spectrum.dll	dynamic link library

spectrum.h	C header file with structure and function definitions

spectrum.lib	C library file with function calling specifications

SpectrumWindow.c	main source code file for example program

resource.h and Script1.rc	C header and resource files for SpectrumWindow.c

SpectrumWindow.exe	example program

SpectrumWindow.exe is an example program illustrating the use of spectrum.dll to create and control a scrolling spectrum display from audio input to your sound card.  SpectrumWindow.exe first opens a full screen application window and then provides a control panel for selection of spectrum processing and display parameters.  Pressing “Start” will use spectrum.dll to launch a child window with scrolling spectrogram display.  Processing and display parameters can be changed on the fly by typing in new values and then pressing “Modify.”

TO COMPILE AND LINK:

SpectrumWindow.c is the source code illustrating use of spectrum.dll.  To compile and link this program with MS Visual C++, first create a new Project for a win32 application with a name such as “SpectrumWindow.”  This will create a directory within DevStudio\MyProjects named “SpectrumWindow.”  Copy all of the above files except SpectrumWindow.exe into this directory.

Now return to MS Visual C++ and open SpectrumWindow.c in the program editor.  Choose “Project - Add to Project - Files” from the main menu, and add SpectrumWindows.c and Script1.rc to the project.

Now tell the linker to link with spectrum.lib.  In Visual C++ 5.0, this is done by choosing “Project-Settings” from the main menu, selecting the “Link” tab, and typing “spectrum.lib” into the “Object/Libray Modules” text box.

Set the C/C++ calling conventions to “_stdcall.”  This setting can be found under Project Settings, C/C++ Code Generation, Calling Conventions in Visual C++ 5.0.

Now select “Build - Build SpectrumWindow.exe” from the main program to compile and link the code into the executable program.

CONDITIONS OF USE:

Spectrum.dll is copyright 1999 by Richard Horne and may be used only for private, non-commercial purposes.  Spectrum.dll is provided without warranty of any kind.  Use of spectrum.dll constitutes agreement with these conditions.