Programming in Nyquist

From Audacity Development Manual
Jump to: navigation, search

Programming in Nyquist

What makes Nyquist distinct from Lisp is that it is designed to work with sound, and has lots of built-in primitives and functions that synthesize, analyze, and manipulate sounds. Within Audacity, this makes it relatively easy to build complicated effects out of Nyquist's palette of built-in functions.

In Nyquist, a variable can hold a sound just as easily as it can hold a number or a string. There are a lot of functions provided that allow you to stretch, distort, and combine sounds very efficiently. It is even possible to "rip apart" a sound and access its individual samples, but that is beyond the scope of this tutorial.

To try out a Nyquist expression in Audacity, you can use Nyquist Prompt in the Effect menu. Whatever audio you have selected will be in the variable *track*, and the selection will be replaced with the result of the Nyquist expression you enter. In Part 3: Creating Nyquist Plugins, you will learn how to create a plugin effect using Nyquist.


The following functions all create new sounds. You can use them to create "generate" plugin effects, or you can combine these synthesized sounds with selected audio to produce interesting effects.

(noise) Generates white noise
(const value [duration]) Generates a constant (silent) signal
(sine pitch [duration]) Generates a sine wave at an indicated pitch and duration.The pitch is a MIDI note number, with 60 for middle C.
(hzosc hz) Generates a sine wave at a particular frequency in Hz.
(osc-saw hz) Generates a sawtooth wave at a particular frequency in Hz.
(osc-tri hz) Generates a triangle wave at a particular frequency in Hz.
(osc-pulse hz bias)
(pluck pitch)


Nyquist has support for envelopes. By applying an envelope to a sound, you can control the overall shape of its amplitude. One of the easiest ways to construct an envelope is with the env function, which takes 7 parameters that are commonly used for shaping synthesized musical notes: attack time, decay time, release time, attack level, decay level, sustain level, and overall duration.See the figure below:


To apply an envelope to a sound, just use the mult function. So if *track* is the sound, then this is the sound with a simple envelope applied to it:

  (mult *track* (env 0.1 0.1 0.2 1.0 0.5 0.3 1.0))

One of the most general type of envelope is a piece-wise linear function, which can be constructed with the pwl function. The pwl function takes a list of parameters which denote (time, value) pairs. There is an implicit initial (time, value) pair of (0, 0), and an implicit final value of 0. There should always be an odd number of parameters, since the final time is not implicit. For example:

  ; symmetric rise to 0.7 (at time 1) and fall back to 0 (at time 2):
  (pwl 1.0 0.7 2.0)

Combining sounds

Besides multiplying two sounds with the mult function, you can add two sounds (or envelopes) with the add function.


Nyquist comes with a number of common filters built-in. Here are some of the more common ones:

(lp sound cut-off)
(hp sound cut-off) High-pass filter (first-order Butterworth). Cut-off may be a float or a signal (for time-varying filtering) and expresses hertz.
(comb sound hz decay) Applies a comb filter to sound, which emphasizes (resonates at) frequencies that are multiples of a Hz.
(alpass sound decay hz) All-pass filter, creating a delay effect without the resonances of a comb filter.
(notch2 sound hz)

Transforming and combining sounds

It is beyond the scope of this introductory tutorial to explain all of the ways that a sound can be transformed in Nyquist. These functions do not modify sounds directly, but instead modify the Nyquist environment. In order for these changes to affect sounds, you must use the cue function.

(stretch factor (cue sound)) Changes the length of the sound being cued by the given factor.
(scale factor (cue sound)) Scales the amplitude of the sound being cued by the given factor.
(loud dB (cue sound)) Increases or decreases the volume of the sound being cued by the given number of decibels.
(at t (cue sound)) Starts the given sound at a particular time in seconds. This cannot be used to add silence at the beginning or end, but it can be used when combining two or more sounds.
(seq (cue s1) (cue s2)) Creates a sequence of sound s1 followed by sound s2.
(sim (cue s1) (cue s2)) Combines two sounds so that they are played simultaneously.


>  Creating Nyquist Plugins

<  Introduction to Nyquist and Lisp Programming

|< Nyquist