Panteltje xpequ-0.3.1 manual

xpequ is copyright (c) 2007-always Jan Panteltje and released under the GPL.

xwindows based equalizer and FFT display,
uses xforms library and headers, libmath, and libpthreads.
Equalizer and fft code taken from xine, slightly modified.
xpequ can read from a input wave file, correct the frequency response,
and write to an output wave file.                                     
For example you can use it to remove noise from old tapes.
It can also read from one dsp device and write to an other dsp device.
Or it can stream via sox.                                             
xpequ uses the OSS sound drivers.
There also is a voice level control that can be used to only output
when audio exceeds some preset level.                              
This can be used to record intermittent conversations or monitor lines,
while keeping file sizes small.                                       


Type
xpequ -h
for help and examples.

or
man xpequ


Xpequ is a simple audio processor.
It basically provides 3 processing functions, and 2 monitor functions:

The processing functions are:
1) 10 band equalizer.
2) VOX, this is voice level activated output, output is done only when the input signal exceeds a certain level.
3) AGC, this is auto gain control, the audio gain is automatically adjusted so it is always peaking at -3dB (70%).
 
The monitor functions are:
1) FFT display, amplitude versus frequency.
2) oscilloscope display, amplitude versus time. Use this to monitor for 'clipping', noise, hum, etc.

xpequ only supports 16 bits per sample at this moment.

Input and output:
Xpequ can use both the ALSA sound system for input and output, or the OSS sound system.

It can read from a hardware device, from stdin, or from a wave file.
It can output to a hardware device, to stdout, or to a wavefile.
When writing to stdout it is _not_ possible to write a wave file header, as the header is first (MS format), and what
goes in the header is not known yet (length) at the start of the recording.
In case the output is a wave, file the beginning of the wave file is modified when all has been written, so that is no problem.

The equalizer:
frequencies are indicated below the slider, you can switch off the equalizer with the 'eq' button, then it will disappear.
Because increasing amplitude of some frequencies may cause clipping, a slider 'equalizer gain' is provided, so you can
adjust the total output level.

The VOX:
When pressed the VOX button will light up yellow when the output level is lower then the level set by the threshold slider
situated just above it, when higher then this level the VOX button will light up green.
When the VOX button is pressed, then _only_ when the VOX button is green will there be any output!!
The 'on' reaction time of the VOX system is set by the 'on ms' slider, and the time there has to be a signal lower then
the threshold signal before audio is switched off again is set by the 'off ms' slider.
Pressing the 'x10' button  multiplies the range of the 'off ms' slider by 10x.
 
The AGC:
Pressing the AGC button will activate the AGC.
On start up, or when audio is enabled with the 'audio' button, the AGC system multiplies the output by a factor 1x.
When no signal exceeds -3dB (.7x max output) the multiplication factor will increase very fast (within a second) up until 50x,
until a signal of > 3dB is sensed.
When this happens the multiplication factor is adjusted downwards, so the output is exactly -3dB at that peak.
From this moment on the gain will increase very very slowly (over minutes) when there are no peaks higher then -3dB in the audio.
The result should be music or speech always at a peak level of -3dB not clipping, independent of the source recording,
almost ideal for digital audio.
When the AGC is in the fast startup mode the button will light up red, after that it will light up orange.


The FFT display:
You can switch between no display, oscilloscope, and FFT display, by repeatedly pressing the OFF/FFT/SCOPE button (right of bottom middle).
 When FFT is selected the button 'log' is visible.
 the FFT amplitude scale is always logarithmic.
 When the 'log' button is pressed the frequency scale also becomes logarithmic.
 FFT stands for fast Fourier Transform, a mathematical method used here to calculate the frequency components of a signal.
 The FFT works on 8192 bytes at the time.


The oscilloscope:
You can switch between no display, oscilloscope, and FFT display, by repeatedly pressing the OFF/FFT/SCOPE button (right of bottom middle).
All controls related to the oscilloscope display will become visible if OSC is selected.
Triggering:
 When the 'auto' button is selected, 2 values will be calculated from the peak maximum and minimum values of the signal, and
 a trigger level of 7/8 of the maximum signal, or 7/8 of the min signal if '-' trigger mode is selected with the +/- button, wil
 be set in case the trigger level slider is all the way to the right.
 With the trigger level slider all the way to the left the slice level will decrease to zero x, so it gives one control.
 If 'auto' is _not_ selected the trigger level slider just sets trigger th level from -1 to + 1, where -1 is bottom display,
 and +1 is top display.
