Orca 实操教程：用纯文本 Livecoding 驱动 MIDI、OSC 与 UDP 外部音频软件

本教程是 Orca 官方《Tutorial》文档的实战展开，面向第一次接触 Orca 的开发者与音乐制作人，讲解如何把 Orca 的网格程序与 Pilot、Ableton Live、Sonic Pi、Bitwig、VCV Rack 等外部音频/视觉软件接通。读完本文，你将掌握 Orca 的 ;（UDP）、:（MIDI）、=（OSC）三类 IO 算子的实战用法，以及各平台虚拟 MIDI 桥的搭建步骤，并能用官方的 Golf 小例子验证 Orca 的求值顺序与 bang 机制。

准备工作：为各平台搭建虚拟 MIDI 桥

Orca 本身不发声，它通过 MIDI / OSC / UDP 把音符与控制器消息发送给其他软件。因此，第一步不是安装合成器，而是建立一条"虚拟 MIDI 通道"，让 Orca 的输出能被目标软件接收。官方文档按平台给出了三种方案：

• OSX：在音频 MIDI 设置中启用 IAC 虚拟 MIDI 总线（在 macOS 的"音频 MIDI 设置"里创建 IAC Driver 设备），随后在 Ableton Live 等软件的输入下拉框中即可看到 IAC Driver(Bus 1)。
• Windows：安装 loopMIDI 虚拟 MIDI 驱动，启动后先创建至少一个虚拟设备，目标软件才能在下拉框中选择 LoopMidi 作为输入。
• Linux：使用 qjackctl（JACK 控制面板）配合 ALSA 虚拟 MIDI，下文 Bitwig 一节会给出完整流程。

从源码看，Orca 的 MIDI 输出通过 Web MIDI API 枚举系统设备并按下标选择输出/输入设备（见 desktop/sources/scripts/core/io/midi.js），所以"能在系统里看到虚拟设备"是 Orca 能选中它的前提。

Pilot：零配置的 UDP 快速上手

Pilot 是 Orca 配套的极简合成器软件，通过 UDP 通信，无需任何桥接配置——只要两个应用同时打开即可互通。官方给出的三步上手流程：

1. 启动 Orca 与 Pilot。
2. 在 Orca 中确保 UDP 指向端口 49161（这是 Orca 的默认 UDP 输出端口）。
3. 放置一个 bang 符号（*）并写出 UDP 算子 ; 与消息，例如：

;03Cff

bang 时 Orca 会把字符串 03Cff 通过 UDP 发给 Pilot 播放一个音符；把 ;revff 打上 bang 则触发混响效果。

UDP 算子 ; 的实现位于 desktop/sources/scripts/core/library.js：它会从算子右侧开始逐格收集字符直到遇到 . 或满 36 格，形成消息串，再交给 client.io.udp.push()。而真正的发送逻辑在 desktop/sources/scripts/core/io/udp.js：通过 Node 的 dgram 模块把消息发送到 client.io.ip 的指定端口。默认输出端口 49161、输入端口 49160 定义在 selectOutput/selectInput 的默认参数中，可用命令 udp:1234;5678 分别修改输出与输入端口。

Ableton Live：通过 : MIDI 算子发送音符

向 Ableton Live 的乐器轨发送 MIDI 音符，核心是 bang 触发 MIDI 算子 :。例如 :03C 表示通道 1、八度 3、C 音（三个字段依次为 channel / octave / note）。完整接线步骤：

1. 启动 Ableton Live。
2. 新建一条 MIDI instrument 音轨。
3. 在音轨输入的设备下拉框中，OSX 选择 IAC Driver(Bus 1)，Windows 选择 LoopMidi。
4. 打开音轨上的 In 开关（激活外部输入监听）。

MIDI 算子的完整端口定义在 desktop/sources/scripts/core/library.js：: 最多携带 5 个输入——channel、octave、note、velocity（默认 f，即 15/16 ≈ 119/127）、length（默认 1，即保持 1 帧）。发送时调用 client.io.midi.push()，随后 midi.js 会先释放同通道、同八度、同音符的重复音，再把新音符压入栈，逐帧递减 length，归零后发送 Note Off（0x80+channel）。这正是 Orca 网格里音符能按帧"出声并止音"的底层机制。

