This module gives some introductory examples to signal processing with plain Haskell lists. For more complex examples see Synthesizer.Plain.Instrument and Synthesizer.Plain.Effect. The examples require a basic understanding of audio signal processing.

In the Haddock documentation you will only see the API.
In order to view the example code,
please use the "Source code" links beside the function documentation.
This requires however,
that the Haddock was executed with `hyperlink-source`

option.

Using plain lists is not very fast, particularly not fast enough for serious real-time applications. It is however the most flexible data structure, which you can also use without knowledge of low level programming. For real-time applications see Synthesizer.Generic.Tutorial.

# Documentation

Play a simple sine tone at 44100 sample rate and 16 bit.
These are the parameters used for compact disks.
The period of the tone is `2*pi*10`

.
Playing at sample rate 44100 Hz results in a tone of `44100 / (20*pi) Hz`

,
that is about `702 Hz`

.
This is simple enough to be performed in real-time,
at least on my machine.
For playback we use `SoX`

.

sineStereo :: IO ExitCodeSource

Now the same for a stereo signal.
Both stereo channels are slightly detuned
in order to achieve a stereophonic phasing effect.
In principle there is no limit of the number of channels,
but with more channels playback becomes difficult.
Many signal processes in our package
support any tuple and even nested tuples
using the notion of an algebraic `module`

(see `C`

).
A module is a vector space where the scalar numbers
do not need to support division.
A vector space is often also called a linear space,
because all we require of vectors is that they can be added and scaled
and these two operations fulfill some natural laws.

play :: T Double -> IO ExitCodeSource

For the following examples we will stick to monophonic sounds played at 44100 Hz. Thus we define a function for convenience.

oscillator :: IO ExitCodeSource

Now, let's repeat the `sine`

example in a higher level style.
We use the oscillator `static`

that does not allow any modulation.
We can however use any waveform.
The waveform is essentially a function
which maps from the phase to the displacement.
Functional programming proves to be very useful here,
since anonymous functions as waveforms are optimally supported by the language.
We can also expect, that in compiled form
the oscillator does not have to call back the waveform function
by an expensive explicit function call,
but that the compiler will inline both oscillator and waveform
such that the oscillator is turned into a simple loop
which handles both oscillation and waveform computation.

Using the oscillator with `sine`

also has the advantage
that we do not have to cope with `pi`

s any longer.
The frequency is given as ratio of the sample rate.
That is, `0.01`

at `44100 Hz`

sample rate means `441 Hz`

.
This way all frequencies are given in the low-level signal processing.

It is not optimal to handle frequencies this way, since all frequency values are bound to the sample rate. For overcoming this problem, see the high level routines using physical dimensions. For examples see Synthesizer.Dimensional.RateAmplitude.Demonstration.

It is very simple to switch to another waveform like a saw tooth wave. Instead of a sharp saw tooth, we use an extreme asymmetric triangle. This is a poor man's band-limiting approach that shall reduce aliasing at high oscillation frequencies. We should really work on band-limited oscillators, but this is hard in the general case.

When we apply a third power to each value of the saw tooths we get an oscillator with cubic polynomial functions as waveform. The distortion function applied to a saw wave can be used to turn every function on the interval [-1,1] into a waveform.

Now let's start with modulated tones. The first simple example is changing the degree of asymmetry according to a slow oscillator (LFO = low frequency oscillator).

The `ping`

sound can also be used
to modulate the phase another oscillator.
This is a well-known effect used excessively in FM synthesis,
that was introduced by the Yamaha DX-7 synthesizer.

filterSaw :: IO ExitCodeSource

One of the most impressive sounds effects is certainly frequency filtering,
especially when the filter parameters are modulated.
In this example we use a resonant lowpass
whose resonance frequency is controlled by a slow sine wave.
The frequency filters usually use internal filter parameters
that are not very intuitive to use directly.
Thus we apply a function (here `parameter`

)
in order to turn the intuitive parameters "resonance frequency" and "resonance"
(resonance frequency amplification while frequency zero is left unchanged)
into internal filter parameters.
We have not merged these two steps
since the computation of internal filter parameters
is more expensive then the filtering itself
and you may want to reduce the computation
by computing the internal filter parameters at a low sample rate
and interpolate them.
However, in the list implementation
this will not save you much time, if at all,
since the list operations are too expensive.

Now this is the example where my machine is no longer able to produce a constant audio stream in real-time. For tackling this problem, please continue with Synthesizer.Generic.Tutorial.