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

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
  告知Audacity“这是一个Nyquist插件”。通常这应该是第一行内容，由它定义文件的内容。

• name
  出现在 Audacity 菜单中的插件名称：

;name "name"

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

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

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

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

• version
  仅使用一行“;version” 。

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

1.2 显示信息标头

• 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 功能性标头

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

这些标头可以与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)))

1.3.6 mergeclips

允许Nyquist插件覆盖Audacity默认的“剪辑合并”行为。默认情况下，当效果（包括生成效果）应用于一个或多个剪辑边界，且返回的音频长度与原始所选音频长度不同时，Audacity会在返回音频的两端添加“分割线”。在所有其他情况下，返回的音频会“合并”到当前音频中。

此选项仅在插件跨剪辑边界（包括跨“分割线”）应用时适用。

1.3.6.1 剪辑合并选项

• -1：自动剪辑合并行为（默认）

;mergeclips -1

• 0：不合并剪辑。跨剪辑边界应用的效果不会合并到现有音频中（无论返回的音频长度是否与原始所选音频长度相同，返回音频的两端都会有分割线）

;mergeclips 0

• 1：始终合并剪辑。返回的音频将始终合并到现有音频中（不添加分割线）

;mergeclips 1

另请参阅“restoresplits”。

1.3.7 preview（预览）

提供效果预览选项。可以定义多个预览选项，以实现所需的行为。

1.3.7.1 预览选项

• enabled（默认值）：启用预览。

;preview enabled

• true：与“enabled”相同。

;preview true

• disabled：禁用预览。如果Audacity无法提供有意义的预览，则应禁用预览。对于影响所选内容内特定时间段的效果，可能需要这样做。

;preview disabled

• false：与“disabled”相同。

;preview false

• linear：通过在应用Nyquist代码之前混合所选音轨，为多音轨预览提供优化。此优化默认禁用。

;preview linear

• selection：预览时，Nyquist代码将应用于整个所选内容（而非仅应用于将预览的长度）。然后，Audacity的“预览”功能会播放处理后音频的前几秒。对于在所选内容持续时间内变化的效果，可能需要这样做。

;preview selection

1.3.8 restoresplits（恢复分割线）

允许Nyquist插件覆盖Audacity默认的“分割线恢复”行为。默认情况下，当效果（包括生成效果）跨一个或多个剪辑边界应用时，Audacity会在原始剪辑边界位置恢复“分割线”。

此选项仅在插件跨剪辑边界（包括跨“分割线”）应用时适用。

1.3.8.1 恢复分割线选项

• 1：恢复剪辑边界处的分割线（默认）

;restoresplits 1

• 0：不恢复剪辑边界处的分割线（剪辑合并）

;restoresplits 0

注意：目前Nyquist插件无法区分所选内容中的静音和“空白区域”，因此音频剪辑之间的间隙将被视为额外的“静音”音频剪辑。

另请参阅“mergeclips”。

作者声明：本文用于记录和分享作者的学习心得，可能有部分文字或示例来自AI平台，如：豆包、DeepSeek(硅基流动)(注册链接)等，由于本人水平有限，难免存在表达错误，欢迎留言交流和指教！
Copyright © 2022~2025 All rights reserved.