Difference between revisions of "Nyquist Basics: The Audacity Nyquist Prompt"

From Audacity Wiki
Jump to: navigation, search
(Made "audio hacks" in Intro a little more understandable. Don't say "marked or selected" - it means the same thing but looks as if it isn't the same if you say both)
(Basic Nyquist Commands: update links)
 
(55 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Introrel|With the Audacity Nyquist Prompt you can test small snippets of Nyquist code you are working on, or run a Nyquist effect in any way you wish (as opposed to how that effect works as built into Audacity). On this page the basic usage of the Nyquist Prompt is explained.|2=|3=
+
{{Nyquist Basics|This page explains how to use the Audacity Nyquist Prompt to test-run Nyquist code snippets. }}
[[:Category:Digital Audio Technology|Digital Audio Technology]]
+
{{ednote|'''Steve 07Apr18''' P1 Images need updating
*[[Nyquist Audio Programming]]
+
*'''Peter 21Jul19:''' Done - by trimming off the TCPs (to aid future generalization against future TCP changes). And added the indentations that Connie likes.}}
*{{external|[http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/manual/home.html Nyquist Reference Manual 2.3.6]}} (the latest Audacity-compatible version) }}
 
 
 
  
 
__TOC__
 
__TOC__
Line 9: Line 7:
 
==Setting up==
 
==Setting up==
  
