SVGAFFT(1)

NAME
svgafft - SVGAlib based discrete harmonic analyzer

SYNOPSIS
svgafft [-screen <screen num>] [-rate <sample rate>] [-size <sample size>] [-atten <attenuation>] [-vpos <vertical offset>] [-bands <# bands>] [-barwidth <width>] [-barsegheight <height>] [-barsegspace <height>] [-fg <vgacolor>] [-bg <vgacolor>] [-graphbg <vgacolor>] [-linecolor <vgacolor>] [-axescolor <vgacolor>] [-barcolor <vgacolor>] [-barclipcolor <vgacolor>] [-peakcolor <vgacolor>] [-peaklowlimit <value>] [-barmaxcolor <vgacolor>] [-labelint <value>] [-bartype <1-6>] [-logscale] [-logfreqscale] [-continuous] [-lowfreq <freq.>] [-highfreq <freq.>] [-medbarval <value>] [-medbarcolor <vgacolor>] [-highbarval <value>] [-highbarcolor <vgacolor>] [-xinterval <value>] [-yinterval <value>] [-distance <value>] [-fadesteps <value>] [-plottype <1-3>] [-rotx <value>] [-roty <value>] [-rotz <value>] [-transx <value>] [-transy <value>] [-transz <value>] [-notext] [-fullscreen] [-x1 <value>] [-y1 <value>] [-x2 <value>] [-y2 <value>] [-ofs8 <value>] [-ofs16 <value>] [-8bit] [-hwindow] -device <device>

DESCRIPTION
svgafft is a program which performs discrete harmonic analysis under Linux using the svgalib graphics library. In other words, when given a digital (discrete) signal, it will continuously perform Fourier analysis on multiple samples of the signal and then display the result graphically in a bar graph format. A sound card compatible with the Linux sound driver is required. Note that the quality of the analysis also depends on the quality of the sound card. Both 8-bit and 16-bit soundcards are supported. In a nutshell, Fourier analysis converts a function from the time-amplitude domain to the frequency-amplitude domain. It is the inverse of Fourier synthesis, and exists in both continuous and discrete forms. Due to the nature of the calculations, a math coprocessor is required and a 486DX or higher machine is needed for useful operation. Device compatibility is currently limited to sound cards which are compatible with Hannu's Linux sound driver, which supports a fairly decent range of sound cards. Also there isn't a mixer control built in to the program so to set the recording gain, input source, etc. you must currently use another program to do this. I use xmix under X windows to do this. If you are on a low-resource machine you could run X to set the input source and recording level then exit X.

USAGE & EXAMPLES
The following examples have been tried on a 486DX/2-66. I won't put in more examples until I get some feedback about performance on other machines. Also since the program is in an early stage of development, some of these examples may be obsolete in the future. Make sure that the man-page matches the version of svgafft you are using. If you don't have one or your machine is under a fair load, this program will be useless (HD access under IDE drives kills it). To exit the program hit the letter q, and to see a quick reference help screen hit the `?' key. The minimal amount of information svgafft needs to run is a device. It works with the Linux sound driver /dev/dsp, so to run it with defaults you could just type:

svgafft -device /dev/dsp This will start svgafft using defaults with a plain line graph display. When you first use svgafft and are using 16-bit mode, it is a good idea to do a zero calibration. To do this, run svgafft then hit the `c' key. You will see a message instructing you to set the input signal to a minimal level. This [ideally] means not to have anything connected to the microphone or line in. Then, svgafft will calculate an average value which you can either use or discard. Do this a few times and when you get consistent results, you can use this value on the command-line with the `-ofs16' option for 16-bit mode and `-ofs8' option for 8-bit mode (both values are kept separate). Once you find a good value you should always use this, since it reduces spectral distortion. The bar display class has a number of bar types which can be changed from the command-line using the bartype option or specified at runtime (see keyboard section). If you have a Sound Blaster Pro (not 16), you may find that it doesn't have very much frequency response over 10khz or so, even at a 44.1khz sample rate (at least mine doesn't). If it was on /dev/dsp1 you could lower the sampling rate while decreasing the sample size, since data is coming in slower; i.e.: svgafft -device /dev/dsp -rate 16000 This sets the device to /dev/dsp1, the sampling rate to 16000 which will give a frequency range of ~0-8khz. There is no auto-attenuation yet, so you may have to play around with the attenuation to get viewable results. Adjust the attenuation with the + and - keys at runtime then specify it as a command-line parameter later (-atten). Also note that the sampling rate can be changed during runtime with the `{' and `}' keys (these are curly brackets). Note that being a real-time program, results will vary greatly due to system load. Under heavy load or disk accesses you'll get pauses and whatnot. The defaults are setup for a 486DX/33 or higher (again tried only on a 486DX/2-66) at 22khz, with a 512 sample size and a value of 8192 for attenuation in 16-bit mode (or 8 in 8-bit mode). I have only been able to try this on my AD1848, SBPro and SB16ASP cards. I did have great trouble getting the Windows Sound System (AD1848) to work correctly in 16-bit mode, it doesn't seem to be sending 16-bit data. The SB16[ASP] works well however. Results will vary greatly depending on processor speed, sample rate and size. DMA buffering of the sound driver affects the performance at lower sample rates and it will probably slow down under ~10khz sample rate since data won't be getting in fast enough. To help compensate for this svgafft attempts to tell the Linux sound driver to reduce the DMA buffer. If you want a more continuous display, you may try the -continuous option to automatically configure the parameters for a full screen analysis (this needs a REAL fast machine for high resolutions--faster than mine ;-), this will work better with future display types like the line graph): svgafft -device /dev/dsp -continuous -size 2048 -ofs16 136 The -ofs16 value of 136 was determined using the zero calibration using the `c' key at runtime. If you are looking for more of a display you may also want to try the `-fullscreen' option which will expand the viewing are to the whole screen (without displaying any text) while keeping all user-interaction keys enabled. Depending on machine configuration, some of the display types will perform better than others. You should experiment with different settings, barwidths, # of bands and everything else to find the best configuration for your machine. Typing `svgafft --parms' will give a list of all default values.

CONFIGURATION FILES
There is another option you'll want to take advantage of if you use svgafft. While running the program, you can press the `s' key to save all of the non-default command-line options to a file. Then to start the program with these defaults, you can just say:

svgafft `cat <option file>` There are a number of included example files included in the example directory in the archive. To use them optimally, install the `analyze' script in the examples directory (which the normal installation should install) and set the environment variable DSPCONFIGS to the directory where the configurations are stored (make sure to append a /). Then, providing you have a configuration file called "mystereo1" (see examples dir), you could just type: analyze /dev/dsp aconfigfile or likewise for any of the example files. See the README in the example directory for more information. This is quite useful for using svgafft as a novelty.

RUNTIME CONFIGURATION
When svgafft is being run, there are real-time calibration and adjustment options available which are described here. The most economical thing to do would to figure out the parameters which work best on your machine and then create an alias to run the program, or use it in conjuction with the `analyze' script i.e. (bash example): alias analyzer1='analyzer /dev/dsp1 mystereo2 -rate 30000' or something similar. An example of an even better method of using the shell features in conjunction with svgafft is given in the description for the `s' key given below. Also note that a quick reference screen can be brought up anytime while svgafft is running by pressing the `?' key. Keyboard Options

?   This key displays a quick reference screen describing the keyboard bindings during svgafft execution.

x   The x key exits the program.

<space>
    The space bar clears the maximum bar color from the graph screen. If you don't want to see the maximum bar color, then you can set it to the background color, e.g. if the background color is 0 then you can specify `-barmaxcolor 0' on the command-line to "mask" it.

+,- The plus and minus keys adjust the attenuation value. The attenuation interval values for 8-bit and 16-bit modes differ due to the large variation in dynamic range.

[,] The left and right square brackets adjust the vertical position.

{,} The left and right curly brackets are used alter the sampling rate in increments of 2048hz during runtime.

j,k,J,K
    The j and k keys increment and decrement the lower frequency limit on the frequency scale. The J and K keys (capital letters) do the same for the upper frequency limit.

f   The f key flushes the signal. Useful when switching tasks, since the DMA buffer tends to fill up, causing a "racing" condition for a few seconds upon return.

p   The p key pauses the display. Press p or any other key to restart the display.

s   The s key causes svgafft to prompt the user for a filename to which all of the non-default command-line options will be written to. This is a nice feature which can be used to create multiple setups, i.e. if you write the current options to a file called `myoptions', you can then retrieve these options (an editable textfile) when running the program again with the [bash] command: svgafft `cat myoptions` Or you could use the `analyze' script and install the configuration in the directory specified by DSPCONFIGS and type: analyze /dev/dsp myoptions

b   The b key toggles between 16-bit and 8-bit sampling resolutions.

z   The z key sets the attenuation and vertical position to default values--not values from the command-line but defaults defined during compilation.

d   The d key resets everthing to the defaults specified at the command-line.

h   The h key toggles Hanning windowing on and off. A `w' will appear in the flags box in the upper-right corner of the screen if this option is selected. When this option is on, the frequency display will be slightly more defined, allowing a finer representation of the signal at the expense of some speed.

c   The c key will initiate auto zero-calibration. This is an important step which should definitely be applied when using 16-bit mode, 8-bit mode is much more forgiving. To use this, hit the key then follow the instructions. When you have an appropriate value you can specify this value on the command-line with either (or both) of the `-ofs16' and `-ofs8' options described below.

l   The l key will toggle between linear and logarithmic vertical scales. A `y' will appear in the flags box in the upper-right corner of the screen if logarithmic scaling is on.

;   The l key will toggle between linear and logarithmic frequency scales. An `x' will appear in the flags box in the upper-right corner of the screen if logarithmic frequency scaling is on. This helps to bring out the lower ranges in the frequency ranges.

y   This instantiates the line graph display object. This is the same as the command-line option of -plottype 1.

u   This instantiates the bar graph display object. This is the same as the command-line option of -plottype 2.

i   This instantiates the three-dimensional wireframe display object. This is the same as the command-line option of -plottype 3.

&,* These keys decrement or increment the x-interval when using the wireframe display class.

(,) These keys decrement or increment the y-interval when using the wireframe display class.

1,2,3,4,5,6
    These are used when the bar display is active. Pressing number keys 1 through 6 will change the type of display bars used.

1,2,3,4,5,6,7,8,9
    These are used when the three-dimensional display is active. They were chosen for use on the numeric keypad. 1, 2, and 3 keys will rotate the x axis in the negative direction, positive direction or reset to original value, respectively. This goes for 4, 5 & 6 with the y axis and 7, 8 & 9 with the z axis.

~,@,#,$
    These keys (see the order of the keys) select different screens. By default, these select different display resolutions. Higher resolutions will result in slower display, but usually the default of 640x480x256 works well. Note that below this resolution some information on the top of the screen is not displayed due to the lack of room.

OPTIONS
svgafft is almost completely command-line configurable. If no options are specified, defaults will be used (see descriptions for defaults) which work well on a 486DX/2-66 class machine.

-device <device>
    This selects a dsp device and is a required parameter. Usually this is /dev/dsp, but if you have a secondary device like /dev/dsp1 then you could use that as well.

-screen <screennumber>
    This selects a screen number to use. By default, the screen numbers are setup to use different resolutions all at 256 colors. If the screen mode you select is not supported by your card (or possibly by svgalib) you will get a quick exit followed by a message. The screen resolutions can also be changed during runtime, see above.

-rate <rate>
    This selects an alternate sampling rate. The frequency range shown will go from something just above zero to one-half the sampling rate. The default is 22050, which should give the 30-10khz range of human hearing, but this also depends on the quality of the sound card. Even though the current version only supports 8-bit samples, 16-bit cards operating in this mode usually give a better frequency response. On most 8-bit sound cards, a 16000 sample rate with a 512 sample buffer usually works better.

-size <size>
    This selects an alternate size for the sample buffer. Larger buffers give more accurate readings but are slower to transform. The default is 1024 bytes which should work well on 486DX/33s and higher for high sample rates. Sample rates around 44.1khz will probably look better on a very fast computer if a 1024 or even 2048 byte size is used. On a slower computer you could try smaller sizes such as 512 or even 256. If the `-continuous' option is specified, a 2048 byte or larger buffer is required due to the higher frequency resolution. Also, smaller sample buffers yield lower frequency resolution. This becomes quite important if you are zooming in on frequency ranges.

-8bit
    This option causes svgafft to startup in 8-bit mode. If you have a 16-bit card you can just hit the b key to toggle to this mode, but if you only have an 8-bit card you need to specify this option to initialize the card correctly. By default, this option is NOT enabled (default is 16-bit).

-atten <attenuation>
    This selects a value for attenuation. This is just a fudge factor to scale everything so the display fits on the screen. The default setting is 8192 for 16-bit mode and 8 for 8-bit mode. It can also be adjusted during runtime then later specified on the command-line.

-vpos <vertical offset>
    This selects a value for the vertical offset. It can be used to set a noise threshold and can be either negative or positive. The defaults value is 0. This can also be controlled from the keyboard with the left and right square brackets.

-bands <# bands>
    This selects the number of bands to display when using the bar display class. The selected number of bands selected will range in frequency from just above zero to one-half the sampling rate, and will be evenly distributed.

--help
    Displays program version information.

--parms
    Displays display parameters and their default values. The parameters displayed with this option are described below.

-barwidth <width>
    This selects the width of each bar graph on the display. The default value is 2.

-barsegheight <height>
    This selects the height of each bar segmented if segmented bars are enabled. The default value is 1.

-barsegspace <height>
    This selects the height of the space between each bar segment if segmented bars are enabled. The default value is 1.

-fg <vgacolor>
    This selects the foreground color as a byte value selection in the vga rgb palette.

-bg <vgacolor>
    This selects the background color as a byte value selection in the vga rgb palette.

-graphbg <vgacolor>
    This selects the background of the actual analyzer.

-linecolor <vgacolor>
    This selects the color of the line graph.

-axescolor <vgacolor>
    This selects the color of the axes.

-barcolor <vgacolor>
    This selects the color of the bar segments as a byte value selection in the vga rgb palette.

-barclipcolor <vgacolor>
    This selects the color of the segment which shows that the signal is going off the display. Note that it doesn't have to be really clipping, but just going above the screen. The value is a byte describing an entry in the vga rgb palette.

-peakcolor <vgacolor>
    This selects the color of the peak drop segment if segmented bars and peak drop is enabled (default). The color is a byte value pointing to an entry in the vga rgb palette.

-peaklowlimit <value>
    This selects a value in which the peak drop segment disappears. Below this segment value it will cease to exist.

-barmaxcolor <vgacolor>
    This selects a color for the background for the bar height max. Whenever the bar reaches a new max, when the bar goes back down this color is left. To remove this set this to the same as the background color. The color given is a byte value pointing to an entry in the vga rgb palette.

-labelcolor <vgacolor>
    This selects a color to be used for the frequency labels. The color is a byte value pointing to an entry in the vga rgb palette.

-labelint <value>
    This selects an interval value for the frequency label values. The higher the number of bands you will need to increase this from the default of 17.

-plottype<1-3>
    This selects which display class to instantiate. Currently the available types are the line graph, bar graph, and the three-dimensional wireframe graph, numbered one through three respectively.

-bartype <1-6>
    This selects the type of bar graph to use when using the bar graph display object. 1 is the base type, and 2-6 are currently other derived types. Any other value given is the same as 1 unless more derived types are added to the program. The bartype can be dynamically changed at runtime by pressing the associated number key. Runtime bar changing is only enabled if RUNTIME_BARCHANGE is defined during compilation.

Bar Types (and what they do)
    1. continuous bar graphs 2. segmented bar graphs, like an L.E.D. display 3. one-segment bar graph, like an L.E.D. display with only the top segment displayed. 4. segmented bar graph like 2 but with added
     falling peaks 5. one-segment bar graph like 3 but with falling peaks 6. one-segment bar graph which has trailing faders Options 4 & 5 & 6 are neat looking but more processor intensive and using 1 with a high number of bands is probably more useful. These are now changeable during runtime by pressing the numeric keys. The default bartype is 1.

-logscale
    This is a boolean toggle which when selected causes svgafft to use a logarithmic vertical scale instead of a linear one.

-logfreqscale
    This is a boolean toggle which when selected causes svgafft to use a logarithmic frequency scale instead of a linear one.

-continuous
    This boolean when present causes svgafft to automatically adjust parameters to fill the screen with the maximum number of bands. To use this options with the C fft routines, a sample buffer size of 2048 or over must be specified on the command-line since the output of the fft is 1/4 the size of the buffer.

-lowfreq
    This selects the lower limit for the displayed frequencies. Note that to smaller viewing ranges decreases frequency resolution. This can be adjusted at runtime with the j and k keys.

-highfreq
    This selects the upper limit for the displayed frequencies. Note that to smaller viewing ranges decreases frequency resolution. This can be adjusted at runtime with the J and K keys.

-medbarval<value>
    This selects the value, expressed as a percentage from 0 to 100 where the segmented bar range becomes the medbarcolor (see below).

-medbarcolor<vgacolor>
    This is the color for the range above the level selected with medbarval. The color is a byte value for the vga palette.

-highbarval<value>
    This is the upper value used to display the highbarcolor (see below). It is expressed as a percentage factor from 0 to 100 of the height of the display.

-higbarcolor<vgacolor>
    The color used for the upper bar segments above the value given in highbarval. It is a byte value which points to an entry in the vga palette.

-distance
    Specifies user distance for the three-dimensional display class.

-rotx<value>-roty<value>-rotz<value>
    Specifies rotational value for three-dimensional display class.

-transx<value>-transy<value>-transz<value>
    Specifies translational value for three-dimensional display class.

-noperspective
    This boolean when present disables perspective in the three-dimeionsional class.

-xinterval<value>
    Specifies the x interval for each wire in the wireframe display class.

-yinterval<value>
    Specifies the y interval for each wire in the wireframe display class.

-notext
    This boolean when present disables all screen text.

-fullscreen
    This boolean when present causes svgafft to adjust the x1, y1, x2, y2 parameters to fill the screen. This options automatically enables the -notext options as well.

-hwindow
    This option turns Hanning windowing on. This generates something akin to a "smoothing" effect on the spectrum and makes frequencies more defined at the expense of speed. This needs work.

[-ofs16|-ofs8]<value>
    These options specify a the zero setting of the soundcard. For 16-bit cards this should be used; 8-bit cards are more forgiving. An easy way to determine the value for your card is to select the correct mode (16 or 8-bit) during runtime and hitting the c key which will prompt you with instructions. Once a value is obtained you can run the program with this value on the command-line. Values for both 8-bit and 16-bit modes can be specified, such as: `-ofs16 125 -ofs8 2'.

[-x1|-y1|-x2|-y2]<value>
    These options override the bargraph-window size specifications. These aren't really useful except for maybe curiosity and some debugging, so there.

BUGS
Surprise, surprise, but do not use this program as any type of replacement yet--the frequency accuracy is not yet due to a lack of equipment which will eventually change, but an announcement will be made when things are working more reliably.

SEE ALSO
analyze(1)

AUTHOR
Andrew Veliath
drewvel@eideti.com
Last update: 5/2/95 This manpage documents version 0.2c of svgafft.