Conventions for Nyquist Plug-ins

Using Nyquist scripts in Audacity.
Post and download new plug-ins.

Conventions for Nyquist Plug-ins

Permanent link to this post Posted by Gale Andrews » Sat Oct 16, 2010 2:34 pm

Steve and I discussed off Forum about having a Wiki page (probably linked to off Nyquist Audio Programming ) that listed the GUI and code conventions expected in plug-ins listed on Download Nyquist Plug-ins and in Nyquist plug-ins distributed inside Audacity.

Although we want to be most strict with plug-ins distributed in Audacity, we don't want to discourage plug-in writers by being overly prescriptive, after all if a plug-in is "elevated" to distribution in Audacity, changes can be made at the time by the person committing the plug-in.

Anyway, I just started this thread in case we want to keep together any comments here before we start a Wiki page about "conventions". One thing I noticed in recent commits is that Vaughan is standardising capitalisation of titles of effect controls so that nouns are capitalised. I think we weren't quite sure if we should do this in Nyquist plug-ins, but I would suggest it would be good practice to do so from now on. So for example in Paraic's 78 rpm Curve Generator (which will at least be officially linked to) the final control would be "XML File Output Path" (if we kept that wording for it).

A lot of Nyquist plug-ins already distributed in Audacity don't follow this capitalisation convention, but that can be changed when they are modified.




Gale
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Providing help

Permanent link to this post Posted by Gale Andrews » Sun Oct 24, 2010 12:51 am

Providing help

Here are some suggested ideas about "providing help".

Help text on the ;info line should be reasonably limited; generally if it exceeds five lines, it may be too verbose.

If the plug-in is to be added to those distributed in Audacity releases, any ;info line text which explains the plug-in should be minimal, to accord with practice in built-in plug-ins.

