当前位置：首页 > news >正文

Audacity Nyquist插件开发：插件标头详解

news 2025/4/2 14:37:32

1 Audacity Nyquist插件开发：插件标头详解

文件头说明的通用格式为：

;keyword args

示例：

;name (_ "Name of Effect")

name表示该插件的名字，括号后的下划线_表示这个菜单和原有菜单之间要添加一个分隔符。

下面是一个较复杂的Nyquist插件(.ny文件)的文件头样例

;nyquist plug-in
;version 4
;type process
;name "High-Pass Filter"
;preview linear
;manpage "High-Pass_Filter"
;debugbutton disabled
;action "Performing High-Pass Filter..."
;author "Dominic Mazzoni"
;release 3.0.2
;copyright "Released under terms of the GNU General Public License version 2 or later.";control frequency "Frequency (Hz)" float-text "" 1000 0 nil

nyquist plug-in：说明这个文件是一个nyquist插件
version：指示nyquist插件版本
type：指定这个插件是哪个类型，最终的结果是决定该插件显示在哪个菜单下。

其他参数在下面详细介绍

1.1 必需的标头

标头	说明
`;nyquist plug-in`	将文本文档定义为 Nyquist 插件
`;name "name"`	设置插件的名称。
`;type "type"`	指定插件的类型。
`;version version`	指定 Nyquist 插件版本。

nyquist plug-in
告知Audacity“这是一个Nyquist插件”。通常这应该是第一行内容，由它定义文件的内容。
name
出现在 Audacity 菜单中的插件名称：

;name "name"

注意：对于要在 Chains 中使用的插件，不能使用冒号字符 “：” （因为它是 Chain 文本文档中的特殊字符）。

如果插件具有接口，则名称应以三个点结尾，以指示在应用插件之前需要其他用户作。无需额外用户作即可立即生效的插件名称末尾不应有点。

type
只有一个 “;type“ 行。
一个插件不能同时出现在多个 Audacity 菜单中，但可以编写多个名称相同但不同的 “;type“ 行。然后，每个插件将出现在相应的菜单中。不建议对多个插件使用相同的名称，通常应避免使用。

类型标头	特性	典型作用
;type analyze	插件显示在Audacity的“分析”菜单中。	- 分析所选轨道音频。 - 时长相对于所选内容长度。 - 代码会遍历每个所选轨道。
;type generate	插件显示在Audacity的“生成”菜单中。	- 生成音频。 - 时长是绝对的（1个“时间单位” = 1秒）。 - 无论轨道数量多少，代码仅运行一次。
;type process	插件显示在Audacity的“效果”菜单中。	- 处理所选轨道音频。 - 时长相对于所选内容长度。 - 代码会遍历每个所选轨道。
;type tool	插件显示在Audacity的“工具”菜单中。	- Nyquist宏/其他。 - Nyquist无法直接修改项目。

工具类型的插件通常是Nyquist宏，或者是不太符合前三种类型中任何一种的插件。它们也可能与其他类型之一结合使用：

类型标头	特性
;type tool analyze	显示在Audacity的“工具”菜单中，行为类似于“分析”类型插件。
;type tool generate	显示在Audacity的“工具”菜单中，行为类似于“生成”类型插件。
;type tool process	显示在Audacity的“工具”菜单中，行为类似于“处理”类型插件。

version
仅使用一行“;version” 。

所有新插件都应使用最新版本号，以便能够使用所有当前功能。版本行是必需的，这样Audacity才能正确运行插件，并且可防止在缺少必要功能的旧版Audacity程序中加载具有新功能的插件。

版本标头	特性
;version 1	滑块控件
;version 2	新增文本输入控件
;version 3	新增多项选择控件
;version 4	- 新增额外全局变量，用于从Audacity向Nyquist传递额外信息。 - 新增可选插件标头： - ;author（作者） - ;copyright（版权） - ;maxlen（最大长度） - ;mergeclips（合并剪辑） - ;preview（预览） - ;release（发布） - ;restoresplits（恢复分割）

1.2 显示信息标头

标头	说明
;author “text”	插件开发人员的名称。显示在 Manage 的 “About” 部分中。当效果按 “Publisher” 排序时也使用。
;copyright “text”	版权/许可声明。显示在 Manage 的 “About” 部分中。
;release version	插件的版本/版本号。显示在 Manage 的 “About” 部分中。

author
插件作者姓名。如果添加这一行内容，当在Audacity的“效果”菜单中按“发布者”进行排序或分组时，其文本内容会显示出来。作者姓名字符串必须用引号引起来。

 ;author "Name of Plugin Author(s)"

copyright
版权/许可条款的简短声明。对于随Audacity附带的插件，其必须与Audacity的GPL v2许可兼容。版权声明字符串必须用引号引起来。

GPL v2许可的推荐文本：

;copyright "Released under terms of the GNU General Public License version 2 or later"

额外的版权细节可包含在插件代码注释中，但不得与版权标头中声明的条款冲突。

 ;copyright "copyright text"

release
在“管理”>“关于”菜单中显示插件的发布版本号。

随Audacity附带的插件，其发布版本号等同于该插件上次更新时的Audacity版本号。

插件作者可以选择他们偏好的任何版本编号方案，但应确保插件的后续版本始终具有更新的版本号。如果版本号包含空格，则必须用双引号括起来。

以下任何一种形式都是有效的（不过一个插件中应该只有一个发布标头）：

release 1
release 0.0.1
release “1.0”
release “3.5 beta”

