Items in scripts are separated by newlines and a script may need to
end with a newline. Empty lines are legal. Lines beginning with a
semicolon are considered comments and are ignored. If a line begins
with a tab character then it is considered the continuation of the
previous line: for instance
0.0 /tmp/snd.aiff from <0,10,1>
to <3,4,5>
volume 50
All times in scripts are given in beats. The default tempo is 60bpm,
so if the tempo is not set then a beat is a second so all times are
also in seconds. The tempo can be set by an instruction like
tempo 90
The above would set the tempo to 90bpm for subsequent items in the script. Tempo instructions should normally go at the top of the file: changing the script changes the interpretation of all times following the tempo line, but not before, and changes all beat references with respect to time 0, so that if a sound was to happen at beat 1 and a second sound was to happen on beat 2, then if there is a trebling in tempo in between, the second sound will actually happen first. If this makes no sense, only use one tempo and put it at the top of the file and don't worry about it!
The listener is considered to be at (0,0,0). X is considered to be positive ahead, negative behind. Y is considered to be positive to the left, negative to the right. If a graph with X and Y axes is drawn in the usual way, this places the listener facing to the right on the page. Z is considered positive upwards, negative downwards. I know this isn't the way everyone would have it (myself included,) but it's things have been done historically with Ambisonics and its the way this program works. It is possible to change the listener's angle (see 'listenerangle.')
Note that as a room model is in use the dimensions of the room have a bearing on the use of coordinates (it is best to stay within the room.) See 'room characteristics' below.
Units are metres.
This, after all, is what it's all about. The standard format is:
<time> <soundfile> <whereabouts> [<other qualifiers>]
The time is interpreted as a beat as described above. The soundfile will be played at the time specified. If not otherwise qualified the sound will be played from beginning to end. Input soundfiles must be mono (however see 'Mixing' below.)
Following the time and name of the soundfile to play come various
qualifiers. Among these there must be a whereabouts for the
sound. There are three forms for the whereabouts, one using a fixed
location, one moving steadily from one location to another and one
which defines motion in an arbitrary circle. The syntax for these
three forms is:
at (<x>,<y>,<z>)
from (<x1>,<y1>,<z1>)
to (<x2>,<y2>,<z2>)
rotate around (<x1>,<y1>,<z1>)
offset (<x2>,<y2>,<z2>)
axis (<x3>,<y3>,<z3>)
In the above, the round brackets are not optional although angle brackets may be used instead. When choosing locations bear in mind the room dimensions in use.
0.0 /tmp/a.wav at (2,0,0)
This plays the sound /tmp/a.wav at the beginning of the piece, directly ahead of the listener.
1.0 /tmp/a.wav from (1,-4,1) to (1,4,1)
The above will play the sound /tmp/a.wav one beat into the piece, and move the sound from a point on the right and move it over to the left. The sound will pass by slightly ahead and above.
where
Note that centre is in fact not the centre of the circle if offset and axis are not orthogonal.
(x1,y1,z1) is the centre point used to locate the rotation. For rotation directly around the listener the origin would be used here. (x2,y2,z2) defines the vector from the centre point that the sound starts, so the sound actually starts at coordinate (x1+x2,y1+y2,z1+z2). The direction of the 'axis' vector (x3,y3,z3) is used like the axis of a wheel to define the direction of the rotation, and should be at right angles to (x2,y2,z2). If it is not then the sound will be moved slightly off centre along the line of the axis vector. Only the direction and not the size of the axis vector is important. Changing the sign of the axis vector will change between 'clockwise' and 'anticlockwise' rotation. The sound naturally rotates at one cycle per beat. This can be changed with the 'cycle' setting below.
2.0 /tmp/a.wav rotate around (3,0,0)
offset (0,-1,0)
axis (0,0,1)
This rotates the sound, centred three units ahead of the listener, starting to the right of the centre and rotating in the horizontal plane (as there is a vertical axis.)
Other qualifiers available are:
from <beat>
to <beat>
volume <gain>
cycle <beats>
The first two of these make the system play only an extract from the mono input soundfile. The third effects the gain of the sound when output. Large gains (10+) are often necessary when sounds are placed a long way from the listener but may slow the system up. The 'cycle' qualifier only applies to the rotating sound, and decides how many beats it takes for a complete rotation.
2.0 /tmp/a.wav at (4,1,1) from 0.3 to 0.7 volume 50
Two beats into the piece, this plays part of the sound /tmp/a.wav. The sound is spatialised at the fixed point (4,1,1). The sound has a gain of 10 applied to it to make it louder, and only 0.4 beats of the sound is played, the part lying between 0.3 beats and 0.7 beats.
2.0 /tmp/a.wav rotate around (0,0,0)
offset (0,3,0)
axis (0,0,1)
cycle 8
This plays the same sound rotating around the listener starting two seconds into the piece. The sound rotates in the horizontal plane, three squares away starting directly to the left of the listener. It will take 8 beats for the rotation to go once around so the sound will return to (0,3,0) ten beats (2+8) into the piece.
Another spatialised soundfile can be insert into the current one using
a line of form
3.4 insert /tmp/space.wav
3.4 insert /tmp/space.wav volume 0.5
The inserted file must be of the same form as the output type for the system, ie mono when used with 'crude', stereo when 'fine' is set to stereo, and ambisonic when 'fine' is set to ambisonic. The volume setting is a gain applied direct to the signal. No room modelling, reverb etc is applied to a mixed sound.
Overall gain controls can be included in the file. These have form:
gain 1.2
Like 'tempo' instructions, these are active for all subsequent sounds so the normal place for a gain instruction will be the top of a script file. These instructions effects all sounds regardless of whether they are spatialised or inserted, and last until the gain changes again or the script ends. The default gain is 1.
There is a subtlety about the use of gain: using this gain control is not equivalent to increasing all 'volume' settings for sound. Setting volumes using clauses on sounds increases the number of reflections generated as more will be audible. This slows the system down. Setting the 'gain' control provided here has no such effect: it acts effectively as a general Csound volume control. See 'optref' and 'opttol' also in the optimisation section.
Like 'tempo' and 'gain' instructions this instruction applies to all
subsequent sounds in the script. By default the listener looks along
the X axis. This angle can be modified using
listenerangle <new angle>
This command applies to all subsequent sounds. Angles are in degrees
clockwise: for instance
listenerangle -90
Like 'tempo' and 'gain' instructions these instructions apply to all subsequent sounds in the script. If no room is defined then a default room is used. The room is a 'box' shape and the distance from the listener of each of the six surfaces making the box is set using
roomdim <back> <front> <left> <right> <ceiling> <floor>
The parameters given effectively define the coordinates that are
'within' the room. Placing sounds outside the room will produce
unpredictable results. The default room setting is
roomdim 10 10 10 10 4 1
Sound is reflected off walls. When this happens there is a 180degree
phase shift and some of the sound is absorbed into the wall. The level
of absorption can be set using
roomdamp <back> <front> <left> <right> <ceiling> <floor>
This sets the proportion of the signal that is reflected off each
surface, so 0 indicates total damping and 1 indicates complete
reflection. Setting dampings above 1 is probably a bad idea. The
default setting is
roomdamp 0.8 0.8 0.8 0.8 0.8 0.8 0.6
Use of high volume settings, small rooms and reflective surfaces can produce very large numbers of sound reflections. This can easily very slow processing. The number of reflections generated can be controlled by changing room and sound characteristics, using gain rather than volume (see above) and using the following two commands.
optref <reflection count>
This instruction limits the maximum number of reflections coming from a single positioned sound. The default is 10. Reflections with the highest level relative to the listener are chosen first.
opttol <signal strength>
This sets a tolerance: a signal strength is calculated for each signal reaching the listener's ear relative to the original sound material. If this strength is below the tolerance set here then the signal is discarded. The default value is 0.02.
Reverb tends to look after itself: it is fed from the initial and
reflected signals and so tends to take on some of the characteristics
of the room anyway. It is possible to apply a scalar to the reverb
level once in a script using
reverblevel <scalar>
Default value is 1. Changing the reverb characteristics further is probably best achieved by working with the reverb instruments defined within the library orchestras.
Fast fades in and out are applied to spatialised sounds at their
beginnings and ends when they are truncated using 'from' and 'to' with
times. Because of this, it should be possible to produce reasonably
clean joins between paths of sounds, allowing fairly continuous motion
in sections, eg
0.0 /tmp/a.wav from (4,1,1) to (-4,1,1)
to 0.455
0.455 /tmp/a.wav from (-4,1,1) to (-4,-4,1)
from 0.455 to 1.2