### 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`.