Pisoco Graphic Equalizer Files

/******************************************************************************
*    This file is part of Pisoco Equalizer.
* 
*    Copyright (C) 2013  Nicholas Othieno
*    Email: n_othien[at] alumni [dot]concordia [dot] ca
*
*    Pisoco Equalizer is free software: 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 3 of the License, or
*    (at your option) any later version.
*
*    Pisoco Equalizer 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 Pisoco Equalizer.  If not, see <http://www.gnu.org/licenses/>.
* 
* 
*******************************************************************************/ 
Introduction
------------
Pisoco Equalizer is a software that converts your Linux box (embedded or
PC) into a 6 band graphical equalizer. Pisoco Equalizer has been tested 
on Fedora 14, Ubuntu 12.04 LTS and Angstrom Linux (on the beagleboard XM).
It needs a few prerequisites to run:
1. ALSA, ALSA libraries and ALSA development files
2. QT4
3. GCC

To compile it
1. Go to the Pisoco Equalizer directory
2. Type ./compile.sh and press enter or,
3. Type "qmake" and press enter, then type "make" and press enter

Usage
-----
1. Connect an audio source (tablet, smartphone, computer etc) to the 
   line in or mic jack of your computer or embedded device. Play some
   music on your audio source.
2. Make sure that the mic/line in is unmuted on the machine that is 
   running Pisco Equalizer. The mic/line in volume should also be 
   raised to about 50%. This can be done in "alsamixer" for Fedora and
   Angstrom, and in "Sound Settings" in Ubuntu.
2. Ensure that the audio source is not at very high volume. This can cause
   clipping in Pisoco Equalizer which leads to clicking and popping sounds.
   30% to 50% volume for the audio source should be OK.
3. Ensure that speakers are connected to your line out/headphone jack or 
   that your linux box has internal speakers.
4. Navigate to the Pisoco Equalizer directory.
5. Type ./fixed_point_graphic_equalizer and press enter if in the terminal,
   or double-click on the file fixed_point_graphic_equalizer to run it if 
   in GUI.
6. Increase the volume on your linux box if the audio is faint or 
   inaudible.   

Things to note:
1. QT4 and GCC must be correctly set up with the correct environment 
   variables notabely QMAKESPEC and PATH.
2. For Fedora users, Pulseaudio must not be running.

Disabling pusleaudio in Fedora:

1. Go to /etc/pulse/client.conf and set autorespawn=no. Make sure to 
   uncomment the line if it is commented.

2. Rename /etc/asound.conf. For example:

3. mv /etc/asound.conf /etc/asound.conf.nick_backup

4. Then search for the running pulseaudio process using:

    ps -ef | grep pulse

5. Kill the pulseaudio process

    kill -9 <pulse process number>

For Developers
---------------
Pisoco Equalizer was written with the beagleboard XM in mind. Therefore 
the critical DSP code is all fixed-point to allow it to run on the 
TMS320C6x DSP chip. All other code is floating-point and is expected to 
run on the ARM GPP. In the Texas Instruments C6EZ tool, variables 
passed to a function running on the DSP must be allocated to a special
shared memory used by the ARM GPP and the DSP. This is done using malloc
which C6EZ converts to a special TI memory allocation call. Usage of 
many mallocs in Pisoco Equalizer is therefore not random :-).

Known Problems
--------------
1. In its current state, the equalizer has heavy CPU usage. Some
   optimization needs to be done in the execution loops and FIR loops.
2. Faint audio output due to scaling down of filter coefficients. The
   filter coefficients were scaled down to prevent clipping, but this 
   has the effect of making the audio output faint.