Conventions for Nyquist Plug-ins

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

If you require help using Audacity, please post on the forum board relevant to your operating system:
Windows
Mac OS X
GNU/Linux and Unix-like

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Tue Apr 19, 2011 8:32 pm

If possible, there should be a comment near the top of the plug-in code to indicate the minimum Audacity version required.

A suitable location could be directly below the copyright notice.
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Mon May 02, 2011 5:58 pm

Plug-in comment block.

It will be generally useful if the following information can be included within the plug-in header section:

Code: Select all
;; <Plug-in name> by <author> <date>
;; <additional credits>
;; Released under terms of the GNU General Public License version 2
;; http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
;; <additional notes>
;; <release notes>
;; Audacity version requirements.


It is recommended that the license terms are also briefly mentioned in the ;info line of the header.
For example:
Code: Select all
;info "By <author's name>nReleased under GPL v2


If the license terms are not GNU General Public License version 2, then it is highly recommended that the plug-in notes this in the plug-in interface as well as in the comment block.

A typical Nyquist plug-in header might look something like this:
;nyquist plug-in
;version 3
;type process
;name "My Effect"
;action "Processing..."
;info "By A.Person http://mydomain.comnReleased under GPL v2

;; my-effect.ny by A.Person April 2011
;; Pre-process function by A.N.Other
;; Released under terms of the GNU General Public License version 2
;; http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
;; Thanks to J.Doe for writing the help file.
;; v 0.1 January 2011
;; v 0.2 February 2011: Includes stereo track support.
;; v 1.0 April 2011: Add compatibility for Audacity 1.3.4
;; Requires Audacity 1.3.4 or later

;control ........
;control ........



;categories
This optional line turns on plug-in categories. Categories are only experimentally implemented, so not available in builds currently released by Audacity. Users who can compile Audacity can turn on categories by uncommenting #define EFFECT_CATEGORIES in src/Experimental.h, but the feature may be subject to change in the future.

If you include the ;categories line, it should be in the form:

Code: Select all
;categories "<URI>"


where <URI> is one of the LV2 or Additional Audacity-Specific categories listed inside quotation marks on
http://wiki.audacityteam.org/wiki/LV2_C ... categories .
Last edited by steve on Fri Apr 24, 2015 3:30 pm, edited 4 times in total.
Reason: Link to supported categories URIs for anyone wishing tio add them
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Mon Aug 22, 2011 4:05 pm

;control variables:

As it is likely that Nyquist plug-ins will be available in Chains in the very near future, the variables used in the ;control widgets will be exposed to users.
It is therefore recommended that the ;control variable names should be humanly readable.

For example:

Select Command_002.png
cryptic ;control parameters
It is not clear to the user what the parameter values are.
Select Command_002.png (23.92 KiB) Viewed 9254 times


Select Command_003.png
;control parameters more obvious.
Select Command_003.png (17.52 KiB) Viewed 9254 times
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Tue Sep 13, 2011 5:23 pm

Indentation:

It is recommended that code indentation is applied using spaces rather than tabs. When viewed in a text editor, tabs will be displayed according to the tab setting in the editor, which may be set very differently from the settings in the editor that was used to write the code, so the layout may be very different from what was intended.

Indentation is very important for the readability of Lisp code. There is a concise guide to the proper way to indent Lisp code here: Indenting Common Lisp
Last edited by steve on Fri Apr 24, 2015 3:30 pm, edited 2 times in total.
Reason: updated link
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Tue Jul 03, 2012 6:06 pm

steve wrote:As it is likely that Nyquist plug-ins will be available in Chains in the very near future

As of Audacity 2.0.1 Nyquist "process" effects are available in Chains.

For effects that are likely to be used on a single file it is often helpful, in the event of invalid user input, to cancel processing and return an error message so that the user can see what they have done wrong. However, for batch processing a large number of files this could be inconvenient, so when designing plug-ins that are likely to be useful for batch processing it may be worth considering how best to handle error messages. One possibility would be to provide a user control to select whether or not to show errors, for example:
Code: Select all
;control messages "Show messages" choice "Yes,Errors Only,None" 0

And then, handle the error message with something like:
Code: Select all
(if (and (> (length error-message) 0)
         (= messages 2))
  (s-rest 0)
  (if (> (length error-message) 0)
      (format nil "Error.~%~a" error-message)))