1.3 功能性标头

标头	说明
`;codetype type`	指定Nyquist代码使用SAL或LISP语法。
`;debugbutton option`	指定“调试”按钮是否可见。
`;debugflags flags`	设置调试消息的行为。
`;helpfile "path to file"`	显示一个“帮助”按钮，该按钮链接到插件帮助文件。
`;manpage "URL"`	显示一个“帮助”按钮，该按钮链接到Audacity手册中的插件帮助页面。
`;maxlen integer`	设置要处理的最大样本数。
`;mergeclips integer`	指定剪辑合并行为。
`;preview option`	指定插件预览选项。
`;restoresplits integer`	指定剪辑分割行为。

1.3.1 `codetype`

代码语法声明。可以是lisp或sal（小写）。

* 对于LISP语法的插件，这通常可省略，但对于SAL语法的插件则应始终包含。* 如果在Nyquist Prompt效果中未声明代码类型，Audacity会尝试从代码中推断正确的语法。* 代码类型只能是Lisp语法或SAL语法，不能两者混合。

 ;codetype type

1.3.2 `debugbutton`

显示或隐藏“调试”按钮。默认是显示该按钮，但对于随Audacity附带的插件，或其他被认为没有错误的插件，可以通过将其设置为“false”或“disabled”来隐藏“调试”按钮。

;debugbutton false

或

;debugbutton disabled

1.3.3 `debugflags`

debugflags标头	说明
;debugflags trace	设置`tracenable`（LISP）或`sal - traceback`（SAL），并且在有内容可显示时显示调试窗口。当显示调试信息对插件功能至关重要，或者在调试脚本时，这可能会很有用。
;debugflags notrace	禁用`tracenable`（LISP）/`sal - traceback`（SAL）。这会阻止在出错时自动打开调试窗口，除非按下了“调试”按钮。如果未按下“调试”按钮且出现错误，错误消息将被发送到Audacity的日志中。请注意，禁用`tracenable`会将调试输出限制为仅错误消息，几乎没有或没有额外的调试信息。
;debugflags compiler	将`sal - compiler - debug`设置为`'true'`。 SAL编译器的输出会打印到调试输出中。如果启用了调试功能（例如，通过单击“调试”按钮），可以在调试窗口中查看；否则会显示在Audacity日志中。
;debugflags nocompiler	将`sal - compiler - debug`设置为`'false'`。禁用来自SAL的编译器消息。只有调试和错误消息会打印到调试输出中。

这些标头可以与debugbutton标头结合使用，以实现多种行为。

debugbutton true, debugflags trace：按下调试按钮，或者Nyquist向调试窗口输出内容时，调试窗口会打开。
debugbutton false, debugflags trace：调试按钮被禁用，但当Nyquist向调试窗口输出内容时，调试窗口会打开。
debugbutton true, debugflags notrace：仅在按下调试按钮时，调试窗口才会打开。如果未按下调试按钮，出现的任何错误消息都会被发送到Audacity日志中。
debugflags compiler, debugflags trace（使用SAL语法时）：调试窗口会始终打开，以显示SAL编译器的输出。
debugflags compiler, debugflags notrace（使用SAL语法时）：仅在单击调试按钮时，调试窗口才会打开以显示SAL编译器的输出，否则输出会打印到Audacity日志中。
debugflags nocompiler, debugflags trace（使用SAL语法时）：调试窗口会始终打开，以显示调试和/或错误消息。SAL编译器的输出将被抑制。

1.3.4 `helpfile`

通过指定帮助文件的相对路径和名称，可以在插件的图形用户界面（GUI）中添加一个“帮助”按钮。由于只有当插件具备图形用户界面时才能创建该按钮，因此对于没有图形用户界面的插件，不应使用此标头。

;helpfile 文件路径

文件路径是相对于插件搜索路径而言的。通常，帮助文件在安装时应与插件放置在同一位置。为支持包含图像和/或媒体的HTML文件，帮助文件及其资源可以放在一个文件夹中，并将该文件夹包含在文件路径内。例如，如果帮助文件名为“my_effect.html” 且包含图像，那么该html文件和图像可以放在名为“my_effect_help” 的文件夹中，此时帮助文件标头应如下所示：

;helpfile "my_effect_help/my_effect.html"

如果找不到帮助文件，“?”按钮将不会显示。

1.3.5 `manpage`

这主要供随Audacity附带的插件使用。它与helpfile标头类似，不同之处在于它会在Audacity手册的搜索路径中查找帮助文件。与;helpfile一样，它应仅用于具有图形用户界面（GUI）的插件。更多信息，请参见手册位置。

;manpage URL

maxlen
用于指定“处理（process）”或“分析（analyze）”类型插件中要处理的样本最大数量。如果要处理的长度由插件而非所选内容的长度决定，这有助于进度条显示。对于专门为短选段设计的插件，它也可作为一种安全保障措施。以下示例将样本数量限制为100万个：

;maxlen 1000000

使用MAXLEN标头时，Nyquist全局变量LEN是“所选样本长度”和“MAXLEN设置的值”中的最大值。

在“处理（process）”类型的效果中，这可能会导致所选音频被截断为指定的样本数量。在这种情况下，如果超过“maxlen”，最好抛出一个错误，例如：

;maxlen 1000000(defun isok ();; Return true if selection is less than "maxlen".(let ((start (get '*selection* 'start))(end (get '*selection* 'end)))(<= (truncate (* *sound-srate* (- end start))) len)))