Patch

节点编辑器：添加、连接和查看节点，并观察实时数据。

Patch（节点编辑器）#

你通过把节点连接在一起来搭建演出。数据沿着连线从左向右流动。有数据流过的连线会发光并显示粒子流；空闲的连线是细细的灰线。

Patch 顶部栏#

Patch 和其他面板使用相同的框架：

齿轮栏（左侧）：齿轮会在侧边面板中显示 Patch 自己的设置（Appearance，例如节点吸附）。再按一次，或选中一个节点，就回到节点属性。
节点图上方的顶部栏：
- ◂ BACK 从 Group 或 Cue 内部退出一层；在最上层时，它会一步一步退回你之前打开过的界面。
- 标题显示你所在的位置：PATCH ▸ group ▸ …。
- 标题下面是演出名称、节点数量，以及你当前在哪个内部（例如 "inside cue Drop FX"）。
底部的 Close 和 BACK 作用相同。

All Nodes（未选中任何节点）#

没有选中节点时，属性面板（停靠或浮动）显示 Node Properties - All Nodes：演出中的所有节点以树状列出，分为 Sources · Controllers · Devices + Routing · Logic · Outputs 几组（每组内按字母排序，并显示数量）。有内部的节点（Group，或内部有触发器的 Device / Router / OSC Input）会带一个 ▸：点击它，或双击这一行，就能展开里面的内容，无论嵌套多深。在内部，节点按连线排列：一个节点位于为它提供数据的节点下面（Script 连到 Graphic 时，Graphic 显示在 Script 下面），和画布上一样从上到下排列。在 Search 框中输入，可以列出任意层级中所有匹配的节点（按名称或类型），并显示每个节点所在的内部。在 Group、Cue 或其他内部里面时，树只列出这一层的节点（标题为 Inside Cue …），按连线顺序排列；按 BACK 退出后可以再次看到整个演出。每一行显示节点的颜色、名称（设置了 Description 时显示 Description；被旁路或停止时变暗）和类型，以及内部有多少个节点。点击一行即可跳到那个节点：Patch 会进入它所在的内部并选中它。添加、删除、重命名和旁路的变化都会自动反映在树上；用滚轮可以滚动它。

节点标题栏控件#

每个节点标题栏的右侧都有：

● 绿点：正常。点击即可 Bypass（变成琥珀色，节点变为透明：数据原样从输入流到输出；节点上会画出一个旁路箭头）。
■ 停止方块：点击即可 Stop（红色）：节点完全静音，不传递任何数据。
▶ 播放（Script 和 Action 节点）：手动测试触发这个节点。

节点类型#

节点	作用
Source	接入一个网络（ProDJLink / TCNet）、Timecode Generator、时间码输入（LTC In / MTC In / Art-Net TC In）或 Test Generator。输出包含所有设备的数据包。
Device	按 Device ID 从数据源的数据包中选出一台设备 → 单个数据帧。（以前叫 "Selector"。）它的 Function 也可以把它变成 Internal Player（播放本地媒体）。双击可以打开它的动作内部：一个私有的 Patch，其中 Data 块携带这台设备的输出。在里面连接 Data → Trigger → Action（→ Script…），每条链路的末端（输出没有连线的任何节点）都会在 Device 节点上变成一个额外的输出引脚，可以在主 Patch 中继续往下连。如果把链路连到内部的 Output 块，它的数据键会被添加到节点的主输出中。引脚名称：设置了 Description 时用 Description，Action 用它选中的动作，否则用节点标题。
Trigger	在数据满足条件时触发（见 §4）。
Script	对数据帧运行 JavaScript（见 §6）。
Action	在触发器触发时做某件事（见 §5）。
输出（发生器）	MIDI · MIDI Clock · MTC · LTC · Click · OSC · UDP · HTTP · MSC · CSV Logger · Art-Net · Art-Net TC · sACN · Ableton Link · Ableton Live · TCNet，见 §8。
Timer	预设为按固定间隔触发的 Trigger（§4）。
Router	8 进 / 1 出；选择一个输入。有 Name。双击会打开一个和 Device 节点完全一样的动作内部（内部每个 Action 对应一个额外的输出引脚）。
Matrix	8 进 / 4 出，有 4 个可调用的预设。有 Name。
Data Generator	时钟 / 已用时间 / 固定值 / 随机值、Mix Analyzer、Tone Monitor、DMX Input（来自灯光控台的 Art-Net / sACN）和 PSN Receiver（跟踪位置）。
Graphic	一个绘图面。连接进来的 Script 用 `g.*` 在上面绘图（见 §6）。有 Name、Width、Height。
Delay	延迟流经它的任何数据。时间 = 固定的毫秒数，或从数据键实时读取（例如 `beat.msToNextBeat`）。
Countdown	倒计时到一个 Duration（由它的 Start · Stop · Reset 引脚或 Command 弹出菜单启动 / 停止 / 重置）、从数据键读取的时长、一个 Time of Day、下一个 Schedule 项目或播放器的下一个 Cue。发布 `countdown.remain`（H:MM:SS）、`remainMs`、`done`、`running`、`warning`、`label`。
Counter	在每个引脚所连信号的上升沿 Up / Down / Reset 计数，带 Min / Max / Clamp / Wrap。发布 `counter.value`。
Timecode Offset	把播放器的时间码偏移 ± HH:MM:SS:FF 后重新发布（所有播放器、一台播放器，或每台播放器不同的偏移），这样下游的每个输出（LTC、MTC、Art-Net TC、TCNet、Cue）看到的都是偏移后的时间。
Group	一个嵌套的子图：把杂乱的部分折叠成一个节点，让 Patch 更整洁。4 个输入 / 4 个输出引脚。双击可以打开它；在里面，Inputs 和 Outputs 端点块对应 Group 的引脚。Close Group（底部）返回上一层；标题条显示路径（Patch ▸ Group…）。Group 可以嵌套，会随演出一起保存，里面的一切都和最上层一样运行（包括数据源、脚本、图形和动作）。

