void play(double duration,int instrument,int octave,int pitch);
void nplay(double duration,int instrument,int numberedNote);
void rplay(double duration,RRA * r);
void dplay(double duration,int *data,int length);
void splay(double duration,int instrument,int octave,int pitch);
void snplay(double duration,int instrument,int numberedNote);
void drum(double duration,int instrument,int numberedNote);
Functions in the play family play a given note for the given duration. The duration is specified in beats. The note to be played is specified by an instument/octave/pitch triplet, an instrument/numbered note pair, an RRA object, or an array of amplitude data. Note that the play family follows the n,r,d convention.
The instrument is an integer returned by the readScale function.
The actual length of the duration depends on the tempo given in a setTime call.
For example, if the note is to be played for two beats and the number of beats per minute is 132 and the sample rate is 44,100 samples per second, then...
2 * 1/132 * 60 * 44100
...or...
3272
...samples from the beginning of the given note will be added into the output buffer starting at the current location. Moreover, additional samples beyond the 3727th will be added in, at ever-diminishing amplitiudes, so that the note does not end abrubtly. The number of additional samples added to the output is governed by the current value of sustain.
The exception to the above behavior are the splay, snplay and drum functions. These functions play the entire note and then rewind the song (using getLocation and setLocation) so that it appears as if only the requested number of beats has elapsed. The splay and snplay functions are useful for playing instruments whose notes always have a fixed duration (such as drums). The function drum randomly adds a little variation to the amplitude, timing, and pitch of the note being played.
The play function and its alternatives update the current location in the output.
Here is an example songlib program that plays a single note:
#include "songlib.h"
int
main()
{
int inst;
initSong();
setTime(132,4);
setSustain(0.99995);
openOutput("song.rra",44100,16);
inst = readScale("../../../samples/guitar","note_");
play(2.0,inst,3,C);
closeOutput();
return 0;
}