What this does is to check the length of 'error-message' [which would be initialised to 0 to indicate no errors], and to check the status of 'messages'.
If (length error-messages) is greater than 0 [there are errors] and 'messages' is set to 2 [don't show error messages] then a null sound is returned, thus suppressing any error messages and not processing the sound.
If 'messages' is not set to 2 and there are errors, they will be displayed.
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Tue Jul 03, 2012 6:25 pm

steve wrote: There is a concise guide to the proper way to indent Lisp code here: Indenting Common Lisp


A few, hopefully useful, examples:

Code: Select all
;; Line up the bindings in LET special form
(let* ((symbols (mapcar #'compute-symbol l))
       (spaces (mapcar #'compute-space symbols (cdr symbols))))
  (when (verify-spacing symbols spaces)
    (make-spacing permanent spaces)))

Code: Select all
;;; Three semicolons often used to explain a function.
(defun f (x)
  (when (< (g x) 3)
    (h x 2)))

Code: Select all
;; Line up the bindings in DO special form
;; and line up the test expression with the first binding
(do ((i 1 (1+ i))               ; first binding
     (j (length l) (/ j 2)))    ; second binding
    ((= j 0) i)                 ; test expression and result value
  (iterate i j)                 ; body of DO loop
  (when (= (f x) 4)
    (setf *level-number* 0)))   ; end of DO loop

Code: Select all
;; Put test expression on same line as WHEN or UNLESS special forms.
;; If multiple expressions, indent and align.
(when (= (f x) 4)
  (setf *level-number* 0)
  (unless *do-not-reinitialize*
    (reinitialize-global-information x)
    (reinitialize-local-information))
  (top-level x))

Code: Select all
;; Indenting and commenting an IF statement.
(if (< (g x) 2)       ; is it sufficiently small?
    (top-level x)     ; if so, abandon everything
    (h y))            ; otherwise try again
 
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by Robert J. H. » Tue Aug 14, 2012 8:05 am

I write my code in the common-or-garden Notepad text editor. Notepad ++would of course be a better choice, but a lot of functions are not accessible for visual impaired people and a lot of times the screen reader skips over some lines.
OK, so the editor is my choice for programming.
What is really annoying: when I open a Plug-in from the Audacity distribution or from this Web page, all line breaks are discarded by the editor. I always have to copy the content to word and copy it back again into the editor. Would it be a draw-back for the other platforms to use the Windows Standard for line-breaks? Besides, Notepad++ knows such a menu point for this conversion.
I do not use indentations, when I am writing code, for the simple reason that the navigation is much easier for me in this way. I am fully aware that other people could profit from a proper indenting when reading the code.
I wonder if not a plug-in could be written, that inspects and corrects a user-written plug-in. It could execute such tasks as:
- control the header for the right order and if a line is missing.
- examine the number of characters in a quoted string from the header (< 50)
- look for the ratio of info-lines and controls.
- write all keywords (like those found with Edgar's Apropos plug-in) in upper case.
- setting the right number of semicolons.
- apply indentation for Defun let do if etc.
How do you think about this proposal? Any suggestions?
Best regards
Robert J. H.
 
Posts: 1813
Joined: Thu May 31, 2012 8:33 am
Operating System: Windows 7

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by steve » Sat Aug 18, 2012 5:36 pm

Robert J. H. wrote:What is really annoying: when I open a Plug-in from the Audacity distribution or from this Web page, all line breaks are discarded by the editor.

NotePad is a very primitive text editor.
Wikipedia states "most modern editors can read and write files using at least the different ASCII CR/LF conventions. The standard Windows editor Notepad is not one of them."

Personally I don't think that plug-in authors should be required to convert their plug-ins into Windows format simply because the default Windows text editor can't handle CR or LF.

On Windows XP, a simple way to convert the new lines to CR+LF (Windows format) is to open the file in WordPad then save it. I've not tested in later versions of Windows.

Alternatively, new lines may be converted to Windows format from the command line using:
Code: Select all
TYPE unix-file-name | FIND "" /V > dos-file-name


There is also a program called CrLf by Joachim Gehweiler that can convert the new line format http://audionyq.com/?p=182 This is a JAVA program that requires JAVA to be installed on the computer.

Of these, opening in WordPad and then saving is probably the easiest and quickest.

Robert J. H. wrote:I do not use indentations, when I am writing code,

That's completely understandable. Good indentation helps readability for sighted users but clearly of no help at all for visually impaired users. David Sky (who was blind) never used indentation in any of his plug-ins.

Robert J. H. wrote:I wonder if not a plug-in could be written, that inspects and corrects a user-written plug-in. It could execute such tasks as:
- control the header for the right order and if a line is missing.
- examine the number of characters in a quoted string from the header (< 50)
- look for the ratio of info-lines and controls.
- write all keywords (like those found with Edgar's Apropos plug-in) in upper case.
- setting the right number of semicolons.
- apply indentation for Defun let do if etc.

I think that would be very difficult to implement.
Nyquist is not very good at manipulating text - that's not what the language was designed for. Checking the syntax for every function and macro would require a huge amount of code and in my opinion would not be worth the effort.

Keywords are generally best written in lower case as editors that provide LISP syntax highlighting usually require lower case keywords.
9/10 questions are answered in the FREQUENTLY ASKED QUESTIONS (FAQ)
steve
Senior Forum Staff
 
Posts: 43908
Joined: Sat Dec 01, 2007 11:43 am
Operating System: Linux *buntu

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by PGA » Sat Aug 18, 2012 8:09 pm

steve wrote: On Windows XP, a simple way to convert the new lines to CR+LF (Windows format) is to open the file in WordPad then save it. I've not tested in later versions of Windows.

That works fine in Windows 7 (and so presumably would also work in Vista as well)
PGA
 
Posts: 693
Joined: Thu Jan 19, 2012 9:16 pm
Operating System: Please select

Re: Conventions for Nyquist Plug-ins

Permanent link to this post Posted by Gale Andrews » Sat Aug 18, 2012 10:18 pm

@Peter (PGA) - I deleted your post as requested where the quote added "word rejected". How did you add the quote? It looked as if that message just became corrupted somehow.


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

PreviousNext

Return to Nyquist



Who is online

Users browsing this forum: No registered users and 2 guests