把节点移进 Group：有两种方法：把节点拖放到 Group 节点上（它们会被折叠进去，彼此之间的连线保留），或者剪切（⌘X / 右键）→ 双击进入 Group → 粘贴（⌘V / 右键点击空白处）。复制 / 粘贴（⌘C/⌘V）用同样的方式在任何地方克隆一组节点，选中范围内部的连线会保留；跨越选中范围边界的连线会断开（通过 Inputs/Outputs 块重新连接）。剪切移动的是原始节点，所以只能粘贴一次；复制粘贴的是克隆（Group 本身可以剪切 / 移动，但还不能深度复制）。

节点会根据名字自动调整大小（有合理的上限）；Graphic 节点保持手动设置的大小。

添加节点 = 右键。 菜单分为三个子菜单：Add Source（ProDJ Link · Test Generator · Data Generator）、Add Processor（Device、Trigger、Timer、Action、Script、Delay、Operator、Countdown、Counter、Timecode Offset、Router、Matrix、Group、Graphic、Viewer、Program）和 Add Output（输出按类型分组：Audio、Timecode、MIDI、Network、Lighting、Video & Media、Show Control、On Screen、Utility，每组内按字母排序），另外还有针对节点的 Duplicate/Cut/Copy。合适时，新节点会从点击的节点自动连线。右键点击空白处会打开同样的添加菜单，新节点会放在现有 Patch 右侧的空白处，不连线。底部只有一个 Close 按钮（旧的 Add 按钮已经去掉）：在浮动的 Patch 窗口中，它会把 Patch 停靠回去；在主窗口中，它预留给将来返回应用的导航。

检查器（节点属性）#

设置行的使用方法（适用于每个侧边面板：节点属性、窗口设置、播放器和路由器面板）。每项设置是一条细长的行：左边是名称，右边是值，最右边的 ↺ 用来恢复默认值。

开 / 关： 点击这一行即可切换。
有范围的数字： 一个滑块。在滑轨上点击或拖动；点击数字可以输入精确的值。
其他整数： − n +。点击 − 或 +，或点击数字直接输入。
选项： 点击值旁边的 ▾ 打开菜单（当前选项带勾）。
文字： 点击值即可原地编辑。按 Return 或点到别处会保留修改，按 Esc 取消。右侧可能有一个辅助按钮（例如 NOW）。
颜色： 点击色块。
文件： 点击文件名来选择一个文件。
动作： 点击按钮。
多行的备注和脚本仍然使用大的文本框。

选中一个节点会显示它分组后的设置。前两组默认展开；下面的组一开始都是折叠的（Live Data monitor 总是在最底部）。点击组标题可以展开 / 折叠。每行的 ↺ 会恢复默认值。组太多放不下时，在设置区域上滚动滚轮（右边缘会出现一个细滚动条）。

Live Data monitor#

检查器底部实时显示进入这个节点的数据。下游用到的数据键会显示为蓝色，并沿整条链路向上追踪。

