Sample playback actor

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). 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.