Getting Started

43

Chapter 4 Programming and Nyquist

In Chapter 3, we looked at data types (including numbers, symbols, and lists), expressions, and functions. In this chapter, we will learn how to write programs and make sounds.

4.1 Getting Started

The normal way to write a program is to type code into a file. The file is then loaded into Nyquist. Loading means that the expressions in the file are evaluated. Usually, most of the expressions in a file de-fine functions. Files are convenient because, if there is an error, you can simply edit the file and reload it rather than retyping everything.

Using the jnyqide program, click on the New File button below the text input area. A new window will appear. Save the empty window to “simple.sal” so the editor will display the file using SAL syntax. Now, you can type a program into this window. Try typing the following text.

Example 4.1.1: ^simple.sal

;; a simple program

define function my-program() begin

print "this is a test"

play pluck(c4) end

Note: examples labeled with a filename as in Example 4.1.1 are included in the accompanying electronic media. (See page 1.) This program begins with a comment. A comment is text that is not evaluated. Comments begin with a semicolon and extend to the end of the line. Sometimes, programmers use two or more semico-lons to make comments stand out, but you could just as well write “^; hey you! – a simple program” as long as the first character is a semicolon. Use comments to describe your programs, intentions, and details that you might forget when you (and others) read the pro-gram.

Following the comment is a function definition. The print command prints a line of text to the Nyquist output to confirm that

the function has been called. The pluck function generates a plucked string sound, and play plays the sound as audio. For now, do not worry about how pluckand playwork because we just want to cre-ate and run any Nyquist program using files.

Notice that my-program has two commands (print and play).

When a function definition has multiple expressions, they are evalu-ated sequentially.

Figure 4.1.1: The Nyquist IDE (Macintosh version)

The screen should look something like Figure 4.1.1. When the program is ready, click on the Load button. Nyquist will then load the file and generate output similar to the following:

Example 4.1.2: Output from loading ^simple.sal SAL> exec setdir("/Users/rbd/temp") SAL> load "/Users/rbd/temp/simple.sal"

SAL>

Notice that you do not need to type anything to the text area. In-stead, jnyqide automatically types a command to set Nyquist’s cur-rent directory to wherever you saved the file and then a command to load the file.

4.1 Getting Started 45

After the file is loaded, my-program will be defined and avail-able for use. To evaluate an expression (such as a function call), use the command exec as shown in Example 4.1.3.

Example 4.1.3: Using ^exec to call a function SAL> exec my-program()

this is a test

Saving sound file to temp.wav total samples: 44100

AutoNorm: peak was 1.24552,

peak after normalization was 0.9,

suggested normalization factor is 0.722587 SAL>

The ^print command in ^my-program generates the output line

“this is a test”. Next, the pluck sound is generated and played by the play function. Some information is printed by play. First, play nor-mally saves a copy of the sound to a file, in this case “temp.wav.”

(You can replay the sound from this file by clicking on the Replay button in jnyqide.) Next, play tells us that it performed 44100 samples of audio. The line beginning with “Autonorm” tells us the peak audio level of the original sound was 1.24552. Normally, audio samples should be in the range from −1 to +1. If necessary, Nyquist tries to adjust the output level to avoid clipping. As indicated in the printout, the sound was scaled to achieve a peak of 0.9. Based on the final outcome, the “suggested” normalization factor of 0.722587 is the value that one might use to scale the sound manually. If you run my-program again, these numbers will change because the pluck sound is initialized with random numbers and produces different peak values each time.

Now go back to the program and change the c4 to f4. Add a new line at the end of the file to call ^my-program. The file should look like Example 4.1.4.

Now, click the Load button in jnyqide. The file is automatically saved and reloaded into Nyquist. Nyquist evaluates the expressions in the file one-by-one. The first expression redefines ^my-program. The next expression calls my-program. You should hear another plucked string sound on the new pitch ^f4.

Example 4.1.4: Using define function in simple2.sal

;; a simple program

define function my-program () begin

print "this is a test"

play pluck(f4) end

exec my-program()

You have now been through two iterations of the standard cycle for program development:

1. create a text file defining functions and calling them 2. load the text file into Nyquist

3. observe and listen to the program behavior

4. edit the program to fix problems or add new features 5. jump to step 2

In the remainder of this chapter, we will first learn how to repre-sent note lists, or scores, in Nyquist. Then we will learn how to turn scores into sounds.