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

From Audacity Wiki
Jump to: navigation, search
m (Simple Examples: - IR refers to infrared, added link to suitable info. Thanks for giving it a once over.)
(Revision of entire page with clearer wording/grammar)
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 plug-in works as built into Audacity). On this page the basic usage of the Nyquist Prompt is explained.|2=|3=[[Nyquist Audio Programming]]
+
{{Introrel|With the Audacity Nyquist Prompt, you can test small snippets of Nyquist code and run an effect in any way you wish (as opposed to how the effect normally works built-in to Audacity). This page explains basic usage of the Nyquist Prompt and what can be accomplished with it.|2=|3=[[Nyquist Audio Programming]]
 
* [[Nyquist Plug-ins]]
 
* [[Nyquist Plug-ins]]
 
*{{external|[http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/manual/home.html Nyquist 2.37 Reference Manual]}} - the latest Audacity-compatible version}}
 
*{{external|[http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/manual/home.html Nyquist 2.37 Reference Manual]}} - the latest Audacity-compatible version}}
{{Hint|1='''Please note:''' The notation in the current Nyquist Reference Manual from the Nyquist homepage at the Carnegie Mellon Universtiy is incompatible to Nyquist in Audacity. Please use the Nyquist 2.37 Manual from the link above if you're working with Nyquist in Audacity.}}
+
{{Hint|1='''Please note:''' The notation in the current Nyquist Reference Manual from the Nyquist homepage at Carnegie Mellon is incompatible with Audacity's Nyquist. Please use the Nyquist 2.37 Manual from the link above if you're working with Nyquist in Audacity.}}
 
 
  
 
__TOC__
 
__TOC__
Line 9: Line 8:
 
==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 some audio in it is selected.
+
The Audacity Nyquist prompt appears in Audacity's "Effect" menu, which is activated only if an Audacity audio track exists and at least some audio in it is selected.
 
{{Hint|For testing generate commands in Nyquist, you can add  
 
{{Hint|For testing generate commands in Nyquist, you can add  
 
[http://audacity.sourceforge.net/nyquist/generate.zip Nyquist Generate Prompt] to the Audacity Plug-Ins folder.}}  
 
[http://audacity.sourceforge.net/nyquist/generate.zip Nyquist Generate Prompt] to the Audacity Plug-Ins folder.}}  
Line 15: Line 14:
 
===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===
  
Click {{Menu|Generate > Tone}}. Leave everything as-is, just click "OK", a mono track will appear in the Audacity window:
+
Click {{Menu|Generate > Tone}}. Leave everything as-is and just click "OK". A mono track will appear in the Audacity window:
  
 
[[Image:Nyquist-prompt-mono-track.png|Audacity mono track]]
 
[[Image:Nyquist-prompt-mono-track.png|Audacity mono track]]
Line 31: Line 30:
 
'''1.''' Create an empty stereo track.
 
'''1.''' Create an empty stereo track.
  
* In '''Audacity 1.2.x''' click {{Menu|Project > New Stereo Track}}.
+
* In '''Audacity 1.2.x''', click {{Menu|Project > New Stereo Track}}.
* In '''Audacity 1.3.x-beta''' click {{Menu|Track > Add New... > Stereo Track}}.
+
* In '''Audacity 1.3.x-beta''', click {{Menu|Track > Add New... > Stereo Track}}.
  
In both cases an empty stereo track will apperar in the Audacity window.
+
An empty stereo track will appear in the Audacity window.
  
'''2.''' Now click {{Menu|Generate > Tone}}. Leave everything as-is, just click "OK", the empty stereo track will get filled with the generated sound.
+
'''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.png|Audacity stereo track]]
 
[[Image:Nyquist-prompt-stereo-track.png|Audacity stereo track]]
Line 42: Line 41:
 
==The Nyquist Prompt==
 
==The 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:
+
Select the track(s) and click {{Menu|Effect > Nyquist Prompt}}. Effects are not activated until at least a portion of the track(s) have been selected. You can select all tracks by pressing {{Shortcut|CTRL + A}} on the keyboard.
 +
 
 +
The Nyquist Prompt appears like this:
  
 
[[Image:Nyquist-prompt-001.png|Audacity Nyquist prompt window]]
 
[[Image:Nyquist-prompt-001.png|Audacity Nyquist prompt window]]
Line 48: Line 49:
 
===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 "hello" into the text field with quotes, like follows:
  
 
[[Image:Nyquist-prompt-002.png|Audacity Nyquist prompt window with quoted hello]]
 
[[Image:Nyquist-prompt-002.png|Audacity Nyquist prompt window with quoted hello]]
  
If you click "OK", you should get a window displaying the word hello:
+
When you click OK, you should get a message box displaying the word hello:
  
 
[[Image:Nyquist-prompt-003.png|Window displaying the word hello]]
 
[[Image:Nyquist-prompt-003.png|Window displaying the word hello]]
  
Click "OK" in the "hello" window to make it disappear again.
+
The message box disappears when you click OK.
  
Congratulations, you just have learned how to send text messages to the user.
+
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, click {{Menu|Effect > Nyquist Prompt}} again, but this time type the word hello without the quotes:
+
After clicking OK in the "hello" message box, go back to {{Menu|Effect > Nyquist Prompt}}, and this time, type the word hello without the quotes:
  
 
[[Image:Nyquist-prompt-004.png|Audacity Nyquist prompt window with unquoted hello]]
 
[[Image:Nyquist-prompt-004.png|Audacity Nyquist prompt window with unquoted hello]]
  
'''Important:''' Now click "Debug" instead of "OK".
+
'''Important:''' This time, click "Debug" instead of "OK".
  
You should first get a window displaying a "Nyquist did not return audio" or similar message:
+
You should first get a window displaying a "Nyquist did not return audio" or a similar message:
  
 
[[Image:Nyquist-prompt-005.png|Window displaying Nyquist did not return audio]]
 
[[Image:Nyquist-prompt-005.png|Window displaying Nyquist did not return audio]]
  
After clicking "OK" in the window above, a second window appears, displaying the detailed Nyquist error messages:
+
After clicking OK in the window above, a second window appears, displaying the error messages that Nyquist returned:
  
 
[[Image:Nyquist-prompt-006.png|Window displaying Nyquist error: unbound variable]]
 
[[Image:Nyquist-prompt-006.png|Window displaying Nyquist error: unbound variable]]
Line 82: Line 83:
 
===Basic Nyquist Commands===
 
===Basic Nyquist Commands===
  
The Nyquist manual relevant to Audacity is available here [http://audacity-forum.de/download/edgar/nyquist/nyquist-doc/manual/title.html Nyquist Reference Manual].
+
The Nyquist manual relevant to Audacity is available here: [http://audacity-forum.de/download/edgar/nyquist/nyquist-doc/manual/title.html Nyquist Reference Manual].
  
Audacity uses the 's' variable to reference the current audio file/selection. Thus you can use basic commands such as 'mult' or 'sum' with 's' and the Nyquist prompt will replace the file/selection with the result (or as Audacity calls it 'returned audio').
+
Audacity uses the 's' variable to reference the current audio file/selection. Thus, you can use basic commands such as 'mult' or 'sum' with 's' and the Nyquist prompt will replace the file/selection with the result (or as Audacity calls it, "returned audio").
  
 
===Simple Examples===
 
===Simple Examples===
Line 103: Line 104:
  
 
====Modulating with a carrier frequency====
 
====Modulating with a carrier frequency====
To multiply a signal with a generated carrier signal you can use the following commands:
+
To multiply a signal with a generated carrier signal, you can use the following commands:
 
   (mult s (hzosc 19000))
 
   (mult s (hzosc 19000))
 
The (hzosc 19000) produces 19kHz sine wave carrier.
 
The (hzosc 19000) produces 19kHz sine wave carrier.
Line 115: Line 116:
 
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 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 etc.
+
The above examples show how you can use the many Nyquist commands to perform basic signal processing without using scripts.
  
{{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 [also it was upside down too...].  This will hopefully form the basis of some more complex examples, since I shall need to use Nyquist to:
+
{{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
 
#Find the zero crossing points
 
#Then only apply the carrier frequency to those regions above zero.
 
#Then only apply the carrier frequency to those regions above zero.

Revision as of 21:25, 22 December 2009

With the Audacity Nyquist Prompt, you can test small snippets of Nyquist code and run an effect in any way you wish (as opposed to how the effect normally works built-in to Audacity). This page explains basic usage of the Nyquist Prompt and what can be accomplished with it.
 
Related article(s):
Please note: The notation in the current Nyquist Reference Manual from the Nyquist homepage at Carnegie Mellon is incompatible with Audacity's Nyquist. Please use the Nyquist 2.37 Manual from the link above if you're working with Nyquist in Audacity.

Setting up

The Audacity Nyquist prompt appears in Audacity's "Effect" menu, which is activated only if an Audacity audio track exists and at least some audio in it is selected.

For testing generate commands in Nyquist, you can add Nyquist Generate Prompt to the Audacity Plug-Ins folder.

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

Click Generate > Tone. Leave everything as-is and just click "OK". A mono track will appear in the Audacity window:

Audacity mono track

Create a Stereo Track

1. Create an empty stereo track.

  • In Audacity 1.2.x, click Project > New Stereo Track.
  • In Audacity 1.3.x-beta, click Track > 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

Select the track(s) and click Effect > Nyquist Prompt. Effects are not activated until at least a portion of the track(s) have been selected. You can select all tracks by pressing CTRL + A on the keyboard.

The Nyquist Prompt appears like this:

Audacity Nyquist prompt window

The Nyquist Interpreter

In the Nyquist Prompt window, type "hello" into the text field with quotes, like follows:

Audacity Nyquist prompt window with quoted hello

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

After clicking OK in the "hello" message box, go back to Effect > Nyquist Prompt, and this time, type the word hello without the quotes:

Audacity Nyquist prompt window with unquoted hello

Important: This time, click "Debug" instead of "OK".

You should first get a window displaying a "Nyquist did not return audio" or a similar message:

Window displaying Nyquist did not return audio

After clicking OK in the window above, a second window appears, displaying the error messages that Nyquist returned:

Window displaying Nyquist error: unbound variable


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.


Basic Nyquist Commands

The Nyquist manual relevant to Audacity is available here: Nyquist Reference Manual.

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

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.

Applying a DC offset to a signal

Original Signal before command.

Original Signal before command.

Type the following into the Nyquist Prompt:

 (sum s 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 s (hzosc 19000))

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

 (mult s (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.