Previous Section | Next Section | Table of Contents | Index | Title Page
Appendix 2: Open Sound Control and Nyquist

Appendix 2: Open Sound Control and Nyquist

Open Sound Control (OSC) is a simple protocol for communicating music control parameters between software applications and across networks. For more information, see The Nyquist implementation of Open Sound Control is simple: an array of floats can be set by OSC messages and read by Nyquist functions. That is about all there is to it.

Note: Open Sound Control must be enabled by calling osc-enable(t). If this fails under Windows, see the installation instructions in sys/win/README.txt regarding SystemRoot.

To control something in (near) real-time, you need to access a slider value as if it a signal, or more properly, a Nyquist SOUND type. The function snd-slider, described in Section "Creating Sounds", takes a slider number and returns a SOUND type representing the current value of the slider. To fully understand this function, you need to know something about how Nyquist is actually computing sounds.

Sounds are normally computed on demand. So the result returned by snd-slider does not immediately compute any samples. Samples are only computed when something tries to use this signal. At that time, the slider value is read. Normally, if the slider is used to control a sound, you will hear changes in the sound pretty soon after the slider value changes. However, one thing that can interfere with this is that SOUND samples are computed in blocks of about 1000 samples. When the slider value is read, the same value is used to fill a block of 1000 samples, so even if the sample rate is 44,100 Hz, the effective slider sample rate is 44,100/1000, or 44.1 Hz. If you give the slider a very low sample rate, say 1000, then slider value changes will only be noticed by Nyquist approximately once per second. For this reason, you should normally use the audio sample rate (typically 44,100 Hz) for the rate of the snd-slider output SOUND. (Yes, this is terribly wasteful to represent each slider value with 1000 samples, but Nyquist was not designed for low-latency computation, and this is an expedient work-around.)

In addition to reading sliders as continually changing SOUNDs, you can get the slider value as a Lisp FLONUM (a floating point number) using get-slider-value, described in Section "Creating Sounds". This might be useful if you are computing a sequence of many notes (or other sound events) and want to apply the current slider value to the whole note or sound event.

Note that if you store the value returned by snd-slider in a variable, you will capture the history of the slider changes. This will take a lot of memory, so be careful.

Suppose you write a simple expression such as (hzosc (mult 1000 (snd-slider 0 ...))) (or in SAL, hzosc(1000 * snd-slider(0 ...))) to control an oscillator frequency with a slider. How long does this sound last? The duration of hzosc is the duration of the frequency control, so what is the duration of a slider? To avoid infinitely long signals, you must specify a duration as one of the parameters of snd-slider.

You might be thinking, what if I just want to tell the slider when to stop? At present, you cannot do that, but in the future there should be a function that stops when its input goes to zero. Then, moving a slider to zero could end the signal (and if you multiplied a complex sound by one of these ending functions, everything in the sound would end and be garbage collected).

Another thing you might want to do with interactive control is start some sound. The trigger function computes an instance of a behavior each time an input SOUND goes from zero to greater-than-zero. This could be used, for example, to create a sequence of notes.

The snd-slider function has some parameters that may be unfamiliar. The second parameter, t0, is the starting time of the sound. This should normally be local-to-global(0), an expression that computes the instantiation time of the current expression. This will often be zero, but if you call snd-slider from inside a seq or seq-rep, the starting time may not be zero.

The srate parameter is the sample rate to return. This should normally be the audio sample rate you are working with, which is typically *default-sound-srate*.

Sending Open Sound Control Messages

A variety of programs support OSC. The only OSC message interpreted by Nyquist has an address of /slider, and two parameters: an integer slider number and a float value, nominally from 0.0 to 1.0.

Two small programs are included in the Nyquist distribution for sending OSC messages. (Both can be found in the same directory as the nyquist executable.) The first one, osc-test-client sends a sequence of messages that just cause slider 0 to ramp slowly up and down. If you run this on a command line, you can use "?" or "h" to get help information. There is an interactive mode that lets you send each OSC message by typing RETURN.

The ser-to-osc Program

The second program is ser-to-osc, a program that reads serial input (for example from a PIC-based microcontroller) and sends OSC messages. Run this command-line program from a shell (a terminal window under OS X or Linux; use the CMD program under Windows). You must name the serial input device on the command line, e.g. under OS X, you might run:
./ser-to-osc /dev/tty.usbserial-0000103D
(Note that the program name is preceded by "./". This tells the shell exactly where to find the executable program in case the current directory is not on the search path for executable programs.) Under Windows, you might run:
ser-to-osc com4
(Note that you do not type "./" in front of a windows program.)

To use ser-to-osc, you will have to find the serial device. On the Macintosh and Linux, try the following:

ls /dev/*usb*
This will list all serial devices with "usb" in their names. Probably, one will be a name similar to /dev/tty.usbserial-0000103D. The ser-to-osc program will echo data that it receives, so you should know if things are working correctly.

Under Windows, open Control Panel from the Start menu, and open the System control panel. Select the Hardware tab and click the Device Manager button. Look in the device list under Ports (COM & LPT). When you plug in your serial or USB device, you should see a new entry appear, e.g. COM4. This is the device name you need.

The format for the serial input is: any non-whitespace character(s), a slider number, a slider value, and a newline (control-j or ASCII 0x0A). These fields need to be separated by tabs or spaces. An optional carriage return (control-m or ASCII 0x0D) preceding the ASCII 0x0A is ignored. The slider number should be in decimal, and theh slider value is a decimal number from 0 to 255. This is scaled to the range 0.0 to 1.0 (so an input of 255 translates to 1.0).

There is a simple test program in demos/osc-test.lsp you can run to try out control with Open Sound Control. There are two examples in that file. One uses snd-slider to control the frequency of an oscillator. The other uses get-slider-value to control the pitch of grains in a granular synthesis process.

Previous Section | Next Section | Table of Contents | Index | Title Page