The Audacity Nyquist prompt appears in Audacity's "Effect" menu. This menu can be only be activated if an Audacity audio track exists and at least part of it is selected.  
+
{{note|1=This article uses [https://en.wikipedia.org/wiki/Lisp_(programming_language) LISP] syntax for Nyquist commands. For an introduction using SAL syntax, see [[Nyquist Basics: The Audacity Nyquist Prompt With SAL]].}}
 +
 
 +
The Audacity Nyquist prompt appears in Audacity's "Tools" menu.
 +
{{Hint|For testing generate commands in Nyquist, you can install the [http://wiki.audacityteam.org/wiki/Nyquist_Generate_Plugins#Nyquist_Generate_Prompt Nyquist Generate Prompt] plug-In, or simulate the behavior of a generate type plug-in in the [http://manual.audacityteam.org/man/nyquist_prompt.html Nyquist Prompt] effect.}}
  
 
===Load a Sound File===
 
===Load a Sound File===
  
If you have a mono or stereo sound file available you can import it into Audacity via:
+
Sound files are imported into Audacity via:
  
 
{{Menu|File > Import > Audio}} or the shortcut {{Shortcut|CTRL + SHIFT + I}}
 
{{Menu|File > Import > Audio}} or the shortcut {{Shortcut|CTRL + SHIFT + I}}
  
If you have no sound files available you can build your own mono or stereo tracks via the Audacity "Generate" menu.
+
If you have no pre-existing sound files to work with, you can create your own mono or stereo tracks via the Audacity "Generate" menu.
  
 
===Create a Mono Track===
 
===Create a Mono Track===
 +
'''1.''' Click {{Menu|Tracks > Add New > Mono Track}}.
 +
An empty mono track will appear in the Audacity window:
  
Click {{Menu|Generate > Tone}}. Leave everything as-is, just click "OK", a mono track will appear in the Audacity window:
+
'''2.''' Click {{Menu|Generate > Tone}}. Leave everything as-is and just click {{button|OK}}. The mono tracks will become filled with the generated sound.
 
+
:[[Image:Nyquist-prompt-mono-track - no TCP.png|Audacity mono track]]
[[Image:Nyquist-prompt-mono-track.png|Audacity mono track]]
 
  
 
===Create a Stereo Track===
 
===Create a Stereo Track===
  
'''1.''' Select the whole mono track either by pressing {{Shortcut|CTRL + A}} on the keyboard, or by clicking with the mouse on the Track Panel (take care not to move the buttons or sliders). The audio waveform will then have a shaded colour.
+
'''1.''' Create an empty stereo track.
 +
*click {{Menu|Tracks > Add New > Stereo Track}}.
  
'''2.''' Click {{Menu|Edit > Duplicate}}. A second, identical mono track will appear below the first one:
+
An empty stereo track will appear in the Audacity window.
  
[[Image:Nyquist-prompt-two-mono-tracks.png|Two mono tracks]]
+
'''2.''' Now click {{Menu|Generate > Tone}}. Leave everything as-is and just click "OK". The stereo tracks will become filled with the generated sound.
 +
:[[Image:Nyquist-prompt-stereo-track - no TCP.png|Audacity stereo track]]
  
'''3.''' In the upper mono track, open the track menu by clicking on the small black triangle at the top of the Track Panel choose '''Make stereo track'''. Both mono tracks then will be combined into the left and right channel of a single stereo track:
+
<div id="prompt"></div>
  
[[Image:Nyquist-prompt-stereo-track.png|Audacity stereo track]]
+
==The Nyquist Prompt==
  
==The Nyquist Prompt==
+
{{alert|Recent versions of Audacity have an option to '''"Use legacy (version 3) syntax"''' in the Nyquist Prompt. Ensure that option is '''NOT''' enabled for these examples.}}
 +
 
 +
Select the track(s) and click {{Menu|Tools > Nyquist Prompt}}.
  
Click {{Menu|Effect > Nyquist Prompt}}. If the Effect Menu is greyed out because no part of the audio is selected,  press {{Shortcut|CTRL + A}} on the keyboard. A window like the following will appear:
+
The Nyquist Prompt appears like this:
  
[[Image:Nyquist-prompt-001.png|Audacity Nyquist prompt window]]
+
:[[Image:Sal-prompt-001.png|Audacity Nyquist prompt window]]
  
 
===The Nyquist Interpreter===
 
===The Nyquist Interpreter===
  
In the "Nyquist Prompt" window, type into the text field a string "hello" with quotes:
+
In the Nyquist Prompt window, type <tt>(print "hello")</tt> into the text field with the parentheses and quotes, as follows:
  
[[Image:Nyquist-prompt-002.png|Audacity Nyquist prompt window with quoted hello]]
+
:[[Image:Nyquist-prompt-002.png|Audacity Nyquist prompt window print with quoted hello]]
  
If you click "OK", you should get a window displaying the word hello:
+
{{Hint|'''NOTE:''' The Nyquist Prompt must see an open parenthesis as the first non-space character; otherwise it will assume this is written using [[Nyquist Basics: The Audacity Nyquist Prompt With SAL|SAL syntax]]. Otherwise, we might have just typed <tt>"hello"</tt>, which worked in earlier versions of Audacity.}}
  
[[Image:Nyquist-prompt-003.png|Window displaying the word hello]]
+
When you click OK, you should get a message box displaying the word hello:
  
Click "OK" in the "hello" window to make it disappear again.
+
:[[Image:Sal-prompt-003.png|Window displaying the word hello]]
  
Congratulations, you just have learned how to send text messages to the user.
+
The message box disappears when you click OK.
 +
 
 +
This, as you have learned, is how you can send messages to the user.
  
 
===The Nyquist Debugger===
 
===The Nyquist Debugger===
  
After clicking "OK" in the "hello" window, go back to the Audacity '''Effect''' menu and choose '''Nyquist prompt''' again, but this time type the word hello without the quotes:
+
Go back to {{Menu|Tools > Nyquist Prompt}}, and this time, type <tt>(print hello)</tt> with the parentheses but without the quotes:
 +
 
 +
:[[Image:Nyquist-prompt-004.png|Audacity Nyquist prompt window print with unquoted hello]]
 +
 
 +
 
 +
'''Important:''' This time, click {{button|Debug}} instead of {{button|OK}}.
 +
 
 +
A "debug window" appears, displaying the error messages that Nyquist returned:
 +
 
 +
:[[Image:Nyquist-prompt-006.png|Window displaying Nyquist error: unbound variable]]
 +
 
 +
 
 +
{{Hint|'''NOTE:''' The Nyquist debug window only appears if you click {{button|Debug}} button. If you click {{button|OK}} button, then errors are printed to the [https://manual.audacityteam.org/man/help_menu_diagnostics.html#show_log Audacity log].}}
 +
 
 +
===Basic Nyquist Commands===
 +
 
 +
The current Nyquist manual is here: [https://www.cs.cmu.edu/~rbd/doc/nyquist/ Nyquist Reference Manual].
 +
 
 +
A useful index of Nyquist commands is here: [https://www.cs.cmu.edu/~rbd/doc/nyquist/indx.html Nyquist Language reference]
 +
 
 +
Audacity uses the '''*TRACK*''' variable to reference the current audio file/selection. Thus, you can use basic commands such as '''mult''' or '''sum''' with '''*track*''' and the Nyquist prompt will replace the file/selection with the result (or as Audacity calls it, "returned audio").
 +
{{note|Prior to version 4 syntax, the variable '''S''' was used instead of '''*TRACK*'''. You may encounter this in some old plug-ins or old documentation. The old syntax is obsolete and should not be used in new code.}}
 +
 
 +
===Simple Examples===
 +
{{Hint|'''NOTE:''' These examples are focused upon using Audacity to manipulate digital signals (clearly Audacity is better suited to audio, but features such as Nyquist can open many other uses).
 +
For those interested, the signal used is an [http://en.wikipedia.org/wiki/Consumer_IR infra red] (IR) sample from a remote control.}}
 +
 
 +
{{Hint|'''NOTE:''' Each code example will be shown once using LISP syntax, and again using SAL syntax. Either form can be used, but never try to mix them in a single program or prompt! ''Prior to Audacity Version 1.3.13 (Beta), only LISP syntax works.''}}
 +
 
 +
====Applying a DC offset to a signal====
 +
 
 +
:[[Image:Raw Digital Waveform - no TCP.gif|Original Signal before command.]]
 +
 
 +
Original Signal before command.
 +
 
 +
Type the following into the Nyquist Prompt (using LISP syntax):
 +
{{code|(sum *track* 1)}}
 +
Or type the following equivalent SAL command:
 +
{{code|return *track* + 1}}
 +
 
 +
:[[Image:DC Offset Applied - no TCP.gif|Resultant Signal after command.]]
 +
 
 +
The whole signal has now moved up to above zero.
  
[[Image:Nyquist-prompt-004.png|Audacity Nyquist prompt window with unquoted hello]]
+
====Modulating with a carrier frequency====
 +
To multiply a signal with a generated carrier signal, you can use the following commands:
 +
{{code|(mult *track* (hzosc 19000))}}
 +
Or the SAL equivalent:
 +
{{code|return *track* * hzosc(19000)}}
 +
The (hzosc 19000) produces 19kHz sine wave carrier.
  
'''Important:''' Now click "Debug" instead of "OK".
+
{{code|(mult *track* (osc-pulse 19000 0))}}
 +
Or the SAL equivalent:
 +
{{code|return *track* * osc-pulse(19000, 0)}}
 +
The (osc-pulse 19000 0) produces 19kHz square wave carrier (note the 0 is the bias or 50/50 duty cycle, -1 to 1 = 0%-100% pulse-width ).
 +
Applying the 19kHz square wave carrier obtains this result.
  
You should first get a window displaying a "Nyquist did not return audio" or similar message:
+
:[[Image:Modulated Signal - no TCP.gif|Resultant Signal after command.]]
  
[[Image:Nyquist-prompt-005.png|Window displaying Nyquist did not return audio]]
+
The top and bottoms of the signal can then be clipped using the Hard Limiter option from the effects menu (0dB limit and Wet level 1) if required.
  
After clicking "OK" in the window above, a second window appears, displaying the detailed Nyquist error messages:
+
The above examples show how you can use the many Nyquist commands to perform basic signal processing without using scripts.
  
[[Image:Nyquist-prompt-006.png|Window displaying Nyquist error: unbound variable]]
+
{{Hint|'''NOTE:''' Unfortunately, this isn't the end of the road for this sample; it is near, but the curved "head/tail" of the signal causes a problem for the digital signal being produced [and it was also upside-down, too...]. This will hopefully form the basis of some more complex examples, since I shall need to use Nyquist to:
 +
#Find the zero crossing points
 +
#Then only apply the carrier frequency to those regions above zero.
 +
Or find another suitable command...}}
  
  
{{Hint|'''NOTE:''' The "Nyquist output" window only appears if you click "Debug" in the "Nyquist Prompt" window. If you click "OK", then, even with a Nyquist error, only the first window will appear.}}
+
''Thanks to [https://forum.audacityteam.org/ Forum] moderators stevethefiddle & kozikowski for their help with Audacity & Nyquist.''

Latest revision as of 19:38, 28 June 2021


This page explains how to use the Audacity Nyquist Prompt to test-run Nyquist code snippets.
The "Nyquist Basics" tutorials start with very simple examples at the top of each page with increasing complexity towards the end. You do not necessarily need to work through to the end of each page to be able to understand the other tutorials. If you feel confused, try any of the other Nyquist Basics tutorials, in any order. Every "Basics" page contains lots of notes and hints where you can find extra information.
 
Related article(s):
Please note: Nyquist supports both a LISP syntax and a more conventional syntax called SAL. You can choose a manual from a link above based on which syntax you are using.
Steve 07Apr18 P1 Images need updating
  • Peter 21Jul19: Done - by trimming off the TCPs (to aid future generalization against future TCP changes). And added the indentations that Connie likes.

Setting up

This article uses LISP syntax for Nyquist commands. For an introduction using SAL syntax, see Nyquist Basics: The Audacity Nyquist Prompt With SAL.

The Audacity Nyquist prompt appears in Audacity's "Tools" menu.

For testing generate commands in Nyquist, you can install the Nyquist Generate Prompt plug-In, or simulate the behavior of a generate type plug-in in the Nyquist Prompt effect.

Load a Sound File

Sound files are imported into Audacity via:

File > Import > Audio or the shortcut CTRL + SHIFT + I

If you have no pre-existing sound files to work with, you can create your own mono or stereo tracks via the Audacity "Generate" menu.

Create a Mono Track

1. Click Tracks > Add New > Mono Track. An empty mono track will appear in the Audacity window:

2. Click Generate > Tone. Leave everything as-is and just click OK. The mono tracks will become filled with the generated sound.

Audacity mono track

Create a Stereo Track

1. Create an empty stereo track.

  • click Tracks > Add New > Stereo Track.

An empty stereo track will appear in the Audacity window.

2. Now click Generate > Tone. Leave everything as-is and just click "OK". The stereo tracks will become filled with the generated sound.

Audacity stereo track

The Nyquist Prompt

Warning icon Recent versions of Audacity have an option to "Use legacy (version 3) syntax" in the Nyquist Prompt. Ensure that option is NOT enabled for these examples.

Select the track(s) and click Tools > Nyquist Prompt.

The Nyquist Prompt appears like this:

Audacity Nyquist prompt window

The Nyquist Interpreter

In the Nyquist Prompt window, type (print "hello") into the text field with the parentheses and quotes, as follows:

Audacity Nyquist prompt window print with quoted hello


NOTE: The Nyquist Prompt must see an open parenthesis as the first non-space character; otherwise it will assume this is written using SAL syntax. Otherwise, we might have just typed "hello", which worked in earlier versions of Audacity.

When you click OK, you should get a message box displaying the word hello:

Window displaying the word hello

The message box disappears when you click OK.

This, as you have learned, is how you can send messages to the user.

The Nyquist Debugger

Go back to Tools > Nyquist Prompt, and this time, type (print hello) with the parentheses but without the quotes:

Audacity Nyquist prompt window print with unquoted hello


Important: This time, click Debug instead of OK.

A "debug window" appears, displaying the error messages that Nyquist returned:

Window displaying Nyquist error: unbound variable


NOTE: The Nyquist debug window only appears if you click Debug button. If you click OK button, then errors are printed to the Audacity log.

Basic Nyquist Commands

The current Nyquist manual is here: Nyquist Reference Manual.

A useful index of Nyquist commands is here: Nyquist Language reference

Audacity uses the *TRACK* variable to reference the current audio file/selection. Thus, you can use basic commands such as mult or sum with *track* and the Nyquist prompt will replace the file/selection with the result (or as Audacity calls it, "returned audio").

Prior to version 4 syntax, the variable S was used instead of *TRACK*. You may encounter this in some old plug-ins or old documentation. The old syntax is obsolete and should not be used in new code.

Simple Examples

NOTE: These examples are focused upon using Audacity to manipulate digital signals (clearly Audacity is better suited to audio, but features such as Nyquist can open many other uses). For those interested, the signal used is an infra red (IR) sample from a remote control.


NOTE: Each code example will be shown once using LISP syntax, and again using SAL syntax. Either form can be used, but never try to mix them in a single program or prompt! Prior to Audacity Version 1.3.13 (Beta), only LISP syntax works.

Applying a DC offset to a signal

Original Signal before command.

Original Signal before command.

Type the following into the Nyquist Prompt (using LISP syntax):

(sum *track* 1)

Or type the following equivalent SAL command:

return *track* + 1
Resultant Signal after command.

The whole signal has now moved up to above zero.

Modulating with a carrier frequency

To multiply a signal with a generated carrier signal, you can use the following commands:

(mult *track* (hzosc 19000))

Or the SAL equivalent:

return *track* * hzosc(19000)

The (hzosc 19000) produces 19kHz sine wave carrier.

(mult *track* (osc-pulse 19000 0))

Or the SAL equivalent:

return *track* * osc-pulse(19000, 0)

The (osc-pulse 19000 0) produces 19kHz square wave carrier (note the 0 is the bias or 50/50 duty cycle, -1 to 1 = 0%-100% pulse-width ). Applying the 19kHz square wave carrier obtains this result.

Resultant Signal after command.

The top and bottoms of the signal can then be clipped using the Hard Limiter option from the effects menu (0dB limit and Wet level 1) if required.

The above examples show how you can use the many Nyquist commands to perform basic signal processing without using scripts.


NOTE: Unfortunately, this isn't the end of the road for this sample; it is near, but the curved "head/tail" of the signal causes a problem for the digital signal being produced [and it was also upside-down, too...]. This will hopefully form the basis of some more complex examples, since I shall need to use Nyquist to:
  1. Find the zero crossing points
  2. Then only apply the carrier frequency to those regions above zero.
Or find another suitable command...


Thanks to Forum moderators stevethefiddle & kozikowski for their help with Audacity & Nyquist.