搜索框也会筛选这个列表，按数据键名称或当前值匹配（例如输入 "cue" 或 "5B"）。
用滚轮滚动列表。
双击一行 → 在 Patch 的位置打开全屏的 Value Editor（和脚本编辑器风格一样）：在你点进去之前，值都是实时的；按 Enter 确认；底部有 Copy Value / Copy Key / Insert into Script / Revert to Live / Close。
覆盖：按 Enter 后，修改过的值会在每一帧替换节点输出中的实时值；重新输入和实时值完全相同的值（或点 Revert to Live）会取消覆盖，编辑器重新变为实时。被覆盖的行显示为琥珀色，右侧有一个 ↺，点击即可恢复。下游的每个节点也会把这个数据键显示为琥珀色（↺ 只出现在拥有这个覆盖的节点上）。即使数据流停止（例如覆盖让上游节点被旁路），被覆盖的行也会一直列出，并且不受搜索筛选影响，所以总能找到恢复按钮。有生效覆盖的节点，在画布上的标题栏下方会显示一条琥珀色下划线。恢复只是停止强制，不会撤销最后写入的值。覆盖只在运行时有效，永远不会保存到演出文件中。
脚本编辑器打开时，右键点击一行会提供 Add "source.key" to Script 和 Add value to Script，两者都会插入到编辑器的光标处。
右键点击一行 → Add Trigger on this key、Add Script with this key（预先填好 output.<key> = <当前值>;；对于 setting.* / util.* / led.* / status.* 数据键，这表示设备会通过回写被保持在这个值；脚本编辑器会立即打开），或复制。
带颜色的 #RRGGBB 值（Cue 颜色）会用它们自己的颜色显示。
曲目有缓存的波形时，会出现一条波形。
双击 waveform.previewRef / waveform.detailRef 会在 Value Editor 中显示波形；metadata.artworkRef 会显示封面图。

Countdown、Counter、Timecode Offset（工具处理器）#

Add Processor 中的三个小节点。每个都会在节点表面显示实时值（倒计时到 Warning 时间会变成琥珀色，结束时变成红色）。

Countdown：引脚 Start · Stop · Reset → Out。

Count Down To：Duration（H:MM:SS、MM:SS 或秒）；Duration From Data Key（时长从 Start 收到的数据帧中读取，例如 beat.msToNextBar，单位为毫秒或秒）；Time of Day（按这台 Mac 的时钟，例如 22:30 或 22:30:00；到时后 Stay Done 或滚动到 Next Day）；Next Program Item（下一个 Schedule 时段；label = 艺术家）；Next Cue（Master 播放器或某台播放器的 Cue 列表，按播放器的速度计算；label = Cue 名称）。
Start = 运行 / 继续，Stop = 暂停，Reset = 回到完整时长并停止。At Zero：Stop（停在 0:00:00，done = 1）、Keep Counting（超时，剩余时间为负）或 Loop（重新开始；done 闪一秒，countdown.loops 计数）。
Pin Key 留空 = 通常的触发规则（Trigger 触发，或 trigger / cue / item / track .active 变为开）。输入一个数据键（例如 midictl.Pads.pad1），就会在这个数据键从关变为开时动作。
Command（Control 组）是一个瞬时弹出菜单（Start / Stop / Reset / Restart），检查器、Stream Deck、Companion、动作和脚本都可以用同样的方式控制它（<Name>.cd.cmd = "Start"）。
数据键（和所有数据一样带有所属节点前缀）：<Name>.countdown.remainMs、.remain（H:MM:SS，向上取整）、.remainS、.done、.running、.warning（剩余时间 ≤ Warning At）、.progress（0..1）、.label、.totalMs、.loops。

Counter：引脚 Up · Down · Reset → Out。Step、Minimum、Maximum、At the Limits（Clamp / Wrap / No Limit）、Reset To。Value 是一个普通设置，随演出保存，可以手动设置，也可以通过任何控制方式设置。数据键：<Name>.counter.value、.atMin、.atMax。Pin Key 和 Command 同上。

Timecode Offset：In → Out，放在 Source / Device / Router 和输出之间。Apply To：All Decks、One Deck 或 Per Deck（八个偏移字段，留空 = 不偏移）；对单台播放器的数据帧和整个 Source 数据包都有效。Offset +HH:MM:SS:FF / -HH:MM:SS:FF（也可以是 HH:MM:SS、MM:SS 或秒），帧按播放器自己的帧率或一个固定帧率计算。它会偏移 timecode.ms、重新生成 timecode.value、累加到 timecode.offsetMs，并且（Shift Deck Position Too 打开时）偏移 playback.positionUS，这样 LTC / MTC / Art-Net TC 输出在两种 Time Source 模式下都会跟随它。Wrap at 24 h（打开时）会像 SMPTE 预卷一样把负值变成 23:59:59:…。节点会添加 <Name>.tcoffset.ms。原有且仍然有用的： 路由器的 −/+ TC 偏移（LIVE 条，毫秒，只作用于这个路由器），以及每个时间码输出自己的 Offset 字段（只作用于这个输出）。Timecode Offset 节点是唯一能按播放器偏移它下游所有内容的地方。

文字变量： $COUNTDOWN（第一个正在运行的倒计时的剩余时间，否则为第一个倒计时的）、$COUNTDOWNLABEL、$COUNTER（第一个计数器的值），可以在 OSD 文字、UDP、Stream Deck 文字以及任何支持 $VARIABLES 的地方使用。