Preview button in Nyquist effects

A new, and long awaited enhancement for Nyquist plug-ins has recently been added to the Audacity 2.0.7 source code. Nyquist “process” type plug-ins may now have a Preview button.

This is “breaking news”, so may be subject to change.

Preview cannot be expected to work correctly for all effects, so it is left to the plug-in author to enable the Preview button when appropriate. This is done with a new header command:

;preview enabled

An alternative syntax is also available:

;preview true

In order for Preview to work reliably, it has been necessary to tighten up the definition of “process” type plug-ins.
As has always been the case, the “process” type plug-in should be used for plug-ins that process audio.
Up to and including Audacity 2.0.6 it has been possible (but poor practice imo) to define “analyze” type plug-ins as “process” type, and vice verse. With the addition of the Preview button, “process” and “analyze” type plug-ins are no longer the same, so the correct “type” should be set by the plug-in author.

Differences between plug-in types

As described on the wiki ( the “type” of a plug-in is set by one of:

  • ;type generate
  • ;type process
  • ;type analyze

The broad definition of each type could be described:

  • ;type generate
    Plug-ins that generate audio.
  • ;type process
    Plug-ins that process audio.
  • ;type analyze
    Plug-ins that perform analysis.

A certain degree of abuse of these definitions has, and continues to be allowed, which is useful as some plug-ins fall outside of all of these descriptions.

Differences between “analyze” and “process” types in Audacity 2.0.7 alpha

  • Process type plug-ins may have a Preview button. Analyze plug-ins would not normally have a Preview button.
  • Analyze plug-ins may return text or numeric output for each selected track. If a process type plug-in returns non-audio data, the plug-in ends execution. This means that a process type plug-in returning text or numeric output can return once only (useful if displaying a help screen, and usually desirable when displaying error messages).
  • Analyze type plug-ins can return labels, process type plug-ins cannot.

When to use / not use a Preview button

The Preview button should only be used in cases where the preview will reliably match the result of processing the selection.

Due to a limitation in Audacity’s “preview” feature, effects that change over the duration of the processed selection will usually not preview correctly.
The Nyquist Prompt effect always has a preview button. This allows code to be tested to see if it is appropriate to use a preview button.

An example of an effect that would preview incorrectly is the “Adjustable Fade” effect.
When applied with the OK or Debug button, the fade will be applied to the entire selection.
When previewed, the fade would occur over the duration of the preview.
Obviously, if the selection was 2 minutes long and the preview 3 seconds, a 2 minute fade will sound completely different from a 3 second fade, so it is not appropriate to include a preview button in this effect.

It will probably be possible to work around this limitation in later versions of Audacity, but currently not.

The new preview button should be available in nightly builds for Windows / Mac OS X from 8th October 2014, and for all platforms if building from the current SVN development code.

This information will be added to the wiki in due course.

I notice though that you can physically add a button to an Analyze effect by adding

;preview enabled

I was expecting that code would have no effect.

I updated the Manual for the button in Nyquist Prompt. Unfortunately the commit message omitted that this button had been added. I only noticed because I happened to see your post.

Should a Preview button be added to Nyquist Generate Prompt ?


Me too. I don’t think that is supposed to happen.
If a plug-in changes (processes) the sound then it should be a “process” effect.

Looking at the code, I see that Leland has enabled it for all Nyquist plug-ins.

I can see that being useful for some “generate” type plug-ins, but it should be noted that if multiple tracks are selected, the preview only generates one track.
What preview actually does is to mix a few seconds from all selected tracks, then apply the code to the temporary mix track. This is not the same as generating into multiple tracks and then mixing.

My current thinking is that we should leave it as it is for now, but recommend that Preview should normally only be used for process effects.

Plug-in writers need to exercise caution when adding a Preview button. For example, with this code:

(if (not (boundp '*scratch*))
    (progn (setf *scratch* 1)
      (osc 80 test))
    (osc 70 test))

When this is run on multiple tracks, the first track gets a tone at MIDI note 80 and the rest get MIDI note 70.
If Preview is run, then SCRATCH gets set, so then all tracks get MIDI note 70.

I expect that many other “gotcha’s” will appear as this feature gets used, so it is for the plug-in writer to exercise caution.

OK so if I select one track or multiple, then preview Risset Drum, all I hear in the preview is Risset Drum. The Risset Drum is generated in all selected tracks. However the Preview sounds like just one risset drum playing, not four drums. Is that all as expected? It’s still more useful than not having Preview for generate I think.

OTOH I think Preview should be disabled for Analyze effects, if they are incapable of returning audio.


So can that be generalised as “Preview should not be used on multiple tracks”? Is it generally speaking desirable that Preview sets SCRATCH?


Certainly a plug-in of any type that is incapable of returning audio should not have a preview button. For example, my “Quick Calculator” plug-in is defined as a “generate” plug-in (because that’s currently the only type that does not require a selection) and it makes no sense for that to have Preview.

Yes, that is expected, and is the limitation that I was referring to.

Yes I agree that it is useful when synthesizing sounds, especially complex or musical sounds where the user may well want to tweak the parameters.
I’m not sure that I’d want it on simple tone generators or Click Track, though if there is a lot of demand then we could consider doing so. I don’t want to add features “just because we can” :wink:

For “process” effects, it usually will not matter if one or multiple tracks are selected. In most cases, applying an effect to tracks individually will be the same as apply the effect to a mix. However, there are exceptions, such as compressors and limiters. This also applies to the built-in compressor effect, though no-one appears to notice or complain.

I don’t think this is a case of “shouldn’t do it”, but a case of the plug-in creator being aware of this caveat and making a decision accordingly.

The point of that code example is to illustrate that Preview runs in the same execution instance as “OK” or “Debug”.
With “OK” (and “Debug”), the plug-in code is parsed, then run, then exits.
With “Preview”, the plug-in code is parsed, then runs, but remains “open” so that it can be adjusted and run again. Nyquist does not exit until it is run with OK, Debug or is cancelled. This is the behaviour that we want because we want the effect window to remain open after previewing. Again this is just something that plug-in writers may need to be aware of.

I’ve updated the first post to say that “Analyze plug-ins would not normally have a Preview button.”

If an analyze plug-in is given a Preview button, but does not return audio (for example it returns text), then the result is a bit odd (but harmless).
On clicking Preview, the mix of the first few seconds is analyzed and returns the result, then the preview mix is played, then the selected track(s) are analyzed in turn returning their results. I can’t think of any situations where this behaviour would be wanted, but perhaps there is one.

Agreed, the generated tones are often only one track anyway.
There are some problems though.

  • A random effect (e.g. arpeggiator or surf LFO) would not return the same sound as heard in the preview.
  • will the durations be handled correctly?

OTOH I think Preview should be disabled for Analyze effects, if they are incapable of returning audio.


Analyze can return audio. My latency-info for example can return a sample sound fitted to the test.
The actual problem is that no extra track is returned like in the generate effects.
The original should indeed not be modified but an audio track might still make sense.
I have here a plug-in that transfers the selection into an audible spectrum.
On Windows, I can use the play feature to listen to the spectrum, while the message box returns the 10 highest peaks and the debug screen shows all like in the plot-spectrum export.
If the “Audibstrum” is passed to Audacity, this should actually generate a new track imo.

The preview feature makes here certainly sense as it allows more efficient parameter choosing (and there are a lot, some exclusively for audio as target output, e.g. contrast/whitening)

Therefore, I think the preview should be available in all effects.
What’s more, the new code should not impose restrictions on the returned value or their number.
For instance:
“ReplayGain” is a process plug-in and can either return a value or normalized audio for each track.
With the restriction, only the value for the first track is displayed.
It is of course desireable that a help screen should only show up once.
However, this should be done per either a help button, or with a predefined help stream.
We’ve already standard-output and similar ones for debug, errors and trace (which all end in the debug window).
If we define help-output, the desired text would be send by e.g.

(format *help-output* "No help available..."

The Nyquist-audacity interface would realize this and stop execution after one message box–the same way it does in 2.0.7 alpha.
Another advantage could be that the help text could as well be passed to e.g. the standard browser.

Let me summarize the effect of preview for two typical effects:

Proces: ReplayGain
Preview with Analyze: replaygain value for all selected tracks (very useful)
Analyze: Only first track returned (bad)
Preview with Normalize: Tracks are handled as down-mix (makes only sense if the tracks are not mix-downs themselves)
Normalize: as expected (the post-down-mix might be different from the preview, I suspect)

Analyze: Wavestats
Preview: Statistics for all selected tracks (good, for this tool at least)
The bad thing is that the selection is previewed inspite of the fact that a message box is returned (after ok).
I wonder where Audacity catches this sound although it is not the last statement?
If I place s at the end and modify it, it is correctly previewed but not if it is modified or destroyed before the text message–it just plays as if nothing had happened…

Actually, my last post was incorrect. That was from a test running an analyze type plug-in from the Nyquist Workbench.
What I’m seeing when running an actual “Analyze” plug-in (from an installed script file) is that when clicking on Preview, it analayzes the preview mix, then plays the preview mix, then stops.

@Robert: Do you have a nightly build installed? I think you need to try this. I’m not sure that Preview makes sense with Analyze type plug-ins.

Just to say, although there are limitations, I think that having Preview available (even if in the end is only for process type plug-ins) is a very welcome addition.

For generate type plug-ins, yes the durations should be handled correctly. Unlike process and analyze plug-ins, the environment is not warped to the selection length, so “1 second” when generating is still “1 second” when previewing.

If I add a Preview button to “Regular Interval Labels” on Windows, Preview plays the Preview selection then does nothing else.

If I choose “Label Interval” in that plug-in and make that interval longer than the waveform selection, I see the error message (which states the selection length as the preview length) then when I OK the message I hear the preview then nothing else happens.


Yes indeed, if it is available for all types :wink:
Let me show you what I mean.
As I’ve mentioned before, I’ve written a plug-in that emulates the plot spectrum but has an audio output, rather than a visual one.
It’s very easy to set the perfect values when the preview option is available.
Here’s a 3 min plus demonstration how one can work with the plug-in:

Note: Eventually, I’m only interested in the debug output in order to copy it to Excel. The actual audio spectrum is therefore undone.
However, the user can select another type of output (after he’s all set up with the preview). That is, he can display the peaks, spectrum flatness, centroid etc. in the message box–or hit escape if he only wanted to listen to the frequency distribution.

I think the plug-in is more suited for the Analyze menu than the Effect menu.

A simpler example might be a plug-in that shows the peak or Rms value, preview delivers the values for all selected tracks as if they were mixed.
Note: the preview should of course behave like in the process plug-ins and not play the original mix after displaying text.
Also, I think the preview for only one selected track should take the sample rate of this track and not the project rate. Otherwise, the returned audio is not comparable to the preview.
I noticed this while preparing the above demonstration. The sample rate of the “somewhere over…” track was 10240 (in order to display integer Hz-steps in the output) and the project rate the usual 44.1 kHz. I had to change the latter to the track’s rate to get the same audio output.

The preview is a wonderful expansion for Nyquist plug-ins (and the prompt), especially for single tracks.

Yes that is what “appears” to happen.
Nyquist does actually analyze the preview mix and returns the labels (specially formatted array of numbers and text), but Preview ignores the returned labels because we are not applying the effect. Audacity only handles returning data to tracks (audio or labels) on OK or Debug (otherwise it’s doing the effect, not just previewing it).

Have you tried it with a Preview button?
If so, does it work as you expect?
If it does, then that would seem to be a valid use of Preview in an analyze plug-in.

Yes, I’ve of course tried the nightly built prior to post any comments.
The mp3 above should show the actual procedure. Each time a pseudo-chirp is played, that’s the preview (alt-v)
The original recording is not much longer than this file, I just truncated some silent gaps inbetween screen reader outputs. With preview enabled, the work is much more efficient.

This is particularly true for filter plug-ins, e.g. finding the right notch frequency.

It would be nice if there were a special variable “preview-mode” with T and NIL.
In this fashion, we would be able to present the right kind of output, either for preview or OK/Debug.
For instance:
The sound finder could tell on preview could display how many labels will be created with the current threshold etc and OK would return the labels.
The program code would still be backwards compatible since the preview branch is never executed (the *preview-mode" is unbound).

I guessed that was happening but found it very difficult to follow the screen reader at that speed - I guess it takes practice.

I think that would require quite a significant rewrite of the Audacity plug-in interface, but perhaps worth keeping in mind for “version 4”.