csf(5)

NAME
csf - polychannel music description file format

DESCRIPTION
The csf file format allows the design of musical scores to be played by sod2 (see sod2(1) for more). Before presenting a description of the format itself, bear in mind these points:

- Lines beginning with "#" are ignored, that is, they are comments. The "#" character must be at the beginning of the line.

- No line should be longer than 70 characters.

- In the following description of the format, each bullet point represents one line of text unless otherwise stated.

With that in mind, the definition is as follows:

- Optionally, one or more comment lines indicating the name of the track, the author, and distribution and copyright details. It would be nice if csf file authors could include this information, as well as a contact address if possible, be it email or postal mail.

- Optionally, a line of the form "*tempo N", where N is the tempo in beats (crotchets) per minute. The default tempo if one is not specified is 125 bpm.

- Optionally, a line of the form "*bsize N", where N is the size (in notespaces) to be used in the 'blocks' section when defining patterns. This number must be at least one, and at most 64. The default pattern size if one is not specified is 64 notespaces.

- The line "*samples".

- One or more lines of the form "samplefile samplerate", where samplefile is the name of a raw sample file to use for this voice number, and samplerate is the sample rate used by the sample file. If the samplefile ends in the text ".ami", it is assumed to be signed, otherwise it is assumed to be unsigned. The samplefile must use 8-bit samples. The voice number mentioned above is implied by the position of the line; the first line after "*samples" defines voice number 1, the second line defines voice number 2, and so on.

- The line "*blocklist".

- One or more lines of the form "A,B,C,...". That is, a comma separated list of pattern numbers to be played, simultaneously, at this point in the score. The first line of patterns gets played first, then the second, etc. The track ends at the end of the last pattern or at the end of the last note played, whichever comes later.

- The line "*blocks".

- One or more 'patterns' as described below. Everything after "*blocks", up to the end of the file, is regarded as a pattern definition.

A minimal pattern is represented by three lines.

The first line specifies the note (within the octave) to be played at each notespace. Characters on this line represent successive notespaces. What happens at a certain notespace is defined by the character present in the corresponding position on the line, as follows: Lowercase letters from 'c', 'd', 'e', 'f', 'g', 'a' and 'b' are natural ('white') notes. Uppercase letters from 'C', 'D', 'F', 'G' and 'A' are sharp ('black') notes. A space is a rest, so no new notes start, but any 'old' notes will continue to play. No other characters should be used. The line must be no longer than the pattern size being used. The line may be shorter, however; undefined characters after the end-of-line are assumed to be spaces (rests).

The second line specifies the octave of the note to be played, in a similar way. Octaves are numbered from 0 to 9, and the corresponding characters in the range '0'...'9' are used to indicate this. Octave numbers need not be given where a rest is present; a space can be used instead, or indeed any printable character.

The third line specifies the voice number (the sample) to be used when playing the note defined at the notespace. This can be done in a similar way as for specifying the octave, or a single voice number can be specified (as the first character on the line) which then is used for all notespaces. Voice numbers greater than 9 are specified by using lowercase letters, so 'a' is number 10, 'b' is 11, etc. An overall volume for the pattern can optionally be set by adding, after a comma, a number specifying the percentage of the original sample's volume to play the notes at. The default if none is specified is 35.

Optionally, one or more 'mode' lines can be added, before these three lines. These set various flags and parameters for the pattern as a whole. The possible mode lines are:

- "*p", which specifies 'piano' note mode. When a new note is started, any currently playing notes in the pattern which are the same note and octave are stopped. This is generally what you want, and this is the default.

- "*m", which specifies 'multi' note mode. Notes are never stopped until they finish. You may want this for some drum tracks, for example a combined bass drum and snare pattern can benefit from this.

- "*r", which specifies 'retrigger' note mode. When a new note is started, any currently playing notes in the pattern are stopped. You should not use this mode if possible, as better results are almost always possible with a combination of piano or multi mode and enveloping.

- "*e S,R", which specifies the envelope to use on the voice. 'After' the note has been resampled to the appropriate speed to play the note, this envelope is applied to it. The S value specifies the 'sustain' time, where the volume is not affected. The R value specifies the 'release' time, where a gradual fade to zero volume takes place. Both values are specified in eighth's of a notespace.

- "*v", which indicates volume changes at notespace resolution. There should be a line following this, similar to the octave line, which specifies the relative volume of notespaces from '0'...'9'. '0' means no note gets played at all, and '9' means the overall volume is used.

At first reading, this probably all appears very confusing. It's best to look at the example files provided, and create your own csf files using them as a guide. Experimenting is also a good way to find out how things work.

TIPS
While a true echo (or reverb) is pretty tedious to do in a csf file, you can use the cheap trick of just copying a pattern and shifting a character or two from the end of each line to the beginning, and reducing the volume this copy plays at. This gives a reasonable echo effect most of the time, and the 'overhang' when it starts and stops often isn't very noticeable.

One nice feature in csf files is that the samples for voices can be defined as being at any rate, even if they weren't sampled at that rate. Having the same sample file loaded as different voices at very slightly different sample rates, then playing the same note at the same time with the two voices, can create some interesting phasing effects.

You should always use enveloping, to hide the way the samples get longer with lower notes and shorter with higher notes.

If you have problems with clicking, you probably have a envelope which is too 'loose'. Try using the '-c' option to sod2 to track down which pattern has the clicking notes. You could just try to fix the sample itself, but this is usually a lot harder.

BUGS
Given the current definition of retrigger mode, notes played in the last notespace carry on to the end because no more notes of that pattern are played. This is generally not what you'd want, but it's tricky to fix properly. Then again, retrigger mode isn't generally what you'd want anyway. :-)

There is no "magic number". This is because I feel uncomfortable using magic numbers in files designed to be created by humans using text editors.

SEE ALSO
sod2(1)

AUTHOR
Russell Marks (mr216@gre.ac.uk).