More extensive help can be provided in a text file to be included with the plug-in file, or in "Help Screens" which can be selected via a control in the plug-in. Help Screens (where necessary) should be used if a plug-in is to be distributed inside Audacity. Text for each help screen should have a forced newline (\n or hit ENTER) at 50 characters. A new paragraph should be created by \n\n or ENTER twice. The maximum number of lines per screen is 25 lines, including empty lines. These conventions keep formatting as neat as possible at both 800 x 600 and very high resolutions where Nyquist message boxes may extend to 260 characters wide (See viewtopic.php?f=28&t=33824&start=40#p108016).

Plug-ins for distribution inside Audacity will be documented in the Manual. The extent of this documentation depends on the extent of help provided in the Help Screens. The Manual is a reference rather than a "how-to", so if short descriptions of controls are the only help needed, consider putting this documentation in the Manual and not including Help Screens. If the plug-in needs extensive examples of how to use the plug-in to achieve the desired result, that would require Help Screens.





Gale
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Outputting a text file/other data to user's home directory

Permanent link to this post Posted by Gale Andrews » Thu Oct 28, 2010 6:43 pm

The user's home directory is the appropriate place to write output data from Nyquist, for example a text file.

On all operating systems supported by Audacity, get-env can be used

Code: Select all
(or (get-env "HOME") (get-env "UserProfile"))


to return the user's home directory.

See viewtopic.php?f=39&t=42368&start=50#p108789 for details and the discussions that led up to it.

Note that Nyquist in Audacity currently cannot read environment variables containing non-ASCII characters. Therefore it may not return the correct directory in localised operating systems where the home directory contains non-ASCII characters.
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Plug-in headers

Permanent link to this post Posted by steve » Wed Dec 08, 2010 5:53 pm

The full format for the header information is as follows:
Code: Select all
;nyquist plug-in
;version version
;type type
;name "name"
;action "text"
;categories "text"
;info "text"
;control parameters
;codetype type
;debugflags flags


Of these, the first four are obligatory, so the minimum header must contain:
Code: Select all
;nyquist plug-in
;version version
;type type
;name "name"


I propose that the convention for "general release" plug-ins should also include "action" and "categories".

"action" is the text that is displayed while the plug-in is processing. If the processing is very quick then this is not displayed, though I would suggest that it is still a useful convention as (a) all current plug-ins use it, so it IS the current convention, (b) it may give a useful clue at to what the plug-in does for anyone examining the code, (c) if for any reason processing takes longer than expected, the process indicator will be displayed.

"categories" is not currently used in Audacity, though I believe that the intention is to reintroduce categories in the future, therefore I propose that the categories text should be included as a matter of convention.

"codetype" MUST be included if the plug-in is written in SAL.
If the "codetype" is missing, Lisp is assumed by default. Most currently available plug-ins are written in Lisp and do not have the "codetype" line.

I'm unclear about the ";debugflag" line, in plug-ins it does not appear to do anything :?

Full documentation of the plug-in header can be found here: http://www.audacity-forum.de/download/e ... ist-en.htm
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 34852
Joined: Sat Dec 01, 2007 11:43 am

Re: Plug-in headers

Permanent link to this post Posted by Gale Andrews » Wed Dec 08, 2010 11:20 pm

steve wrote:"categories" is not currently used in Audacity, though I believe that the intention is to reintroduce categories in the future, therefore I propose that the categories text should be included as a matter of convention.

Agreed. I think this is the link to LV2 category types which are recognised by Audacity's built-in plug-ins and by Nyquist and LADSPA plug-ins.

Plug-ins are not currently sorted unless you compile Audacity with EFFECT_CATEGORIES defined.

steve wrote:I'm unclear about the ";debugflag" line, in plug-ins it does not appear to do anything :?

Is this in SVN HEAD? If you recall this was discussed with Roger last month after he committed r10785. That fixed the problem that once you clicked the Debug button in a Nyquist effect, it would then always run in Debug in that session even if the user clicked OK.

However the fix means that "debugflags" now has no effect if there is a dialogue box for the effect - "OK" will always run the effect without debug and "Debug" will always show the Debug window. Although Roger said this was the "most unsurprising" behaviour, I think if a plug-in author has chosen to use "debugflags" that should be respected even if there is a dialogue (meaning that pressing "OK" or "Debug" gives you debug). Of course, I would expect the plug-in author to note the behaviour in the plug-in.

If we both agree, I think Roger would be amenable to have debugflags force debug even if user clicked OK.



Gale
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Re: Plug-in headers

Permanent link to this post Posted by steve » Wed Dec 08, 2010 11:36 pm

Gale Andrews wrote:Agreed. I think this is the link to LV2 category types which are recognised by Audacity's built-in plug-ins and by Nyquist and LADSPA plug-ins.

Yes, and that is a subset of http://lv2plug.in/ns/lv2core/
(subcategories of "plugin" in LV2 only. So, for example, "lv2:Template" is not used in Audacity)

Gale Andrews wrote: If you recall this was discussed with Roger last month after he committed r10785.

Thanks, I missed that one (extremely busy at work) - I'll look it up and investigate.
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 34852
Joined: Sat Dec 01, 2007 11:43 am

;info line attribution and Licence

Permanent link to this post Posted by Gale Andrews » Thu Dec 09, 2010 10:16 pm

The first two sentences in the ;info line should be the primary authorship of the plug-in, followed by "Released under" to provide the licensing. The licence must be GPL v2 ( or compatible with GPL v2) to be distributed in Audacity and to be hosted on this Forum or on other Audacity sites.

For example:

Code: Select all
   
;info "By Steve Daulton and Bill Wharrie. Released under GPL v2."


If the plug-in is a significant derivation from some other primary author's work, consider attributing that person by using "after" in the first sentence:
Code: Select all
   
;info "By Steve Daulton, after [plug-in] or [type of work] by David Sky". Released under GPL v2."


In the comments in the .ny file, give fuller authorship, date and licensing details as in this example:
Code: Select all
;; notch.ny by Steve Daulton and Bill Wharrie, September 2010
;; Released under terms of the GNU General Public License version 2
;; http://www.gnu.org/licenses/old-licenses/gpl-2.0.html


Full details of credits and changelogs can be also be added here.




Gale
Last edited by Gale Andrews on Sat Jun 21, 2014 6:32 am, edited 1 time in total.
Reason: The licence must be GPL v2 (or compatible with GPL v2) to be distributed in Audacity and to be hosted on this Forum or on other Audacity sites.
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Sat Dec 11, 2010 2:54 pm

Gale Andrews wrote:However the fix means that "debugflags" now has no effect if there is a dialogue box for the effect - "OK" will always run the effect without debug and "Debug" will always show the Debug window. Although Roger said this was the "most unsurprising" behaviour, I think if a plug-in author has chosen to use "debugflags" that should be respected even if there is a dialogue (meaning that pressing "OK" or "Debug" gives you debug). Of course, I would expect the plug-in author to note the behaviour in the plug-in.

If we both agree, I think Roger would be amenable to have debugflags force debug even if user clicked OK.


One plug-in that immediately comes to mind is "apropos.ny" http://audacity-forum.de/download/edgar ... tm#apropos
setting ";debugflags trace" seems to work in Audacity 1.3.12 on XP, but only partially works in Audacity 1.3.12 on Linux (shows debug window only the first time it is run), and does not work at all in Audacity 1.3.13 on Linux.
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 34852
Joined: Sat Dec 01, 2007 11:43 am

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by Gale Andrews » Sat Dec 11, 2010 9:41 pm

steve wrote:
Gale Andrews wrote:I think if a plug-in author has chosen to use "debugflags" that should be respected even if there is a dialogue (meaning that pressing "OK" or "Debug" gives you debug). Of course, I would expect the plug-in author to note the behaviour in the plug-in.

If we both agree, I think Roger would be amenable to have debugflags force debug even if user clicked OK.


One plug-in that immediately comes to mind is "apropos.ny" http://audacity-forum.de/download/edgar ... tm#apropos
setting ";debugflags trace" seems to work in Audacity 1.3.12 on XP, but only partially works in Audacity 1.3.12 on Linux (shows debug window only the first time it is run), and does not work at all in Audacity 1.3.13 on Linux.


OK, I've asked Roger (Cc'd to you) if he can make ;debugflags trace force debug in GUI plugins even when you hit OK.



Gale
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Maximum height of plug-in interface

Permanent link to this post Posted by Gale Andrews » Mon Jan 31, 2011 1:07 am

To accommodate the minimum Audacity-supported resolution of 800x600, the plug-in interface should have a maximum of 12 controls assuming there was only a single line of ;info text. For two or three lines of ;info text, maximum number of controls is 11, for four or five lines, maximum controls is 10 and so on.



Gale
________________________________________FOR INSTANT HELP: (Click on Link below)
* * * * * Tips * * * * * Tutorials * * * * * Quick Start Guide * * * * * Audacity Manual
Gale Andrews
Quality Assurance
 
Posts: 14615
Joined: Fri Jul 27, 2007 12:02 am

Next

Return to Nyquist



Who is online

Users browsing this forum: No registered users and 1 guest