值得注意的还有音高转调表：MIDI 算子会把超出自然音阶的字母解释为转调值（详见 desktop/sources/scripts/core/transpose.js），例如 3H 等价于 4A——H 对应 A0 的转调。这与 README 中的 Transpose Table 一致，写音符时可以直接用字母代替升降记号。

Sonic Pi：通过 = OSC 算子驱动 live_loop

Sonic Pi 通过 OSC 消息接收外部控制，Orca 侧使用 OSC 算子 =，并把输出端口设为 Sonic Pi 监听的端口。官方教程给的是端口 4560；同时在源码 desktop/sources/scripts/core/io/osc.js 的预设端口表中，sonicPi 预设为 4559——不同 Sonic Pi 版本监听的 OSC 端口可能有差异，实际使用以你的 Sonic Pi 版本文档为准，并可用 osc:端口 命令随时切换。

Sonic Pi 侧用 sync 同步 Orca 发来的地址，例如 bang =a 会向路径 /a 发送 OSC 消息，Sonic Pi 的 live_loop 收到后触发采样：

live_loop :drum do
  use_real_time
  sync "/osc*/a"
  sample :bd_haus, rate: 1
end

= 算子的实现（library.js）把第一个字符作为路径、后续字符作为消息体逐格读入；而 osc.js 在发送时会把每个字符用 orca.valueOf() 转成 base36 数值（0-9 与 a-z 对应 0-35）追加进 OSC Message。例如 =1abc 会向 /1 发送整数 10、11、12；=a123 向 /a 发送 1、2、3。这意味着 OSC 的数值参数天然是 0-35 的整数步进，适合做节拍、音阶序号等"网格化"控制量。

Bitwig（Linux + JACK）：完整的 virmidi 接线流程

在 Linux 下让 Bitwig 接收 Orca 的 MIDI，官方教程引用了 Bitwig 官方社区的做法，核心思路是用 ALSA 虚拟 MIDI 设备中转。完整步骤如下：

1. 如果 Bitwig 正在运行，先退出。
2. 启动 qjackctl。
3. 进入 Setup > Settings > Parameters，把 MIDI Driver 设为 none（关闭 jack-midi）。
4. 进入 Setup > Misc，勾选 Enable ALSA Sequencer Support（若未启用）。
5. 停止 Jack（若在运行）并退出 qjackctl。
6. 运行 sudo modprobe snd_virmidi midi_devs=1 启用一块虚拟 MIDI 设备（先用一块设备更易理解）。
7. 重新启动 qjackctl，并启动 Jack。
8. 打开 Connections，把左侧的设备（例如 0: QuNexus MIDI 1）连接到 0:VirMIDI 5-0。
9. 打开 Bitwig，进入 Options > Preferences > Controllers，点击 Add controller manually。
10. 选择 Generic MIDI Keyboard。
11. 当它出现在输入列表中时，选择 Virtual Raw MIDI/1 作为输入。

这条链路本质上是"Orca → 虚拟 MIDI 设备 → JACK 连接 → Bitwig"，与上面 macOS / Windows 的虚拟总线思路完全一致，只是 Linux 生态用的是 ALSA sequencer 与 JACK 的连接图。

VCV Rack：用 Ctrl+Period 轮换 MIDI 输出设备

VCV Rack 是模块化合成器环境，Orca 通过 MIDI 输出驱动其中的 VCV MIDI-CV 模块：

1. 启动 VCV Rack。
2. 在机架中添加一个 VCV MIDI-CV 模块。
3. 把第一个参数（MIDI Driver）设为本地回环驱动：
   • Windows：启动 loopMIDI，确保创建至少一个设备，然后选择 loopMIDI。
   • Linux：选择 ALSA（Linux 上广泛支持的声音架构）。
4. 把第二个参数设为 MIDI 接口：
   • Windows：选择你刚创建的 loopMIDI 设备。
   • Linux：选择默认的 MIDI Through 设备（多数 ALSA 配置默认可用）。
5. 启动 Orca。
6. 使用快捷键 Ctrl+Period（macOS 为 Cmd+Period）循环切换 MIDI 输出设备，直到右下角显示你的目标设备。
7. 给 MIDI 算子打上 bang 发送音符，例如 :03c88——通道 1、八度 3、C# 音、力度 8，MIDI-CV 模块会据此输出 gate 与音高 CV。

