A simple granulation actor
The granulator actor suite (granActor, granHand, granAlg) provides a simple granulation algorithm. Like the sample actor, it is not a good example for developing actors in the vss framework, because it requires some special handling that is not general to vss generators and algorithms, and generally does not follow the actor/handler protocol.
The principal parameters of the sample playback engine are the base directory (where it looks for sample files; relative paths are relative to the vss launch directory), the filename (names with path are relative to the base directory, unless they begin with "/"), and the position in the sample file from which a grain is taken.
The granulation algorithm loads the entire source file's sample data into memory, so one should use as few as possible, and delete them when they are no longer needed.
To use the granulation actor, load gran.so and create an actor of type Granulator.
Granulator messages
In addition to the messages understood by all generator actors, the Granulator understands the following messages:
- SetDirectory hActor "dir"
- Set the default base directory for new instances created by this actor to dir.
dir must be double-quoted as shown.
- SetAllDirectory hActor dir
- Set the base directory of all children to dir, and set the default base directory for all future children.
- LoadFile hActor "filename"
- Load this soundfile into memory for quick future access. filename must be double-quoted as shown.
- UnloadFile hActor "filename"
- Free the memory used to store this soundfile. filename must be double-quoted as shown.
- UnloadAllFiles hActor
- Free the memory used to store all soundfiles.
- SetDur hActor duration
- Set the duration of all future grains to duration seconds.
- SetPlaybackRate hActor r
- Set the default playback rate of all future grains to r.
The default rate upon actor creation is r=1.0 which
corresponds to playback at the normal rate (i.e. a rate of 2.0 plays back at
double speed). VSS always computes and plays out samples at its own set
sample rate; for sample files recorded at different rates, samples are
automatically interpolated to maintain a consistent perceived playback rate.
- SetStart hActor start
- Set the starting offset into the soundfile of all future grains to start (0 = start of file, 1 = end of file). If this is less than twice the duration of the grain's "slope" (see below), the grain's duration will be set to twice the duration of the slope.
- SetSlope hActor duration
- Set the length of the attack and release segments of all future grains to duration. If this exceeds half the grain's total duration, the grain's slope will be set to half the grain's total duration.
- SetControlMin hActor value
- Set the minimum value expected by SetDur and SetStart to value (range is 0 to 1). Defaults to 0.
- SetControlMax hActor value
- Set the maximum value expected by SetDur and SetStart to value (range is 0 to 1). Defaults to 0.
- SetJumpMin hActor value
- Set the minimum offset to start a grain at to value (range is 0 to 1). Defaults to 0.
- SetJumpMax hActor value
- Set the maximum offset to start a grain at to value (range is 0 to 1). Defaults to 1.
- Rebound hActor value
- Set the amount to randomly adjust the offset of a grain by, when it would have started out of range (<0 or >1), to value (range is 0 to 1). Defaults to 1.
- Spread hActor value
- Set the range (+/-) to randomly adjust the offset of a grain by, to value (range is 0 to 1). Defaults to 0.05.
Nonzero values result in a less tedious sound at times when the starting point doesn't explicitly change.
Note that BeginSound plays only a single grain, not a stream of grains.
Granulator handler messages
In addition to the messages understood by all handlers, the handler for the Granulator algorithm understands the following messages:
- SetDirectory hSound "dir"
- Set the base directory to dir.
dir must be double-quoted as shown.
- SetFile hSound "filename"
- Load the sample file fileName and initialize
playback. Starting position, duration, and slope are copied
from the Granulator actor during this message. filename
must be double-quoted as shown.
- SetStart hSound value
- Set the default starting offset for grains to value.
- Spread hSound value
- Set the default spread for grains to value.
- Rebound hSound value
- Set the default rebound for grains to value.
- SetSlope hSound value
- Set the default slope for grains to value.
- SetDur hSound value
- Set the default duration for grains to value.