Volts full scale:
 This display, together with the the 2 associated buttons next to it marked '+' and '-' sets the sensitivity of the display.
 There are 3 positions, 1.5V, .15V and 0.015V (the display only shows 0.1 due to its size) full screen.
Timebase:
 This display, together with the the 2 associated buttons next to it marked '+' and '-' set how many time units it takes
 for the trace to make it from left to right.
 A higher number is lower.
 Around 6 is a good setting to monitor audio.

'ALSA' / 'OSS' button:
 This button will select the interface for input and output to use the ALSA or OSS sound system.
 In newer versions of Linux ALSA is standard, in older versions OSS.

'input' button:
 In case OSS is selected this will sequence between /dev/dsp0, /dev/dsp1, /dev/dsp2, and /dev/dsp3.
 In case ALSA is selected this will sequence between
  hw:0,0, hw:0,1: hw:0,2, hw:0,3,
  hw:1,0, hw:1,1: hw:1,2, hw:1,3,
  hw:2,0, hw:2,1: hw:2,2, hw:2,3,
  hw:3,0, hw:3,1: hw:3,2, hw:3,3.
 If you have other device numbers you can, both in case of ALSA and OSS, use the -u command line option,
 for example: -u plughw:10,4, or -u /dev/dsp10

'output' button:
 In case OSS is selected this will sequence between /dev/dsp0, /dev/dsp1, /dev/dsp2, and /dev/dsp3.
 In case ALSA is selected this will sequence between
  hw:0,0, hw:0,1: hw:0,2, hw:0,3,
  hw:1,0, hw:1,1: hw:1,2, hw:1,3,
  hw:2,0, hw:2,1: hw:2,2, hw:2,3,
  hw:3,0, hw:3,1: hw:3,2, hw:3,3.
 If you have other device numbers you can, both in case of ALSA and OSS, use the -t command line option,
 for example: -t plughw:10,4, or -t /dev/dsp10

'audio' button:
 When the audio processing thread is running this button lights up green.
 You can stop outputting audio by pressing it, start audio by pressing it again.
 Note that changing audio input or output device will stop audio and then restart it.
 If you were recording to a wave file, pressing 'audio' to stop, and then to start again, will create a new wave file,
 and overwrite the old one.
 This can be used to start and stop recording to a wave file for a specific segment of the input, so start xpequ,
 stop audio, wait just before what you want to record, press 'audio', and when you have all you wanted to record, press
 'audio' again, the  it will close the wave file and write the correct header.
 Wave files are limited to 4GB in length, due to the MS 32 bit header format, however xpequ will keep writing data if the
 file is longer, and write the max 32 bit values to the wave header, as _some_ programs can read this.

Sample speed display:
A blue sample speed display is located left of the audio mode button.

Channels display:
A blue, or magenta (if mono), channel number display is located next to the sample speed display.

'E' button:
Pressing this button will stop audio, write a wave header if needed, and exit.


Notes:
When reading from one device, and writing to an other on a different sound card, you may get buffer overruns, or maybe even
under-runs reported, as when the clock oscillators of both cards are not exactly the same, if one cannot supply
data as fast as the other card can write it...... I guess, I have seen these overruns, xpequ will write warnings to stderr
if that happens.
Try writing to a file to avoid this.

Files:
~/.xpequ
~/.xpequ/xpequ.xpm                                  icon for iconify. 
~/.xpequ/sweep.wav.equalizer                        each wave file gets its own equalizer setting.										
~/.xpequ/your_love_is_my_blessing.wav.equalizer     each wave file gets its own equalizer setting.
~/.xpequ/-.equalizer                                and if piping via stdin, this one will be the settings for stdin.
~/.xpequ/setup/
~/.xpequ/setup/audio_settings                       all variables used, read on startup by xpequ standalone or as server.


When in client mode xpequ does _not_ write to the audio settings file, it identifies itself to the server by sensing 'xpequ -y',
then receives the server status as in ~/.xpequ/setup/audio_settings at the server side, thne anytime a button or slider is
actived sends the new status to the server.
When the server exits because of either EOF or exit button pressed, it will first ask the client to disconnect by sending
'xpequ client disconnect'.
This frees the socket immediately, preventing long wait times for the kernel to do it.
A disconnected client will try for a server every second.
A server will just accept _one_ xpequ -y at any one time.
A xpequ -x  server sends its status back to a xpequ -y client once per second.
If this gives problems with 'bouncing back buttons' in the client, then one can increase the time interval in the file
internet.c, where it says:
        /* not to fast, else in remote buttons bounce back due to status send back */
        timeout.tv_sec = 1;
and change the '1' to for example '2' or more, experiment.


end of text