Nyquist Macros

From Audacity Development Manual
Jump to: navigation, search
Nyquist is a LISP like language integrated into Audacity. It was originally written to process audio.
  • Nyquist now also has the ability to control Audacity, similar to how Macros work, but with greater flexibility.

Comparison of Ordinary Macros to Nyquist Macros

Ordinary Macros execute a fixed sequence of commands in a fixed order.

By contrast, the Nyquist language is a full language from the LISP family. That makes it more powerful and also more complex to use.

  • Nyquist has commands for logic, loops and conditionally executing code.
  • Nyquist supports streams and string formatting functions.
  • Nyquist supports data structures, and is especially strong in handling lists.
  • Nyquist, in Audacity, can prompt for parameters and then use those parameters in its code.

Nyquist can be used independently of Audacity. When used from within Audacity, it gains an additional command, AUD-DO.

AUD-DO

AUD-DO is a function that extends Nyquist's capabailities.

AUD-DO makes it possible to use all Audacity Macro scripting commands from within Nyquist. The full list of scripting commands and their parameters is provided at the page Scripting Reference. The scripting commands are passed to AUD-DO as strings.

A very similar approach is used for Audacity Python Scripting. Commands must be created as strings and passed to a function to process. One advantage of Nyquist Macros over Python Scripting is that Nyquist is already built in to Audacity.


Using AUD-DO

Your Nyquist Script will need to have "type tool". AUD-DO is not available for other types. 

;type tool

The following command in a nyquist script would set the first label in a project to 'foo' 

(AUD-DO "SetLabel: Text=\"Foo\"")

The text string after AUD-DO is passed to the scripting engine to process.

A complete example of a Nyquist Script using AUD-DO that you can enter at the Tools Nyquist Prompt is given below: 

$nyquist plug-in
$version 4
$type tool
$name (_ "Test Me")
$debugbutton false
$action (_ "Applying TestMe...")
$author (_ "Nemo Nemesis")
$release 2.3.0
$copyright (_ "Public Domain")

;; test-me.ny by Nemo Nemesis, August 2018

;; For information about writing and modifying Nyquist plug-ins:
;; https://wiki.audacityteam.org/wiki/Nyquist_Plug-ins_Reference

(AUD-DO "SelectTime: Start=60 End=170")
(AUD-DO "SelectTracks: Track=1 TrackCount=2")

Possibly the easiest way to find the correct strings to use is to use the Macros command to add commands to a macro and examine the strings added.

Bulb icon The full list of commands available via AUD-DO is given in the Scripting Reference

Differences to normal Nyquist Scripting

The '$type' setting in Nyquist sets what capabilities Nyquist will have for that Nyquist script. For example, $type process and $type analyze scripts are given the *TRACK* variable. Process scripts, when applied, will be called repeatedly, once for each channel to process.

Another use of the '$type' setting is to set which menu in Audacity a script will be placed in. It can occasionally be useful to place a process, generator or analyze Nyquist script in the tools menu, even though its functionality is one of the other types. To do that you can use two arguments to the '$type' setting.

You can create nyquist plug-ins with for the Tools menu using any of the following: 

$type tool
$type tool process
$type tool generator
$type tool analyze

The first argument to 'type' determines which Audacity menu the plug-in ends up in. All four examples are for the Tools menu. The qualifier process / generator / analyze determines how the plug-in actually behaves. Only '$type tool' should be used with AUD-DO.


Examples

Example Using Parameters

Scripts using AUD-DO can use parameters. Probably the easiest way to pass them to AUD-DO is using the XLISP format command. 

$nyquist plug-in
$version 4
$type tool
$name (_ "Test Me2")
$debugbutton false
$action (_ "Applying TestMe2...")
$author (_ "Nemo Nemesis")
$release 2.3.0
$copyright (_ "Public Domain")

$control start (_ "Start time") float-text "" 5 nil nil
$control end (_ "End time") float-text "" 15 nil nil

;; test-me.ny by Nemo Nemesis, August 2018

;; For information about writing and modifying Nyquist plug-ins:
;; https://wiki.audacityteam.org/wiki/Nyquist_Plug-ins_Reference



(AUD-DO (format nil "SelectTime: Start=~S End=~S" start end))
(AUD-DO "SelectTracks: Track=0 TrackCount=10")
(AUD-DO  (format nil "Message: Text=\"Start was set to ~S End to ~S\"" start end))

Click Removal Example

On the scripting page, for example, the parameters for the click removal command are documented:

int Threshold, (default:200)
int Width, (default:20)

To invoke the same command in Nyquist, you need to pass a string to AUD-DO. For example: 

(AUD-DO "ClickRemoval: Threshold=200 Width=25")

Default values do not need to be specified, so a shorter version of the same command would be: 

(AUD-DO "ClickRemoval: Width=25")

GetInfo Example

The AUD-DO "GetInfo" Scripting commands provide results as strings, and offers three different result formats.

Bulb icon It is usually easiest, in Nyquist, to ask for the results of GetInfo commands as strings in LISP format

The parameters of GetInfo are:

enum Type, (default:0)

  • Commands
  • Menus
  • Preferences
  • Tracks
  • Clips
  • Envelopes
  • Labels
  • Boxes

enum Format, (default:0)

  • JSON
  • LISP
  • Brief

You'd use a command like the following to get a list of labels (as a string). 

(AUD-DO "GetInfo: Type=Labels Format=LISP")