"Ctrl+Period 切换输出设备"对应源码中的快捷键绑定 CmdOrCtrl+. → this.io.midi.selectNextOutput()（见 desktop/sources/scripts/client.js），其实现（midi.js）会在已枚举的输出设备列表里逐个递增下标，所以轮换顺序就是系统设备枚举顺序。

常见问题（FAQS）

为什么 V 的放置位置很重要？

Orca 从左上方到右下方线性求值，算子按这个顺序逐帧执行。V 变量算子既写又读：放在网格上方的 V 写入的变量，会被下方后执行、同名读取的 V 覆盖；反之放在下方的写操作可能来不及被上方的读操作使用。因此同一帧内"先写后读"才能保证读到预期值。这一求值顺序可以在 desktop/sources/scripts/core/orca.js 的 parse() 与 operate() 中看到：解析器按 y 行、x 列逐格收集算子，执行时又跳过被锁定（lock）的格子，形成严格的先后次序。

为什么 Orca 不出声？

Orca 不是合成器，而是一个用于控制音频/视觉软件或硬件的 livecoding 环境。它刻意不包含任何"生成音乐或画面"的领域算子，只提供最通用的运算与 IO 原语，把发声交给 Pilot、Ableton、VCV Rack 等外部工具。所以"没声音"时，请检查：MIDI/OSC/UDP 目标设备是否选中、bang * 是否与 IO 算子相邻、目标软件的输入监听是否打开——这些才是 Orca 生态里真正的"发声开关"。

Golf 小例子：验证求值顺序与 bang 机制

教程最后用四个高尔夫小例子演示基础运算与 bang 行为，它们可以直接粘贴进 Orca 网格运行验证：

模运算（Modulo）

输出 6 % 4 的结果：

1X.
6I4

I（increment）算子取左侧 step 与右侧 mod，把南向格子按步进递增并取模；这里配合 X（write）把结果写到偏移位置，最终得到 6 % 4 = 2。I 的实现见 library.js：(val + step) % (mod > 0 ? mod : 36)。

大写转换（Uppercase）

输出大写 C：

cA1.
.dAZ

c（clock）每帧输出 frame / rate 对 mod 取模的字符，Z（lerp）按速率把南向格子向目标值过渡，配合大写敏感的输出逻辑得到大写字母。大小写输出由 operator.js 的 shouldUpperCase() 控制：当右侧输入是大写字母时，输出也转成大写。

小写转换（Lowercase）

输出小写 c：

H..
CM1

M（multiply）计算乘积，H（halt）锁定南向格子阻止其被改写，最终得到小写 c。

非空判断（Not Null）

当 L 的自由输入不为空时触发 bang：

.L0.
..F0

L（lesser，输出两个输入中的较小值）与 F（if，输入相等时 bang）配合：L 的左侧输入非空时，F 比较成立，在南向格子写入 *。F 的实现见 library.js，其输出端口标记为 bang: true，通过 operator.js 的 bang() 把目标格写成 * 并加锁，下一帧 * 再触发相邻算子。

附：与教程相关的端口速查与命令

用途	默认端口	相关算子/命令
UDP 输入（接收外部控制）	49160	udp:输出;输入
UDP 输出（发送给 Pilot 等）	49161	; 算子
OSC 输出（发送给 Sonic Pi 等）	49162	osc:端口、= 算子
MIDI 输出/输入设备	自动枚举	midi:输出;输入、Ctrl+Period 切换

以上默认值均可在 desktop/sources/scripts/core/io/udp.js 与 desktop/sources/scripts/core/io/osc.js 中验证，命令解析入口在 desktop/sources/scripts/commander.js。所有命令都有两字符缩写（如 udp:、osc:、midi:、ip:），在 Orca 内按 CmdOrCtrl+K 打开命令行即可输入；也可以把命令写进 $（self）算子，由 bang 触发后注入，实现"图案内嵌命令"。

掌握上述接线链路与算子语义后，你就可以把 Orca 当作一个可视化、可实时改写的程序化音序器，自由穿梭于 Pilot、Ableton Live、Sonic Pi、Bitwig 与 VCV Rack 之间。