Basic types and functions.

WARNING (for Csound users): the maximum amplitude is 1.0. There is no way to alter it. Don't define your amplitudes with 9000 or 11000. But the good news are: all signals are clipped by 1 so that you can not damage your ears and your speakers by a little typo.

We are going to make electronic music. But what is Csound? And why should we use it?

Csound is a domain specific programming language. It helps you to define synthesizers and make some music with them (http://www.csounds.com). Csound was born in 1985 (a bit older than Haskell) at MIT by Barry Vercoe. It's widely used in the academia. It has a long history. So with Csound we get a lot of music dsp-algorithms ready to be used. It's written in C. So it's very efficient. It's driven by text, so we can generate it. Csound's community is very friendly (what a coincidence!). Csound is very well documented.

You don't need to know Csound to use this library. but it's helpful to know the main features of the Csound: how can you create music with Csound in general, what design choices were made, basic features and quirks. Csound belongs to the MUSIC N family of programming languages. What does it mean? It means that description of the music is divided in two parts:

1. Orchestra. User defines instruments
2. Scores. User triggers instruments with a list of notes

An instrument is something that listens to notes and converts them to signals. Note is a tuple: (instrument name, start time, duration, parameters). Parameters cell is a tuple of primitive types: numbers (D), strings (Str) and tables or arrays of numbers (Csound.Tab).

Scores are very simple yet powerful. Csound handles polyphony for you. If you trigger several notes at the same time on the same instrument you get three instances of the same instrument running in parallel. It's very cool feature (not so easy thing to do with Pd).

But main strength lies in the Orchestra section. Here you can define the timbres for your musical journey. Csound is mostly for making strange sounds. How you can do it? You do it with instruments. An instrument is a sequence of statements that define a flow-graph for your sound waves. For an instrument you can use predefined sound generators and transformers (Csound.Opcode and Csound.Air).

Score/Orchestra division stays in this library too. You define your instruments of the type

 (Arg a, Out b) => a -> b

An instrument is something that converts arguments-like things (tuple of primitive values) to output-like things (tuple of signals).

When you are done with the orchestra section you can trigger the instruments with the function sco

 sco :: (Arg a, Out b, CsdSco f) => (a -> b) -> f a -> f (Mix (NoSE b))

It takes an instrument and the bunch of notes for this instrument. Bunch of notes is represented with f-container. It's parametrized with note type. f belongs to the type class CsdSco. This library lets you use your own representation of scores. The default one is CsdEventList. It is close to the Csound native representation of the scores (so it is not very convinient to use it). You can use a package temporal-csound as an alternative.

The output looks scary but let's try to understand it by bits:

• CsdSco f => f a - you can think of it as a container of some values of type a (every value of type a starts at some time and lasts for some time in seconds)
• Mix a - is an output of Csound instrument it can be one or several signals (Sig or CsdTuple).
• NoSE a - it's a tricky part of the output. NoSE means literaly 'no SE'. It tells to the type checker that it can skip the SE wrapper from the type a so that SE a becomes just a or SE (a, SE b, c) becomes (a, b, c). Why should it be? I need SE to deduce the order of the opcodes that have side effects. I need it within one instrument. But when instrument is rendered I no longer need SE type. So NoSE lets me drop it from the output type.

If you got used to Csound you can ask -- where is the instrument name in the score? No need to worry about names they are generated automatically.

In Csound to apply some effect one must use the global variables. There are some instruments that produce signals and write them to the global variables and there is an instrument that functions as mixer. It's turned on for the whole piece and it reads the global variables and applies the effects to the sound and finally writes it to the file or to the speakers. In this library it's very easy to apply an effect to the outputs of the instruments. There is a function mix:

 mix :: (Out a, Out b, CsdSco f) => (a -> b) -> f (Mix a) -> f (Mix (NoSE a))

Looks like the function sco. But now the first argument is an effect. It takes not a note but a signal (or a tuple of signals) and gives back some signal. The second argument holds the sound that we'd like to apply the effect to. With this function we can apply reverb or adjust the gain levels or apply some envelope, any valid csound transformation will do.

Music is defined in two parts. They are Orchestra and Scores. But there is a third one. It's used to set the global settings like sample rate or control rate values (block size). In this library you can set the initial values with CsdOptions.

Csound has made a revolution in electronic music technology. It introduced two types of signals. They are audio rate and control rate signals. The audio rate signals is what we hear and control rate signals is what changes the parameters of sound. Control rate is smaller then audio rate. It speeds up performance dramatically. Let's look at one of the sound units (they are called opcodes)

 ares buthp asig, kfreq [, iskip]

It's a butterworth high pass filter as it defined in the Csound. a-sig - means sig at audio rate. k-freq means freq at control rate (for historical reasons it is k not c). iskip means skip at i-rate. i-rate means init time rate. It is when an instruments instance is initialized to play a note. i-rate values stays the same for the whole note. So we can see that signal is filtered at audio rate but the center frequency of the filter changes at the control rate. In this library I've merged the two types together (Sig). If you plug a signal into kfreq we can infer that you want this signal to be control rate. In Csound some opcodes exist go in pairs. One that produces audio signals and one that produces control rate signals. By default if there is no constraint for the signal it is rendered at the audio rate except for those units that produce sound envelopes (like linseg).

You can change this behaviour with functions ar and kr. They set the signal-like things to audio or control rate. For instance if you want your envelope to run at control rate, write:

 env = ar $ linseg [0, idur/2, 1, idur/2, 0]

For speed table size should be the power of two or power of two plus one (all tables for oscillators). In this library you can specify the relative size (see CsdOptions). I've tried to hide the size definition to make sings easier.

You'd better get acquainted with Csound docs. Docs are very good. How to read them? For instance you want to use an oscillator with cubic interpolation so you dig into the Csound.Opcode.Basic and find the function:

 oscil3 :: Sig -> Sig -> Tab -> Sig

From Hackage we can guess that it takes two signals and table and returns a signal. It's a clue but a vogue one. Let's read along, in the docs you can see a short description (taken from Csound docs):

 oscil3 reads table ifn sequentially and repeatedly at a frequency xcps. 
 The amplitude is scaled by xamp. Cubic interpolation is applied for table look up from internal phase values. 

and here is the Csound types (the most useful part of it)

 ares oscil3 xamp, xcps, ifn [, iphs]
 kres oscil3 kamp, kcps, ifn [, iphs]

We see a two versions of the opcode. For audio and control rate signals. By default first is rendered if we don't plug it in something that expects control rates. It's all about rates, but what can we find out about the arguments?

First letter signifies the type of the argument and the rest is the name. We can see that first signal is amp with x rate. and the second one is cps with x rate. We can guess that amp is the amplitude and cps is cycles per second. This unit reads the table with given amplitude (it is a signal) and frequency (it is a signal too). Or we can just read about it in the docs if we follow the link that comes at the very last line in the comments:

• doc: http://www.csounds.com/manual/html/oscil3.html

I've said about a-, k- and i-rates. But what is the x-rate? Is it about X-files or something? X means a-rate or k-rate. You can use both of them for this argument. Let's go through all types that you can find:

• asig -- audio rate (Sig)
• ksig -- control rate (Sig)
• xsig -- audio or control rate (Sig)
• inum -- constant number (D)
• ifn -- table (Tab). They are called functional tables in Csound.
• Sfile -- string, probably a file name (Str)
• fsrc -- spectrum (Spec). Yes, you can mess with sound in the space domain.

Often you will see the auxiliary arguments, user can skip them in Csound. So we can do it in Haskell too. But what if we want to supply them? We can use the function withInits for this purpose.

You can find many examples at:

• A translation of the Amsterdam catalog of Csound computer instruments: https://github.com/anton-k/amsterdam
• Csound expression Tutorial at (TODO).

Got interested in Csound? Csound is very well documented. There are good tutorials, read about it at:

• Reference manual: http://www.csounds.com/manual/html/index.html
• Floss tutorials: http://en.flossmanuals.net/csound/
• Amsterdam catalog of Csound computer instruments: http://www.codemist.co.uk/AmsterdamCatalog/
• Lots of wonderful real-time examples by Iain McCurdy: http://iainmccurdy.org/csound.html
• Outdated but short manual on Csound http://cara.gsu.edu/courses/csound_users_seminar/csound/3.46/CsIntro.html

A constant value doesn't change while instrument is playing a note. Only constants can be passed as arguments to the instruments.

In Csound tables can be treated as primitive values. They can be passed to instruments in the score events. There are limited set of functions which you can use to make new tables. Look at the following module for details:

Signals can be audio or control rate. Rate is derived from the code. If there are rate-collisions, values will be converted to the right rates. For example, if you are trying to apply an opcode that expects control rate signal to some audio rate signal, the signal will be downsampled behind the scenes.

Use functions from the module Data.Boolean to make boolean expressions.

Let's make some noise. Sound is build from list of tracks (SigOut).

We can define an instrument and tell it to play some notes.

We can define a midi-instrument. Then we can trigger the instrument with a midi-keyboard. Msg, midi, pgmidi,

Now we are ready to create a csound-file. The function renderCsd creates a String that contains the description of our music. We can save it to a file and compile it with our csound wizard.

Handy short-cuts for function playCsd.

Handy short-cuts for function playCsd.

TODO (you can send me your definitions)

Handy short-cuts for function playCsd.

TODO (you can send me your definitions)

Some colors to paint our soundscapes.

Frequently used combinations of opcodes.

We can set some csound options.

Handy short-cuts for function playCsdBy.

Handy short-cuts for function playCsd.

TODO (you can send me your definitions)

Handy short-cuts for function playCsd.

TODO (you can send me your definitions)