Maestro - user's guide and function documentation. ---------------------------------------------------------------------------------- ---------------------------------------------------------------------------------- Justin King Math 198 Hypergraphics Spring, 2004 ---------------------------------------------------------------------------------- ---------------------------------------------------------------------------------- Functions should be listed below in alphabetical order, except On commands are listed before Off ones ---------------------------------------------------------------------------------- ---------------------------------------------------------------------------------- sndAmpP_On(float which, float ampl); -------------------------------- Parameters: - Float - which: proper values are between 0 and 7000 (inclusive) - Float - ampl: proper values are between 0 and 1 (inclusive) Return Value: Void Function plays a specified pitch at the specified amplitude in the specified temperment until a sndAmpP_Off() command is executed. Known Issues: - If Client program exits unexpectedly, sound will continue to play until VSS Server is killed or a Kill All command is sent to the VSS Server. ================================================= sndAmpP_Off(void); -------------------------------- Parameters: - None Return Value: Void Function turns off an sndAmpP_On() command - stops the note from playing Known Issues: - A Current bug is that sndAmpP_Off() will also turn off all other generators at the same time. ================================================= sndAmpPM_Off(void); -------------------------------- Parameters: - None Return Value: Void Function turns off an sndAmpPM_On() command - stops the note from playing Known Issues: - A Current bug is that sndAmpPM_Off() will also turn off all other generators at the same time. ================================================= sndAmpPM_On(int numamp, float* ptchs); -------------------------------- Parameters: - Integer - numamp: proper values are between 1 and 8 (inclusive) - Float* (array) - ptchs: proper values for each cell are between 0 and 7000 (inclusive); - Float* (array) - amps: proper values for each cell are between 0 and 1.0 (inclusive); Return Value: Void Function plays a set of up to 8 specified FM Pitches (nos. 0 through 7) at the specified amplitudes (nos. 0 through 7) until a sndAmpPM_Off() command is executed. If fewer than 8 is specified by num, only the first num elements (nos. 0 through num-1) of the arrays are considered, and the other generators are silenced. Known Issues: - If Client program exits unexpectedly, sound will continue to play until VSS Server is killed or a Kill All command is sent to the VSS Server. - If num is greater than the elements in the array, bad data values or segmentation faults could occur. A good way to avoid this is to use the same variable for num as you use for declaring the size of the float array. ================================================= sndBeep(int which); -------------------------------- Parameters: - Integer - which: proper values are between 0 and 10 (inclusive) Return Value: Void Function plays a specified beep sound Known Issues: - Currently, beeps number 7 through 10 are unimplemented in the .aud file, and so will sound the same as beep number 1. ================================================= sndExit(void); -------------------------------- Parameters: - None Return Value: Void Function ends sound in maestro programs. If parambient sounds are playing, they are stopped. Known Issues: - No known issues ================================================= sndInit(void); -------------------------------- Parameters: - None Return Value: Void Function initializes sound for Maestro programs - passes .aud file to VSS and checks to make sure VSS is ready Known Issues: If VSS fails, sound may not be able to be achieved until program is restarted ================================================= sndNote(int whichNote, int bpm, int tempr); -------------------------------- Parameters: - Integer - whichNote: proper values are between 0 and tempr*4 (inclusive, 4 octave range) - Integer - bpm: proper values are between 20 and 240 (inclusive, speed of the note, default is 120) - Integer - tempr: proper values are greater than or equal to 2 (large tempr will slow your program, default is 12) Return Value: Void Function plays a specified note, treated as a quarter note, at the bpm speed, in the specified temperment Known Issues: - None currently known. ================================================= sndNoteP_On(int whichNote, int tempr); -------------------------------- Parameters: - Integer - whichNote: proper values are between 0 and tempr*4 (inclusive, 4 octave range) - Integer - tempr: proper values are between 2 and 100 (inclusive). This argument is optional, default is 12. Return Value: Void Function plays a specified musical note in the specified temperment until a sndNoteP_Off() command is executed. Known Issues: - If Client program exits unexpectedly, sound will continue to play until VSS Server is killed or a Kill All command is sent to the VSS Server. - Works on the same generator as sndPitchP_On(), so a command of that type will eliminate your sound from this function ================================================= sndNoteP_Off(void); -------------------------------- Parameters: - None Return Value: Void Function turns off an sndNoteP_On() command - stops the note from playing Known Issues: - A Current bug is that sndNoteP_Off() will also turn off all other generators at the same time. ================================================= sndPause(int howLong); -------------------------------- Parameters: - Integer - howLong: no limits on values Return Value: Void Function is used mostly for sound debugging, and has little practical application elsewhere. However, function can be used to pause execution of your program while waiting for the sound buffer to clear out a bit. Known Issues: - Negative values for howLong could potentially cause program to enter endless loop or crash. However, the hope is that this function will not be used in actual programming. ================================================= sndPlay(int which = 1, int loops = 1); -------------------------------- Parameters: - Integer - whichNote: proper values are between 0 and tempr*4 (inclusive, 4 octave range) - Integer - loops: proper values are greater than or equal to 1 (default is 1) Return Value: Void Function plays a specified AIFF sound file number the specified number of times Known Issues: - Loops feature appears to not work properly - Only AIFF files will play in this command - .aud file must be edited to reflect location on disk of the AIFF files. The proper location for editing is near the top of the .aud file. - Multiple calls in succession will result in the same AIFF file playing multiply at the same time in the VSS Server ================================================= sndPitch(float which, float length); -------------------------------- Parameters: - Float - which: proper values are between 0 and 7000 (inclusive) - Float - length: proper values are between 0.1 and 120 (inclusive) Return Value: Void Function plays a specified pitch for the specified number of seconds (standard FM synthesis) Known Issues: - None currently known. ================================================= sndPitchP_On(float which); -------------------------------- Parameters: - Float - which: proper values are between 0 and 7000 (inclusive) Return Value: Void Function plays a specified FM Pitch until a sndPitchP_Off() command is executed Known Issues: - If Client program exits unexpectedly, sound will continue to play until VSS Server is killed or a Kill All command is sent to the VSS Server. - Works on the same generator as sndNoteP_On(), so a command of that type will eliminate your sound from this function ================================================= sndPitchP_Off(void); -------------------------------- Parameters: - None Return Value: Void Function turns off an sndPitchP_On() command - stops the note from playing Known Issues: - A Current bug is that sndPitchP_Off() will also turn off all other generators at the same time. ================================================= sndPitchPM_On(int num, float* ptchs); -------------------------------- Parameters: - Integer - num: proper values are between 1 and 8 (inclusive) - Float* (array) - ptchs: proper values for each cell are between 0 and 7000 (inclusive); Return Value: Void Function plays a set of up to 8 specified FM Pitches (nos. 0 through 7) until a sndPitchPM_Off() command is executed. If fewer than 8 is specified by num, only the first num elements (nos. 0 through num-1) of the array are considered, and the other generators are silenced. Known Issues: - If Client program exits unexpectedly, sound will continue to play until VSS Server is killed or a Kill All command is sent to the VSS Server. - If num is greater than the elements in the array, bad data values or segmentation faults could occur. A good way to avoid this is to use the same variable for num as you use for declaring the size of the float array. ================================================= sndPitchPM_Off(void); -------------------------------- Parameters: - None Return Value: Void Function turns off an sndPitchPM_On() command - stops the note from playing Known Issues: - A Current bug is that sndPitchPM_Off() will also turn off all other generators at the same time. ================================================= =================== END OF FILE ===================