### A sample-file playback actor

The sample actor suite (sampActor, sampHand, sampAlg) provides a simple means of controlling sample file playback. (The sample actor is not a good example for developing other actors, because it requires some special code and breaks several actor/handler conventions.)

Sample files are on the machine running vss (the server, not the client).<pp> Sample files must be in `aiff` or `wav` format. Other formats like .au or .aifc must first be converted to .aiff. On an SGI computer, one of these two commands will usually work:
`sfconvert inputfile outputfile.aiff format aiff
sfconvert inputfile outputfile.aiff format aiff int 16 2`
(Simply renaming `foo.wav` to `foo.aiff` won't work). Or you can use SGI's `soundfiler` application. On linux machines, `sox` converts file formats well.

AIFF files must be in 16-bit, not 8-bit, format; WAV files may be either 16 or 8-bit. 16-bit files generally sound much cleaner (less hiss and rumble); they are strongly preferred.

WAV files must be in conventional PCM format, not something funky like ADPCM or MULAW or G728_CELP.

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 "/"),
- the loop points (begin and end),
- the loop flag (if true, looping occurs),
- and, to a lesser degree, the bounding points (begin and end) for playback of a smaller segment from within the sample file.

The sample playback algorithm loads the entire sample data into memory, so be careful to load only the samples which you need, and delete them when they are no longer needed. Sound files can be quite large. If you're still cramped for memory, consider converting the files to a lower sample rate, or from stereo to mono, with SGI's `soundfiler` application.

To use the sample actor, load samp.so and create an actor of type SampleActor.

### SampleActor messages

In addition to the messages understood by all generator actors, the SampleActor understands the following messages:

PlaySample `hActor "fileName"`
  Load the specified sample file into memory, play it from beginning to end without looping, and then delete the handler. No handle is returned to the client. `filename` must be double-quoted as shown.
LoadFile `hActor "fileName"`
  Load the specified sample file into memory, and add it to a quick-playback file list maintained internally by vss for future references to sample file `fileName` by `hActor`. `filename` must be double-quoted as shown.
UnloadFile `hActor "fileName"`
  Delete the specified sample file from memory, and remove it from the file list for `hActor`. `filename` must be double-quoted as shown.
UnloadAllFiles `hActor`
  Delete all current sample files for actor `hActor` from memory, and clear the associated file list.
RewindAll `hActor`
  Rewind all children. That is, set their playback indices to the beginning of the sample file, or to the "start" parameter given in the message SetAllBounds.
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 to this directory also.
SetAllBounds `hActor x y`
  Set the start and end points of sample playback for all children to `x` (start) and `y` end. Otherwise, the start and end points default to the beginning and end of the sample file(s).
SetLoop `hActor bool`
  Set the default loop flag for new instances created by this actor to `bool`. Looping occurs for `bool`=1. The default behavior upon actor creation is for looping to be off.
SetAllLoop `hActor bool`
  Set the loop flag of all children, and the default loop flag for all future children to `bool`.
SetAllLoop `hActor x y bool`
  Set the loop points for all children to `x` (start) and `y` (end). If `bool` is specified, set the loop flag for all children, and the default loop flag for all future children, to `bool`. If `bool` is not specified, set the loop flag for all children, and the default loop flag for all future children, to 1.0 (true).
SetPlaybackRate `hActor r`
  Set the default playback rate for new instances created by this actor 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.
SetAllPlaybackRate `hActor r time`
  Set the playback rate for all children, and the default playback rate for all future children, to `r`. If `time` is specified, children will modulate to the new playback rate over the specified duration. Default playback rate for future children is always set immediately regardless of `time`.

### Sample playback handler messages

In addition to the messages understood by all handlers, the handler for the sample playback algorithm understands the following messages:

DeleteWhenDone `hSound bool`
  If `bool` is true (not 0.), delete the handler when the playback index reaches the playback endpoint (only if looping is turned off). `bool` defaults to true. If DeleteWhenDone isn't sent, the handler will not be automatically deleted in this way.
DeleteWhenDoneMG `hSound hMessageGroup`
  When the playback index reaches the playback endpoint, delete the handler and send a message to the Message Group `hMessageGroup` consisting of a floating-point array one element long. This single element is `hSound`, the handle of this (currently being deleted) handler. You can use this message to discover when a sound has finished playing.
JumpTo `hSound time`
  Move the playback index to the specified time (in seconds). Fails if `time` is less than zero (all sample files are assumed to start at relative time zero) or greater than the length of the file in time.
Rewind `hSound`
  Set the playback index to the beginning of the sample file, or to the "start" parameter given in the messages SetBounds or SetAllBounds.
SetDirectory `hSound "dir"`
  Set the base directory to `dir`. `dir` must be double-quoted as shown.
SetFile `hSound "fileName"`
  Load the sample file `fileName`, if not previously loaded, and initialize for playback. Playback and loop points are reset to the beginning and end of the file. `filename` must be double-quoted as shown.
SetBounds `hSound x y`
  Set the start and end points of sample playback to `x` (start) and `y` (end). Otherwise, the start and end points default to the beginning and end of the sample file, or to the points specified through message SetAllBounds.
SetLoop `hSound bool`
  Set the default loop flag to `bool`.
SetLoop `hSound x y bool`
  Set the loop points to `x` (start) and `y` (end). If `bool` is specified, set the loop flag to `bool`. If `bool` is not specified, set the loop flag for this handler to 1.0 (true).
SetPlaybackRate `hSound r time`
  Set the rate at which which the algorithm plays back the sample file. The default rate upon actor creation is `r`=1.0 corresponding to playback at the normal rate (i.e. a rate of 2.0 plays back at double speed). If `time` is specified, modulate to the new playback rate over the specified duration.