Merge branch 'master' of github.com:ThanosApollo/config

1 files changed, 184 insertions, 0 deletions

diff --git a/.moc/moc/README_equalizer b/.moc/moc/README_equalizer
new file mode 100644
index 0000000..3c78cc8
--- /dev/null
+++ b/.moc/moc/README_equalizer
@@ -0,0 +1,184 @@
+Preamble
+---
+This document is meant to give you an overview on the idea of having a
+parametric equalizer for sound enhancement and how you can create your
+own presets.  Also the interaction with the equalizer in MOC is described.
+
+I would like to improve this document to make it more usable; so if you
+have any comments and/or ideas feel free to contact me.
+
+- Hendrik Iben (hiben<at>tzi(dot)de)
+
+
+Content
+---
+0. Document History
+1. Motivation
+2. Usage
+3. Preset Format
+4. Creating Presets
+5. TODO
+6. References
+
+
+0. Document History
+---
+07.09.2008 - Initial version
+15.03.2011 - Reformatted
+
+
+1. Nuts and Bolts / Motivation for Implementing the Equalizer
+---
+The equalizer is an implementation of a biquadratic peaking equalizer
+filter looked up from the Audio EQ Cookbook[1].
+
+It happens to be a parametric equalizer and this means that, different
+from other equalizer implementations, the number of bands* is not fixed.
+When I started the idea of implementing the equalizer I looked around
+in the source of other audio playback software and found that a lot of
+them are recycling the code used by the famous XMMS[2] audio player.
+I also would have liked to recycle the code but I decided against it
+for two reasons:
+
+The first reason is that there is almost no documentation on the algorithm
+used.  Maybe the signal processing folks have fun finding out what makes
+this thing work but I was totally lost.  So I decided that I wanted to
+*know* what I am doing if I do it.
+
+As for the second reason, the code used by XMMS is totally optimized for
+integer arithmetic.  There is no problem with this in general but I had
+the goal of implementing something that was as accurate as I could and
+I wanted to use floating point arithmetic.
+
+So I am no signals processing guy, but I have -- I think -- a solid
+understanding of the matter.  I sat down and started to read about
+equalizing, audio processing and signal theory in general.  After some
+time I found a mathematical description and a C implementation of
+biquadratic filters in the Audio Cookbook.  I made an implementation of
+the XMMS equalizer and the biquadratic filter using Octave[3] to compare
+the outcome of both filters.  I was a bit surprised how different filters
+can be but in the end succeeded (?) in finding a quite good biquadratic
+filter set that would produce results not unlike the XMMS equalizer.
+
+Although I did not use the XMMS-code I think that people will be more
+happy to accept this equalizer if they can use their presets with it.
+There is some conversion needed, but it's a straightforward process.
+I converted all presets provided by XMMS into presets for this mixer.
+They should be available at [4].
+
+* A band is a chosen center frequency where a filter has most impact.
+  If you look at WinAmp / XMMS / Beep Media Player you will find that
+  they settled on a common set of 10 bands.
+
+
+2. Using the Equalizer
+---
+The default keys for the equalizer are:
+
+'e' - Refresh equalizer
+'E' - Toggle equalizer (on/off)
+'k' - Select next preset
+'K' - Select previous preset
+
+Each of these actions results in a message displayed in the message area.
+This message will be overridden by the next action.
+
+
+3. Preset Format
+---
+Presets for the equalizer are to be placed in a directory called 'eqsets'
+in MOC's home directory (e.g., $HOME/.moc/eqsets).  There is no convention
+for the filename, but it will serve as the name in the selection process.
+
+File format in pseudo EBNF:
+
+  EQSET
+  ((<CF> <BW> <AMP>)|(0 <PREAMP>))*
+
+  CF:     Center frequency (sane values are from ~20 to ~20000).
+  BW:     Bandwith in Octaves.  This defines how fast the bands
+          influence vanishes over the frequencies.
+  AMP:    Amplification factor (in dB) to apply to the band.
+  PREAMP: Specifies an amplification factor applied before equalizing.
+
+So a valid equalizer set would be:
+
+  # this is a comment
+  EQSET
+  # amplify audio by 1.4dB
+  0 1.4
+  # damp frequencies at 100Hz by -4dB, filter bandwidth 1.5 octaves
+  100   1.5 -4
+  # amplify frequencies at 4000Hz by 2dB, filter bandwidth 1.5 octaves
+  4000  1.5 2
+
+There is no order to stick to when specifying frequencies.
+
+
+4. Creating Your Own Presets
+---
+For a start you should have a look at the converted presets[4].  The
+bandwidths used in the conversion have been extracted by taking a look
+at the filters signal response (implementation and analysis in Octave).
+I tried to do this as accurately as possible but I don't know if I made
+a mistake.  They sound correct though... :-)
+
+You might note that there is never a positive amplification factor in
+the presets although there are in the original preset.  The reason for
+this is that I used the maximum amplification in the preset as zero
+amplification and adjusted the other values accordingly.
+
+In general, when creating a preset get used to the following idea: Do not
+amplify the frequencies you want but damp those that are of no interest.
+This has the same effect but avoids clipping and this equalizer type seems
+to be very prone to clipping.  Also be very careful with pre-amplifying
+the audio for the same reason.
+
+With that said, the next confusing thing is the bandwidth definition.
+Every band needs a defined bandwidth in octaves where the bandwidth
+defines where the filter's effect has been reduced by 3dB*.  This means
+that if you define a band at 1000Hz with a bandwidth of 1.5 octaves and
+an amplification of -10dB, at 353.6Hz** and at 2828.4Hz the amplification
+will be reduced to -7dB.
+
+If unsure, stay in between 1.0 and 2.0.  Just keep in mind that if two
+bands overlap you might get an undesired amplification.
+
+When designing presets, just save the preset and select it in MOC.  After
+each change press the refresh key (default 'e').  This will re-create the
+equalizer reflecting your changes.
+
+If your preset is not found, have a look at the output of MOC's server
+thread.  Parsing errors are emitted there.
+
+*  3dB is commonly used for bandwidth.  -3dB equals about 70.7% of
+   original amplification.
+** 353.6 =~ 1000*(2^-1.5), 2828.4 =~ 1000*(2^1.5)
+
+
+5. TODO
+---
+- The equalizer is currently not optimized in any way.
+
+- It converts all sound data into floating point values to perform the
+  equalization and converts them back afterwards.  A better approach
+  would be either to provide integer algorithms for equalization or to
+  leave the audio data in floating point format.
+
+- There is no sorting for the presets; their order is defined by reading
+  the directory content.
+
+- Maybe it would be nice to add a name to the preset different from the
+  filename.
+
+
+6. References
+---
+[1] Cookbook formulae for audio EQ biquad filter coefficients
+    http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt
+[2] X Multimedia System
+    http://www.xmms.org/
+[3] GNU Octave
+    http://www.gnu.org/software/octave/
+[4] Converted WinAmp / XMMS Equalizer sets
+    http://www.informatik.uni-bremen.de/~hiben/moc/eqsets.tar.gz