open-audiovisual
搜尋 GitHub

文件

open-audiovisual 使用手冊

跑起來、寫作品、上台演出需要知道的事,都在這一頁。這裡寫到的 API 名稱、選項和訊號,都對照過原始碼,兩者對不上時,以程式碼為準。

19 章 · 202 節 · oav-p5 0.8 · 框架 0.9

內容以 Markdown 寫在 docs/zh/,這一頁由它產生。 GitHub ↗ · 給語言模型:/llms.txt · /llms-full.txt

簡介#

01原始檔: docs/zh/introduction.md

open-audiovisual(OAV)是一套在瀏覽器裡跑的 JavaScript 框架,給現場影音表演用。它只用原生的 ES module:不用建置、沒有相依套件、不用註冊帳號。把 repo clone 下來,跑一個檔案,打開一個網頁,就可以開始了。

每一場演出都要從頭重做的那一塊,由它來處理:MIDI 的底層接線、把輸入變成參數、有場景的時間軸、導演控台、給演奏者的演出模式,以及給舞台監督的後台頁面。你只要寫世界,也就是作品本身。框架的介紹、一台即時在跑的樂器,還有二十六件範例作品,都在首頁。

給誰用#

  • 演奏者用 MIDI 鍵盤、麥克風、鏡頭、手機或螢幕鋼琴來彈範例,從控台操作一場演出。
  • 寫程式的人大約二十行就能寫好一個世界,呼叫一次 createShow(),輸入、映射、時間軸、控台、聲音和後台就都有了。
  • AI 代理先讀 AGENTS.md,接上 repo 內附的 MCP 伺服器,在一個已經能跑的底盤裡寫世界。見給 AI 代理。

四層與兩條主軸#

text
L1 INPUT     "what is happening"       midi · audio · chord · pose · keys · drums · phones
               → every input publishes named SIGNALS: midi/cc/74, chord/consonance, audio/rms
L2 MAPPING   "what it means"           routes: signal → param, with curve, range, smoothing, learn
L3 WORLD     "how the system behaves"  your piece; reads PARAMS, never inputs; any renderer
L4 OUTPUT    "how it leaves"           screen · in-browser sound · MIDI out · OSC to UDP

spines       timeline (automation, scenes, cues) · monitor (backstage over WebSocket)
around them  console (the director's desk) · relay, surface, remote (phones as controllers)

每一層只做一件事,各有一份寫明的介面約定(架構),所以換掉任何一層,都不用動到其他層。能一直這樣,靠的是兩條規則,寫在核心概念。

從哪裡來#

框架的核心是從 《The Last Input 終局之前》(吳哲宇,2026)抽出來的。那是台北 IRCAM 聲鬥陣 × C-LAB 台灣聲響實驗室駐村的一場演出,鋼琴和一個活著的數位世界同台,喇叭穹頂有 49.4 聲道。時間軸、和弦語意、多對多的 MIDI learn、OSC 批次傳送,都先撐過一整場十四個場景的真實演出,才在這裡整理成通用的框架。從那之後就定了一條規則:真實演出要求過的功能,框架才長。

映射層的想法,承接 libmapper 對訊號命名空間的研究。姊妹專案 WebToe 是節點式的資料流引擎,可以匯入 TouchDesigner 專案。WebToe 是引擎,open-audiovisual 是演出。

怎麼讀這本手冊#

這裡寫的每一件事,都對照過 packages/ 裡的原始碼。這一頁和程式碼對不上時,以程式碼為準,那就是這一頁的 bug,請開一個 issue。

快速開始#

02原始檔: docs/zh/getting-started.md

三種進場方式#

挑一個最接近你手上東西的。越往下,東西越大。

  1. 在 p5.js 草圖裡加一行。 任何一份 p5.js 草圖(OpenProcessing、p5 編輯器、你自己的網頁)在最前面加一行,就能用 MIDI 控制器、螢幕上的控制器或手機來彈。讀 p5.js 一行接上,再玩帶著這一行的草圖: 範例 15。同一行還能出聲音、開一台能用一行字寫節奏的鼓機、聽麥克風、錄成影片,每一樣在範例裡都有一份現成的草圖(16 到 26)。
  2. 在網頁裡放一台控制器。 <oav-controller profile="akai-lpd8"> 把一台能彈的控制器放進任何網頁。讀 MIDI 控制器與嵌入,到控制器圖鑑挑你的那一台。
  3. 一整場演出。 一個世界加上一次 createShow() 呼叫,輸入、映射、時間軸、控台、聲音和後台就一起組好。從 範例 01 開始,接著往下讀。

跑起來#

你需要 Node.js(目前任何一個版本都可以,CI 用 Node 22 跑測試)和一個瀏覽器。不用安裝任何東西:沒有 npm install,也沒有打包工具。

bash
git clone https://github.com/frank890417/open-audiovisual.git
cd open-audiovisual
node serve.js            # → http://localhost:8080

serve.js 是關掉快取的靜態檔案伺服器(在舞台上跑到舊的程式碼,是一場惡夢),也在 ws://<host>:8080/relay 開好給手機用的中繼。想換連接埠,就把埠號傳進去:node serve.js 3000。這些指令也都寫成了 npm script:

指令實際執行的是
npm startnode serve.js
npm run monitornode packages/monitor/server.js,後台監看,連接埠 7457
npm run bridgenode packages/osc/bridges/osc-bridge.js,OSC → UDP 橋接,連接埠 7456
npm testnode --test tests/*.test.js

打開 http://localhost:8080/examples/01-hello-particles/。每個範例都不需要硬體就能跑。

一個檔,不用 clone#

做自己的演出不需要這個 repo。把 show.html 存下來(打開後另存網頁,或複製原始碼),用任何靜態伺服器開它所在的資料夾,再打開它:

bash
python3 -m http.server 8080      # or any static server, or any static host

這個檔是一頁加一個 import:你要改的世界,和一次 createShow() 呼叫。其他東西都從一個網址進來:

js
import { createShow, createCanvas } from 'https://cdn.jsdelivr.net/gh/frank890417/open-audiovisual@v0.9.0/packages/openav.js';

需要的東西都從這一個網址匯入。用了第二個網址,同一頁裡就有兩份框架。靜態頁面帶不來的只有兩樣:手機遙控會用公開的 relay(除非你跑 serve.js),後台監看要從 clone 下來的 repo 跑 node packages/monitor/server.js。

作品上線之後,把它加到「用它做的」。

固定一個版本#

網址裡的 @v0.9.0 是整個框架的一個版本。這個網址永遠不會變,所以你排練的那一場就是你演出的那一場。要換新的,自己改那個數字,再排練一次。

網址拿到什麼
https://cdn.jsdelivr.net/gh/frank890417/open-audiovisual@v0.9.0/packages/openav.js就是 0.9.0,永遠是
https://openaudiovisual.com/packages/openav.js最新的,每次發佈後幾分鐘內
https://openaudiovisual.com/p5/oav-p5.jsp5.js 的那一行:最新的(它自己的版本)

1.0 之前,新的次版本(0.9 到 0.10)可能改名或拿掉東西,更新紀錄會在那一條的第一行寫出來。修訂版本(0.9.0 到 0.9.1)只修問題。我們最用力不去弄壞的是:世界的約定(name、params、init、update、render、 dispose)、訊號裡的訊號名稱、控制器設定檔的格式,以及 oav-p5 給草圖的那些名字。window.openav.version 會告訴你一場正在跑的演出是哪一版。

用哪個瀏覽器#

不確定你這台裝置能做什麼?打開裝置體檢。它會看你的瀏覽器、Web MIDI、麥克風、鏡頭和繪圖能力,每一項都告訴你怎麼辦。按了按鈕才會開始,也不會把任何東西送出裝置。

Web MIDI 是各瀏覽器差最多的一項(出處查證於 2026-10-15):

  • Chrome 和 Edge 有。演出請用它們。從 Chrome 124 起,任何 MIDI 的使用都會問你要不要允許;以前只有系統專用(system-exclusive)才問(Chrome 部落格)。
  • Firefox 桌面版從 108 版起有 Web MIDI,但要先裝 Firefox 的網站權限附加元件(Firefox 108 版本說明)。
  • Safari(Mac、iPhone、iPad)沒有 Web MIDI(caniuse)。WebKit 把它列為不實作,理由是指紋辨識的疑慮(WebKit),bug 107250 至今還開著、沒人認領。iPhone 和 iPad 上的 Chrome 底層也是 WebKit,所以一樣沒有。Mac 上有第三方的 Safari 擴充 Safari-WebMIDI,我們沒有實測。

瀏覽器沒有 Web MIDI 的時候,有三條路:

  • 直接在螢幕上彈。 圖鑑裡每一台控制器都能用手指彈,事件照常觸發。
  • 把手機當控制器。 見手機、中繼與控制面板。
  • iPad 上的瀏覽器 App。 MIDIWeb Browser 是第三方 App(iOS 17.6 以上),讓網頁用得到 Web MIDI。我們沒有拿它跟 open-audiovisual 一起實測。

Windows 11 內建的 Windows MIDI Services(2026-02-17 釋出)讓各程式共用 MIDI 埠並附有 loopback,從瀏覽器送 MIDI 到 DAW 不必再裝 loopMIDI(Windows 部落格);見用它彈你的 DAW。

不管哪個瀏覽器,還有兩條規則:

  • 鏡頭和麥克風只在安全環境(secure context)裡能用:http://localhost 或 https://。在跑 serve.js 的那台電腦上,請用 localhost 打開演出,不要用它的區域網路位址。
  • 手機在區域網路裡用一般的 http:// 連進來,就能用觸控、琴鍵和控制面板。iOS 只把動作感測器和鏡頭開放給 https:// 頁面(見手機、中繼與控制面板)。

你看到的是什麼#

範例頁面分成兩部分:左邊是舞台(世界畫在這裡),右邊是側邊面板。側邊面板由上到下是:

  1. 鋼琴,附兩個核取方塊:keyboard(電腦鍵盤擷取)讓你用電腦鍵盤彈,simulate performance(模擬演奏)讓一位模擬演奏者自己彈,不用你動手。
  2. 播放控制:播放/暫停、上一個/下一個場景、重設、時鐘、目前的場景,以及一條拖曳軸,每個場景占一格。
  3. Layers(各層狀態):每一層現在在做什麼(每個輸入每秒幾個事件、啟用中的路由、世界和 FPS、哪些東西正從瀏覽器送出去)。
  4. L1 · Input(輸入):MIDI 裝置(取消勾選就把那台靜音),以及要點一下才會啟用的來源按鈕:🎤 mic(麥克風)、🖐 hands(手)、🕺 body(身體)。
  5. L2 · Mapping(映射):每一條路由,附一個靜音核取方塊,按 ✕ 刪除。
  6. L3 · Params(參數):每個參數一支推桿,按 ✕ 清除覆寫,按 learn 建立映射。
  7. L4 · Output — sound(輸出:聲音),演出有聲音時才會出現:按 🔊 enable sound(開啟聲音)。
  8. Signals(訊號):每個訊號一個即時儀表。

點面板標題就能收合。

按鍵動作
Space播放/暫停時間軸
← →上一個/下一個場景
R停止,並把時間軸倒回 0:00
T演出模式(提詞畫面)
F全螢幕
M顯示/隱藏螢幕上的 MIDI 控制器(演出設定了 modules.midi.controllers 才有)

不用硬體也能彈#

  • 螢幕鋼琴:用滑鼠點或手指按琴鍵,在琴鍵上一路拖過去就是刮奏。
  • 電腦鍵盤:先勾選 keyboard(預設不擷取,免得字母鍵搶走控台的快捷鍵)。A W S E D F T G Y H U J K O L P ; 這幾個鍵,從鋼琴的基準音開始,依序彈出相差半音的 17 個音。Z/X 換八度,按住 Shift 會彈得比較大聲。
  • 模擬演奏:模擬演奏者在五聲音階裡隨興地彈,有級進、跳進、三和弦和休止,你只要看映射怎麼跟著起伏。
  • 鼓機(範例 03 和 06):一台步進音序器,送出的訊號跟麥克風偵測鼓點時送出的長得一樣。
  • 螢幕上的 MIDI 控制器(範例 09):畫面上是一台市售的控制器,可以用滑鼠彈(支援的裝置列在控制器頁面)。接上實體的那一台,畫面就跟著你的手一起動。

這些送出的訊號都跟真實硬體一樣,所以下游分不出差別。

你的第一個世界#

世界就是一個物件,裡面有 params 和四個生命週期函式。把它交給 createShow(),演出的其他部分就會圍著它組起來:

js
import { createShow } from '@openav/show';
import { createCanvas } from '@openav/stage';

const pulse = {
  name: 'pulse',
  // what the piece is performed WITH: sliders, knobs, hands, the timeline
  params: [{ key: 'size', min: 10, max: 200, def: 40 }],
  init({ container, signals }) {
    this.view = createCanvas(container);
    this.r = 0;
    // a struck note is an event, so it may come straight from a signal
    signals.on('midi/note/on', ({ vel }) => { this.r = 120 * vel; });
  },
  update(dt, state) { this.r = Math.max(0, this.r - dt * 90); this.size = state.size; },
  render() {
    const { ctx } = this.view, { w, h } = this.view.fit();
    ctx.fillStyle = '#000'; ctx.fillRect(0, 0, w, h);
    ctx.fillStyle = '#fff';
    ctx.beginPath(); ctx.arc(w / 2, h / 2, this.size + this.r, 0, 7); ctx.fill();
  },
  dispose() { this.view.dispose(); },
};

await createShow({ world: pulse, modules: { sound: true } });

彈一個音:圓圈會跳大,再慢慢縮回去。拖動 size 推桿,或按旁邊的 learn,再轉一顆旋鈕。整個模型就是這樣:連續控制用參數,事件用訊號。

做一個新範例#

  1. 把 examples/01-hello-particles/ 複製成 examples/<nn>-<name>/(用下一個還沒用的編號)。它的 index.html 已經替每個 @openav/* 套件寫好 import map。那些 ?v= 後綴是快取戳記,部署前由 tools/stamp-version.mjs 寫進去。
  2. 在 main.js 寫你的世界(寫一個世界)。
  3. 改掉 index.html 裡的 <title>。如果你用 p5 或其他繪圖工具,也在這裡加上 CDN 的 script 標籤。
  4. 打開 http://localhost:8080/examples/<nn>-<name>/。

第 1–2 步,AI 代理可以用 MCP 工具 scaffold_world 一次做完(給 AI 代理)。

檢查你的成果#

  • npm test 通過(測的是純邏輯:和弦、時間軸、映射、中繼、控制面板、MIDI 解析與裝置設定檔、網站頁面)。
  • 頁面載入時,主控台沒有錯誤。只有一則訊息是預期中的:如果後台監看沒在跑,瀏覽器會回報 ws://localhost:7457 拒絕連線。頁面會自己默默重試,間隔越拉越長(最長 30 秒)。跑 npm run monitor,這則訊息就不會再出現。
  • 按 Space:時間軸開始播放,畫面裡有東西隨時間改變。
  • 勾選 keyboard,按 A:不接任何硬體,世界也會有反應。
  • 開發者工具主控台裡的 window.openav 就是整場演出(signals、params、mapper、timeline…),可以自己動手戳戳看。

核心概念#

03原始檔: docs/zh/concepts.md

六個詞撐起整套框架:訊號、參數、路由、世界、時間軸、演出。這一章一個一個講清楚,最後講把它們綁在一起的兩條規則。

訊號#

訊號(signal)是一個有名字的數值,告訴你現在發生了什麼:一顆旋鈕的位置、房間裡的音量、手腕的高度、上一個和弦的協和度。每個輸入套件都把訊號發布到同一個登錄表(@openav/core 的 Signals),除此之外什麼都不做。訊號是輸入唯一的通用貨幣。

訊號有兩種:

種類存放的是範例讀取方式
連續目前的值,通常在 0..1 之間midi/cc/74 = 0.42signals.get(name)、signals.norm(name)
脈衝最近一次事件帶的內容midi/note/on → { note: 60, vel: 0.8, … }signals.on(name, cb)

名稱是路徑,來源放最前面:midi/cc/74、audio/band/low、pose/hand/right/y、phone/ab12/tilt/x、surface/main/hue。只要在演出上說得通,範圍都會正規化,y 軸也會翻過來,讓 1 代表舉高。你拿到的絕不會是原始的像素值。

宣告訊號時要帶上範圍,儀表和 learn 才知道怎麼縮放它:

js
signals.define('breath/pressure', { min: 0, max: 1, source: 'breath' });
signals.set('breath/pressure', 0.37);               // continuous
signals.define('breath/sigh', { kind: 'pulse' });
signals.pulse('breath/sigh', { depth: 0.8 });       // pulse

對一個沒人宣告過的名稱呼叫 set(),會當場把它定義成 0..1 的連續訊號。如果你的數值落在別的範圍(角度、MIDI 音高編號),請先宣告範圍。

一顆旋鈕、一隻舉起的手、一個和弦的協和度,在這個登錄表裡平起平坐。正因為這樣,你才能把它們混著用:旋鈕做得到的,手也做得到。

參數#

參數(param)是世界在聽的數值:hue、bloom、gravity。參數由世界自己宣告,每個參數是一行 schema:

js
{ key: 'energy', label: 'Energy', min: 0, max: 1, def: 0.3 }
{ key: 'mode', label: 'Mode', min: 0, max: 3, def: 0, step: 1 }   // stepped: snaps, holds on the timeline
{ key: 'burst', label: 'Burst!', pulse: true }                      // a trigger, not a level

每一格畫面,每個參數都會解析成一個數字:

text
timeline automation at time t      (the score; def if the param has no automation)
  ⬑ overridden by → the latest override   (a slider, a mapped knob, a phone fader)

覆寫會黏住(sticky)。一旦有手或路由碰過 bloom,時間軸就不再推動它,直到你清掉覆寫(在控台按 ✕,或呼叫 params.clearOverride('bloom'))。這跟舞台上一樣:人一伸手接管,樂譜就讓位。路由可以選別的做法:mode: 'trim' 把旋鈕疊加在時間軸的值上,release 讓旋鈕靜止時把參數還回去(映射)。

完整的欄位列表在寫一個世界。

路由與映射#

路由(route)把一個訊號接到一個參數。路由就是單純的資料:

js
{ source: 'pose/hand/right/y', target: 'energy', curve: 'smooth', smooth: 0.15 }

映射器(mapper,@openav/mapping)收著所有路由,也負責套用:讀取訊號,夾進一個範圍(inMin..inMax),需要的話反轉,用曲線彎折,縮放到參數的範圍,有指定的話再隨時間做平滑。一個訊號可以推動好幾個參數,一個參數也可以聽好幾個訊號。learn 會綁定下一個動起來的訊號,旋鈕和揮動的手都適用。路由可以序列化成 JSON,所以一套接線就是一個檔案,可以帶到下一個場地。細節:映射。

世界#

世界(world)就是作品:一個物件,裡面有名稱、參數,以及 init、update、render、dispose。它每一格讀已解析的參數,遇到離散事件也可以直接訂閱訊號。要怎麼畫由它自己決定,2D canvas、p5、three.js、WebToe 節點網路、DOM 都可以,框架不管。細節:寫一個世界。

時間軸與場景#

時間軸(timeline,@openav/timeline)就是樂譜:每個參數的關鍵影格自動化,加上一串場景,每個場景附標題和給演奏者的備註。時間歸它管,世界從來不讀時鐘。場景可以排在 0 秒之前,當作開演前的待命。細節:演出控制。

演出#

演出(show)就是一個世界,加上呼叫一次 createShow()(@openav/show)。這一呼叫會建好訊號登錄表、參數、舞台、時間軸、映射器、你要的輸入、聲音、控台、後台資料流和畫面迴圈,然後全部回傳給你。每個範例都是一個世界加上這次呼叫,所以框架長出新模組時,每場演出只要宣告一下就能用。

js
const show = await createShow({
  world,
  timeline: { total: 120, automation, scenes },
  routes: [{ source: 'audio/rms', target: 'energy', smooth: 0.1 }],
  modules: { keys: { base: 48 }, chord: true, audio: true, sound: true },
});

兩條規則#

框架的每個部分能自由組合,靠的是這兩條規則。每條都有兩種說法,一種講系統怎麼設計,一種講寫程式的人因此要守什麼。

1. 訊號是輸入唯一的通用貨幣。所以:連續控制走參數,離散事件可以直接用訊號。

假設一個世界在 update() 裡直接讀 signals.get('midi/cc/74'),今天配上你的控制器還是能跑,但時間軸、舞者的手腕、手機或別人的控制器,就再也演奏不了它。你等於把這場演出焊死在一個輸入上。改成宣告一個參數,讓一條路由接上 midi/cc/74 → yourParam。這樣同一個世界誰都能用,控台、手機控制面板和 learn 也都看得到這個參數。

事件就不一樣了。「按下一個音」「一個和弦解決了」「大鼓打了一下」都是瞬間,不是持續的數值。在 init() 裡訂閱它們是對的,我們也鼓勵這麼做。世界能對你反應,靠的就是這些事件,少了它們,世界只會自己飄。

2. 世界永遠不知道誰在演奏它。所以:外殼永遠不知道作品是什麼。

世界讀的是參數,數值來自時間軸、MIDI 旋鈕、舞者還是推桿,它看不見。框架也一樣:不要為了讓某個範例好看去改 packages/*。改框架,就要讓每件作品都變好。換作品,就是換掉世界和它的資料,外殼留著不動。

架構#

04原始檔: docs/zh/architecture.md

open-audiovisual 是一套資料層框架。它的價值全在一件事:四層和兩條主軸分得乾乾淨淨,換掉其中任何一個,都不用碰到其他部分。這一章把每一層的介面約定講清楚。

畫面迴圈#

整套系統由一個 Loop(@openav/core)帶著跑。下面是 createShow() 每一格的執行順序(packages/show/index.js):

js
const loop = new Loop((dt) => {
  keys?.update(dt);                              // 0. on-screen performers: SimPlayer, drum sequencer
  drums?.update(dt);
  audio?.update();                               //    microphone analysis → audio/* signals
  onFrame?.(dt, show);                           //    your assembly-level hook
  timeline.advance(dt);                          // 1. time moves
  sync?.frame();                                 //    several pages: the leader says where it is, a follower asks again if unanswered
  director?.update(timeline.t, dt, { holding, playing }); //    with a score: segment modules enter / update / exit
  mapper.update(dt);                             // 2. smoothed routes settle
  const state = stage.frame(dt, timeline.state()); // 3. params resolve → world updates & renders
  sound?.update(state);                          // 4. sound/* params reach the synth
  remote?.frame(dt, state);                      //    param values echo back to phones
  consoleUI.render(state);                       // 5. the desk reflects reality
  monitor?.frame(snapshotOf({ timeline, params, signals, stage, loop }, state)); // 6. backstage hears about it (not with monitor: false)
});

訊號在兩格之間進來,裝置或 socket 什麼時候觸發,就什麼時候到。沒有平滑的路由會立刻寫入參數,有平滑的路由則是設一個目標值,由 mapper.update(dt) 慢慢滑過去。createShow() 不包含 OSC 輸出,要用的話,在 onFrame 裡呼叫 flush 送出(見演出控制)。

dt 以秒為單位,上限夾在 0.1(new Loop(fn, { maxDt })),所以就算卡頓,世界也不會爆掉。瀏覽器凍結 requestAnimationFrame 的時候(例如投影視窗被切到背景),一個 Web Worker 心跳會讓迴圈繼續跑,大約每 66 ms 一次(約每秒 15 格)。有人切了視窗,時間軸、映射中的訊號和後台資料流也不能停。

誰來給影格是一個選擇,頁面自己的只是預設。new Loop(fn, { clock, raf }) 讓時間和影格請求由你供應(測試用的假計時器、錄影工具的影格推進器),new Loop(fn, { manual: true }) 則什麼都不排程:每次 loop.step(dt) 就是一個影格。createShow({ loop: 'manual' }) 對整場演出做的就是這件事(自己驅動影格)。

參數解析的順序(整個設計的核心):

text
timeline.state(t)          — automation curves per param
  ⬑ rewritten by  →  director.param()   — a segment module, inside its own segment (with a score)
  ⬑ overridden by →  params.overrides   — set by hand sliders, mapped signals

覆寫會黏住:一旦有旋鈕碰過 bloom,時間軸就不再推動它,直到你清掉覆寫(在控台按 ✕)。這跟演出現場一樣:人一伸手接管,樂譜就讓位。路由可以選別的做法:mode: 'trim' 把旋鈕疊加在時間軸的值上、不取代它,release 讓旋鈕靜止時把參數還回去(映射)。

L1 · 輸入:訊號(Signals)#

介面約定:輸入套件把有名字、經過正規化的訊號發布到 Signals 登錄表,除此之外什麼都不做。它們從不碰參數或世界。

  • 名稱像路徑:midi/cc/74、chord/consonance、pose/hand/right/y
  • 連續訊號宣告 {min, max},隨時都有一個目前值
  • 脈衝訊號(kind: 'pulse')觸發事件,帶的內容就是事件物件
  • 誰都可以訂閱:signals.on(name, cb) 或 signals.onAny(cb)

新增一種輸入方式(呼吸感測器、遊戲手把、股票報價、天氣 API),就是寫一個呼叫 signals.set()/signals.pulse() 的 class。下游什麼都不用改。重點就在這裡。

現有的輸入:@openav/midi(硬體與螢幕上的控制器)、keys、drums、audio(麥克風)、pose(鏡頭看身體與手)、leap(Leap Motion/Ultraleap 的手),以及經由 remote 和 surface 的手機。瀏覽器自己打不開的硬體,透過一支講網頁協定的本機小橋接程式進來(leap 的橋接在 ws://127.0.0.1:6437);瀏覽器這一側仍然只是一個發出訊號的 class。

分析器位在原始來源和映射之間:@openav/chord 訂閱 midi/note/on|off,再發布 chord/*。對映射器來說,它還是一個輸入,只是它聽的是別的訊號,沒有直接接裝置。

L2 · 映射:映射器(Mapper)#

介面約定:把訊號接到參數的,只有它一個。路由就是資料:

js
{ source: 'pose/hand/right/y', target: 'energy',
  inMin: 0, inMax: 1, curve: 'smooth', invert: false,
  smooth: 0.15, outMin: 0, outMax: 1 }
  • 多對多:一個訊號可以推動好幾個參數,一個參數也可以聽好幾個訊號(以最後寫入的為準)。learn 只會新增路由,從不取代。
  • learn 是廣義的 MIDI learn:mapper.learn('bloom') 會綁定下一個動了至少自身範圍 5% 的訊號,旋鈕和揮動的手都算數。
  • 路由可以序列化成 JSON → 映射設定檔就是可以分享的檔案。

完整說明:映射。

L3 · 世界:舞台(Stage)#

介面約定:世界(World)是 { name, params, init, update(dt, state, io), render, dispose }。它讀 state(已解析的參數值)。它可以為了離散事件訂閱訊號(一個 note-on 生出一顆粒子,是事件,不是參數),但連續控制一定要經過參數,不然時間軸和其他輸入就再也演奏不了你的世界。

舞台(Stage)管生命週期和參數彙整,刻意不管繪圖。p5、three.js、2D canvas、SVG、DOM 都可以,框架不插手。

憲法級的規則(承襲自《The Last Input 終局之前》):外殼永遠不知道作品是什麼。 換作品=換掉世界+自動化資料。外殼留著。

完整說明:寫一個世界。

L4 · 輸出:影像與聲音兩條分支,都是選用#

輸出層分成兩條分支。兩條都接在同一條「訊號 → 映射 → 參數」主軸上:聲音是一種可以演奏的狀態,不是附帶的效果。

影像分支

  • 螢幕是預設的輸出。演出模式(T)給演奏者一個提詞畫面,觀眾看的是全螢幕的舞台視窗(F)。
  • 錄製(@openav/record):作品和演奏者的鏡頭合成進一張尺寸精確的畫布(直式 1080×1920 到 4K),跟作品自己的聲音交給同一個 MediaRecorder 錄,畫面和聲音用的是同一個時鐘。MIDI 錄音則把演奏本身錄下來,再播回演出裡。
  • 未來:NDI 閘道(見路線圖,基礎工作在姊妹專案 WebToe 裡)。

聲音分支

  • MIDI 輸出(外接合成器、DAW):midi.send()/noteOn()/cc(),所有訊息走同一個出口,而且看得到(onSend),儀表能顯示每一則送出的訊息。另外有一個真的派得上用場的 panic()。
  • 頁面內合成:@openav/sound,一份精簡、可抽換的引擎介面約定(params, enable, noteOn, noteOff, set, dispose),先支援 Tone.js 引擎(從 CDN 載入,按下 enable 才載)。這個引擎彈的是登記好的樂器:取樣的平台鋼琴、敲擊琴、弦樂、風琴、合成器音色,一個檔案一種聲音,在控台上挑。引擎的參數註冊成 sound/*,旋鈕、手或時間軸演奏濾波器截止頻率的方式,跟演奏畫面完全一樣。@openav/drums 的鼓組是用同一份介面約定寫的第二個引擎(純 WebAudio,不需要取樣音檔)。
  • OSC:瀏覽器 → HTTP → osc-bridge.js → UDP(Spat、Reaper、TD、燈光)。每格批次送出,同一個位址在一格裡只留最新的一則訊息。

主軸 · 時間軸#

純邏輯,不碰 DOM:參數+自動化關鍵影格+場景 → state(t)。場景可以從負的 t 開始(開演前的待命)。onSceneChange 就是 cue 的掛鉤:聲音、燈光、提示都從這裡觸發。帶 hold: true 的場景,播放到它的結尾就停住,等操作者放行。

有結構的演出,會把總譜(@openav/score)加進這條主軸:把演出寫成各段的長度,由 Score 算出每個起點、終點、cue 和倒數,再由 Director 去執行負責每一段的模組(進一次、出一次,某個模組壞掉只會停用它自己)。時間軸的場景和總長都從總譜來,導演則以參數層的身分接在時間軸上:

text
cut (segment lengths) → Score ─┬─ scenes(), total ──→ Timeline ── state(t) ──→ params
                               └─ Director ── enter / update / exit ──→ segment modules ──→ the world (through `api`)
                                    └─ param() ── timeline.layer ──────────────────────→ Timeline

總譜只決定什麼時候。實際發生的事,仍然是以參數的形式傳進世界。完整說明見總譜與導演。

時間軸也可以不自己往前走,改去追另一條時間軸的時鐘,好幾個頁面就是這樣演同一場:主控端在跑,從屬端透過 BroadcastChannel 或房間中繼追它的 T,每個參數仍然是那個 T 的函式解出來的(好幾個頁面,一場演出)。

主軸 · 後台監看#

演出頁面透過 WebSocket,把 JSON 快照(有節流,約 15 Hz)串流到一個沒有相依套件的中繼(server.js,手寫的 RFC 6455 實作)。區域網路裡任何一支手機或一台筆電,打開後台頁面就能看到:時鐘、場景、世界、FPS、覆寫、每個訊號和參數,還有「舞台畫面斷線」警示。後台監看在框架裡跟其他層一樣重要:沒有後台的演出,只是一場彩排。

主軸周邊:控台與手機#

  • 控台(@openav/console):側邊面板裡的導演控台,依層排列(Layers → L1 → L2 → L3 → L4 → Signals),另外還有演出模式,以及把整場 automation 畫成曲線的曲線面板。它讀的就是迴圈正在跑的那批物件,自己不保存任何狀態。
  • 手機(@openav/relay、@openav/surface、@openav/remote):手機和 iPad 透過 WebSocket 中繼加入一個房間,發布 phone/* 和 surface/* 訊號。對映射器來說,它們只是多一個輸入。見手機、中繼與控制面板。

寫一個世界#

05原始檔: docs/zh/writing-a-world.md

世界是整套框架裡,唯一一定要自己寫的部分。其他都是組裝。

介面#

js
export const myWorld = {
  name: 'my-world',

  // params: what the world can be performed WITH.
  // These appear in the console, are automatable by the timeline,
  // and are mappable to any signal.
  params: [
    { key: 'energy', label: 'Energy', min: 0, max: 1, def: 0.3 },
    { key: 'mode',   label: 'Mode',   min: 0, max: 3, def: 0, step: 1 },  // step → snaps, holds on the timeline
    { key: 'reset',  label: 'Reset',  pulse: true },                       // momentary trigger
  ],

  init(ctx) {
    // ctx = { container, signals, params }
    // build your renderer here: p5, three, or the built-in 2D helper:
    this.view = createCanvas(ctx.container);
    // discrete events may come straight from signals:
    this._unsub = ctx.signals.on('chord/event', (a) => this.onChord(a));
    this._unpulse = ctx.params.onPulse('reset', () => this.reset());
  },

  update(dt, state, io) {
    // state = resolved param values. This is your ONLY continuous input.
    // io = { signals } plus any output handles the assembly added (see "Sound output")
  },

  render() { /* draw */ },

  dispose() { this._unsub?.(); this._unpulse?.(); this.view.dispose(); },
};

約定#

成員什麼時候執行拿到什麼
name—一個不重複的字串,舞台用這個名字註冊世界
params註冊世界時讀一次參數宣告組成的陣列(見下方)
init(ctx)世界啟用時{ container, signals, params }。可以是 async,createShow() 會等它跑完才啟動迴圈
update(dt, state, io)每一影格dt 以秒為單位(≤ 0.1),state 是每個參數的 { key: value },io 是 { signals, … }
render()每一影格,緊接在 update 之後不帶參數,用 update 存下來的東西來畫
dispose()換成另一個世界時釋放 GPU 物件、DOM、訂閱
surface選用手機控制面板的版面。有它的話,modules.remote 直接用它,不再自動產生(手機)

container 是一個絕對定位、鋪滿整個舞台的元素。舞台在每次 init 之前都會把它清空,所以你不用收拾別人留下的 DOM。update 或 render 丟出的例外,舞台會接住並記下來([stage] update:/[stage] render:),演出照常進行。

參數#

欄位意義
key路由、自動化和控台用的名字。必填。
label控台上顯示的文字。預設是 key。
min, max範圍。覆寫的值會限制在範圍內,路由也會把訊號縮放到這個範圍。
def沒有自動化、也沒有覆寫時的值。核心只讀 def,只有 autoSurface() 另外看得懂 default。
step覆寫的值會對齊到 step 的倍數。在時間軸上,有 step 的參數會在每個關鍵影格停住,不做內插。
pulse設成 true,它就變成一次性的觸發:控台會顯示 fire(觸發)按鈕,映射過來的脈衝訊號(或一個往上越過 0.5 的連續訊號)會觸發它,世界用 params.onPulse(key, cb) 來聽。脈衝參數在 state 裡沒有值。
group分組用的標籤。聲音引擎的參數用 'sound'。autoSurface() 會替每一組做一頁手機頁面。
options有 step 的參數,每個值各叫什麼名字(['Circle', 'Petal', 'Star']),手機控制面板會把它們顯示成單選按鈕。
surface給手機控制面板的提示:{ type, color, label }。

兩個註冊過的世界如果宣告了同一個 key,就共用同一個參數(以先宣告的為準)。

大家最常違反的那條規則#

連續控制一律走參數。事件可以直接用訊號。

如果你的世界在 update() 裡直接讀 signals.get('midi/cc/74'),它還是會動,至少今天、接你的控制器時會動。但時間軸、舞者、別人的控制器設定檔,就再也推不動它了。你把這場演出焊死在一個輸入上了。改用路由:宣告一個參數,讓映射器接上 midi/cc/74 → yourParam,同一個世界誰來都能演奏。

事件不一樣:「按下一個音」「一個和弦解決了」「打到一次起音」是瞬間,不是持續的量。在 init() 裡訂閱這些事件是對的,我們也鼓勵這樣做。有了這些事件,世界才會回應你,不然它只是被參數推著走。

常用的事件訊號:midi/note/on 和 midi/note/off(任何鍵盤、螢幕鋼琴、模擬演奏者、手機都會發)、chord/event(每一次彈奏做一次分析)、audio/onset、audio/kick、drum/kick。完整清單在訊號一覽。

場景與自動化#

時間軸跟世界寫在一起,在呼叫 createShow() 時設定:

js
await createShow({
  world: gardenWorld,
  timeline: {
    total: 120,                                       // seconds
    automation: {
      growth: [[0, 0.6], [40, 1.4], [90, 0.8], [120, 0.2]],   // [t, value], linear between keyframes
      wind:   [[0, 0.05], [60, 0.3], [100, 0.7]],
    },
    scenes: [
      { id: 'dawn',  t: 0,  title: 'Dawn',       note: 'single seeds · listen' },
      { id: 'bloom', t: 40, title: 'Full bloom', note: 'triads — stack real thirds' },
      { id: 'storm', t: 90, title: 'Storm',      note: 'clusters welcome' },
    ],
  },
  modules: { keys: { base: 48 }, chord: true, sound: true },
});
  • 關鍵影格寫成 [seconds, value],依時間排序。第一個關鍵影格之前取第一個值,最後一個之後取最後一個值。
  • 場景依 t 排序。title 和 note 是演奏者在演出模式(T)裡讀到的文字,下方還會顯示下一個場景和倒數。
  • t 為負數的場景,是演出開始前的待命段落:設成 t: -30,時鐘就從 -0:30 開始走。
  • 試著只用時間軸演出你的世界。如果很無聊,就是少了一個參數。

細節見演出控制。

渲染器#

舞台本身不帶渲染器。在 init 裡建一個,在 dispose 裡銷毀。

2D canvas#

@openav/stage 的 createCanvas(container, { alpha = false }) 回傳 { canvas, ctx, fit, dispose }。fit() 讓 canvas 跟容器一樣大(裝置像素比最高到 2),回傳以 CSS 像素計的 { w, h }。在 render() 一開頭呼叫它。範例 01、02、03、07、08 和 09 都用它。

p5.js#

在範例的 index.html 用 script 標籤載入 p5,再用 instance mode 跑在容器裡。p5 有自己的繪圖迴圈,所以 update 只負責存下 state,render 留空(範例 05 和 06):

html
<script src="https://cdn.jsdelivr.net/npm/p5@1.9.4/lib/p5.min.js"></script>
js
const world = {
  name: 'p5-world',
  params: [{ key: 'hue', min: 0, max: 360, def: 200 }],
  init({ container }) {
    const self = this;
    this.s = {};
    this.p5 = new p5((sk) => {
      sk.setup = () => { sk.createCanvas(container.clientWidth, container.clientHeight); sk.colorMode(sk.HSB); };
      sk.draw = () => { sk.background(self.s.hue ?? 200, 60, 20); };
      sk.windowResized = () => sk.resizeCanvas(container.clientWidth, container.clientHeight);
    }, container);
  },
  update(dt, state) { this.s = state; },
  render() { /* p5 runs its own loop */ },
  dispose() { this.p5?.remove(); },
};

three.js#

內附的範例目前都沒用 three.js,寫法如下。把 three 加進範例的 import map("three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js"),渲染器存在 this 上,所有東西都要 dispose:

js
import * as THREE from 'three';

const orbit = {
  name: 'orbit',
  params: [{ key: 'spin', min: 0, max: 3, def: 1 }],
  init({ container }) {
    this.container = container;
    this.renderer = new THREE.WebGLRenderer({ antialias: true });
    container.appendChild(this.renderer.domElement);
    this.scene = new THREE.Scene();
    this.camera = new THREE.PerspectiveCamera(50, 1, 0.1, 100);
    this.camera.position.z = 4;
    this.mesh = new THREE.Mesh(new THREE.IcosahedronGeometry(1, 2), new THREE.MeshNormalMaterial({ wireframe: true }));
    this.scene.add(this.mesh);
  },
  update(dt, s) { this.mesh.rotation.y += dt * s.spin; },
  render() {
    const w = this.container.clientWidth, h = this.container.clientHeight;
    if (w !== this.w || h !== this.h) {
      this.w = w; this.h = h;
      this.renderer.setSize(w, h); this.camera.aspect = w / h; this.camera.updateProjectionMatrix();
    }
    this.renderer.render(this.scene, this.camera);
  },
  dispose() {
    this.mesh.geometry.dispose(); this.mesh.material.dispose();
    this.renderer.dispose(); this.renderer.domElement.remove();
  },
};

WebToe 節點網路#

@openav/world-webtoe 的 webtoeWorld() 把一張 WebToe 節點網路變成一個世界。節點網路跑在 iframe 裡。哪一格有參數改變,就把算好的參數值傳進 iframe,節點網路裡寫成 ext('name', fallback) 的參數都會收到(範例 04):

js
import { webtoeWorld } from '@openav/world-webtoe';

const world = webtoeWorld({
  name: 'garden-patch',
  project: new URL('./garden.webtoe.json', location.href).href,   // the app fetches it: CORS must allow it
  params: [
    { key: 'speed', min: 0, max: 1, def: 0.5 },
    { key: 'hue', min: 0, max: 360, def: 205 },
  ],
  // extra: (state, out) => { out.hueRad = state.hue * Math.PI / 180; },   // derive more ext() values
});

選項:name(預設 'webtoe')、app(預設 https://webtoe.openaudiovisual.com/)、project、params、extra。

DOM、SVG、影片#

任何東西加進 container 都可以。舞台只負責呼叫你的函式。

一場演出裡的多個世界#

js
const show = await createShow({ world: calm, worlds: [storm, after], timeline });
// switch on a cue: the old world is disposed, the new one initialized
show.timeline.onSceneChange((i, scene) => {
  if (scene.id === 'storm') show.stage.activate('storm');
});

所有世界的參數一開始就會註冊,所以控台和時間軸碰得到每一個世界的參數。那個世界已經啟用的話,stage.activate(name) 什麼都不做。

從世界輸出聲音#

update(dt, state, io) 會收到 io。用 createShow() 時,io 裡只有 signals。演出建好之後,再把輸出用的物件加上去,每個世界都看得到:

js
const show = await createShow({ world });
show.stage.io.midi = show.midi;          // the show's @openav/midi engine (MIDI out)
// show.stage.io.osc = osc;              // an OscOut you created (see Show control → OSC output)

接著在世界裡:

js
// trigger a sampler note when something happens in the simulation
io.midi?.noteOn(48 + creature.species * 12, 90, 2);   // note, velocity 0..127, channel 2

// stream a position to a spatializer
io.osc?.send(`/source/${i}/xyz`, [x, y, z]);

很多時候,直接在組裝演出的程式裡處理會更簡單,範例 05 就是這樣:show.signals.on('midi/note/on', ({ note, vel }) => show.midi?.noteOn(note, Math.round(vel * 127), 1))。要用頁面裡的樂器(平台鋼琴、敲擊琴、弦樂、風琴、合成器音色),請用 modules.sound(演出控制)。

演出前檢查清單#

  • 每一個連續控制都是參數(試著只用時間軸演出你的世界)
  • dispose() 會釋放 GPU 物件和事件訂閱(世界會在演出中即時切換)
  • dt 突然變大時,世界撐得住(Loop 會把它限制在 100 ms 以內,但別假設它是 16 ms)
  • 世界裡沒有任何地方直接讀時鐘:時間歸時間軸管
  • 頁面載入時瀏覽器主控台零錯誤,只用螢幕鋼琴也跑得動

輸入#

06原始檔: docs/zh/inputs.md

每一種輸入只做一件事:發出訊號。用 createShow() 時,在 modules 裡打開需要的輸入就好。每一種輸入也都是普通的類別,可以單獨拿出來用。訊號的確切名稱和範圍,查訊號一覽。

輸入套件modules 的 key預設發出的訊號
MIDI 硬體@openav/midimidi開(設成 false 就關掉)midi/…
螢幕上的 MIDI 控制器@openav/midimidi: { controllers }關midi/<device>/<control>
螢幕鋼琴、電腦鍵盤、模擬演奏者@openav/keyskeys開(設成 false 就移除)midi/note/on、midi/note/off
鼓機@openav/drumsdrums關drum/…,以及第 10 頻道的 midi/note/on
麥克風@openav/audioaudio關audio/…
和弦分析@openav/chordchord關chord/…
身體(鏡頭)@openav/posepose關pose/…
手(鏡頭)@openav/posehands關hand/…
手(Leap Motion)@openav/leapleap關leap/…
手機與 iPad@openav/remoteremote關phone/…、surface/…、midi/note/…

麥克風、鏡頭這類需要權限、或要使用者先點一下才能開的來源,createShow() 會先建好,但要等你在控台的 L1 · Input(輸入)面板按下對應的按鈕,才會開始:🎤 mic(麥克風)、🖐 hands(手)、🕺 body(身體)。

MIDI#

createShow() 啟動時會建立一個 Midi 引擎並呼叫 enable(),所以頁面一打開,瀏覽器可能就會跳出 MIDI 權限的詢問。演出中可以隨時插拔裝置,L1 · Input 面板會列出它們,取消勾選某一台就能把它靜音,不用拔線。

每收到一則訊息,都會用兩組名稱發出去:

  • 舊式名稱(legacy,大多數世界用的就是這組,不分頻道):midi/note/on 和 midi/note/off 脈衝、midi/cc/<n>(0..1)、midi/bend(−1..1)。
  • 分頻道:midi/ch/<ch>/cc/<n>、midi/ch/<ch>/note/<n>(按住時是 0..1 的力度,放開時為 0)、midi/ch/<ch>/bend、midi/ch/<ch>/pressure、midi/ch/<ch>/poly/<n>。

note-on 帶的內容是 { note, vel, velocity, ch, device }:vel 是 0..1,velocity 是原始的 1..127,ch 是 1..16,device 是連接埠的 slug。

接了兩台以上的裝置時,每一台還會用自己的 slug 另外發一份,控制項才不會撞名:midi/<slug>/cc/<n>、midi/<slug>/note/on、midi/<slug>/note/off、midi/<slug>/bend。slug 取自連接埠名稱(Arturia MiniLab 3 → arturia-minilab-3,同型號的第二台會加上 -2),所以裝置斷線再接回來,路由還在。舊式名稱也照常發出,所以接在 midi/cc/74 上的路由聽得到每一台裝置。

Clock 訊息直接略過。Program change、transport 和 SysEx 不會發出(框架從不要 SysEx 權限)。

不透過 createShow(),單獨使用:

js
import { Midi } from '@openav/midi';

const midi = new Midi({ signals });     // options: signals, filterOut = 'IAC', requestAccess
await midi.enable();                    // false if the browser has no Web MIDI or permission was denied
midi.devices();                         // [{ slug, name, listening }]
midi.setListening('nanokontrol2', false);

filterOut 是一個不分大小寫的正規表示式,名稱符合的輸入連接埠一律略過。預設值 'IAC' 把 macOS 的 IAC bus 擋在外面,不然演出透過 IAC 送出 MIDI,又會聽到自己送出的訊息。想從 IAC 接收,請看疑難排解。MIDI 輸出寫在演出控制。

螢幕上的已知控制器#

modules: { midi: { controllers: { profile: '<profile id>' } } } 會在螢幕上放一張已知控制器的圖。接上那台控制器,畫面就跟著你的手一起動,沒接的話,用滑鼠或手指直接在畫面上彈。它的控制項會發出 midi/<device>/<control> 這類名稱,controllerRoutes() 幫你寫好接到參數的路由。設定檔(profile)、怎麼 learn 不認識的裝置、LED 回饋和嵌入,都在MIDI 控制器與嵌入這一章。支援的裝置列在控制器頁面。

螢幕鋼琴、電腦鍵盤與模擬演奏者#

@openav/keys 預設開啟。它會在控台上方放一台鋼琴,附兩個核取方塊:keyboard(電腦鍵盤擷取)和 simulate performance(模擬演奏)。選項(modules.keys):base(最低音,預設 48)、octaves(預設 2)、sim(是否顯示模擬演奏的核取方塊,預設 true)、capture(是否顯示 keyboard 核取方塊,預設 true)。

它發出 midi/note/on { note, vel, ch: 0 } 和 midi/note/off { note, ch: 0 }。注意跟硬體不同:ch 是 0,而且沒有 velocity 和 device 欄位。只讀 note 和 vel 的世界,兩種都能用。

  • 電腦鍵盤(勾選 keyboard 之後):A W S E D F T G Y H U J K O L P ; 從 base 開始,依序彈出相差半音的 17 個音。Z/X 移動一個八度(base 維持在 24 到 84 之間),按住 Shift 力度加 20。擷取開著的時候,鋼琴會接管所有字母鍵(preventDefault),Space、方向鍵和數字鍵照常交給控台。
  • 模擬演奏者(SimPlayer)在比 base 高一個八度的地方彈五聲音階:大多是級進,偶爾跳進或彈三和弦,中間也會真的停下來。用程式碼控制:show.keys.sim.toggle(true)。
js
import { mountKeys, KeysPiano, SimPlayer, PIANO_KEYMAP } from '@openav/keys';

const keys = mountKeys(el, { signals, base: 48, octaves: 2 });   // → { piano, sim, update(dt), dispose() }
// call keys.update(dt) every frame (it drives the SimPlayer)

鼓機#

modules: { drums: true } 會加上一台 16 步、四軌(kick、snare、hat、clap)的音序器,附節奏型(four on floor、breakbeat、half time、latin、sparse)、速度滑桿(60–180 BPM,預設 112)、swing,以及模擬真人手感的時間偏移。勾選 drum machine(鼓機)就開始打。它用自己合成的鼓組發聲(不用取樣音色),發出:

  • drum/kick、drum/snare、drum/hat、drum/clap:脈衝 { level }。
  • drum/<lane>/env:每一軌一條 0..1 的波封,大約 0.12 秒衰減完,可以直接映射到參數。
  • midi/note/on { note, vel, ch: 10 },用 General MIDI 的音高(kick 36、snare 38、clap 39、closed hat 42)。

這些訊號跟麥克風偵測鼓點時發出的長得一樣(audio/kick、audio/kick/env…),所以映射到 kick 的世界分不出真的大鼓和鼓機。範例 06 就把兩者接到同一組參數。選項(modules.drums):engine(改用另一個聲音引擎)、autoEnableEngine(預設 true:第一下打擊就會啟動鼓組的音訊引擎,不必另外點一下)。

麥克風#

modules: { audio: true } 會建立一個 AudioAnalyzer,按下 🎤 mic 之後麥克風才會開始收音。(範例 06 寫的是 audio: 'mic',任何 truthy 的值都可以。)回音消除、降噪和自動增益都是關掉的,分析聽到的就是現場原本的聲音。

每一影格發出:audio/rms(平滑過的音量)、audio/peak、audio/band/low(20–250 Hz)、audio/band/mid(250 Hz–2 kHz)、audio/band/high(2–8 kHz)、audio/centroid(亮度),以及脈衝 audio/onset { rms },每次觸發後有 100 ms 的冷卻時間。鼓點偵測把聲音瞬間的起音(暫態)依頻段拆開:audio/kick(20–120 Hz)、audio/snare(150–800 Hz)、audio/hat(6–14 kHz),每個都是脈衝 { level },並附一條對應的 …/env 波封。

js
import { AudioAnalyzer } from '@openav/audio';

const audio = new AudioAnalyzer({ signals, fftSize: 2048, smooth: 0.7 });
await audio.enableMic();            // or audio.enableElement(videoEl), or someNode.connect(audio.input())
// every frame: audio.update()      → also returns { rms, peak, low, mid, high, centroid, onset, kick, snare, hat }

和弦#

modules: { chord: true }(或 { chord: { window: 80 } })會加上一個 ChordDetector,把每一個 midi/note/on 和 midi/note/off 餵給它。它把 window 毫秒內(預設 80)按下的音歸成一次彈奏,每次彈奏發出:

  • chord/consonance(−1..1)、chord/count(音的數量)、chord/root(最低的 MIDI 音)。
  • chord/event,一個帶著完整分析結果的脈衝:
欄位意義
notes, count, root, vel, pcs排序後的音、音的數量、最低音、平均力度(0..1)、音級(pitch class)
consonance兩兩音程權重的平均,−1..1(單音為 1)
isConsonant, isDissonant有兩個以上的音,而且協和度 > 0.25/< −0.15
isTriad和弦類型是大三、小三、sus2、sus4、減三或增三和弦
thirdsFraction相鄰音程中,3 或 4 個半音所占的比例(「真正一層層疊上去的三度」)
dissonanceLevel0 無 · 1 輕微(暴風雨的預兆)· 2 嚴重(真正的音堆)
chordTypesingle、major、minor、sus2、sus4、dim、aug、maj7、min7、dom7、halfdim7、maj9、min9、dom9、six、min6、cluster 或 chord

它是替演出設計的語意層,原本是為一件作品做的:協和讓花園開花,音堆讓花園凋零(範例 02)。完整的樂理分析不在它的範圍內。detector.analyze(notes, vels) 是純函式,你也可以自己呼叫。

身體與手#

modules: { pose: true } 加上一個 PoseTracker(一個身體),modules: { hands: true } 加上一個 HandTracker(兩隻手,每隻 21 個點)。按下 🕺 body 或 🖐 hands,鏡頭才會開始。兩者都用 MediaPipe Tasks Vision(0.10.14),第一次啟用時從 jsDelivr 載入,模型從 Google 的儲存空間下載。推論在你的電腦上跑,影像不會離開這台機器。畫面預設左右鏡像(mirror: true),你舉右手,畫面右邊的手跟著動。y 軸是反過來的,1 代表舉高。

  • 身體:pose/present、pose/hand/left/x|y、pose/hand/right/x|y(手腕)、pose/hand/left/v、pose/hand/right/v(手腕速度)、pose/hands/spread、pose/height(鼻子高度:蹲下 ↔ 站起)、pose/lean(−1..1)。
  • 手:每一側各有 hand/<side>/present、hand/<side>/x|y(手掌)、hand/<side>/pinch/index 和 hand/<side>/pinch/middle(拇指尖到手指尖)、hand/<side>/spread(食指尖到小指尖)。距離都除以手掌大小,所以手往鏡頭靠近,捏合的值不會變。捏緊時數值接近 0:如果希望越捏越大,在路由上設 invert: true(範例 03)。

兩種追蹤器都能把骨架畫在 2D context 上:tracker.skeleton(ctx, w, h)。

Leap Motion#

modules: { leap: true } 加上一個 LeapInput。瀏覽器讀不到感測器,所以每台電腦跑一支小橋接程式:node packages/leap/bridge/leap-bridge.mjs(要先裝 Ultraleap Hand Tracking;加 --mock 不接感測器也有兩隻會動的假手;macOS 上 bash packages/leap/bridge/install.sh 讓它開機就在跑)。它只在本機迴路上提供 ws://127.0.0.1:6437。控台的 L1 · Input 面板會說哪一段沒接上(橋接、追蹤服務、裝置),並畫出看到的手;面板上的 simulate 按鈕把滑鼠變成手。

訊號:每一側各有 leap/hand/<side>/present、x|y|z(手掌在互動空間裡的位置,0..1,y 往上、z 朝向你)、pinch、grab、roll|pitch|yaw(弧度)、speed,指尖 leap/hand/<side>/<finger>/x|y|z;另有 leap/hands、leap/both/distance、leap/status;脈衝 pinch-start|pinch-end、grab-start|grab-end(每一側)與 leap/both/pinch-start|pinch-end,都有遲滯(捏超過 0.86 才開始、低於 0.5 才結束)。要畫手的關節,讀 leap.hands。同一支橋接在 /v6.json 回應舊的 leap.js 作品,在 /raw 送原始的手部資料(見範例 12 與套件 README)。

手機與 iPad#

modules: { remote: true } 讓手機透過 serve.js 架起的中繼加入演出。手機的感測器發出 phone/<id>/…(傾斜、加速度、旋轉、敲擊、觸控、光線),同時複製一份到 phone/any/…。控制面板發出 surface/<page>/<widget>,手機上的琴鍵像一般鍵盤一樣發出 midi/note/on|off。演出頁面如果是在手機上打開,也能用 localSensors() 讀這支手機自己的動作感測器。完整說明在手機、中繼與控制面板。

自己做一個輸入#

任何呼叫 signals.set() 或 signals.pulse() 的東西,都是輸入。下面把滑鼠/觸控指標當成樂器:

js
const { signals } = show;
signals.define('pointer/x', { source: 'pointer' });     // continuous, 0..1 by default
signals.define('pointer/y', { source: 'pointer' });
signals.define('pointer/tap', { kind: 'pulse', source: 'pointer' });

addEventListener('pointermove', (e) => {
  signals.set('pointer/x', e.clientX / innerWidth);
  signals.set('pointer/y', 1 - e.clientY / innerHeight);  // 1 = top, like every other y
});
addEventListener('pointerdown', (e) => signals.pulse('pointer/tap', { x: e.clientX, y: e.clientY }));

show.mapper.addRoute({ source: 'pointer/x', target: 'hue', smooth: 0.25 });

命名時把來源放在最前面(breath/pressure、weather/wind),宣告它的範圍,下游的一切(儀表、learn、路由、手機控制面板)都不用改就能用。

映射#

07原始檔: docs/zh/mapping.md

在映射層,「發生了什麼」變成「它代表什麼」。把訊號接到參數的,只有 Mapper(@openav/mapping)這一個元件,它手上就只有一份路由清單。

路由#

一條路由就是一個普通物件。只有 source 和 target 是必填,其餘由 addRoute() 補上:

欄位預設意義
source—訊號名稱,例如 midi/cc/74、hand/right/pinch/index、phone/any/tilt/x
target—參數的 key,例如 bloom、sound/cutoff
inMin, inMax0, 1取用訊號的哪一段,超出的值會壓在邊界上
outMin, outMax參數的 min、max寫進參數的範圍
curve'linear'linear、exp、log 或 smooth
invertfalse在套用曲線之前,把正規化後的值翻過來(1 − x)
smooth0滑到新值所需的時間,單位是秒(0 = 立即到位)
mode(沒寫 = 'override')'override' 取代時間軸的值,'trim' 疊加在它上面,'pickup' 要旋鈕先碰到參數的值才接管:見微調、接管與放手
release(沒寫 = 不放手)訊號靜止這麼多秒之後,路由放手、時間軸接回去
enabled(沒寫 = 開啟)設成 false 就把這條路由靜音
id自動指定一個數字,移除路由時用
js
show.mapper.addRoute({ source: 'midi/cc/74', target: 'bloom' });
show.mapper.addRoute({ source: 'phone/any/tilt/x', target: 'drift', inMin: -1, inMax: 1, smooth: 0.12 });
show.mapper.addRoute({ source: 'hand/right/pinch/index', target: 'tightness', curve: 'smooth', invert: true, smooth: 0.1 });

在 createShow() 裡,同樣的物件放進 routes: [...]。

一個數值經過哪些步驟#

訊號一到,每一條啟用中、source 相符的路由,都會依序跑這幾步:

  1. 輸入窗:x = (value − inMin) / (inMax − inMin),限制在 0..1 之間。
  2. 反轉:如果有 invert,x = 1 − x。
  3. 曲線:x = curve(x)。
  4. 縮放:out = outMin + (outMax − outMin) · x。
  5. 寫入:smooth: 0 時,直接用 out 覆寫參數(並限制在參數的範圍內、對齊它的 step)。smooth > 0 時,out 變成一個目標值,mapper.update(dt) 每個影格把參數往它推近一點。trim 路由寫的是時間軸的值加上 out;pickup 路由在旋鈕碰到參數之前什麼都不寫。

曲線#

曲線公式手感
linearx手怎麼動,值就怎麼動
expx²起步慢、尾端快:低段可以細調
log√x起步快、尾端慢:高段可以細調
smoothx²(3 − 2x)兩端都平緩(smoothstep)

不認得的曲線名稱,會退回 linear。

輸入窗與輸出範圍#

inMin/inMax 決定取訊號的哪一段,outMin/outMax 決定它落在參數的哪裡。常見用法:

  • 雙極訊號:{ source: 'midi/bend', inMin: -1, inMax: 1 },或手機傾斜 { source: 'phone/any/tilt/x', inMin: -1, inMax: 1 }。
  • 很小聲的訊號:{ source: 'audio/rms', inMax: 0.3 },讓人聲實際到得了的音量,就能推滿整個參數範圍。
  • 讓旋鈕只推動參數範圍的一段:{ source: 'midi/cc/1', target: 'hue', outMin: 180, outMax: 270 }。
  • 不用 invert 的反向關係:outMin: 1, outMax: 0。

平滑#

smooth 是時間常數,單位是秒:過了 smooth 秒,參數大約走完到新值 63% 的距離(單極點濾波器,每個影格 k = 1 − e^(−dt/smooth))。0.05–0.15 可以藏住 MIDI 旋鈕或 30 Hz 手機資料流的階梯感,0.2–0.5 會讓手的動作變得沉重。滑行從參數目前的值出發(手動設的值,否則就是時間軸現在說的,見 base),所以第一下動作絕不會跳,而且滑到了就停筆。

脈衝目標#

目標是 pulse 參數時,路由不寫數值,改成觸發它:

  • 脈衝來源(midi/note/on、audio/kick、drum/kick、phone/any/knock…)每來一個事件就觸發一次。
  • 連續來源在正規化後的值往上越過 0.5 時觸發(手機控制面板上的按鈕從 0 變成 1、推桿推過中間)。

curve、invert、smooth 和輸出範圍,對脈衝目標都不起作用。

多對多#

一個訊號可以推動很多個參數(加幾條 source 相同的路由),一個參數也可以聽很多個訊號。兩條路由寫同一個參數時,最後寫入的那條算數。Learn 只會新增路由,從不取代既有的路由。

跳線盤設計規劃了每條路由的 combine(last、max、add、avg)和 label 欄位,目前還沒做。

覆寫與時間軸#

路由用覆寫的方式寫入參數,而覆寫會黏住:映射過來的訊號一動,時間軸就不再推那個參數。清掉覆寫(按參數旁的 ✕,或 show.params.clearOverride(key)),參數就交還給時間軸,直到訊號再動一次。

有平滑的路由只在滑行的時候寫入。滑到了就停筆,所以按 ✕(或你拖動滑桿)就能把參數拿回來,而且在旋鈕再動之前它都會留在手上;滑到一半按 ✕,滑行就停下。映射器會發現參數在它上一次寫入之後被別人寫過,然後退讓。路由靜音之後就不再寫入,參數維持原本的值(靜音的 trim 會把偏移還回去)。

取代式的路由握著參數的時候,時間軸的曲線就被丟在一邊。如果旋鈕只該微調時間軸,或是放開手就該還給它,請看下一節。

微調、接管與放手#

有三個路由欄位決定旋鈕碰上時間軸時誰說了算。沒寫就全部不起作用:沒有 mode 也沒有 release 的路由,就是上面說的取代式路由。

欄位旋鈕做什麼
mode: 'override'預設:旋鈕的值取代時間軸的值,直到按 ✕
mode: 'trim'旋鈕的值是一個偏移,加在時間軸的值上,時間軸在底下照樣往前走
mode: 'pickup'跟 override 一樣,但旋鈕要先碰到參數現在的值,才接管
release: 4任何模式都能用:旋鈕靜止 4 秒就放手,讓時間軸接回去

mode 和 release 對脈衝目標不起作用。

告訴映射器時間軸在哪裡#

trim、pickup,還有平滑滑行的起點,都需要知道參數此刻在時間軸上的值。映射器從 base 取得,它是一個回傳 { key: value } 的函式:

js
const mapper = new Mapper({ signals, params, base: () => timeline.state() });
// a show made with createShow() already does this for you

timeline.state() 是還沒套用覆寫的值,而且總譜的段落模組已經套用過了,也就是沒有人碰它時參數會有的值。沒有 base 的話,映射器用參數的 def:對沒有任何自動化的參數是對的,對時間軸畫著曲線的參數就不對。base 丟出錯誤或回傳別的東西,就當作沒有,絕不會擋住演出。它要輕:trim 握著參數的每個影格都會問一次,trim 或 pickup 的旋鈕每次讀數也會再問。

trim:在時間軸上微調#

時間軸已經把整場演出畫好的作品,不該因為旋鈕轉到 0.9 就把曲線整條丟掉。trim 路由的 outMin/outMax 是偏移量的範圍,參數等於 時間軸的值 + 偏移,再夾在參數的範圍內。沒寫的話,旋鈕往兩邊各走參數範圍的一半(旋鈕在中間 = 不動):

js
// ±30° around whatever the timeline says, smoothed
show.mapper.addRoute({ source: 'midi/cc/74', target: 'hue', mode: 'trim', outMin: -30, outMax: 30, smooth: 0.1 });
  • 偏移騎在時間軸上:曲線動,參數每個影格都跟著動。
  • smooth 平滑的是偏移量(從 0 開始,不會跳)。
  • 同一個參數上的兩條 trim 路由會相加,所以粗調和細調兩顆旋鈕可以一起用。參數上若同時有取代式路由,trim 疊在取代式路由的值上面。
  • trim 握著參數的時候,參數是被覆寫的狀態:控台會在它旁邊顯示 ✕,讀覆寫值的 timeline.record 來源拿到的是加總後、觀眾看到的值。✕ 清掉偏移,旋鈕下次再動它就回來。移除或靜音路由,參數馬上交還。

pickup:到了才接管#

旋鈕和參數很少一開始就在同一個位置。用 mode: 'pickup' 時,旋鈕的值要先碰到參數現在的值,路由才開始寫入:離得不到路由輸出範圍的 2%,或是兩次讀數之間越過了它。之後它就像取代式路由,從參數原本的位置滑過去(不跳)。比較用的是參數此刻的值,所以時間軸在動的時候也成立。release 或 ✕ 會把路由放回「還沒碰到」。

release:還回去#

release: 4 的意思是:訊號 4 秒沒有動,路由就放手。「動」指的是變化超過輸入窗的 0.1%,從上次算動過的位置開始量,所以慢慢飄也算動,而一直重送同一個值的來源不算。放手時:

  • smooth: 0:參數當場回到時間軸;
  • smooth > 0:用大約三倍 smooth 秒淡進時間軸,然後清掉覆寫(trim 是把偏移淡到 0);
  • 放手之後,路由要等來源再動才會接管:一直重送同一個值的來源拿不回參數;
  • 它只清自己寫的。如果這段時間滑桿已經接手,就讓它留著。
js
// a main knob: meets the value first, glides, and gives the param back 4 s after the hand leaves
show.mapper.addRoute({ source: 'midi/cc/71', target: 'bloom', mode: 'pickup', release: 4, smooth: 0.15 });

Learn#

在 L3 · Params(參數)面板裡,點參數旁的 learn(或呼叫 mapper.learn('bloom')),然後動一樣東西。映射器會綁定第一個符合下列條件的訊號:

  • 從 learn 開始時的位置移動了至少宣告範圍的 5%(旋鈕、推桿、手、手機傾斜),或
  • 它是脈衝,而且觸發了一次(琴鍵、打擊墊、敲擊)。

新路由用的是預設值:線性、不平滑、參數的完整範圍。需要曲線的話,事後再改。再點一次 learn 就取消。learn 是「加入」:已經有路由的參數會保留原本那條,再多一條。

要一口氣綁一整串,L2 · Mapping(映射)面板有 🎛 map knobs in order:它先替第一個參數啟動 learn,你轉一顆旋鈕就綁上,接著自動換下一個參數。skip、back、stop(或按 Esc)可以操控它。程式裡用 LearnWizard(細節)。

一則 MIDI 訊息同時發出好幾個名稱時(midi/cc/74、midi/ch/1/cc/74,接兩台裝置時還有 midi/<slug>/cc/74),learn 綁定的是第一個,也就是聽得到每一台裝置的 midi/cc/74。如果只想聽其中一台,把 source 改成那台裝置的專屬名稱。

靜音與移除#

L2 · Mapping 面板把每條路由列成 source → target,各附一個核取方塊(靜音)和 ✕(移除)。用程式碼的話:

js
const r = show.mapper.routesFor('bloom')[0];
r.enabled = false;                  // mute
show.mapper.removeRoute(r.id);      // remove

儲存的設定檔#

映射器把路由存在 localStorage 的 openav.map.<profile> 底下。createShow() 用世界的名稱當設定檔名稱(或用 profile 選項),並且:

  1. 有儲存的路由就載入,沒有的話就加入宣告的 routes。
  2. 已經有儲存的設定檔時,宣告的路由裡 source → target 組合還沒出現過的,也會補進去,所以程式碼裡新加的路由一定會出現。
  3. 每 3 秒存一次。

所以 learn 來的路由和你做的修改,重新載入之後都還在。反過來說:如果你在程式碼裡改了某條宣告路由的曲線或平滑,同一組 source → target 以儲存的版本為準。要從乾淨的狀態開始,就傳入 profile: false(每次載入都從程式碼讀路由,像範例 09 那樣),或刪掉儲存的設定檔:

js
localStorage.removeItem('openav.map.particles');   // 'particles' = the world's name

要把一套接線帶到另一台電腦、或另一個世界,用對應檔(下一節)。

對應檔:匯出、匯入與分享#

L2 · Mapping 面板在「map knobs in order」下面有三個按鈕:

  • ⬇ export:把目前的路由下載成 oav-map-<世界名>.json。
  • ⬆ import:選一個對應檔。也可以把 .json 拖進頁面任何地方。匯入會取代現有路由,新的這組馬上被記住。
  • clear:移除全部路由(要點兩下)。下次載入時,世界宣告的路由會回來,跟第一次來一樣。

按鈕下面會寫最近一次匯入的結果:進來幾條、略過哪幾條、為什麼。讀不了的檔案會說明原因,而且不動任何路由。

格式#

json
{
  "format": "openav.map",
  "version": 1,
  "world": "particles",
  "exported": "2026-10-15T08:30:00.000Z",
  "routes": [
    { "signal": "midi/cc/74", "param": "bloom", "curve": "exp",
      "range": { "in": [0, 1], "out": [0, 100] }, "smooth": 0.1, "invert": false },
    { "signal": "audio/rms", "param": "energy", "curve": "linear",
      "range": { "in": [0, 0.3], "out": [0, 1] }, "smooth": 0, "invert": false, "enabled": false }
  ]
}

路由用 signal 和 param 的名字指認,不用 id,所以檔案可以在不同世界之間搬:

  • 這個世界沒有的 param:略過並列出來。
  • 這場演出裡沒有東西能產生的 signal(例如沒有 Leap Motion 模組卻有 leap/palm/x):略過並列出來。要等第一則訊息才會出現的訊號(midi/…、surface/…、phone/…、osc/…、key…、take/…)會留下,算作「等待中」。
  • 檔案的 world 跟現在不同時,range.out 會丟掉,讓每個 param 用自己的範圍(in 窗、曲線、平滑、反相照樣帶過來)。
  • version 比這個版本讀得懂的新,會拒絕並說明。mapper.toJSON() 的純陣列(舊作法)仍然可以匯入,當作版本 0。
  • mode("trim" 或 "pickup")和 release(秒)是版本 1 裡選填的路由欄位,路由有用到才會寫出來。還沒有這兩個欄位的舊版會直接忽略,把那條路由當成取代式路由讀。trim 路由的 range.out 是偏移量的範圍。
  • 超過 256 KB 或超過 500 條路由的檔案會被拒絕。

開頁就載入:?map=#

text
https://openaudiovisual.com/examples/01-hello-particles/?map=https://example.com/my-map.json
https://openaudiovisual.com/examples/01-hello-particles/?map=maps/stage-left.json

?map=<網址> 在頁面打開時抓檔案,像匯入一樣載入。只接受同源位址(含相對路徑)或絕對的 https 位址;指向其他主機的 http:、data:、javascript:、file:,以及帶帳號密碼的位址都會被拒絕。跨站的檔案要有 CORS(Access-Control-Allow-Origin: *;raw GitHub 和 gist 都有)。演出照常開始:位址被拒、抓取失敗或檔案有問題時,面板會顯示原因,路由維持原樣。明確寫的 ?map= 優先於被記住的接線,載入的內容也會像匯入一樣被記住。程式裡 createShow({ map: 'maps/a.json' }) 效果相同,map: false 則忽略 ?map=。

自動記住#

映射器每 3 秒、以及每次匯入或清除之後,把路由存進 localStorage(openav.map.<世界名>),每個世界一格,下次打開從你停下的地方繼續。每次讀寫都包了 try/catch:私密視窗或儲存被擋時什麼都不會壞,只是不會被記住。

程式裡:

js
import { loadMapUrl, parseMap } from '@openav/mapping';

const file = show.mapper.exportMap();                    // the object above
const report = show.mapper.importMap(text);              // text or object; { mode: 'add' } keeps current routes
// → { ok, added, skipped: [{ signal, param, reason: 'param' | 'signal' }], waiting, dropped, crossWorld }
await loadMapUrl(show.mapper, 'maps/a.json');            // what ?map= calls; never throws
parseMap(text);                                          // validate without touching a mapper

替你寫好的路由#

有幾個套件會產生同樣格式的路由:

  • autoSurface(world.params)(@openav/surface)會做出一個手機控制面板,以及它需要的 surface/<page>/<widget> → param 路由,帶 smooth: 0.04。routesFromLayout(layout, params) 對手寫的版面做一樣的事(手機、中繼與控制面板)。
  • controllerRoutes(profile, { knob1: 'hue', pad1: 'burst' })(@openav/midi)依螢幕上控制器的各個控制項寫出路由(MIDI 控制器與嵌入)。

Mapper API#

js
import { Mapper } from '@openav/mapping';

const mapper = new Mapper({ signals, params, profile: 'default', onChange, onLearn, base });
mapper.addRoute(route)        // → the stored route (defaults filled in, id assigned)
mapper.removeRoute(id)
mapper.routesFor('bloom')     // → routes targeting a param
mapper.routes                 // the live array
mapper.learn('bloom')         // arm / cancel learn; mapper.learnTarget is the armed key
mapper.base = () => timeline.state()   // the timeline's value now (trim, pickup, smooth start); optional
mapper.update(dt)             // every frame: glides smoothed routes, keeps trims on the timeline, applies release
mapper.toJSON(); mapper.fromJSON(array)
mapper.exportMap(); mapper.importMap(text|object, { mode })   // the portable file, see above
mapper.clear()                // remove every route (and forget them)
mapper.report                 // what the last import / ?map= said
mapper.save(); mapper.load()  // localStorage 'openav.map.<profile>'; load() → true if found
mapper.dispose()              // stop listening to signals

onChange() 在路由變動時執行(給介面用),onLearn(route, signalName) 在 learn 綁定完成時執行。

演出控制#

08原始檔: docs/zh/show-control.md

把一張草稿變成一場演出,靠的是這一章的幾個部分:呼叫一次就組好的外殼、時間軸、控台、演出模式、後台監看,還有讓聲音和資料送出瀏覽器的幾種方式。

createShow#

createShow()(@openav/show)以一個世界為中心組好整場演出,再把每個部分交給你。它是 async,因為要等世界的 init 跑完。

js
import { createShow } from '@openav/show';

const show = await createShow({
  world: myWorld,
  timeline: { total: 120, automation: { hue: [[0, 205], [60, 320]] }, scenes },
  routes: [{ source: 'audio/rms', target: 'energy', inMax: 0.3, smooth: 0.1 }],
  modules: { keys: { base: 48 }, chord: true, audio: true, sound: true },
  artwork: { title: 'Untitled', artist: 'You', year: 2026 },
  hint: 'play the piano · Space plays the timeline',
});
選項預設意義
worldnull要演出的世界,最先啟用
worlds[]另外要註冊的世界(用 show.stage.activate(name) 切換)
timeline{ total: 120 }給時間軸的 { total, automation, scenes }
routes[]要加進映射器的路由(映射)
modules{}要打開的輸入與輸出(見下表)
artworknull{ title, artist, year, note }:舞台上的一行作品署名,以及一個 <meta name="artwork">
hint''舞台左下角的一行 HTML
map網址裡的 ?map=開始時載入的對應檔:同源或 https 網址。false = 忽略 ?map=(對應檔)
profile世界的名稱映射器儲存設定檔的名稱。false = 忽略儲存的路由(儲存的設定檔)
onFramenull(dt, show) => {},每個影格執行一次,在時間軸前進之前
mount自動產生要渲染進去的 { stage, side } 元素或選擇器,取代整頁版面
telemetrytrue每次載入頁面送一筆匿名的 oav_show_start(見控制器章的〈使用統計〉),false 就不送
scorenull{ cuts, cut, modules, api, midi, … }:把演出的結構寫成段落長度,由段落模組去演出。網址上的 ?cut=<id> 決定用哪個版本(總譜與導演)
loop'auto'誰來給影格:'auto'(頁面的 requestAnimationFrame)、'manual'(你自己呼叫 show.loop.step(dt)),或 { clock, raf, maxDt, heartbeat },也就是 new Loop() 的選項(見下)
monitortrue後台推送:false = 不推送(頁面不會開任何 socket),{ url, hz } = 換一個中繼位址或頻率
consolenull控台的選項,也就是 mountConsole 的:{ keys, layers, signals, learnOrder };keys 用來挪動鍵盤快捷鍵
syncnull好幾個頁面演同一場:{ role: 'leader' | 'follower', channel, url, input, extra, state, follow }。一個頁面當主控端,其餘的追它的時鐘,從屬端自己不收任何輸入(見下)

沒有 mount 時,頁面的 body 會變成兩欄的格線:一欄是舞台,一欄是 340 px 寬、放鋼琴和控台的側邊面板。

modules 的 key值加入什麼
midi預設開啟,或 falseMidi 引擎(輸入與輸出)
midi.controllerstrue 或 { profile, profiles, open }一台停靠在舞台上的螢幕 MIDI 控制器、一個 🎹 按鈕和 M 鍵。網址加上 ?profile=<id> 可以指定裝置(控制器)
keys預設開啟、false 或 { base, octaves, sim, capture }螢幕鋼琴、電腦鍵盤和模擬演奏者
drumstrue 或 { engine, autoEnableEngine }鼓機
audio任何為真(truthy)的值麥克風分析器(按 🎤 mic 啟動)
chordtrue 或 { window }對每個彈出的音做和弦分析
handstrue手部追蹤(按 🖐 hands 啟動)
posetrue身體追蹤(按 🕺 body 啟動)
remotetrue 或 { room, auto, surface, feedbackHz, url }手機和 iPad 當控制器(手機)
soundtrue、樂器 id('piano')或 { instrument, remember, picker, engine, baseUrl }頁面裡的樂器和選單,用 Tone.js(聲音)

它回傳 { signals, params, stage, timeline, mapper, midi, controllers, midiPanel, keys, drums, sound, audio, hands, pose, chord, remote, score, director, sync, monitor, console, app, loop },你沒要的部分是 null。同一個物件也掛在 window.openav,方便在 devtools 主控台裡查看。每個影格的執行順序寫在架構。

自己驅動影格#

預設情況下,演出跑在頁面的 requestAnimationFrame 上(分頁被藏起來時,由 Web Worker 心跳接手)。loop 讓你改由別人給影格:這樣就能一格一格精確錄影、把整場演出當一個單元測試、或讓它在沒有視窗的機器上跑一整晚,而不必換掉頁面的全域 requestAnimationFrame 或 performance.now。

js
// 'manual': nothing runs until you say so. Thirty show seconds, the same thirty every time.
const show = await createShow({ world, loop: 'manual', monitor: false });
show.timeline.play();
for (let i = 0; i < 60 * 30; i++) show.loop.step(1 / 60);

// your own clock and frame pump (a test, a recorder): the show runs on whatever these say
const frames = [];
let now = 0;
const driven = await createShow({ world, loop: { clock: () => now, raf: (cb) => frames.push(cb) } });
now += 1000 / 60;
frames.splice(0).forEach((cb) => cb(now));              // one frame
  • 'auto'(或不寫 loop)就是演出一直以來的行為。
  • 'manual' 什麼都不排程。show.loop.step(dt) 會跑一個完整的影格(執行順序),長度 dt 秒。dt 不會被夾到 0.1 秒(那是你自己決定的),0 是原地重畫一次,負數或不是數字的 dt 什麼都不跑、回傳 false。onFrame 和 show.loop.fps 看到的時間是虛擬的:已經 step 過的 dt 的總和,所以步數相同的兩次執行就是同一次執行。第一次 step 之前不會畫任何東西,時間軸也只有在播放中才會前進(show.timeline.play())。
  • { clock, raf } 維持自動迴圈,但時間由你供應。clock() 回傳毫秒,raf(cb) 要求下一格呼叫一次 cb,cb(now) 可以帶時間戳記(沒帶就讀 clock())。Worker 心跳會關掉,因為真實的計時器不該去推一個假時鐘;heartbeat: true 可以重新打開。maxDt 對這些影格照樣有效。

交出去的只有影格迴圈。Date.now、setTimeout、映射器的自動存檔、Web MIDI 和音訊引擎照樣用真實時間,後台推送也是用牆上時鐘自己節流,所以錄影時要把 loop: 'manual' 和 monitor: false 一起用。自己組裝的演出用 new Loop(fn, { manual: true }) 做同一件事(@openav/core)。

時間軸#

js
const timeline = new Timeline({
  params,
  total: 2400,                       // seconds (default 600 when used directly; createShow uses 120)
  automation: {
    growth: [[0, 0.2], [300, 1.0, 'ease'], [1200, 0.4, 'out']],   // [t, value, curve?] keyframes; no curve = linear
    mode:   [[0, 0], [600, 1], [1800, 2]],          // step params hold (no interp)
  },
  scenes: [
    { id: 'standby', t: -30, title: 'Standby', note: 'house lights · breathe' },
    { id: 'act1',    t: 0,   title: 'Act I',   note: 'single seeds only' },
    { id: 'act2',    t: 600, title: 'Act II',  note: 'full harmony' },
  ],
});
timeline.onSceneChange((i, scene) => { /* fire cues: sound, lights, OSC */ });
  • 場景時間是負數 = 開演前的待命(時鐘顯示 -0:30)
  • jumpScene(±1)(← → 鍵)是你的緊急導航,排練時就要拿它練
  • 排練時用 timeline.rate 快轉(rate = 4)
  • 播放到 total 會自己停下
  • 帶 hold: true 的場景,播放到它的結尾就停住,直到被放行(Space、→):見 Hold
  • loop: true 播到 total 就繞回開頭繼續播;loop: 'scene' 重複播放頭所在的場景,直到你往下走:見曲線、loop、cue、錄製
  • reset() 回到 start(預設 0,所以 −30 的開演前待命場景要用 scrubber 才到得了。傳 start: -30(或 start: 'first',意思是「第一個場景」),按 R 才會回到那裡)
  • 帶 score 時,場景、總長和起點都從總譜來,這時自動化曲線讀的是 score.baseTime(t),用 scale: 0.5 衍生出來的版本會把曲線一起拉伸。曲線也可以改成以段落為單位來寫,這樣換一個長度不同的 cut 也不會失準:見 Lane
成員作用
play(), pause(), toggle()播放控制。停在 hold 時,play() 和 toggle() 會放行它
seek(t)跳到第 t 秒(下限是第一個場景的負數時間,沒有的話是 0,上限是 total)
jumpScene(d)跳到往前或往後 d 個場景的開頭
next(), prev()→ 和 ←:next() 在 hold 時會放行(並接著播放),其他時候就是 jumpScene(1)
release()放行 hold:下一個場景開始,播放繼續。沒有在 hold 就回傳 false
reset()停止、清掉 hold,並倒回 start(預設 0)
advance(dt)每個影格呼叫,播放中把 t 往前推 dt × rate
state(t), valueAt(key, t)某個時間點的自動化數值(不含覆寫)
sceneIndexAt(t), currentScene(t), sceneEnd(i)查詢場景
onSceneChange(cb)每當播放或 seek 進到另一個場景,就呼叫 cb(index, scene, { cause })。cause 是 'play'、'release'、'seek'、'jump'、'reset' 或 'loop'
onCue(cb)、cues()、fireCue(cue)播放經過時觸發的場景 cue、cue 清單,以及手動觸發
loop、onLoop(cb)、loopRange()、loops讓整段、場景或一段範圍繞回去重播
record(key, source)、stopRecording()、onRecord(cb)、mergeTake(key, take)把一個數值來源錄進一條 lane
onSeek(cb)播放頭被手動移動時呼叫 cb(t, kind)('seek'、'jump'、'reset'),播放中不會呼叫
lanePos(t), laneTime(id, p), lanePlan(), lanes()automation 的秒 ↔(段落 id,段內進度 p)、段落表,以及把整份 automation 改寫成以段落為單位
exportAutomation(opts), importAutomation(doc, opts)把 automation 匯出成純 JSON(用秒或以段落為單位),以及匯入回來
anchor(epoch, opts), unanchor(), drift(), onDrift(cb)讀牆鐘:計算演出比牆鐘慢了多少、警告、追回來、準時開演
layer(key, value, t) => value:在覆寫之前改寫參數值(導演的 param() 就接在這裡)
t, playing, holding, rate, total, start, scenes, automation, score可讀也可寫的狀態

曲線、loop、cue、錄製#

曲線。 關鍵影格寫成 [t, value, curve?]。第三項是「抵達這個影格的那一段」怎麼走:'linear'(預設,不寫就跟以前一樣)、'ease'(慢、快、慢)、'in'(起頭慢)、'out'(起頭快)、'step'(先守住舊值,到影格那一刻才跳),也可以放自己的 0..1 函式。CURVES 有匯出。帶 step 的參數不論寫什麼曲線都照舊守住。

js
automation: { speed: [[0, 0.3], [16, 1.6, 'in'], [20, 3.4, 'step'], [30, 0.8, 'out']] }

Loop。 loop: true 在 total 繞回 0 繼續播;'scene' 重複播放頭所在的場景(next() 會把循環帶到下一個場景);寫場景 id 就循環那個場景;{ from, to } 循環一段範圍(秒數或場景 id)。它是個屬性,timeline.loop = !timeline.loop 就是整個 L 鍵。onLoop(cb) 會告訴你每一圈,繞進另一個場景時 onSceneChange 的 cause 是 'loop'。範圍裡的 hold 照樣會停住。

Cue。 scene.cues 是 [{ name, t }](控台的時間列本來就把它們畫成小刻度)。onCue((cue, { cause }) => …) 在播放經過時觸發,一次,而 seek、跳場景、拖時間列、reset 都不觸發:拖著看不算演出。loop 每一圈會再觸發一次。fireCue(cue) 可以手動觸發。用總譜時由導演自己觸發 cue;一般的時間軸才用 onCue。

js
show.timeline.onCue((cue) => show.params.firePulse(cue.name));   // scenes: [{ …, cues: [{ name: 'flash', t: 20 }] }]

錄製。 record(key, source) 把一條 lane 設為待錄。時間軸播放時,每個影格讀一次 source():回傳數字就寫進一段 take,回傳 null 表示沒人在碰,這一段就收尾。

js
timeline.record('hue', () => params.isOverridden('hue') ? params.overrides.hue : null);
timeline.onRecord(({ key }) => params.clearOverride(key));      // the curve takes over again

暫停、seek、reset、hold、整場結束、loop 每圈結尾,也都會收尾一段 take,錄製器本身保持待命,直到 stop() 或 stopRecording()。合併規則(mergeTake()):先把 take 抽稀(數值動了超過該參數範圍的 0.6%,或隔了 0.5 秒,才留下),再用它取代它時間範圍內的既有影格。範圍外的影格原封不動,所以 lane 會從前一個影格滑向 take 的第一點,再從 take 的最後一點滑向下一個影格;範圍外既有的曲線種類不會變。有 score 時,影格寫的是基準版本的時間,跟你宣告的那些一樣。

cue(換場時要觸發的燈光、音效等提示)清單,寫起來就是一個換場處理函式:

js
show.timeline.onSceneChange((i, scene) => {
  if (scene.id === 'storm') show.stage.activate('storm');   // switch worlds
  show.midi?.cc(20, i, 16);                                  // tell the lighting desk
});

Lane:以段落為單位寫曲線#

有總譜時,演出是一串長度會改變的段落,而用絕對秒數寫的曲線,只要其中一段變長就失準了。改成把曲線寫在段落上。某個 key 的 automation 可以是一個物件:key 是段落 id,值是關鍵影格 [p, value, curve?],p 是這一段走了多少,0 到 1。

js
const show = await createShow({
  world,
  score: { cuts, cut: 'full' },
  timeline: { automation: {
    haze: { dawn: [[0, 0.1], [1, 0.4, 'ease']],                  // dawn: 0.1 → 0.4, slow-fast-slow
            noon: [[0, 0.4], [0.6, 0.9], [1, 0.5, 'out']],
            dusk: 0.5 },                                           // a number holds the whole segment
    speed: [[0, 0.3], [30, 1.2], [120, 0.4]],                      // absolute seconds still work, in the same object
  } },
});

一個點 [p, v, curve] 就是關鍵影格 [段首 + p × 段長, v, curve],沒有別的規則:時間軸在建立時就把每條 lane 編譯好,timeline.automation 裡放的是一般的絕對秒數影格,所以 valueAt、錄製、mergeTake 和控台的行為都跟以前一樣。控台的曲線面板會把 lane 畫在整場演出上,後面標著段落 id。

  • 任何 cut。 lane 是對著總譜的基準 cut(衍生 cut 的來源)編譯的。長度不同的 cut 會用自己的長度讀同一條 lane,所以 (dawn, 0.5) 在每個 cut 裡都是 dawn 走到一半;衍生 cut(from + scale)會像絕對秒數影格一樣被拉伸。差別在結構、不只在長度的兩個 cut,也可以共用同一條 lane。
  • 接縫。 一段的最後一點和下一段的第一點之間,數值像任何兩個影格之間一樣滑過去(用抵達那一點的曲線)。要無縫,就在 p: 1 和下一段的 p: 0 寫同一個值。同一個時刻有兩個不同的值,就是跳變。
  • 這個 cut 沒有的段落。 總譜裡別的 cut 有、這個 cut 沒有的 id 會被略過,所以一條 lane 可以同時服務少一段的 cut。任何 cut 都沒有的 id(多半是打錯字)會丟錯,訊息寫明 key 和 id;p 超出 0…1 或順序倒退也會丟錯,寫明 key、段落和第幾個點。
  • 沒有總譜時,場景就是段落:一個場景持續到下一個場景開始。

存取 automation#

record() 把一段 take 寫進記憶體裡的 timeline.automation。要留下來,就匯出成純 JSON,之後再匯入這條時間軸或另一條:

js
const doc = timeline.exportAutomation({ as: 'segments' });           // lanes per segment: still right on another cut
localStorage.setItem('automation', JSON.stringify(doc));
// later:
timeline.importAutomation(localStorage.getItem('automation'));        // a string or the object
json
{ "format": "openav-automation", "version": 1, "cut": "full", "as": "segments",
  "automation": { "haze": { "dawn": [[0, 0.1], [1, 0.4, "ease"]], "noon": [[0, 0.4], [1, 0.5]] } } }

exportAutomation({ keys, as, precision }) 回傳一份拷貝。as: 'seconds'(預設)把每個 key 寫成基準 cut 秒數的影格;as: 'segments' 把每個 key 寫成 lane,p 四捨五入到 precision 位小數(預設 9,null 則保留所有位數)。兩者互為反函數:lane 編譯回來是同一條曲線。落在演出之外的影格沒有所屬的段落,只能匯出成秒數;曲線是函式的影格根本寫不進 JSON:兩種情況都會丟錯,訊息寫明是哪個 key。cut 是基準 cut 的 id。

importAutomation(doc, { keys, replace, ignoreCut }) 吃這份檔案,或一張光溜溜的 { key: 影格 | lane }。檔案裡有的 key 會被換掉(keys 可以再縮小範圍;replace: true 連檔案沒提到的 key 也一併清掉)。它是全有或全無:有任何一個 key 壞了,就什麼都不會變。秒數屬於它被寫下時的 cut,所以 cut 和這條時間軸的基準 cut 不同的檔案會被拒絕(ignoreCut: true 可以蓋過);lane 不綁 cut。

底層的換算是公開的。lanePos(t) 回答某一秒的 { id, index, p }(演出之外是 null;段界屬於從那裡開始的那一段),laneTime(id, p) 回答那一秒,lanePlan() 是段落表,lanes() 是以段落為單位寫的整份 automation。它們用的是 automation 的秒,也就是 timeline.automation 裡和 onRecord 的 from/to 用的那種。要換算播放頭本身的演出秒,用總譜:score.locate(T) 和 score.timeAt(id, p)(Score)。純函式 compileLane、decompileLane、lanePos、laneTime 也有匯出,給手上有段落表 [{ id, start, end }](score.rootSegments)、沒有時間軸的工具用。

牆鐘:anchor 與 drift#

影格迴圈把 dt 夾在 0.1 秒(架構)。頁面卡了半秒,演出只走 0.1 秒,就比牆鐘慢了 0.4 秒。短的演出沒人會發現;一整晚的裝置,卻沒有人在場看它到底漏了多少。anchor() 讓時間軸在每個播放中的影格讀牆鐘(Date.now,毫秒),比較牆鐘走了多久、演出走了多少。不呼叫就什麼都不會發生:沒有錨定的時間軸從來不讀鐘。

js
timeline.anchor();                                                       // count only (mode 'warn')
timeline.anchor(Date.parse('2026-10-24T20:00:00+08:00'), { mode: 'catch-up' });   // start at 20:00 sharp, and stay on the clock
timeline.drift().text;   // "0.42 s behind the wall clock · 7 stalls cost 1.30 s (worst gap 0.52 s) · caught up 0.88 s"
createShow({ world, timeline: { total: 120, anchor: { mode: 'catch-up', jump: 5 } } });   // the same, from the options

anchor(epoch?, opts):epoch 是演出時間 0 對應的牆鐘時刻,可以是毫秒、Date 或 ISO 字串。不給的話,第一個播放的影格就是時間 0:沒有什麼可以遲到,只計算那之後的停頓。

選項預設意義
mode'warn''warn' 只計數和通知,絕不動 t。'catch-up' 把漏掉的追回來,超前時則等牆鐘
warnAt1慢了幾秒時 onDrift 收到 'behind'(沒人聽就 console.warn);降到一半以下收到 'recovered'
tolerance0.05'catch-up':欠得比這少就不補
jump10'catch-up':欠超過這麼多秒,用一次 seek 補上(cue 不會觸發,跟 seek 從不觸發 cue 一樣),不邊播邊追
waittrue'catch-up':epoch 在未來時,演出站著不動(播放中但不前進)等到那一刻
stall0.02牆鐘時間比 dt 長超過這麼多秒的影格算一次停頓(只影響計數)
nowDate.now時鐘,單位毫秒;測試或手動迴圈用的假時鐘,傳同一個進來
onDrift無'behind'、'recovered'、'jump' 時呼叫 cb({ kind, …drift() });timeline.onDrift(cb) 可以再加

'catch-up' 做的事:把差額加進那一個影格的步長,所以 cue、hold 和 loop 都跟正常播放一樣(hold 照樣會把演出停住)。過去的 epoch 就是晚到的開演:為了 20:00 開演的節目,在 20:07 重開機的那台機器,會直接落在第七分鐘。暫停、hold 和演出結束,都是演出刻意停下來,不算漂移:停下來那一刻欠的帳一筆勾銷(forgiven),從演出停住的位置重新計。超前於牆鐘(behind 為負)時,'warn' 只回報;'catch-up' 會把演出慢下來等牆鐘(held):只會等,不會倒退,這也抵銷了卡頓之後 Loop 的心跳多補的那個 0.1 秒影格。reset() 讓計數重來;還在未來的 epoch 會留著。

drift() 沒有錨定時回傳 null,否則回傳 behind(比牆鐘慢幾秒,負數 = 超前)、lost(Loop 夾 dt 或任何停頓吃掉的)、repaid、held、forgiven、stalls、worst(兩個影格之間最長的牆鐘間隔)、frames、jumps、started、waiting、startsIn、epoch、mode,以及 text:給導演台或後台看的一行摘要。如果你是用手動或測試用的迴圈在推時間軸,記得把同一個假時鐘當成 now 傳給 anchor(),不然它量的是真實時間。

追另一條時鐘:follow#

時間軸可以不自己往前走,改去追另一條時間軸的時鐘。這是好幾個頁面演同一場裡時間軸的那一半:主控端(leader)在跑,從屬端(follower)跟著。來源可以是任何能回答「主控端現在在哪」的東西:@openav/sync 的從屬端、一段錄下來的紀錄、測試用的假主控端。不呼叫 follow() 就什麼都不會發生:從來不追的時間軸,行為跟以前一模一樣。

js
timeline.follow(follower, { jump: 0.5, lostAfter: 4 });   // follower: anything with latest() (or a function () => frame)
timeline.followStatus().text;   // "0.012 s behind the leader · worst 0.140 s · 1 jump"
timeline.unfollow();            // the timeline walks by itself again, on the rate it had before follow()

follow(source, opts)。來源回答主控端的最後一則 frame,{ T, playing, holding, rate, at }:T 是主控端送出這則 frame 那一刻的時間,at 是這則 frame 到達這裡的時刻(毫秒,和 now 同一個鐘;不給就當作此刻剛到)。還沒聽到任何人時回答 null。從屬端每一幀都算出主控端「現在」在哪:T,加上從 at 到現在的時間乘 rate(主控端暫停或停在 hold 時不外插),再加 latency。

選項預設意義
nudge0.05追趕的時候,rate 是主控端的 rate 乘 1 ± 這個數:落後 0.3 秒的從屬端大約六秒追上,沒有人看得到跳動
deadband1/60差不到一幀就不管。超過才開始推 rate,追到剩一半才放手,所以不會在邊緣上抖
jump0.5差超過這麼多秒,就一次 seek(T, 'seek'):onSeek 聽得到,cue 不會觸發
lostAfter4這麼多秒沒收到 frame,就當主控端不見了;Infinity 是永遠等
latency0frame 在路上花的秒數,數字或函式。不同機器的頁面要自己設(例如來回時間的一半)
nowsource.now,否則 performance.now時鐘,毫秒;來源蓋 at 用的那一個
onFollow無cb({ kind, …followStatus() }),kind 是 'found'、'lost'、'jump';timeline.onFollow(cb) 可以再加

從屬端從主控端複製的有:rate、暫停(從屬端停在主控端正確的 T 上)和 hold。主控端停在 hold 場景結尾時,從屬端自己走到邊界、自己停下來(路上它自己的 cue 和場景切換照常觸發);要等主控端的 T 過了邊界才放手,所以邊界前一刻的舊 frame 放不掉先到的從屬端。循環的演出會跟著繞過圈尾,走比較近的那個方向。主控端才是時鐘:追的時候,從屬端自己的 play()、pause()、seek() 和 rate 都會被下一幀蓋掉,anchor() 也讓到一邊,直到 unfollow()。

超過 lostAfter 秒沒有 frame 進來,從屬端就自己往前走,用它最後拿到的 rate,跟不追的時間軸一模一樣(暫停中的從屬端就維持暫停)。followStatus().lost 變成 true,onFollow 聽到 'lost'(沒人接就 console.warn)。主控端回來,從屬端就接回去('found')。一個人都還沒聽到的時候它會等(state: 'waiting'),過了 lostAfter 秒也照樣自己走。

followStatus() 在時間軸沒有在追時回傳 null,否則回傳 state('waiting'、'tracking'、'lost')、error(主控端的 T 減我們的,秒;正數 = 我們落後)、worst(第一次追上之後最大的 |error|)、jumps(seek 的次數)、silence(距離上一則 frame 幾秒)、lost、lostCount、lostAfter、heard、frames、nudging(-1、0 或 1)、rate、leaderRate、leaderT、leaderPlaying、leaderHolding,以及 text:給導演台或後台看的一行摘要。數字是最後一幀的。

控台#

mountConsole(el, app, { layers, signals, keys })(@openav/console)會做出導演控台,createShow() 把它掛在側邊面板。app 就是 createShow() 回傳的 show.app(timeline、params、mapper、signals、stage、midi、sound、audio、hands、pose…),缺了哪個部分,對應的區塊就不顯示。傳入 { layers: false } 或 { signals: false },可以拿掉那些面板。控台上有播放控制,以及一條標出場景區段、可以拖曳的時間列。各層的面板有 Layers(各層總覽)、L1 Input(輸入)、L2 Mapping(映射)、L3 Params(參數,滑桿附覆寫與 learn 小按鈕)、L4 sound(聲音)。另外還有即時訊號儀表和 MIDI 紀錄。

鍵盤:Space 播放/暫停(停在 hold 時:放行)· →/← 下一個/上一個場景(停在 hold 時,→ 放行)· R 重設 · T 演出模式 · F 全螢幕 · M 螢幕 MIDI 控制器(midi.controllers)· C 曲線面板 · Esc 離開鍵盤鋼琴的捕捉,或結束對應精靈。在輸入欄位裡打字、按住不放的連發,以及 ⌘/Ctrl/Alt 組合鍵,都不會觸發這些快捷鍵。螢幕鋼琴捕捉鍵盤的時候,字母鍵歸鋼琴(T 和 F 本來就是琴鍵),所以 R、T、F、M 沒作用,要取消勾選或按 Esc 才恢復。Space 和方向鍵永遠有效。

挪動快捷鍵#

把電腦鍵盤當鋼琴彈的演出,會想把字母鍵要回來。keys 把每個動作對應到一個鍵(或一串鍵),疊在預設值上面;某個動作設 false 就關掉它,keys: false 則關掉所有快捷鍵。

js
// the piano owns the letters: move the desk's R, T, F and M to keys it does not use
await createShow({
  world,
  modules: { keys: { capture: true }, midi: { controllers: true } },
  console: { keys: { reset: 'F6', perf: 'F7', fullscreen: 'F8', midi: 'F9' } },
});
動作預設作用
playSpace播放/暫停(停在 hold 時:放行)
next、prevArrowRight、ArrowLeft下一個/上一個場景(停在 hold 時,next 放行)
resetR回到開頭,並讓被停用的段落模組恢復
perfT演出模式
fullscreenF全螢幕
midiM螢幕 MIDI 控制器面板
cancelEscape結束對應精靈,或離開鍵盤鋼琴的捕捉
curvesC打開/收起曲線面板(沒有任何參數有 automation 的時候沒有作用)

鍵寫成字串。'r' 是字元(大小寫都算);'KeyR' 是實體按鍵,不管鍵盤配置在那個位置打出什麼字(注音配置會打出 ㄐ);'F6'、'Backquote'、'ArrowUp'、'Space' 是 KeyboardEvent.code 或按鍵名稱,大小寫不拘。'Shift+T'、'Ctrl+K'、'Alt+…'、'Meta+…' 可以加修飾鍵:寫法裡沒有 Ctrl、Alt、Meta 的時候,這三個鍵不能被按著(⌘R 和 Ctrl+F 仍然歸瀏覽器),單純的字母則不管 Shift。鋼琴捕捉鍵盤的時候,字母鍵(a–z 和 ;)不管你把動作放在哪裡都不作用;F6、Backquote 這類鍵則照常有效。動作名稱不認得,或鍵的寫法不對,會在掛載任何東西之前丟出錯誤。控台上的提示(播放鈕的說明文字、HOLD 橫幅、提詞機)會印出你選的鍵,show.console.keys 也存著這份設定。自己呼叫 mountConsole 的時候,若傳入 app.midiPanel,midi 鍵就會切換它。

有總譜的時候,控台還多了導演台面板、scrubber 上的 cue 刻度,以及顯示操作者 acts 的提詞機(總譜與導演)。L2 Mapping 面板有 🎛 map knobs in order,這個精靈會依序替每個參數啟動 learn(細節)。

覆寫的規則:一碰滑桿(或有映射的控制項),那個參數就脫離時間軸,直到你按 ✕ 清掉覆寫。標籤變黃 = 已覆寫。曲線面板會把同一個覆寫畫在那個參數的曲線上,並用 ↩ 清掉它。

曲線面板#

曲線面板(Curves)讓你一眼看到時間軸接下來要對每個參數做什麼,而且是整場演出。它是控台上的一個面板,一開始是收起來的:點它的標題,或按 C,就會打開。每個有 automation 的參數有一條曲線,橫軸是時間(和 scrubber 同一條軸,0 秒之前的待命段也算在內),縱軸是參數的範圍。在曲線或刻度列上按下或拖曳,就能移動播放頭,和 scrubber 一樣。沒有任何參數有 automation 的演出,就沒有這個面板。

  • 段落。 刻度列標出各個段落(總譜的段落,或單純時間軸的場景),曲線後面有它們的邊界;金色虛線是 hold 等待的位置。窄到放不下名字的段落,名字留給滑過時的提示。衍生的 cut 會用它自己的長度畫出同樣的曲線,按段落寫的 lane 也會落在它那個段落的位置上。
  • 播放頭。 一條白色的直線,曲線上有一個圈,標出演出現在的位置。標題列上的數字是這一個影格演出實際使用的值。
  • 覆寫。 被滑桿、有映射的旋鈕或手機接管的參數會標成琥珀色:一個圓點在它被帶去的值上,一條虛線橫過整場,標題列上有 ↩,按下去就把參數還給它的曲線(和 Params 面板的 ✕ 一樣)。↩ all 會把畫面上每一條曲線都還回去。沒有曲線的參數,它的覆寫不在這個畫面裡,也不會被動到。
  • 錄音。 timeline.record 正在寫進某條 lane 的 take,會在播放的時候用紅色畫出來,take 結束後曲線會重畫。
  • 成本。 收起來的時候它什麼都不做:不量測、不繪製,連 canvas 都還沒建立。打開之後,每一條曲線只畫一次,只有 automation、cut 或寬度改變時(匯入、一個 take、改了一個關鍵影格)才會再畫;每個影格只重畫播放頭和覆寫。捲出 264 px 清單之外的列既不畫也不清,所以五十個有 automation 的參數,要畫的量大約和六個一樣。

它只讀時間軸和參數,所以任何演出都不用作品多說一個字就能用。

js
const show = await createShow({
  world,
  console: { keys: { curves: 'F4' } },       // moves like any key; false switches it off, and the header still opens the panel
  // console: { curves: false }               leaves the panel out · { curves: { open: true } } starts it open
});
show.console.curves.toggle();                // .open · .info() → { keys, bands, axis, stats }

演出模式#

按 T 切到全螢幕的提詞畫面:目前場景的標題和備註,用站在舞台上也看得清楚的大字顯示,另外有操作者要做的事(場景的 acts)、下一個場景的預覽、時鐘和場景倒數、演出在等你時的 HOLD 橫幅,以及段落模組被停用時的警告。這是給演奏者看的。給觀眾看的,是你按 F 開成全螢幕的舞台。同一個頁面開兩個視窗,一個當控台,一個當舞台。

後台監看#

bash
node packages/monitor/server.js       # on the performance machine (npm run monitor)
# stage manager's phone/laptop: http://<performance-machine-ip>:7457/

每個用 createShow() 做的演出頁面,大約每秒 15 次把快照串流到 ws://<the page's host>:7457,所以監看伺服器要跑在提供演出頁面的那台電腦上。後台即時顯示時鐘、場景、世界、FPS、覆寫、所有訊號和參數。舞台 4 秒沒有傳來資料,就會跳出紅色的「stage feed lost」(舞台連線中斷)橫幅,這時候就輪到舞台監督出手。不用設定,沒有相依套件,兩端都會自己重新連線。GET /health 回應 { ok, clients }。

監看伺服器沒在跑時,演出頁面會一直重試,間隔從大約 5 秒拉長到 30 秒。瀏覽器會記下每一次被拒絕的連線,這些訊息是預期中的。

不需要後台的機器,或是中繼架在別處,都是 createShow() 的選項:

js
await createShow({ world, monitor: false });                                  // no backstage feed, no socket
await createShow({ world, monitor: { url: 'wss://stage.example.com/monitor', hz: 10 } });   // another relay

monitor: false 不會建立推送(show.monitor 是 null),頁面也不會開任何 socket。{ url, hz } 交給 MonitorFeed:一個 ws:// 或 wss:// 位址(null 會做出一個永遠不連線的推送),以及每秒送幾次快照(預設 15)。架在 TLS 後面的中繼要用 wss:// 位址,中繼本身仍然聽在你啟動它的埠(node packages/monitor/server.js 7460)。

如果演出是你手動組起來的:

js
import { MonitorFeed, snapshotOf } from '@openav/monitor';
const monitor = new MonitorFeed({ url: 'ws://192.168.1.20:7457', hz: 15 });   // both optional
monitor.connect();
// every frame:
monitor.frame(snapshotOf({ timeline, params, signals, stage, loop }, state));

作品自己的數字#

作品可以把自己的健康數字送上後台頁面:模擬跑到第幾個 tick、跟牆上時鐘差了多少、攔到幾次 NaN。這些數字以 snapshot.extra 送過去,顯示在一個 Work 面板裡;什麼都沒送時,面板是隱藏的。不送的演出,送出的快照跟以前完全一樣。

js
// 1. from the world: snapshotOf asks the active world, so a createShow() show needs no wiring
const world = { name: 'lanterns', params: [/* … */], update() { /* … */ },
  monitor() { return { 'sim/tick': sim.tick, 'sim/drift': { v: sim.drift, min: 0, max: 0.5, warn: sim.drift > 0.2 } }; } };

// 2. from a hand-assembled show: on the feed (asked only when a frame is sent) …
const off = monitor.extra(() => ({ 'sim/nan': nanCount }));          // off() takes it away again
// … or in the snapshot itself (an object, or a function answering one)
monitor.frame(snapshotOf({ timeline, params, signals, stage, loop, extra: { build: 'rehearsal-2' } }, state));

一個值可以是數字、字串(最長 80 字)、布林或 null。寫成 { v, min, max, warn } 的話,有 min 和 max 就會畫量條,warn: true 會讓那一列變紅。名稱最長 48 字,一份快照最多 64 個欄位。JSON 帶不走的東西(NaN、BigInt、函式、巢狀物件)會被丟掉或變成 null,所以一個壞數字不會讓整幀送不出去;丟出錯誤的提供者會被略過。monitor() 和函式形式的 extra 每個影格都會被問一次,monitor.extra(fn) 只在真的送出一幀時才問(大約每秒 15 次),比較耗時的量測請放在那裡。同一個名稱有兩個來源時,extra 蓋過世界,後掛的 monitor.extra 蓋過先掛的。

好幾個頁面,一場演出#

三顆輸出拼成的一面牆、舞台加大廳、排練的筆電放在演出筆電旁邊:一場演出,好幾個頁面。其中一個頁面是主控端(leader):它跑時間軸、收輸入,每一幀說出自己在哪。其餘是從屬端(follower):它們的時間軸追主控端的 T(follow),所以每個頁面顯示的都是同一場演出的同一個瞬間。每個頁面用同一份程式碼,只有 role 不同:

js
const role = location.hash === '#follow' ? 'follower' : 'leader';
const show = await createShow({
  world, score: { cuts, modules },
  sync: { role, channel: 'hall' },               // pages of one browser on one machine: a BroadcastChannel, no network
  // sync: { role, channel: 'hall', url: 'ws://leader.local:8080/relay' },   // pages on other machines: the room relay
});
sync 的 key預設意義
role必填'leader' 或 'follower'
channel必填BroadcastChannel 的名稱,也是 relay 的房間名:1–32 個字母、數字、- 或 _。同一個 channel 的頁面就是同一場演出
url無不給:用 BroadcastChannel(同一個瀏覽器設定檔、同一個來源的頁面)。true:本頁自己的 /relay(node serve.js 會架)。'ws://host:port/relay':那台機器上的 relay
input主控端 true、從屬端 false這個頁面要不要有自己的輸入。沒有的話,會產生輸入的模組都關掉:keys(鍵盤鋼琴)、midi、drums、audio、hands、pose、leap、remote。其他的由你決定
follow{}從屬端:timeline.follow() 的選項(jump、lostAfter、latency、nudge、onFollow)
extra、state無主控端:跟著時鐘一起走的資料(見下)
info、accept、onFrame、onState、onGap無從屬端:掛鉤與檢查(見下)
hz每幀主控端:每秒最多送幾幀;狀態改變(播放、暫停、hold、rate、seek)的那一幀會馬上送
id、now隨機、performance.now對等端的 id 與時鐘

傳輸。 同一台機器上,頁面之間走 BroadcastChannel:不用網路,也不用另外跑任何東西。瀏覽器只會連通同一個來源、同一個設定檔的頁面,所以主控端和從屬端要從同一個網址打開。跨機器的話,它們用 role=leader 和 role=follower 加入房間中繼的房間;主控端那台機器跑 node serve.js 就夠了(url: 'ws://<那台機器>:8080/relay')。用 https 提供的頁面要用 wss:// 位址(瀏覽器擋掉那裡的 ws://)。中繼沒有身分驗證:請用封閉的網路,以及沒人猜得到的 channel 名(安全性)。兩種傳輸送的是同一份 JSON,所以換傳輸時作品不用改。

訊息。 兩種傳輸都一樣;seq 是主控端送出的 frame 的編號。

text
{ v:1, kind:'frame', src, seq, T, playing, holding, rate, cut?, extra? }      leader → followers, every frame
{ v:1, kind:'hello', id, role:'follower', info?, reason? }                    follower → leader: "I am here, where are we?"
{ v:1, kind:'state', src, seq, to, T, playing, holding, rate, cut?, extra? }  leader → that follower

從屬端一上線就說 hello,之後每秒再說一次,直到拿到 state;seq 出現缺口、沉默一段時間之後、以及連線重連時也會再說。主控端回一則 state,所以中途加入或重新載入的頁面,第一幀就落在演出的現在。cut 是總譜的版本 id:從屬端的版本和主控端不同(長度不同,T 的意思就不同)時,會拒收它的 frame,後台會顯示 refused: cut …。

帶作品自己的資料。 凡是要跟著時鐘一起走的東西(操作員設的覆寫值、一個音符、被跳過的開場)都放在 extra。框架把它送到、每則一次、依序,從來不讀它。

js
sync: {
  role: 'leader', channel: 'hall',
  extra: () => ({ build: BUILD, events: takeNewEvents() }),   // asked once per frame sent; return undefined for "nothing"
  state: (hello) => ({ build: BUILD, tape: wholeTape }),       // asked when a follower says hello: all a late joiner needs
}
sync: {
  role: 'follower', channel: 'hall',
  onFrame: (msg) => appendEvents(msg.extra.events),            // every frame, in order, each one once
  onState: (msg) => loadTape(msg.extra.tape),                  // on joining, and again after anything went missing
  accept: (msg) => msg.extra?.build === BUILD || 'build differs',   // false or a string refuses this leader
  info: { build: BUILD },                                      // arrives with every hello
}

一則 frame 不見了(連線斷了一下),在 seq 上就是一個缺口:從屬端通知 onGap、再要一次 state,由 state 補上漏掉的東西。中繼預設會丟掉超過 256 KB 的訊息;帶著整捲磁帶的 state 需要 attachRelay(server, { maxMessageChars, maxBytes })。

發生什麼事從屬端怎麼做
它重新載入,或中途加入hello,然後收到 state:第一幀就落在主控端的 T
掉了一則 frame,或連線斷掉又回來回報 seq 的缺口,再要一次 state
主控端安靜了過了 lostAfter 秒(4)就自己用最後的 rate 往前走;followStatus().lost 和 monitor 裡的 sync/lost 變紅
主控端回來,或手動把另一個頁面升成主控端安靜了 1.5 秒的主控端可以被另一個取代;從屬端換過去並重新同步
同時有兩個主控端它守著先聽到的那個;另一個算進 ignored
主控端用的是別的版本(cut)拒收,什麼都不動
從屬端漂移不會累積:每一幀都對主控端的 T 量,不是對從屬端自己的時鐘

這一套沒做的事。 frame 帶的是主控端的 T,不是牆上時鐘的時刻,而且 latency 要你自己設:跨機器時,從屬端大約會落後一趟路程的時間,除非你告訴它。沒有選舉:要升一個從屬端,就是在舊主控端不見之後,用 role: 'leader' 載入它。頁面之間共用的是時間。會積分 dt 的世界(殘影、粒子系統)在 T 相同的兩個頁面上不會長得一樣,除非要一致的東西都寫成 T 的函式。在後台,有同步的頁面會在 monitor 的 Work 面板多出 sync/… 這幾個數字(role、error、silence、lost、jumps)。

不用 createShow 的話:@openav/sync 的 createSync({ role, channel, url, timeline }) 組出同樣的東西;每個影格在 timeline.advance(dt) 之後呼叫 sync.frame()(@openav/sync)。

OSC 輸出#

bash
node packages/osc/bridges/osc-bridge.js 7456 192.168.1.50 3456
#                       http port ↑    target host ↑   udp port ↑

預設值是 7456 127.0.0.1 3456。瀏覽器不能送 UDP,所以 OscOut 透過 HTTP 把一批批訊息送到橋接程式,再由橋接程式包成 OSC 封包送出去。

js
import { OscOut } from '@openav/osc';

const osc = new OscOut();          // http://127.0.0.1:7456
await osc.enable();                // probes /health, fails gracefully (false)
osc.send('/source/3/xyz', [x, y, z]);
osc.flush();                       // once per frame (batches, dedupes per address)

數字以 OSC float 送出,Spat、Reaper 和 TouchDesigner 要的正是這個,其他型別一律當字串送。每個位址在一格裡只留最新的一則訊息。橋接程式不見的話,OscOut 會透過 onStatus(ok, info) 回報,連續 30 次 flush 失敗之後就不再試。

createShow() 不會幫你建 OscOut,要自己加一個(並把 "@openav/osc": "../../packages/osc/index.js?v=1f11cf5e" 加進頁面的 import map):

js
const osc = new OscOut();
await osc.enable();
const show = await createShow({ world, onFrame: () => osc.flush() });
show.app.osc = osc;          // the Layers panel shows the OSC rate
show.stage.io.osc = osc;     // worlds can send from update(dt, state, io)

TouchDesigner 當接收端#

OSC 照上面的方式送進 TouchDesigner。TouchDesigner 也可以用 Web Render TOP 把 open-audiovisual 的頁面當成畫面,它把網頁畫在同一台機器的 TouchDesigner 裡(Web Render TOP)。Web Render TOP 支不支援 Web MIDI 或 WebGPU,我們還沒有驗證。控制請維持走 OSC。

頁面如果來自 openaudiovisual.com,Chrome 會先問,才讓頁面連到 127.0.0.1 上的橋接:見Chrome 跳出「區域網路」的詢問(Chrome 部落格)。跑 node serve.js、從 http://localhost:8080 打開頁面,就不會跳出詢問。

MIDI 輸出與緊急靜音#

midi.noteOn/noteOff/cc/send 會送到選定的輸出埠。midi.panic() 會在全部 16 個頻道送出 all-notes-off、all-sound-off、放開延音踏板,再逐音送 note-off。它跟其他輸出走同一個出口,一樣看得到。把它綁在一個摸黑也找得到的打擊墊上。每個演奏者遲早都會用到它,在這裡只要呼叫一次。

js
show.midi.outputs.map((o) => o.name);   // available output ports
show.midi.selectOutput('IAC Driver Bus 1');
show.midi.noteOn(60, 100, 1);           // note, velocity 0..127, channel 1..16
show.midi.noteOff(60, 1);
show.midi.cc(74, 64, 1);                // controller, value 0..127, channel
show.midi.send([0xb0, 74, 64]);         // raw bytes
show.midi.panic();

還沒選輸出埠之前,用的是第一個輸出埠(enable(preferredOut) 先找名稱完全相同的埠,找不到再找名稱包含這個字串的)。送出的每一則訊息都會經過 onSend,Layers 面板裡分頻道的 MIDI OUT 儀表就是靠它更新。

熱插拔。 演出中拔掉一條線,不能讓 DAW 一聲不響、什麼提示都沒有。目前的輸出被拔掉時,Midi 會換到次佳的可用埠:先找你用 selectOutput() 或 enable(name) 選的那個,再找 prefer 清單(new Midi({ prefer: ['IAC'] }))裡第一個符合的,最後是第一個埠。你選的那個埠重新插上,輸出就換回去。無關的裝置冒出來,永遠不會把輸出搶走。每換一次,MIDI 紀錄(Signals 面板,經由 midi.onMessage)和瀏覽器 console 各印一行,MIDI 控制器面板會閃一下,L1 Input 面板的 MIDI out → 那一列也會更新。程式裡可以用 midi.onOutput(({ text, reason }) => …) 接。

回音。 送進虛擬匯流排的訊息,不能又被當成輸入收回來。名稱符合 filterOut(預設 IAC,macOS 的那條匯流排)的輸入永遠不會被聆聽。另外,任何輸入上,在 echoWindow 毫秒內(預設 40,0 就關掉)收到一則和剛送出的完全相同的訊息,就當作回音丟掉,每送出一則只抵消一則。midi.echoDropped 會計數。

要讓外部程式跟著演出走,用 ScoreMidi 把總譜的段落切換和 cue 當成 note 與 CC 送出(Score to MIDI)。

聲音#

modules: { sound: true } 會加入 Sound(@openav/sound),用的是 Tone.js 引擎。瀏覽器要等使用者點一下才會開始播放音訊,所以控台會在 L4 · Output — sound(聲音輸出)面板放一個 🔊 enable sound(開啟聲音)按鈕,下面是選樂器的選單。開啟之後,選好的樂器就會跟著每個 midi/note/on 和 midi/note/off 彈,不管是誰送的(MIDI 鍵盤、電腦鍵盤鋼琴、模擬演奏者、手機)。Tone.js(15.0.4)要等開啟聲音時才從 jsDelivr 載入。

js
await createShow({ world, modules: { sound: true } });       // the warm pad, as before
await createShow({ world, modules: { sound: 'piano' } });    // start on the grand piano
await createShow({ world, modules: { sound: { instrument: 'synth/pluck', remember: false, picker: false } } });

樂器#

id聲音怎麼做的
piano平台鋼琴Salamander Grand Piano 取樣:30 個音檔(每個八度的 A、C、D♯、F♯),共 2.0 MB,選到才載入
epiano電鋼琴兩組 FM 加上立體聲顫音
xylophone、marimba、vibraphone、glockenspiel、music-box木琴、馬林巴、顫音琴、鐵琴、音樂盒模態合成:照每種琴鍵自己的泛音比例,疊幾個會衰減的分音,再加上琴槌敲下去的那一聲
strings弦樂合奏幾個音高略為錯開的鋸齒波、像拉弓的起音、合唱效果、抖音
harp撥弦Karplus–Strong
organ音栓風琴九根音栓合成一個加法波形,再加上旋轉喇叭的顫音
choir合唱襯底鋸齒波穿過母音的共振峰
synth/pad溫暖襯底原本的音色,仍然是預設
synth/saw-lead、synth/square-lead、synth/pluck、synth/supersaw、synth/bass、synth/acid、synth/brass、synth/bell、synth/sub、synth/chip合成器音色同一台複音合成器,音色寫成資料

鋼琴取樣是 Alexander Holm 錄製的 Salamander Grand Piano,授權是 CC-BY 3.0。選單會在鋼琴旁邊列出這行出處,公開演出用到它時,也要標上出處。音檔放在 packages/sound/samples/salamander/。萬一載不進來,鋼琴會改用電鋼琴彈,不會變成一片安靜。

選聲音#

可以在控台上選,也可以寫在程式裡:

js
await show.sound.setInstrument('organ');   // true once it plays
show.sound.instrument;                     // 'organ'
show.sound.onChange((e) => console.log(e.type, e.id, e.progress));   // instrument · loading · ready · error
show.timeline.onSceneChange((i, scene) => {
  if (scene.id === 'chorale') show.sound.setInstrument('organ');      // a cue may switch instruments
});

邊彈邊換樂器時,舊樂器上還按著的音會先放開,不會有音卡住。取樣樂器在音檔載完之前,會繼續用舊的聲音彈,選單上看得到載入進度。每換一次,也會發出一個 sound/instrument 脈衝訊號({ id, name })。選單上最後一次的選擇會記在這個頁面,下次打開時會沿用,就算程式裡宣告了別的樂器也一樣。不想要這樣,就設 remember: false。

樂器是一個離散的選擇。要連續演奏的東西仍然是參數:引擎的參數會併進演出的參數,放在 sound/ 底下。sound/cutoff(100–8000 Hz,預設 2500)、sound/space(殘響的 wet 比例,0–1,預設 0.3)和 sound/volume(−36–0 dB,預設 −8)是所有樂器共用的,所以一顆旋鈕、一隻手或樂譜,演奏濾波器的方式就跟演奏畫面一樣。樂器可以建議自己的起始值(鋼琴會把濾波器開到 8000 Hz),也可以加上自己的旋鈕,它在彈的時候控台才會顯示:風琴的 sound/drawbars 和 sound/rotor,弦樂的 sound/attack 和 sound/vibrato,合唱的 sound/vowel,電鋼琴和顫音琴的 sound/tremolo。自動化和手動覆寫永遠比建議的起始值優先。延音踏板(midi/cc/64)對每種樂器都有效,會先留住放開的音。MIDI 第 10 頻道的音(鼓機送的)留給鼓組引擎,這裡不彈。

加入自己的樂器#

一個可以選的聲音就是一個檔案:一些資料,加上一個 create(Tone, ctx),回傳 noteOn、noteOff 和 dispose。在 createShow() 之前 import 這個檔案,每個選單就會列出它,packages/* 完全不用改。

js
import { registerInstrument } from '@openav/sound';

registerInstrument({
  id: 'kalimba',
  name: { en: 'Kalimba', zh: '拇指琴' },
  category: 'mallets',
  params: [{ key: 'decay', label: 'Decay (s)', min: 0.2, max: 4, def: 1.2 }],   // → sound/decay
  create(Tone, { output }) {
    const synth = new Tone.PolySynth(Tone.FMSynth, { harmonicity: 5.1, modulationIndex: 2,
      envelope: { attack: 0.001, decay: 1.2, sustain: 0, release: 1 } }).connect(output);
    const hz = (n) => 440 * 2 ** ((n - 69) / 12);
    return {
      noteOn: (note, vel, time) => synth.triggerAttack(hz(note), time, vel),
      noteOff: (note, time) => synth.triggerRelease(hz(note), time),
      set: (key, v) => key === 'decay' && synth.set({ envelope: { decay: v } }),
      dispose: () => synth.dispose(),
    };
  },
});

id 重複會丟出錯誤,真的要換掉時,寫 registerInstrument(def, { replace: true })。可以選填的欄位有:defaults(cutoff、space、volume 的起始值)、credit(出處)、gain(dB)、transpose(半音)、fallback(載入失敗時改用的樂器 id)。回傳的物件也可以帶 ready(一個 Promise,載入時呼叫 ctx.onProgress(0..1),選單就會顯示進度)、set(key, value) 和 releaseAll(time)。敲擊類的聲音可以完全用資料寫,交給 modalInstrument({ id, name, partials, strike })。

合成器音色也是資料,會變成 synth/<id>:

js
import { registerSynthPreset } from '@openav/sound';

registerSynthPreset({
  id: 'glass', name: { en: 'Glass', zh: '玻璃' },
  voice: 'fm', harmonicity: 3.01, modulationIndex: 14,
  envelope: { attack: 0.002, decay: 1.4, sustain: 0, release: 1.2 },
  effects: [{ type: 'chorus', frequency: 1.5, depth: 0.4, wet: 0.3 }],
});

自己寫引擎#

引擎只是一個小物件,整個換掉也可以:

js
const sineEngine = () => {
  let ctx = null, out = null;
  const voices = new Map();
  return {
    params: [{ key: 'gain', label: 'Gain', min: 0, max: 1, def: 0.3 }],   // → sound/gain
    async enable() {
      ctx = new AudioContext();
      out = ctx.createGain(); out.gain.value = 0.3; out.connect(ctx.destination);
    },
    noteOn(note, vel) {
      voices.get(note)?.stop();
      const o = ctx.createOscillator(), g = ctx.createGain();
      o.frequency.value = 440 * 2 ** ((note - 69) / 12);
      g.gain.value = vel * 0.3;
      o.connect(g).connect(out); o.start();
      voices.set(note, o);
    },
    noteOff(note) { voices.get(note)?.stop(); voices.delete(note); },
    set(key, value) { if (key === 'gain' && out) out.gain.value = value; },
    dispose() { ctx?.close(); },
  };
};

await createShow({ world, modules: { sound: { engine: sineEngine() } } });

@openav/drums 的鼓組也是一個引擎:drumEngine({ samples }) 把 General MIDI 的鼓組音符對應到合成的鼓聲(或你的取樣,{ 36: 'kick.wav', … }),只有一個參數 kitVolume(−30–0 dB)。

不用 createShow#

createShow() 只是圖個方便。需要自己的版面或迴圈時,就手動組裝各個部分。它做的事大致如下:

js
import { Signals, Params, Loop } from '@openav/core';
import { Midi } from '@openav/midi';
import { Mapper } from '@openav/mapping';
import { Timeline } from '@openav/timeline';
import { Stage } from '@openav/stage';
import { mountConsole } from '@openav/console';
import { MonitorFeed, snapshotOf } from '@openav/monitor';

const signals = new Signals();
const params = new Params();
const stage = new Stage({ container: document.querySelector('#stage'), params, signals });
stage.register(myWorld);
await stage.activate(myWorld.name);

const timeline = new Timeline({ params, total: 120, automation, scenes });
const mapper = new Mapper({ signals, params, profile: myWorld.name });
if (!mapper.load()) routes.forEach((r) => mapper.addRoute(r));

const midi = new Midi({ signals });
midi.enable();

// mount the console after every world (and sound engine) is registered: it builds one row per param
const app = { timeline, params, mapper, signals, midi, stage };
const desk = mountConsole(document.querySelector('#desk'), app);
const monitor = new MonitorFeed();
monitor.connect();

const loop = app.loop = new Loop((dt) => {
  timeline.advance(dt);
  mapper.update(dt);
  const state = stage.frame(dt, timeline.state());
  desk.render(state);
  monitor.frame(snapshotOf({ timeline, params, signals, stage, loop }, state));
});
loop.start();

演出前檢查清單#

  • 用 Chrome、接上電源、關掉螢幕休眠、關掉通知(chrome://settings)
  • 這個來源(origin)已經取得 WebMIDI 權限(權限依來源、依埠分開)
  • 映射設定檔已經儲存(mapper.save()),而且也匯出成 JSON 檔
  • 監看伺服器在跑,舞台監督的裝置也在同一個網路裡
  • 已經點一下開啟聲音,panic 打擊墊也映射好了
  • 演練一次出錯:關掉分頁、重開,30 秒內回到演出狀態

總譜與導演#

09原始檔: docs/zh/score.md

一場演出長大之後,需要一個能跟著長大的結構。總譜(@openav/score)把演出寫成一段一段、只有「長度」的段落,導演則負責執行每一段的程式。兩者都是純邏輯、不碰 DOM。createShow() 會幫你把它們接上時間軸、控台和提詞機。

核心想法:只寫長度,不寫秒數#

把時間軸寫成一張絕對秒數的表,它就長不大。第二個場景拉長一點,後面每個場景、cue、曲線,還有程式裡的每一句 if (t > 466) 全都錯了,而且你只能在一次又一次排練裡一個一個找出來。在總譜裡你只寫每一段「多長」:

js
const cuts = [
  { id: 'full', title: 'A day', segments: [
    { id: 'standby', title: 'Standby', dur: 6, hold: true, acts: ['Check sound', 'Press Space when the room is ready'] },
    { id: 'dawn',    title: 'Dawn',    dur: 24, cues: { birds: 0.3 } },
    { id: 'noon',    title: 'Noon',    dur: 30, cues: { flare: { s: 8 }, peak: 0.5 }, acts: ['Open the haze slowly'] },
    { id: 'dusk',    title: 'Dusk',    dur: 24, linger: 8 },
    { id: 'night',   title: 'Night',   dur: 36 },
  ] },
  { id: 'short', from: 'full', scale: 0.5 },          // the same show at half the length
];

每個起點、終點、cue 的時間、倒數和場景,都從這些長度算出來。把 noon 改成 dur: 40,它後面的一切往後挪十秒,前面的一切原地不動。第二個版本只是幾行資料,不是要和第一份時間軸同步維護的另一份時間軸。

cut#

一個 cut 是演出的一個版本。它有 id、選填的 title,加上「段落」或「基底 cut 與倍率」其中一種。

cut 欄位意義
id在所有 cut 之間不重複,不能含 .
title顯示在版本選單
segments下表的段落,依演出順序排列
from、scale衍生 cut:名為 from 的 cut,每個長度乘上 scale(scale 要大於 0)。衍生的 cut 可以再被衍生,倍率會相乘
start演出一開始停在哪一段、reset 回到哪一段(段落 id,預設是第一段)
段落欄位意義
id在 cut 內不重複,不能含 .。它同時是負責演出這一段的模組 id
title、note導演台和提詞機顯示的字
dur長度,單位秒,要大於 0。這是段落唯一的時間
cues段落內有名字的時刻:比例 0 ≤ r < 1(佔這一段的幾分之幾),或 { s: 秒數 }(段內第幾秒)
acts這一段操作者要做的事:字串陣列,顯示在導演台,也大字顯示在提詞機
linger段落結束後,它的模組再繼續跑幾秒(餘韻、衰減的尾巴),預設 0
hold播放到這一段的段尾就停住,等操作者放行(Hold)
module負責演出它的模組名稱,不是段落自己的 id 時才需要
meta作品想掛在段落上的任何其他資料(層、色盤、事件窗口):總譜不讀的一個物件,以 segment.meta 原樣交還。總譜不認得的其他欄位也會一併放進 meta;明寫的 meta 同名項目優先

衍生 cut 會縮放 dur、linger 和 { s } 形式的 cue,所以 cue 在音樂裡的位置不變。比例形式的 cue 本來就不需要動。

meta 對總譜來說就是純資料:建立 cut 時複製一層(之後再改你的來源物件,不會有任何影響),衍生 cut 和它的來源 cut 共用同一份 meta,模組用 ctx.segment.meta 讀。請當成唯讀。segment.meta 永遠是物件,沒有就是 {};meta 不是物件會是 ScoreError。

cut 在建立總譜時就會檢查。id 重複、dur 等於或小於 0、from 指到不存在的 cut、scale 等於或小於 0、cut 衍生自己、cue 落在段落外面、acts 不是字串,每一種都會丟出 ScoreError,訊息裡寫明是哪個 cut、哪一段、為什麼,而且一次把所有問題列出來。有問題的總譜上不了台。

總譜 Score#

js
import { Score } from '@openav/score';
const score = new Score({ cuts, cut: 'full' });      // cut defaults to the first
成員回傳
table()每段一列:{ index, id, title, start, end, dur, linger, hold }
total演出全長:各段長度的總和
segmentAt(T)、indexAt(T)演出時間 T 正在播的段落。一段擁有 [start, end)。小於 0 回第一段,超過全長回最後一段
cueTime('dusk')以演出秒表示的某個時刻:'dusk' 是段落開頭,'dusk.end' 是段落結尾,'dusk.glow' 是 cue。不認得的名字回 NaN
cuesBetween(T0, T1)播放頭從 T0 走到 T1 之間經過的 cue:時間落在 T0 < time ≤ T1 的,依時間排序。T1 ≤ T0 時什麼也沒有
cues()整個 cut 的所有 cue,依時間排序,每個帶著編號 n
scenes()把段落變成給時間軸用的 scenes 陣列(含 acts、hold、cues、meta)
validate()有任何問題就丟 ScoreError,沒問題回 true(建構時已經呼叫過)
cut、title、segments、startT目前的 cut,以及 reset 要回到哪裡
cuts每個 cut 的 { id, title, total, from, scale, base },做版本選單用
scale、base、baseTime(T)這個 cut 相對於它最終衍生來源的總倍率、那個來源的 id,以及用來源 cut 表示的 T
locate(T)、timeAt(id, p)演出時間 ↔ 所在的段落和走了多少:locate(45) 是 { id: 'noon', index: 2, p: 0.5, t: 15 }(t 是段內第幾秒;演出之外 p 會小於 0 或大於 1),timeAt('noon', 0.5) 是它的反函數,用這個 cut 的秒數(這個 cut 沒有的 id 回 NaN)
rootSegments、allSegmentIds()這個 cut 衍生來源那個 cut 的段落,用那個 cut 的秒數(automation 就是對著它寫的),以及所有 cut 的 id

衍生 cut 上的自動化曲線#

自動化曲線只要對著它衍生來源的那個 cut 寫一次,衍生 cut 會把它一起拉伸。timeline.valueAt(key, t) 讀的是 score.baseTime(t) 處的曲線值,也就是 t / scale。在上面的短版裡,t = 20 讀的是曲線 40 秒處。沒有被衍生的 cut 倍率是 1,什麼都不會變。

如果兩個 cut 的差別在結構而不只是長度,就不要讓它們共用用絕對秒數寫的自動化曲線。改成以段落為單位來寫:automation: { haze: { dusk: [[0, 0.2], [1, 0.9, 'ease']] } }(p 是這一段走了多少)。時間軸會對每個基準 cut 自己的段落長度編譯它,缺了某一段的 cut 會略過那一段,衍生 cut 則照上面的方式把它拉伸(Lane)。或是改用段落模組的 param() 去驅動參數,那裡的 ctx.p 自己就會跟著縮放。

cue#

cue 是一個有名字的時刻:在 noon 段裡寫 cues: { peak: 0.5 },就有了 noon.peak,位置在這一段的一半。有三個地方看得到它:

  • 時間軸 scrubber 會畫一個刻度,點一下刻度就跳到那裡。
  • 導演在播放頭「經過」它的那一刻呼叫一次 onCue({ name, cue, T, n, segment }),並呼叫目前這個模組的 cue(name, ctx)。
  • 模組裡的 ctx.cue('peak') 會告訴你它在哪裡,單位是進度,可以直接和 ctx.p 比大小(別段的 cue 寫成 'noon.peak',ctx.cueT(name) 回傳演出秒數)。

seek 跳過去的 cue 不算經過,播放時倒回去再經過,它會再觸發一次。剛好落在演出第一瞬間的 cue,會在第一個影格觸發。

Hold#

hold: true 的意思是:播放到這一段的段尾,就停住等。 最典型的用法是等現場準備好的待機段。確切的行為如下:

  • 時間軸停在邊界前一微秒,所以演出仍然「在」被 hold 的那一段裡,並且設定 timeline.holding = true、timeline.playing = false。時鐘就凍結在那裡,你要等多久都行。
  • 被 hold 的那一段的模組每個影格仍然會收到 update(),此時 ctx.p === 1、ctx.holding === true,還有 ctx.held,也就是已經等了幾秒。任何要在演出凍結時繼續呼吸的東西,就用 ctx.held 當它的時鐘。(這裡做的選擇是:演出在段尾「停住」,不是在段內循環。循環會讓 p 回到 0、讓 cue 重複觸發,也會打破「每個模組只 enter 一次、exit 一次」。)
  • Space、→、▶ 按鈕、timeline.play() 和 timeline.next() 都能放行:下一段立刻開始,播放繼續。程式裡用 timeline.release() 也一樣。
  • seek(scrubber、goto、←)或 reset 會清掉 hold,而 seek 永遠不會「停在」hold 上,只有播放才會。最後一段不會 hold(演出在那裡結束)。
  • 後台監看會顯示 ⏸ HOLD,導演台和提詞機會顯示閃動的橫幅。

段落模組#

段落模組是負責演出某一段的程式。它的 id 就是那一段的 id(或是段落的 module 名稱):

js
const dusk = {
  id: 'dusk',
  enter(api, ctx)  { api.sky.caption = 'dusk'; },        // the segment began, or a seek landed inside it
  update(api, ctx) { /* every frame, playing or not */ },
  exit(api, ctx)   { api.sky.caption = ''; },            // it ended (after its linger) or a seek left it: give back what you took
  param(key, value, ctx) { return key === 'sun' ? 1 - ctx.p : value; },   // optional: bend a timeline param while this segment is current
  cue(name, ctx)   { /* optional: one of this segment's cues was just passed */ },
  reset(api)       { /* optional: R was pressed; forget everything */ },
};

enter、update、exit 的第一個參數是 api(你自己給的,見下面),每個鉤子都會收到 ctx:

ctx意義
p這一段走了多少,0 到 1。餘韻期間大於 1,hold 時剛好是 1
t段內第幾秒(p × dur)
dt距離上一個影格幾秒
dur這一段的長度,單位秒
T演出時間,單位秒
segment這一段:id、title、start、end、dur、cues、acts、hold、linger、index、meta
cue(name)、cueT(name)cue 的位置,分別以進度和演出秒表示(不認得的名字回 NaN)
phase'active'、'linger',或 'failed'(只出現在崩潰後的 exit() 裡)
holding、held是否正停在 hold,以及已經等了幾秒
playing時間軸有沒有在跑(不管有沒有在播放,update 每個影格都會呼叫)
api同一個 api 物件,讓沒有拿到 api 參數的 param() 和 cue() 也碰得到演出
  • 進一次、出一次。 演出走進一段,那一段的模組就 enter,離開就 exit,不管是怎麼走過去的。seek 到段落中間,enter 收到的 p 是正確的值,所以模組要能從中間接上。
  • linger。 段落結束後,它的模組仍會收到 update()(此時 p > 1、phase: 'linger'),直到餘韻結束才 exit()。這段時間裡,下一段的模組已經在跑了。
  • param()。 一段(和它的餘韻)進行中,它的模組可以改寫任何一條時間軸參數。回傳數字就取代原值,回傳其他東西就維持原值。表演者的手永遠最大:手動覆寫是在這一層之後才套用的。
  • 模組丟出錯誤,只停用它自己。 每個鉤子都在自己的 try/catch 裡執行。如果有一個丟出錯誤,導演會對那個模組呼叫一次 exit()(phase: 'failed')、印一行 console.error,之後不再呼叫它。其他模組和整場演出照常進行。導演台會用紅字警告,寫出模組名稱和錯誤訊息,按 R(reset)就能把它叫回來。影格迴圈不准因為房間裡最新、最沒測過的程式壞掉就停下來。

導演 Director#

js
import { Director } from '@openav/score';
const director = new Director({ score, modules: [dawn, noon, dusk], api: { sky } });
// every frame, after the timeline advanced:
director.update(timeline.t, dt, { holding: timeline.holding, playing: timeline.playing });
timeline.layer = (key, value, t) => director.param(key, value, t);
timeline.onSeek((t, kind) => (kind === 'reset' ? director.reset() : director.seek(t)));
選項意義
score那份 Score
modules模組陣列(用 id 對應),或是以段落 id 當 key 的物件
apienter/update/exit 的第一個參數(也是 ctx.api)。給函式的話,第一次用到時才呼叫一次
onStatus(status)目前的段落、hold 狀態或被停用的模組清單有變化時才呼叫,不是每個影格
onCue(cue)播放頭經過每個 cue 時呼叫
maxStep兩次 update() 之間 T 跳超過這麼多秒,就當作 seek,中間的 cue 不會觸發(預設 2)。如果排練時把 timeline.rate 開得很高,就把它調大
成員作用
update(T, dt, { holding, playing })每個影格一次:進出並更新模組,觸發經過的 cue
param(key, value, T)時間軸的參數層
seek(T)播放頭跳走了:不再涵蓋 T 的段落模組立刻 exit,下一次 update() 以正確的 p 進入新的段落
reset()所有正在跑的模組 exit,每個模組收到 reset(api),被停用的模組回來
status(){ cut, T, total, segment: { index, id, title, note, start, end, dur, t, p, remaining, hold, acts, cues }, next: { id, title, start, in } 或 null, holding, held, active, failed, errors, missing }
register(module)、holding、failed之後再加模組、讀取狀態

搭配 createShow 使用#

js
const show = await createShow({
  world,
  score: { cuts, cut: 'full', modules: [dawn, noon, dusk],
           api: (show) => ({ sky: show.stage.active }),       // what the modules may touch (default: the whole show)
           midi: false },                                      // see "Score to MIDI"
  timeline: { automation: { haze: [[0, 0.1], [60, 0.5]] } },   // optional: written against the base cut
});
score 選項意義
cuts、cut所有的 cut,以及預設用哪一個。網址上的 ?cut=<id> 優先於 cut,不認得的 id 會警告並忽略
modules段落模組
api一個物件,或一個吃 show 的函式,預設是 show 本身
onStatus、onCue、maxStep直接交給導演
midifalse(預設)、true 或 { channel, segment, cue, … }:Score to MIDI

有總譜的時候,時間軸的場景、總長和起點都從總譜來(你傳的 timeline.scenes 或 timeline.total 會被忽略),影格迴圈在時間軸前進之後多一步 director.update(...)。createShow 另外回傳 show.score、show.director,還有給排練和腳本用的 show.show(也就是 window.openav.show):

window.openav.show
table()用 console.table 印出段落表,並回傳這些列
goto('dusk')、goto('dusk.glow')、goto(2)跳到某一段、某個 cue,或第幾段
seek(T)跳到演出秒數
cue('dusk.glow')回傳這個 cue 的演出秒數(哪裡也不會跳)
status()導演的狀態
next()、prev()和 → 與 ← 一樣
cutscut 清單

導演台#

有總譜的時候,控台會多出這些:

  • Scrubber。 段落區塊、每個 cue 一個刻度(點一下就跳過去),以及 hold 段落那條虛線的尾端。
  • 曲線面板(C)。整場演出每個參數的 automation,後面標著段落 id 與 hold,播放頭落在每條曲線上,旋鈕把參數從曲線上帶開的地方有 ↩:曲線面板。
  • 導演台面板。 版本選單(選別的版本會用 ?cut=<id> 重新載入頁面,不會有切一半的狀態)、目前的段落(有進度條和剩餘時間)、HOLD 橫幅、下一段與倒數、操作者要做的事(acts)、這一段的 cue(經過就打勾),以及被停用的模組的紅色警告。
  • 提詞機(T)。全螢幕、大字、高對比:段落標題、你要做什麼(acts)、剩幾秒、下一段、等待時的 HOLD 橫幅,以及被停用模組的紅字。點一下畫面或再按一次 T 離開。只要場景帶有 acts,一般的時間軸也能用。

按鍵#

按鍵作用
Space播放/暫停。停在 HOLD 時:放行
→下一段。停在 HOLD 時:放行
←上一段
R回到起點、停止,被停用的模組回來
T提詞機
F全螢幕
C曲線面板
Esc結束旋鈕對應精靈,或離開鍵盤鋼琴的捕捉

在輸入欄位裡打字、按住不放的連發,以及帶著 ⌘、Ctrl 或 Alt 的按鍵,一律忽略。螢幕鋼琴捕捉鍵盤的時候(鋼琴列上的 keyboard 勾起來),字母鍵歸鋼琴:R、T、F、C 都沒作用,因為 T 和 F 本來就是琴鍵,而且你正在彈的時候,不小心按到 R 不該把整場演出倒帶。Space、方向鍵和 Esc 永遠有效,所以你可以用同一個鍵盤又彈又控場。MIDI 控制器的 M 鍵也照這條規則。

依序對應旋鈕#

L2 Mapping 面板有一個 🎛 map knobs in order。它先替第一個參數啟動 learn,你轉一顆旋鈕就綁上,接著自動換下一個參數。skip、back 和 stop(或按 Esc)可以操控它。learn 永遠是「加入」路由(Mapper.learn),所以再跑一次是替參數多綁第二顆旋鈕,原本那顆還在。順序是參數宣告的順序,跳過隱藏的參數。想自己指定順序就用 mountConsole(el, app, { learnOrder: ['hue', 'size'] })。邏輯在 @openav/mapping 的 LearnWizard:

js
import { LearnWizard } from '@openav/mapping';
const wiz = new LearnWizard({ mapper, keys: () => params.schema.map((p) => p.key), onChange: (w) => draw(w) });
wiz.start(); wiz.current; wiz.skip(); wiz.back(); wiz.stop();

Score to MIDI#

要跟著演出走的軟體(每一段啟動一個 clip 的 DAW、要跳場景的燈光台)讀不到總譜,但讀得到 MIDI。ScoreMidi(@openav/midi)把段落切換和 cue 變成 note 與 CC。它預設關閉,要用才開:

js
score: { cuts, midi: { channel: 15,
                       segment: { note: 36, cc: 20 },                       // segment i → note 36 + i, and CC 20 = i
                       cue: { note: 84, notes: { 'dusk.glow': 90 }, cc: 21 } } }  // a cue → note 84 (or its own note), CC 21 = its number
選項預設意義
channel15MIDI 頻道 1 到 16
segment{ note: 36 }note:基準音,送出的音是 note + index。cc:一個 CC,值就是段落編號。velocity。false 就不送段落標記
cue{ note: 84 }note 是所有 cue 共用的音,notes: { 'seg.name': note } 替特定的 cue 指定音,cc 的值是這個 cue 在 cut 裡的編號。false 就不送 cue 標記
length0.15標記音的 note-off 在幾秒之後送
scrubfalse手動移動播放頭時也送標記。預設只有演出「在播放」(或 hold 被放行)時才送,所以拖動 scrubber 不會讓 DAW 亂觸發 clip

reset 永遠不送。所有訊息都走 Midi 引擎自己的 noteOn/cc,所以 MIDI OUT 表會看到它們,panic() 也關得掉。程式裡這樣用:new ScoreMidi({ midi, channel, segment, cue }),再呼叫 .segment({ index, cause }) 和 .cue({ name, n })。

為什麼沒有引擎時鐘#

如果一場演出同時有兩條時間線(舊邏輯讀的「故事時間」,和觀眾經歷的「演出時間」),就需要替每個引擎說明它跟哪一條走:天氣從不停,城市則在插入的段落播放時暫停。那就是每個引擎一個時鐘。這個框架只有一條時間線,也就是演出的 T,沒有東西可以讓時鐘去選,段落模組想讓某個引擎暫停,只要自己不去推進它(ctx.t 是它自己的時鐘,ctx.held 又是另一個)。如果哪一場真實的演出需要兩條時間線,clocks 表就該放進 cut,和 segments 並排。在那之前它只是沒有人用的機器。

不用 createShow#

js
import { Score, Director } from '@openav/score';
import { Timeline } from '@openav/timeline';

const score = new Score({ cuts, cut: new URLSearchParams(location.search).get('cut') || 'full' });
const timeline = new Timeline({ params, score });                 // scenes, total and start come from the score
const director = new Director({ score, modules, api: { world } });
timeline.layer = (key, value, t) => director.param(key, value, t);
timeline.onSeek((t, kind) => (kind === 'reset' ? director.reset() : director.seek(t)));
const desk = mountConsole(deskEl, { timeline, params, mapper, signals, stage, score, director });

const loop = new Loop((dt) => {
  timeline.advance(dt);
  director.update(timeline.t, dt, { holding: timeline.holding, playing: timeline.playing });
  mapper.update(dt);
  desk.render(stage.frame(dt, timeline.state()));
});

排練檢查清單#

  • show.show.table() 印出來的,就是你心裡的演出順序
  • 用 timeline.rate = 4 從頭到尾播一次:每個 cue 都響了,沒有模組被停用
  • 每個版本都開 ?cut= 試一次,確認導演台顯示的總長正確
  • 每個 hold 都按一次 Space、再按一次 →,段落進行中也按一次 R
  • 故意讓一個模組壞掉(在 update 裡 throw),看演出照常進行
  • 提詞機(T)從你站的位置看得清楚

MIDI 控制器與嵌入#

10原始檔: docs/zh/controllers.md

open-audiovisual 把 MIDI 控制器寫成資料:每台裝置一個 JSON 檔,記下面板配置、每個控制項送出的 MIDI 訊息、LED 回饋、怎麼認出它的埠,以及每個數字出自哪一份文件。同一個檔案可以變成螢幕上能彈的控制器,接上實體裝置時跟著動,也能放進任何網頁。支援的裝置全部列在控制器頁面。

放進網頁#

html
<script type="module" src="https://openaudiovisual.com/packages/midi/element.js"></script>
<oav-controller profile="akai-lpd8" readout></oav-controller>

這樣就接好了。沒有 Web MIDI 的瀏覽器(Safari、iPad)一樣能彈、一樣送出事件,只有硬體和 MIDI 輸出這兩項會顯示無法使用。沒打開 hardware、midi-out 或學習模式,它就不會跟瀏覽器要 MIDI 權限。Safari 沒有,是因為 WebKit 沒有實作(bug 107250,至今還開著)。

屬性作用
profile哪一台:id、短名稱,或你自己的設定檔 JSON 網址
layoutauto、face(照實物的樣子)或 stack(為直拿的手機重新排)
hardwareon,或 ask 顯示一個按鈕:實體裝置會帶動螢幕上那一台
midi-out埠名稱(IAC、loopMIDI)、/正規表示式/ 或 ask:彈的東西送到這個埠
channel1–16,你的機器設在別的頻道時用
picker、readout、learn、follow裝置選單、最後一則訊息、學習按鈕、接上哪台認得的裝置就切到哪台

接收它的事件#

js
const el = document.querySelector('oav-controller');
el.addEventListener('control', (e) => {
  const { id, value, signal, message, source } = e.detail;
  // 'k1'  0..1  'midi/lpd8/k1'  { type: 'cc', ch: 1, cc: 70, value: 53 }  'ui' | 'hardware'
});
await el.ready;
el.set('k1', 0.5);           // 像手一樣動一個控制項
el.ingest([0xb0, 70, 64]);   // 從任何地方來的 MIDI:面板會跟著動

其他事件:noteon、noteoff、connect、disconnect、status、profilechange、ready、 error。全部都會冒泡,也會穿過 shadow root。每個事件有哪些欄位,都寫在 packages/midi/README.md。

不用自訂元素#

js
import { createController } from 'https://openaudiovisual.com/packages/midi/index.js';

const ctl = createController('akai-lpd8', { signals });   // signals:發進一場演出
ctl.mount(document.querySelector('#pads'));                // 可省略
ctl.on('control', (e) => console.log(e.signal, e.value));

在演出裡,別在 update() 裡直接讀 midi/lpd8/k1,改用 controllerRoutes(profile, { k1: 'hue' }) 把它接到參數(AGENTS.md 的第一條規則)。範例 09 就是這樣一次接好六台裝置。

用 iframe#

給只能放 iframe 的地方:

html
<iframe src="https://openaudiovisual.com/embed/controller/?profile=akai-lpd8&readout&frame=pads"
        width="720" height="220" style="border:0" allow="midi" title="AKAI LPD8"></iframe>

每個事件都會包成 { source: 'openav', type, frame, detail } 傳給上層網頁。反過來,它也接受 { target: 'openav', type: 'set' | 'ingest' | 'press' | 'release' | 'reset' | 'profile' | 'layout' | 'get', … }。加上 origin=https://你的網站,它就只跟你的網頁對話。

用它彈你的 DAW#

  1. macOS:音訊 MIDI 設定 → 視窗 → 顯示 MIDI 工作室 → IAC 驅動程式 → 勾選「裝置已上線」。 Windows 11:內建的 Windows MIDI Services(2026-02-17 釋出,24H2、25H2 分批推送)讓各程式共用 MIDI 埠,並附有 loopback;微軟的公告寫明,用 Web MIDI 的網頁也能用(Windows 部落格)。我們沒有拿它跟 open-audiovisual 一起實測。舊版 Windows:安裝 loopMIDI,新增一個埠,這條路仍然可用。
  2. <oav-controller profile="akai-lpd8" midi-out="IAC">(Windows 上填你建立的埠名,或 Windows 顯示的埠名)。
  3. Ableton Live:把那個輸入的 Track 和 Remote 打開。TouchDesigner:放一個 MIDI In CHOP。 Resolume:到 Preferences → MIDI。

螢幕上彈的會送出去,實體硬體的動作不會轉送(DAW 本來就聽得到它)。引擎從不聽 IAC 輸入,元素也會把跟輸出同名的輸入靜音,所以不會繞成迴圈。

使用統計#

為了知道控制器和演出被用在哪裡,套件在每次載入頁面時,會送出一筆匿名紀錄到 Google Analytics 4(openaudiovisual.com 的資源,G-1YG2JHK2WT):

事件什麼時候內容
oav_embed_load<oav-controller>、createController() 或 iframe 開始運作oav_kind(element、headless、iframe)、oav_profile、oav_host、oav_version
oav_hardware_connect接上實體控制器,而且對上了機型oav_kind、oav_profile、oav_host、oav_version
oav_show_startcreateShow() 開始oav_kind(show)、oav_host、oav_version

oav_host 只有網頁的網域(iframe 的話是放它的那個網頁),不會送路徑、查詢字串或標題。彈了什麼不會送出,也不寫 cookie,每次載入頁面的識別碼都是隨機的,沒辦法拿來追蹤同一個訪客。套件不會載入 gtag.js,網頁自己裝的 Google Analytics 不受影響。在 localhost、區域網路、file://、openaudiovisual.com 本站,或瀏覽器開了「不要追蹤」(Do Not Track、Global Privacy Control)時,什麼都不送。

關掉的方法:<oav-controller telemetry="off">、createController(p, { telemetry: false })、createShow({ telemetry: false })、iframe 加 ?telemetry=0,或在載入前設 globalThis.OPENAV_TELEMETRY = false。程式在 packages/midi/telemetry.js。

p5.js 的那一行(oav-p5)預設什麼都不送,草圖自己設 telemetry: 'on' 才會送。

簽名不是一筆紀錄。 createShow() 還會在頁面的 head 裡放一個 <meta name="generator" content="open-audiovisual 0.9.0">,WordPress 和 Hugo 留的也是這種標籤。它不發出任何請求,檢視原始碼的人、公開網頁的搜尋與普查可以從它讀出哪些頁面跑在 open-audiovisual 上,就這樣而已。createShow({ signature: false }) 就不放。原始碼:packages/core/src/signature.js。想被列出名字的作品,自己到用它做的加上來。

SysEx:模式、模板、LED 顏色#

有些事只有 SysEx 做得到:把 Launchpad 切到程式模式、選 Launch Control XL 的模板、把打擊墊點成任何 RGB 顏色。有這些功能的設定檔會列在 sysex,每則訊息都附出處,機器的頁面看得到。

瀏覽器會為 SysEx 跳權限視窗,所以這個專案絕不自己要權限:<oav-controller sysex> 會加一顆按鈕,背後是 controller.enableSysex()(要在使用者按下時呼叫)。開啟之後,機器每次連上都會設定好,setLedColor(id, { r, g, b }) 和 sendSysex(id) 也能用。套件 README。

在其他軟體使用#

每台機器的頁面都有同一份資料的 QLC+ 輸入設定檔(.qxi)和 Mixxx mapping(.midi.xml 加一支小 .js),node tools/export-controller.mjs <id> 也能從任何設定檔產生。Mixxx 的檔案只是起點,請用 Mixxx 的 Learning Wizard 改成你要的。資料庫也列出從 QLC+ 輸入設定檔匯入的控制器,版面是自動產生的,每個控制項都標成未確認。

加入一台控制器#

  1. 從 packages/midi/profiles/ 複製最接近的檔案,或一個通用版面。
  2. 照說明書的 MIDI 實作表,寫下每個控制項的類型和訊息。
  3. 每一筆資料都寫上出處。還沒確認的,標上 "verified": false,再寫一句說明。"verified": true 只給在實機上確認過的數字,而且要在 verifications 留一筆紀錄,寫明誰、哪一天、什麼韌體、作業系統和瀏覽器(沒有的話 validateProfile 不會過)。
  4. validateProfile(profile) 會列出所有問題,npm test 會檢查每一個內建設定檔。
  5. 用 <oav-controller profile="./my-device.json"> 試彈,再登記到 profiles/index.js,開一個 pull request。

沒有說明書的話:選一個通用版面,按「學習」,把控制項一個一個動過去,再把 controller.exportMapping() 的結果存下來,當作設定檔的起點。

這個格式也放得下音符和 CC 以外的東西:sysex(切模式、換模板、LED 顏色,每則訊息都附出處)、palette(LED 色票)、verifications(誰在實機上驗過什麼)。完整欄位在套件 README,同一份格式的 JSON Schema 在 profile.schema.json。

p5.js 一行接上#

11原始檔: docs/zh/p5.md

任何一份 p5.js 草圖(OpenProcessing、p5 編輯器、你自己的網頁)在最前面加一行,就能用 MIDI 控制器、螢幕上的控制器或手機來彈:

js
document.head.prepend(Object.assign(document.createElement('script'), { src: 'https://openaudiovisual.com/p5/oav-p5.js' }));

在 OpenProcessing 也可以不寫這行,改把網址貼到右側 Libraries 的 +(自訂函式庫)。在 p5.js Web Editor 或自己的網頁,也可以照其他 p5 函式庫的裝法,在 index.html 裡 p5 的 script 之後、sketch.js 之前加一行:

html
<script src="https://openaudiovisual.com/p5/oav-p5.js"></script>

這幾種寫法在 p5 1.x、2.x 的全域模式都能用,setup() 裡不用呼叫任何東西。帶著這一行、現在就能彈的草圖:範例 15。

速查表#

所有名稱一眼看完,照你要做的事分組:喊、敲、彈、讓數字好用。用法跟 p5 自己的名稱一樣:變數像 mouseX 那樣直接讀,函式像 keyPressed() 那樣你來寫、p5 來叫。每個名稱都連到它的參考條目。 速查表頁是同一張表單獨成頁,可以印成一張橫式 A4。

像讀滑鼠一樣讀它#

js
function draw() {
  background(knob1 * 255);                 // knob 1, 0..1, like mouseX
  circle(width / 2, height / 2, 50 + knob2 * 300);
}

function notePressed(note, velocity) {     // like keyPressed(): any key, or a pad
  circle(random(width), random(height), velocity * 100);
}
讀值
knob1 … knob8、knob(n)0 到 1,編號照控制器上印的順序
fader1 … fader8、fader(n)0 到 1
pad1 … pad16、pad(n)按著的時候是力度,放開回到 0
note、velocity最後按的鍵(MIDI 編號)和多用力(0 到 1)
noteIsPressed、noteIsDown(60)跟 keyIsPressed、keyIsDown() 一樣
寫這個函式什麼時候被叫
notePressed(note, velocity)、noteReleased(note)按下、放開一個鍵(打擊墊也算,除非你寫了 padPressed)
knobMoved(n, value)、faderMoved(n, value)轉旋鈕、推推桿
padPressed(n, velocity)、padReleased(n)打擊墊按下、放開

旋鈕 1 就是你手上那台的旋鈕 1:控制器設定檔記著每顆旋鈕送哪個訊息(MiniLab 3 的旋鈕 1 是 CC 74, LPD8 是 CC 70)。OAV 沒有設定檔的控制器,你先轉的那顆就是 knob1,再轉的是 knob2。草圖裡自己已經有 note、velocity、knob1 這些名字的話,原本的會留著。

音名#

收音符號碼的地方,也都能直接寫音名(0.8):

js
function draw() {
  if (noteIsDown('C4')) circle(width / 2, height / 2, 100);   // the same as noteIsDown(60)
}

function mousePressed() {
  midi.play('C#4', 0.8);                    // sends note 61, as a key would
}
寫得到
noteNumber('C4')60;給數字就原樣回來,夾在 0 到 127
noteName(61)'C#4';noteName(61, { flats: true }) 是 'Db4',noteName(61, { octave: false }) 是 'C#'
noteFreq('A4')、noteFreq(69)440(赫茲),給自己合成聲音的草圖用;noteFreq(69.5) 是高四分之一音
noteIsDown('C4')、midi.isDown('C4')、midi.play('C#4', 0.8)跟寫 60、61 一樣

音名是字母 A 到 G(大小寫都行)、可有可無的 # 或 b(♯、♭ 也行),再加八度數字:C4、c#4、Db3、F♯2,從 C-1(0)到 G9(127)。C4 是 60,跟課程模組用的科學音高記法一致;有些軟體(Ableton、Yamaha)把 60 叫 C3,從那邊抄來的音名會差一個八度。這也是 Strudel 的寫法(c4 e4 g4,升記號 #,降記號 b)。其他寫法,像 H4、C-2,會停下來並跳出一張一行的卡片,告訴你正確怎麼寫。 notePressed(note, velocity) 拿到的仍然是號碼:noteName(note) 把它寫回音名。

搭配 OP Configurator#

OP Configurator 3000(OPC,OpenProcessing 內建)幫變數取名字、定範圍。頁面上有這一行,控制器就照宣告順序接上這些變數,不用一個一個對應:

js
OPC.slider('radius', 60, 10, 300);   // knob 1
OPC.slider('speed', 1, 0, 5, 0.1);   // knob 2
OPC.toggle('trails', true);          // pad 1 flips it

旋鈕依序接 slider,推桿接在旋鈕後面,打擊墊接 toggle 和 button。轉旋鈕時 OPC 面板上的滑桿跟著動, parameterChanged() 照常會被叫。OpenProcessing 的 OPC 面板自己也能學實體控制器(面板上的 MIDI 開關),一看到它的對應在動,實體控制器就交給它,這一行繼續接螢幕上的控制器和手機(這兩個 OpenProcessing 看不到)。 OPC 變數不要取 p5 已經有的函式名稱(hue、fill),p5 1.x 會撞名。

一顆旋鈕只做一件事。 草圖自己也直接讀 knob1 的話,旋鈕 1 就歸草圖:OPC 的第一條拉桿不再跟著它(改在 OPC 面板上拉),其他旋鈕照接,並跳一次提示說明。🎹 面板的第一行就是接線表,例如「接線:旋鈕1 → knob1(草圖;radius 改用滑桿) · 旋鈕2 → speed(OPC)」。

麥克風#

同一行也接得上麥克風,草圖讀它的方式一樣:讀變數。

js
function draw() {
  background(230, 40, 10);
  fill(200 + bass * 160, 70, 100);                      // bass: the low end, 0..1
  circle(width / 2, height / 2, 50 + micLevel * 300);   // micLevel: how loud, 0..1
}

function beatDetected(level) {                          // like keyPressed(): a beat just landed
  // flash, spawn, jump to the next scene
}
讀值
micLevel0 到 1,聽起來多大聲:房間本身的底噪是 0,說話大約 0.4–0.6,大喊接近 1
bass、mid、treble0 到 1,20–250 Hz、250–2000 Hz、2000–8000 Hz 三段的能量
beat每個拍子有一格是 true,像按著滑鼠時的 mouseIsPressed
micIsOn麥克風有沒有在跑
startMic()、stopMic()用程式開、關(回傳 promise)
micSensitivity(2)靈敏度變兩倍;micSensitivity() 回傳現在的值
寫這個函式什麼時候被叫
beatDetected(level)一個拍子:音量比房間剛才的樣子突然跳起來(level 0 到 1)
kickDetected(level)、snareDetected(level)、hatDetected(level)低、中、高頻段各自打一下(20–120 Hz、150–800 Hz、6–14 kHz)

草圖開口要,它才開。 頁面載入時什麼都不會要。草圖第一次讀到 micLevel、bass、mid、treble、beat,或呼叫 startMic(),瀏覽器才會問你要不要給麥克風;答案回來之前,每個值都是 0。只寫了 beatDetected()、什麼值都沒讀的草圖,會在第一次點擊或按鍵時開。🎹 面板裡的 🎤 按鈕可以手動開關、顯示音量;瀏覽器擋下麥克風時,它會寫出來(從網址列左邊重新允許之後,再按一次)。

  • 瀏覽器要你先點一下的話。 瀏覽器在頁面被點過之前不讓聲音動起來。這個檔在 draw() 一讀到值就去要,瀏覽器擋住的話,第一次點擊或按鍵再開一次,所以不用寫 userStartAudio()。
  • 跟 p5.sound 並存。 分析用的是 @openav/audio(一個 AnalyserNode),第一次用到時從這個檔旁邊載入,有自己的 AudioContext。同一頁可以放 p5.sound(p5.AudioIn、p5.FFT),兩邊的麥克風互不相干,這裡新增的名字也沒有一個跟 p5 或 p5.sound 的名字重複。p5 1.x、2.x 的全域模式都能用。
  • 多大聲算大聲。 micLevel 是以分貝算的「聽起來的大小」,從房間量起:最低點跟著房間自己的底噪走(一兩秒內就定下來,往上每秒最多 1.5 dB,所以一直講話不會被當成新的安靜),−10 dBFS(對著筆電大喊)是 1。所以 50 + micLevel * 300 在有人說話時就看得出變大。麥克風太小聲或離太遠:micSensitivity(3)(micLevel 多 9.5 dB、三個頻段乘三,上限還是 1)。原始數值在 OAVp5.mic.rms(0 到 1)、OAVp5.mic.db、OAVp5.mic.floor(房間底噪,dBFS)。 OAVp5.mic.on('beat', fn) 跟定義 beatDetected 一樣,回傳一個可以取消的函式。
  • 你自己的名字優先。 草圖裡已經有 bass、mid(let、函式、別的函式庫)的話,原本的會留著,這個檔也不會為了它去開麥克風。
  • 關掉自動開。 ?mic=click(或 window.OAV_P5 = { mic: 'click' }):只有 🎤 和 startMic() 能開; mic=off 就什麼都開不起來(名字還在,值一直是 0)。跟所有用麥克風的頁面一樣,要 https 或 localhost。
  • 現成可開的麥克風草圖:p5/examples/mic/。

聲音:彈什麼就聽到什麼#

js
function setup() {
  createCanvas(windowWidth, windowHeight);
  startSound('piano');          // every key is heard: a keyboard, the 🎹 on screen, a phone
}
呼叫/讀值
startSound(instrument)開聲音(預設 'piano');開著的時候再叫一次就換樂器
stopSound()關聲音
soundIsOn現在彈下去有沒有聲音

樂器來自 @openav/sound:piano(Salamander 平台鋼琴,第一次要載 2 MB 的取樣,載入中先用電鋼琴頂著,載不到就一直用電鋼琴)、epiano、organ、strings、choir、harp、marimba、vibraphone、xylophone、 glockenspiel、music-box,還有 synth/… 一系列合成器。🎹 面板上的 🔊 可以開關聲音,打開後有樂器選單和載入進度。

  • 沒叫它就不載。 呼叫 startSound() 或按 🔊 之前什麼都不載;之後從這個檔旁邊載 @openav/sound,從 jsDelivr 載 Tone.js 15 (選項 tone=<網址> 可以改從別的地方載)。
  • 先點一下。 瀏覽器要網頁被點過才讓它出聲,按 MIDI 鍵盤不算。setup() 裡呼叫 startSound() 的草圖,第一次點擊或按鍵之後才聽得到;在那之前 🎹 按鈕上的 🔊 是黃的。
  • 打擊墊是鼓。 第 10 軌的音(MiniLab 3、LPD8 的打擊墊,General MIDI 的鼓軌)打的是鼓組,不會彈成鋼琴。延音踏板會讓音延長。
  • 一行程式都不用寫。 頁面網址加 ?oav_sound=piano(任何樂器名;OpenProcessing 用 ?sketch_oav_sound=piano),任何草圖點一下之後就有聲音;sound=off 則保持安靜。
  • 現成可開、邊彈邊畫的草圖:p5/examples/keys/。

鼓機#

js
function setup() {
  startDrums('breakbeat', 110);   // a 16-step grid on screen; click a cell to change the beat
}

function kickDetected(level) {    // the microphone's own callback
  // swell, flash, spawn
}

function drumHit(lane, velocity) {   // every hit: 'kick', 'snare', 'hat' or 'clap'
}
讀值
drumsAreOn鼓機有沒有在打
drumStep0 到 15,剛打到第幾格
drumBar1、2、3……,從 startDrums() 開始數第幾小節
drumBpm速度(格子上的滑桿也會改它)
drumPhase0 到 1,這一小節走到哪,連續的、照聽到的時間算:rotate(drumPhase * TWO_PI) 一小節轉一圈
beatPhase0 到 1,這一拍(四分音符)走到哪:1 - beatPhase 每一拍一開始最大,慢慢縮到下一拍
startDrums(pattern, bpm)、stopDrums()開始(打著的時候再叫一次就換節奏、換速度)、停
寫這個函式什麼時候被叫
drumHit(lane, velocity)每打一下,每一種鼓都叫(一行節奏裡的碎音鈸、疊音鈸、中鼓也是)
kickDetected(level)、snareDetected(level)、hatDetected(level)大鼓;小鼓、拍手或鼓邊;鈸(閉鈸、開鈸、踩鈸)
beatDetected(level)大鼓或小鼓,每一格最多一次(beat 也會有一格是 true)
rhythmChanged(src, how)那一行換了:startDrums()、點格子、打字、↶(0.7)

寫給麥克風的草圖,換成鼓機照樣動。 鼓機每打一下,叫的就是麥克風會叫的那幾個函式,所以麥克風草圖不用改就跟著鼓機動。草圖開了鼓機之後,只是寫了 kickDetected() 不會在第一次點擊時去開麥克風(有讀 micLevel 的草圖還是會問,那時兩邊都會叫它)。

  • 節奏。 'four on floor'、breakbeat、'half time'、latin、sparse,自己寫的格子 startDrums({ kick: 'x...x...x...x...', snare: '....x.......x...', hat: 'x.x.x.x.x.x.x.x.' })(沒寫的那軌不打),或一行節奏(下面一節)。
  • 鼓機卡。 中文瀏覽器的軌道名是中文(大鼓、小鼓、鈸、拍手),速度旁邊顯示現在第幾小節,正在響的那一欄是黃框(跟深色卡片的對比 13:1,投影也看得清楚)。
  • 格子放在哪。 畫面上方正中間:在 OpenProcessing 是 🎹 和 OPC 圖示中間,不擋到下面的 console;🎹 面板打開時移到面板下面。「–」收起格子,「×」關掉鼓機;🎹 面板裡的 🥁 不寫程式也能開關。🥁 打開的鼓機先不播放,勾格子上的播放框才會出聲(草圖自己寫的 startDrums() 會直接播放)。
  • 鼓組。 @openav/drums 的合成鼓組(沒有取樣),跟聲音一樣點一下之後才聽得到;回呼從一開始就會被叫。

畫面再重,鼓都不歪。 鼓是照音訊時鐘提前排好的:Web Worker 裡的心跳每 25 毫秒醒一次,把接下來 0.1 秒內要打的鼓,照精確的時間交給鼓組。用鼓組自己的輸出量(draw() 每一格故意忙 30 毫秒):大鼓到大鼓的間隔,差異是 0.000 毫秒; 0.5 版在畫面輪到那一格才打,差異是 15 毫秒。回呼還是在畫面的某一格叫,叫的是聲音聽得到的那一格(排定的時間加上瀏覽器回報的輸出延遲),在 draw() 之前,順序跟以前一樣。

  • 切到別的分頁:聲音照響、照數小節,drumBar 跟牆上的時間一致,cue 照樣觸發,barStarted 每小節叫一次。每一下的鼓和 stepStarted 在沒人看得到的時候先不叫,回到這個分頁也不補,所以「每打一下就加一顆粒子」的草圖不會一回來就爆出一大堆。
  • draw() 一格超過 0.1 秒:鼓機從那之後提前 0.3 秒排(🩺 會寫);代價是點格子改節奏,最多晚 0.3 秒才聽到。
  • 藍牙喇叭會晚 0.15 到 0.25 秒;瀏覽器有回報時回呼會等它,也可以用 ?oav_drumlatency=200(毫秒)自己設。
  • 保險:?oav_drums=frame(OpenProcessing 是 ?sketch_oav_drums=frame)退回 0.5 版逐幀推進的鼓機。

一行節奏#

js
function setup() {
  startDrums("bd*4, [~ sd]*2, hh*8", 110);   // a kick on every beat, a snare on 2 and 4, eight hats
}

不是節奏名稱的字串,就當成一行節奏;節奏名稱、自己寫的格子、數字,行為跟以前一模一樣。這一行字會顯示在格子上方,正在響的那個字會亮起來、再淡掉。

寫意思例
一個字一種鼓:bd 大鼓、sd 小鼓、hh 鈸、oh 開鈸、cp 拍手、rim 鼓邊、lt mt ht 中鼓、cr 碎音鈸、rd 疊音鈸、cb 牛鈴"bd sd bd sd"
~休息"bd ~ sd ~"
空白幾個字平分一小節"bd hh sd hh"
[ ]一組擠進一格"bd [sd sd]"
*n在那一格打 n 下"hh*8"
,再疊一行"bd*4, hh*8"
< >每小節輪一個"<bd*4 [bd ~ bd ~]>"
(k,n)n 格裡平均打 k 下"bd(3,8)"

完整的寫法在 @openav/pattern,跟鼓機一起從 oav-p5.js 旁邊載入。格子上沒有那一軌的鼓(碎音鈸、疊音鈸、中鼓、開鈸)會多一列;不在 16 格上的音(三連音)畫在它落在那一格裡的位置。startDrums("…") 寫錯了會跳一張卡(照頁面語言)說第幾個字、為什麼、怎麼改,鼓機先打 'four on floor';只寫 'x...x...'(格子的一軌)會提醒你放進 { kick: … }。

從 strudel.cc 複製來的也能用:startDrums('s("bd*4, [~ sd]*2").fast(2)') 打的是 [bd*4, [~ sd]*2]*2。讀得懂 s("…")、sound("…")("、'、` 都行;好幾個 $: s(…) 會疊在一起)、.fast(n)、.slow(n);setcpm(110/4) 或 setcps(…) 在 startDrums() 沒給速度時拿來當速度。.bank("…") 先略過(OAV 用自己合成的鼓組),鏈上其他的(.jux(rev)、 .every(…)、.gain(…))會跳一張卡說 OAV 還不支援、請按「在 Strudel 打開」;其餘照打。

一行節奏的寫法來自 TidalCycles/Strudel(strudel.cc),OAV 是依公開文件獨立實作。

格子和那一行互相改#

0.7 起,格子上方那一行一直都在(節奏名稱也會顯示它的格子寫成一行的樣子:'four on floor' 就是 bd*4, [~ sd]*2, hh*8),兩個方向都能改:

  • 點格子:那一行照人會寫的樣子改寫,鼓機馬上照新的那一行打。整齊的寫成 bd*4/hh*8,每組一下的寫成 [~ sd]*2,歐幾里得節奏寫成 bd(3,8)(含旋轉:bd(3,8,2) 晚兩格開始),其他的一拍一拍寫:bd [~ ~ ~ bd] bd*2 ~;各軌用 , 疊起來。如果那一行有 16 格寫不出來的東西(三連音、< >、/2、?、bd:2),第一次點只跳一張卡說哪些會被換掉,再點一次才改。
  • 直接打字:點那一行就能改;按 Enter 或停手 400 ms 就套用,格子跟著變。打錯的字標紅、跳一張卡說哪裡錯, 鼓機繼續打上一個能用的版本(不會跳回 'four on floor');Esc 放棄還沒套用的部分。打的字不會觸發草圖的 keyPressed()。
  • 卡上的 ↶(或碰過鼓機卡之後按 ⌘Z/Ctrl+Z)回到上一版;OAVp5.drums.history 是改過的每一版。
  • 複製:把 startDrums("…", 110) 放進剪貼簿,直接貼進 setup()。
  • 在 Strudel 打開:用新分頁在 strudel.cc 打開同一行,寫成 s("…"),前面加 setcpm(bpm/4)(OAV 一小節是 Strudel 的一個 cycle、四拍;strudel.cc 文件寫的是 setcpm(bpm/bpc))。OAVp5.drums.strudelUrl 是那個連結。
js
function rhythmChanged(src, how) {   // how: 'code' · 'cell' · 'type' · 'undo' · 'menu'
  line = src;                        // e.g. draw the line on the canvas, so a recording shows it
}

OAVp5.drums.src 是正在打的那一行,OAVp5.drums.edit("…") 像打字一樣換一行,OAVp5.drums.undo() 回上一版。按鍵換節奏、上一步、開到 Strudel 的草圖:p5/examples/rhythm-lab/。

把節奏畫在畫布上#

鼓機卡是網頁的一部分、不在畫布上,所以錄影錄不到它。drawRhythm() 把節奏畫在畫布上:

js
function draw() {
  background(0);
  drawRhythm(20, 20, 360, 90, 'grid');          // the sixteen steps, a playhead
  drawRhythm(20, 130, 300, 300, 'circle');      // a ring of 16 per drum, a hand turned by drumPhase
  drawRhythm(340, 130, 300, 300, 'spiral', { bars: 4, colors: { kick: '#ff7b54' } });   // the last 4 bars, wound outwards
}

drawRhythm(x, y, 寬, 高, 樣式, 選項):樣式是 'grid'、'circle' 或 'spiral';每一下在聽到的那一刻亮起來(跟 drumPhase 同一個時鐘),三連音畫在它落下的位置。選項:colors({ kick: '#f66', … },p5 認得的顏色都行)、color (全部同一色)、off(空的格子)、playhead(顏色,或 false 不畫)、bg、bars(螺旋幾小節)。在 push()/pop() 裡用 p5 自己的圖形畫,2D 和 WEBGL、p5 1.x 和 2.x 都行;WEBGL 的 (0, 0) 在畫布正中間: drawRhythm(-width / 2, -height / 2, width, height, 'circle')。不給位置就畫在底部一條('grid')或正中間一個正方形。三種一起用的草圖:p5/examples/rhythm-visual/。

時間軸:小節與 cue#

鼓機也是時鐘:一小節十六格,從 startDrums() 開始數。宣告第幾小節要發生什麼:

js
function setup() {
  startDrums('breakbeat', 110);
  cue(1, 'calm', 12);             // bar 1, and again every 12 bars
  cue(5, 'bloom', 12);
  cue(9, 'storm', 12);
}

function cueFired(name, bar) {    // or read cueName in draw()
  look = SCENES[name];
}
呼叫/讀/定義
cue(bar, name, every)第 bar 小節(1 是第一小節,4.5 是第 4 小節的一半);有給 every 就每隔那麼多小節再來一次
cueName最近一次觸發的 cue(第一次之前是 '')
cueFired(name, bar)到了某個 cue 的那一小節
barStarted(bar)、stepStarted(step, bar)每一小節的第一格;每一格

同樣的 cue() 叫兩次不會多一個,所以放在 draw() 裡也可以。同一格上先照宣告順序觸發 cue,再來 barStarted、stepStarted、那一格的鼓。只要時鐘不要聲音:startDrums({})。全部用上的草圖:p5/examples/drums/;一行節奏加 drumPhase、beatPhase:p5/examples/rhythm/;把節奏畫在畫布上:p5/examples/rhythm-visual/。

數值隨時間:lag、env、speed、spring、trail#

旋鈕和 micLevel 是跳著變的;好看的是它在兩次跳動之間怎麼動。TouchDesigner 用 CHOP 做這件事;這裡有同樣的運算子,在 draw() 裡一個一行,不用宣告;秒就是秒(30 fps 和 144 fps 畫出同一條曲線):

js
circle(width / 2, height / 2, 50 + lag(micLevel, 0.03, 0.4) * 300);   // a VU meter: opens at once, closes slowly
scale(1 + env('kick', 0.01, 0.3));                                     // the drum machine: every kick swells it, gone in 0.3 s
rotate(spring(knob1, 100, 6) * TWO_PI);                                // flick a knob: it overshoots and settles

第一行像 VU 表:一出聲立刻撐開、安靜下來慢慢收。第二行:鼓機每打一下大鼓就撐開一下,0.3 秒收回。第三行:旋鈕一甩,會衝過頭再彈回來停下。

TouchDesigneroav-p5
Lag CHOP(Lag 1/Lag 2)lag(value, up, down)跟著 value 走:往上用 up 秒、往下用 down 秒(不給 down 就等於 up;預設 0.1)
Trigger CHOP(attack、decay)env('kick', attack, decay)、trigger('boom')0..1:每個事件之後 attack 秒升到 1,decay 秒回到 0(預設 0.01、0.3)。事件:'kick' 'snare' 'hat' 'beat'(麥克風或鼓機,跟 kickDetected 聽到的是同一套)、'note'(任何琴鍵)、'bar' 'step'(鼓機)、cue 的名字、草圖自己的 trigger('boom');也可以給開關:env(mouseIsPressed, …)
Speed CHOPspeed(rate)每秒加 rate:rotate(speed(TWO_PI)) 一秒轉一圈
Spring CHOPspring(value, stiffness, damping)像掛在彈簧上的東西一樣跟著走(100、6:彈兩三下;damping 20:不彈)
Trail CHOPtrail(value, seconds)最近 seconds 秒(2)的值,一個陣列,每秒 60 個,舊的在前、最新的在最後
Slope CHOPslope(value)每秒變化多少
Count CHOPcount(beat)、count(beat, 4)、count('kick')打開過幾次;給 4 就 0 1 2 3 0 … 循環;給名字:那個事件到現在幾次
CHOP 的檢視器scope(value, 'label')頁面角落的小示波器(見下面)
drawTrail(values, x, y, w, h)同樣的曲線畫在畫布上,作品裡看得到、錄影也錄得到

秒數跟 TouchDesigner 一樣。 lag 的秒數就是 Lag CHOP 的秒數:大約是跟上一次跳動 90% 所需的時間,所以這裡的 lag(x, 0.1) 動起來就像 Lag CHOP 填 0.1(Lag CHOP 文件)。底下是一個時間常數為「秒數 ÷ 2.3(ln 10)」的單極平滑;@openav/mapping 的 smooth 仍照它原本 63% 的時間常數。attack、decay 兩邊都是長度。

不用宣告。 draw() 裡第一個 lag() 記第一個 lag 的值、第二個記第二個,每一幀都一樣;spring()、speed()、trail() … 各自分開數。把它放進 if,或放在長度會變的迴圈裡,順序就會錯開:畫面上會有一張提示說明,之後 oav-p5 改成照「寫在哪一行」對應。最穩的是給它名字,最後一個參數放字串:lag(p.size, 0.1, 0.5, 'p' + p.id)。有名字的在哪裡呼叫都是同一個,draw()、setup()、 mousePressed() 都行;沒名字的在 draw() 外面沒有東西可以對,直接回傳原值(speed 回 0、trail 回 []),也會有提示。 env()、trigger()、count('kick') 是跟著事件走的,在哪裡都能用。草圖自己有 speed 或 count 變數的話照用自己的; OAVp5.chop.speed(…) 是同一個函式換個地方拿。

看得見的值。 scope(value, 'label') 會把 value 原樣回傳,所以可以直接包住一段算式: circle(x, y, scope(lag(micLevel, 0.03, 0.4), 'lag') * 300)。每個標籤是一條線,畫在 🎹 對面角落的小示波器裡:最近 4 秒和現在的值;旁邊再放一個 scope(micLevel, 'mic'),就看得到 lag 做了什麼。它在網頁上、不在畫布上:不會錄進影片和 📷,也不會擋到點擊; hints=off 或 scope=off 就不顯示。要畫進作品裡:stroke(255); drawTrail(trail(micLevel, 3), 0, height - 100, width, 100) (或 drawTrail(micLevel, …),它自己記 2 秒):框的底是 0、頂是 1(h 後面可以給 lo、hi),用草圖的 stroke()(noStroke() 時用白色)。

數學在 @openav/chop,第一次呼叫時從這支檔案旁邊載入;載好之前(幾幀)每個函式都直接回傳原值。參數意義參考 TouchDesigner 官方文件(Derivative),程式由 OAV 自行實作。原值和 lag 後並排、配 scope 的範例:p5/examples/lag/;用 env、spring、speed、count、slope 做一個大鼓撐開的圓盤(只靠 startDrums(),不用麥克風):p5/examples/chop/。

錄影:畫面和聲音一起錄#

js
function keyPressed() {
  if (key === 'r') recordingIsOn ? stopRecording() : startRecording();   // startRecording(10): ten seconds, then it stops
}

function recordingSaved(info) {   // info.name, info.seconds, info.bytes, info.format ('mp4' or 'webm')
}
呼叫/讀/定義
startRecording()、startRecording(秒數)、startRecording({ seconds, fps, mic, name, canvas, bitrate })錄下畫布和作品的聲音;給秒數就錄那麼久自動停;一段最長 5 分鐘。canvas 指定要錄哪個畫布(p5 的畫布或 createGraphics(),預設是頁面上最大的 p5 畫布),bitrate 是每秒位元數(預設依畫布大小和幀率算:4 到 16 Mb/s,幀率高過 30 時最高 24 Mb/s)
stopRecording()停止,檔案自動下載
recordingIsOn現在有沒有在錄
recordingSaved(info)存好了:name、seconds、bytes、format、width、height、audio、sources、warnings、blob、url

🎹 面板上的 ⏺ 不寫程式也能開始、停止;錄影中 🎹 按鈕上有紅點和時間(點紅點就停)。📷 把畫布存成一張 PNG。

  • 影片裡有什麼。 p5 的畫布,用它實際的像素(Retina 螢幕是兩倍),每秒 30 格;加上這個檔發出的所有聲音:startSound()、鼓機和打擊墊、開著的麥克風、p5.sound 1.x,混成一軌,喇叭照常出聲。🎹、鼓機格子、提示卡片、OPC 面板都不在畫布上,所以不會進影片。
  • 檔案。 瀏覽器能錄 MP4(H.264+AAC)就錄 MP4:Chrome 126 以後、Edge、Safari,IG、YouTube、剪輯軟體都直接吃。其他瀏覽器(Firefox、舊版 Chrome)錄成 WebM,卡片會說 IG 不收。檔名像 oav-20261015-183005.mp4;電腦上直接存到「下載」,手機上卡片有 分享 按鈕,可以存進相簿或直接傳到 IG。
  • 每錄完一段都會檢查。 卡片寫出錄到什麼(格式、長度、大小、有沒有聲音);有問題就說發生什麼、為什麼:開著聲音卻什麼都沒錄進去(還沒點過畫面、沒有彈)、錄成 WebM、檔案幾乎是空的、畫布有畫面但影片全黑(Safari 錄 WebGL 畫布,WebKit 229611)、畫布上有別的網站的圖(沒有 CORS)、這個瀏覽器不能錄。
  • 麥克風開著就會一起錄:戴耳機,不然喇叭的聲音會被錄兩次。record=nomic 不收麥克風。
  • p5.sound。 給 p5 1.x 的 p5.sound 1.x 會一起錄。給 p5 2.x 的 p5.sound 把每個聲音直接接到喇叭,沒有總輸出可以接進錄影:錄不到,卡片會說。草圖改用 p5 1.11,或改用 startSound()、startDrums()。草圖自己用 Tone.js、Web Audio 做的聲音也錄不到。
  • 靜態圖。 📷(或 OAVp5.record.shot())只存畫布,檔名 oav-<日期>-<時間>.png,不含 🎹 和卡片;在程式裡用 p5 自己的 saveCanvas('名字', 'png') 也一樣。
  • 選項。 record=nomic(不收麥克風)、record=off(沒有 ⏺ 和 📷,startRecording() 什麼都不做)、recfps=60、 reclimit=600(秒)、title=作品名(放進檔名);只改這一段:startRecording({ seconds, fps, mic: false, name, canvas, bitrate })。
  • 全部用上的草圖:p5/examples/record/。

三種輸入#

輸入怎麼用
實體控制器Chrome、Edge、Firefox 的 Web MIDI,瀏覽器問一次就記住
螢幕上的控制器按 🎹 打開 <oav-controller>,接上哪台控制器就換成哪台
手機面板上的 📱 顯示 QR code,手機遙控頁的 MIDI 分頁就能彈這份草圖

三種輸入進來都是同一串 MIDI,草圖分不出是誰彈的(想知道的話看 midi.last.source)。Safari 和 iPad 沒有 Web MIDI,螢幕上的控制器和手機照樣能用。草圖自己寫了 Web MIDI(navigator.requestMIDIAccess、WebMidi.js)的話,螢幕和手機會變成多出來的一個輸入,名字叫 OAV Virtual MIDI。

別的程式是第四種輸入(0.7)。程式送進 OAV Virtual MIDI 輸出的東西——Strudel 的 .midi('OAV Virtual MIDI')——會在它標的那個時刻到草圖(midi.last.source 是 virtual-out);外部 MIDI 時鐘推動 drumPhase、drumBar 和鼓機; link=<房間> 把另一個分頁、另一台電腦的程式接進這份草圖。全部寫在和 Strudel 一起用。

出狀況的時候#

彈的時候沒人會去看 OpenProcessing 畫布下面的 console,所以出狀況會直接寫在畫面上:🎹 旁邊一張小卡片,不擋畫布中間,用瀏覽器的語言,同一則只跳一次,按 × 關掉。每張都寫三件事:發生什麼、為什麼、下一步按哪裡,console 也同步寫一樣的話。

  • 麥克風:被擋下(網址列左邊的鎖頭 → 允許 → 回來點一下畫面)、被電腦的系統設定擋住、在沒有 allow="microphone" 的嵌入框裡、找不到麥克風、被別的程式(Zoom、OBS)占用、網址不是 https、瀏覽器還在等你按允許。
  • MIDI:瀏覽器沒有 Web MIDI(Safari、iPad:改用 🎹 或手機)、MIDI 權限被擋。只對有用 MIDI 的草圖說;什麼功能都沒用到的草圖不會跳任何卡片。
  • 你自己的程式:notePressed()、kickDetected()、drumHit() 這些回呼裡出錯,卡片寫出錯誤訊息、哪個檔第幾行,草圖照樣繼續跑。草圖自己宣告了 note、knob1(let、var、function),原本的會留著,卡片告訴你改讀什麼(midi.last.note、knob(1))。
  • 聲音和鼓機:要先點一下畫面、鋼琴還在載入(先用電鋼琴頂著)、某個樂器載不到(改用備用的)、Tone.js 連不上、鼓機在打但還沒點過畫面所以沒聲音。
  • 錄影:開始錄了(錄到哪些聲音、怎麼停)、錄好了(格式、長度、大小、有沒有聲音)、錄到的影片沒有聲音、錄成 WebM(IG 不收)、整段黑、檔案幾乎是空的、畫布上有別的網站的圖、這個瀏覽器不能錄。

?oav_hints=off(或 window.OAV_P5 = { hints: 'off' })只寫在 console;OAVp5.hints 列出說過的提示。

🩺 體檢。 🎹 面板上的 🩺(或 OAVp5.check())把版本、頁面、瀏覽器、麥克風、MIDI、聲音、鼓機、錄影(這裡能錄 MP4 還是 WebM、上一段)、接線、草圖自己的名字、目前為止的提示整理成一張卡,截圖貼到 Discord 就能遠端看;有「複製文字」按鈕,也連到完整的裝置檢查。

在 Hydra 裡用#

Hydra 有自己的載入函式;同一個檔在那裡也能用,Hydra 的箭頭函式每一格都會重讀變數:

js
await loadScript('https://openaudiovisual.com/p5/oav-p5.js')
osc(10, 0.1, () => knob1 * 2).out()                     // knob 1 sets the colour offset
js
osc(10, 0.1, () => 1 + micLevel * 3).out()              // the microphone, asked for when this line first runs

note、velocity、knob1 … knob8、fader1 …、pad1 …、drumStep,還有 🎹 螢幕上的控制器,都一樣在。 Hydra 不是 p5,沒有可以定義的 notePressed() 回呼,改用訂閱: midi.on('notePressed', (note, velocity) => { … }) 或 OAVp5.drums.on('hit', (lane, velocity) => { … })(都回傳一個取消訂閱的函式)。測試用的是 hydra-synth 1.4.0,也就是編輯器跑的那個函式庫(p5/test/hydra-smoke.cjs)。

細節#

和 Strudel 一起用#

12原始檔: docs/zh/strudel.md

Strudel 是在瀏覽器裡即興寫音樂的 live coding 環境,TidalCycles 的 JavaScript 版。OAV 是另一個獨立的程式。兩個並排跑,像舞台上兩台機器那樣合作:Strudel 負責演奏,OAV 補上 Strudel 沒有的東西——螢幕上和手機上的旋鈕、會分析的麥克風、瀏覽器沒有 Web MIDI 時的 MIDI——並且把 Strudel 演奏的東西,在同一頁、另一個分頁或另一台電腦的 p5.js 草圖裡畫出來。兩邊只透過 MIDI(OAV 的虛擬埠「OAV Virtual MIDI」)和網頁上的變數(knob1、micLevel、drumPhase)碰面。OAV 不載入、也不呼叫 Strudel 的任何程式。

這一頁每個寫法,都在 strudel.cc 上用一般使用者的方式跑過(它的編輯器、Ctrl+Enter、文件寫的函式): p5/test/strudel-smoke.cjs 會再跑一次。

在 Strudel 載入 OAV#

Strudel → settings → prebake,最後加一行,按 save:

js
await import('https://openaudiovisual.com/p5/oav-p5.js')
  • 網址用單引號。 Strudel 把雙引號(和反引號)裡的字當成 mini-notation:網址寫雙引號會出現 [mini] parse error。
  • 為什麼放 prebake。 它在你的程式之前跑,重新整理後也會跑(編輯器出現後約 2.5 秒),所以 OAV 一定比任何開 MIDI 的東西早到。要是 Strudel 的 midin() 比 OAV 先跑,midin('OAV Virtual MIDI') 會收不到東西、也不報錯:重新整理就好。這種時候 🩺 會寫「沒有程式向 OAV Virtual MIDI 要過 MIDI」。
  • 這一行也可以放在程式第一行。選項寫在它前一行:window.OAV_P5 = { link: 'my-room' }。
  • Strudel 的 share 會把 prebake 一起放進連結(勾著 share with patterns 時):打開連結的人也會載入 OAV。

在 strudel.cc 上 OAV 會換一套禮貌。載入時不要 MIDI 權限(hardware=click:交給 Strudel 的 midin() 去問)。🎹 面板變成角落的一個小框,高度是視窗的三分之一,程式碼不會被蓋住。一張卡片說明哪些名字 Strudel 已經有了——note、 velocity、beat 是 Strudel 的函式,OAV 不動它們——以及改讀什麼:OAVp5.last.note、OAVp5.last.value、 OAVp5.mic.on('beat', fn)。knob1、micLevel、drumPhase 這些名字在那裡都沒人用,照常可讀。

配方一:旋鈕、手機、麥克風變成 Strudel 的參數#

Strudel 的 signal() 把一個函式變成參數;OAV 的名字就是函式可以回傳的數值。

js
s("bd*4").gain(signal(() => knob1))
s("hh*8").lpf(signal(() => 300 + micLevel * 8000))
  • knob1 跟著螢幕上 🎹 的旋鈕 1、MIDI 控制器的旋鈕 1,或手機(🎹 → 📱 掃碼)。knob(2)、fader1、pad1 也都在。實測:旋鈕 1 轉到 0,大鼓沒有聲音;轉到 127,聽得到(RMS 0.58)。
  • Strudel 是在排程時讀值,比聲音早 0.2–0.3 秒:轉旋鈕大約晚這麼多才聽到。
  • micLevel、bass、mid、treble 是 OAV 對麥克風的分析(Strudel 沒有);讀到其中一個就會要麥克風。請戴耳機:麥克風會聽到喇叭,gain(signal(() => micLevel)) 會越來越大聲。
  • Strudel 自己的 MIDI 輸入也能接 OAV 的埠,連 Safari 都可以(Safari 沒有 Web MIDI,OAV 的埠是虛擬的):
js
const cc = await midin('OAV Virtual MIDI')
s("bd*4").gain(cc(74))

螢幕上 MiniLab 3 的旋鈕 1 是 CC 74。midikeys('OAV Virtual MIDI') 讓 🎹 的琴鍵和手機變成 Strudel 的鍵盤。

配方二:Strudel 演奏,p5 草圖畫畫面#

同一頁。 送到 OAV 的埠:

js
note("c3 [e3 g3] <a3 b3> c4").midi('OAV Virtual MIDI')

Strudel 每個音都提早 0.21–0.32 秒交出來,附上它應該響的時刻;OAV 等到那一刻才呼叫 notePressed(note, velocity)(在 Strudel 裡沒有草圖:用 OAVp5.on('notePressed', fn)),CC 推動 knob1,打擊墊照樣打。實測(strudel.cc):每個音和 Strudel 的時間戳差 5 ms 以內(10 個音,最晚 4.5 ms;p5/test/strudel-smoke.cjs),drumPhase 跟 Strudel 時鐘的差平均 0.1 ms。從這個埠進來的東西,絕不會再從 OAV 的輸入送回去,所以 midikeys('OAV Virtual MIDI') 接到 .midi('OAV Virtual MIDI') 只會有一次回音,不會無限循環。

Strudel 的時鐘。 MIDI 一拍 24 個 clock,一個 cycle 是四拍一小節時就送 96 個:

js
setcps(128 / 60 / 4)
$: s("bd*4, [~ sd]*2, hh*8")
$: midicmd("clock*96, <start stop>/8").midi('OAV Virtual MIDI')

drumPhase、beatPhase、drumBar、drumStep、drumBpm 都跟著它走。用 startDrums() 開的鼓機會照 Strudel 的速度、在 Strudel 的小節起點上打,跟著它開始和停止(鼓機卡上寫「跟著外部時鐘 · 128 BPM」)。128 bpm 實測:drumPhase 和 Strudel 的小節差 1.2 ms 以內(中位數 0.04 ms),每一下大鼓和 Strudel 的拍點差 6 ms 以內(跑三次);Strudel 的 start 會用同一個時間戳送三次,只算一次。沒有時鐘時什麼都不變;clock=off 會忽略時鐘。

另一個分頁,或另一台電腦。 兩邊設同一個房間。Strudel 的 prebake:

js
window.OAV_P5 = { link: 'my-room' }
await import('https://openaudiovisual.com/p5/oav-p5.js')

p5 草圖(OpenProcessing:寫在那一行之前;或在作品網址加 ?sketch_oav_link=my-room):

js
window.OAV_P5 = { link: 'my-room' };
document.head.prepend(Object.assign(document.createElement('script'), { src: 'https://openaudiovisual.com/p5/oav-p5.js' }));

Strudel 送進 OAV 埠的一切——音符、CC、時鐘——都會經由手機用的同一個 relay,送到房間裡其他每一個 OAV 頁面。🎹 會多一個 🔗:有另一頁在時是綠色;面板上寫著房間、頁數和單程時間。收的那一頁在 Strudel 演奏的那一刻才演奏,不是收到就演:它用看過最快的那幾趟、加上兩頁各自量到的來回時間,把兩邊的時鐘對齊(做法寫在 packages/relay/link.js),Strudel 提早四分之一秒的量剛好吃掉路上的時間。一台 Mac 兩個分頁、經由 wss://remote.cheyuwu.com(單程約 61 ms)實測:音符和 Strudel 的時間戳差 −3 到 +7 ms(跑兩次)。兩台電腦時再加上「來回兩段不一樣長」的誤差(通常幾 ms)。relay 請用預設的(wss://):Chrome 不讓 strudel.cc 連到你自己電腦或區網裡的 relay(ws://127.0.0.1… 會被它的區網存取檢查擋下)。網路抖得比 Strudel 的提早量還兇時,用 linkdelay=(毫秒)多留一點緩衝。收到的東西不會再轉出去;有程式把房間傳來的音又彈回去,會被當成回音擋下。這個房間同時也是手機的房間:一張 QR 碼能彈房間裡每一頁。

畫畫面那一邊的現成例子:p5/examples/with-strudel/(網址加 ?room=…)。

配方三:Strudel、Hydra、OAV 同一頁#

OAV 放在 prebake:

js
await initHydra()
osc(10, 0.1, () => knob1 * 2).rotate(() => drumPhase * 6.28).color(1, () => micLevel, 0.6).out()
setcps(120 / 60 / 4)
$: s("bd*4, [~ sd]*2, hh*8").gain(signal(() => 0.3 + knob1))
$: midicmd("clock*96").midi('OAV Virtual MIDI')

Hydra 照 Strudel 的時鐘一小節轉一圈(經由 drumPhase),旋鈕 1 同時推 Hydra 和 Strudel,麥克風給畫面上色。

和 Strudel 有關的選項#

寫在那一行之前(window.OAV_P5 = { … }),或在 p5 頁面網址加 ?oav_key=value。

選項值預設
link房間名(英數、-、_):同房間的頁面互相聽得到對方的程式無
linkdelay連線頁面的音符多留幾毫秒緩衝0
clockfollow(外部 MIDI 時鐘推動 drumPhase 和鼓機)· offfollow
strudelauto(strudel.cc,或頁面上已經有 Strudel 的函式)· on · offauto
compacton(面板是角落的小框)· offStrudel 裡 on
hardwareauto · click · offStrudel 裡 click

致謝與授權#

Strudel 的著作權屬於它的貢獻者(由 Felix Roos 和 Alex McLean 開始),以 GNU Affero General Public License v3 授權的自由軟體:strudel.cc,原始碼在 codeberg.org/uzu/strudel。 Strudel 帶到瀏覽器裡的那套寫節奏的方式,來自 Alex McLean 的 TidalCycles。用 Strudel 做出來的音樂是你自己的(Strudel 的 FAQ)。

OAV 以 MIT 授權,是另一個獨立的程式。它不含 Strudel 的任何程式碼、執行時不載入 @strudel/*、也不呼叫 Strudel 的任何函式:它只看網頁的網址、看頁面上已經有哪些名字,來決定自己的禮貌。兩邊像舞台上的兩台機器一樣,透過 MIDI 碰面。OAV 自己的節奏字串(startDrums("bd*4, hh*8"),@openav/pattern)是依公開文件獨立實作的 TidalCycles/Strudel 式寫法。OAV 的問題請不要到 Strudel 的社群問:請到 GitHub。

手機、中繼與控制面板#

13原始檔: docs/zh/remote.md

手機和 iPad 可以當控制器,能用的有動作感測器、一台鋼琴,還有一個照世界的參數自動長出來、類似 TouchOSC 的控制面板。負責的是三個套件,每個都能單獨使用:

套件角色
@openav/relay零相依、分房間(room)的 WebSocket 中繼,以及它的瀏覽器端用戶端
@openav/surface控制面板元件、版面 JSON、autoSurface(params)
@openav/remote手機 app(分頁:感測 · 琴鍵 · 控制台 · MIDI),以及演出端的轉接器

對映射器來說,手機只是多一種輸入:它發出訊號,路由再把訊號接到參數。

架設#

  1. 在演出電腦上執行 node serve.js。它提供頁面,同時在 /relay 架起中繼,不需要其他東西。
  2. 打開一個宣告了 modules: { remote: true } 的演出,例如 http://localhost:8080/examples/08-remote-surface/。
  3. 舞台左上角的加入卡片會顯示手機該打開的網址,裡面已經填好演出電腦的區域網路位址(頁面會到 /__info 向 serve.js 詢問)和房間:http://<lan-ip>:8080/packages/remote/?room=default。
  4. 用同一個網路裡的手機打開那個網址。卡片會顯示目前連上幾支手機。

卡片上同時畫出這個網址的 QR code,用手機相機對著掃就行。

在 openaudiovisual.com(以及任何靜態主機)#

那裡沒有 serve.js,也就沒有自己的中繼。宣告了 modules: { remote: true } 的演出會改接公開中繼(wss://remote.cheyuwu.com/relay),卡片上會寫 public relay。在電腦上打開範例 08,用手機掃 QR code,手機上的推桿就能推動演出。

  • 房間是隨機的(show- 加 10 個字元),第一次進來產生,記在這個瀏覽器的 localStorage,重新整理還是同一間,兩位訪客也不會撞進同一間。演出裡宣告的房間名(room: 'main')在這裡會被忽略,原因就在這;網址上的 ?room=class-7 永遠優先,教室裡要大家進同一場演出就用這個。
  • ?relay=wss://your.host/relay 用你自己的中繼(手機連結會一併帶上);?relay=off 把那一頁的遙控關掉。
  • 選哪個中繼由 @openav/remote/relay-pick 的 pickRelay() 決定:本機或區域網路(localhost、192.168.x.x、*.local…)照舊用同源的 /relay,行為完全不變;其他主機一律用公開中繼。
  • 公開中繼沒有帳號,也沒有身分驗證。房間名稱是唯一的祕密,所以 QR code 要當成祕密看待:掃到的人就能操控那場演出。不要把它放進會分享出去的簡報。

手機 app#

/packages/remote/ 是單一頁面,上方是狀態列(連線、延遲、房間、這支手機的 id),下面是幾個分頁:

  • 感測:一顆跟著傾斜滾動的球、加速度與旋轉的讀數、多點觸控板、敲擊(手機被猛地一震),以及前鏡頭讀到的亮度。iOS 要先點一下「開始」,才會給動作資料。
  • 琴鍵:一台鋼琴。橫拿時是一排,大約三個八度,直拿時是上下兩排,上排接著下排往高音延伸。手指按在琴鍵的哪個高度,決定力度。另外有按住就延音的按鈕和換八度按鈕。
  • 控制台:一個控制面板。它的版面依序從這些地方找:?surface=<layout.json url> 查詢字串、?meta=<json url> 查詢字串(裡面的 params 會交給 autoSurface)、演出透過中繼發布的版面。都沒有的話,就用一個小小的通用面板,頁面永遠不會空白。
  • MIDI:一台虛擬 MIDI 控制器,和演出畫面上顯示的是同一台(MIDI 控制器與嵌入)。
查詢字串意思
room=<name>要加入的房間(1 到 32 個字元,只能用 A–Z a–z 0–9 _ -,其他值一律當成 default)
tab=sense|keys|control|midi一開始打開哪個分頁
surface=<url>控制台分頁用的版面 JSON
meta=<url>一個含有 params 陣列的 JSON 檔,控制台分頁會變成 autoSurface(params)
relay=ws://…改連別處的中繼,不用頁面所在伺服器上的那一個

每支手機會在 localStorage 存一個短短的隨機 id,也就是 phone/<id>/… 裡的 <id>。

iOS 與 HTTPS#

iOS Safari 只把動作感測器和鏡頭開放給透過 https:// 提供的頁面。觸控、琴鍵和控制面板,在區域網路上用一般的 http:// 就能用。要在 iPhone 上用傾斜和敲擊,請透過 HTTPS 通道(tunnel,把本機的服務開成一個 https 網址)連到 serve.js,在手機上打開通道的網址。中繼會跟著頁面的來源(origin)走,HTTPS 頁面就用 wss://。鏡頭的部分,Android Chrome 也一樣。

演出端#

在 createShow() 裡設 modules: { remote: true }(或用 @openav/remote/host 的 mountRemoteHost()),演出端會做五件事,世界完全不必知道手機在不在:

  1. 以房間的 runner(演出端)身分加入中繼。
  2. 把每一個手機訊號放進 signals,並把 phone/<id>/… 複製一份到 phone/any/…。phone/any 的值永遠來自最後送出數值的那支手機。
  3. 建立控制面板:世界有附版面就用 world.surface,沒有就用 autoSurface(world.params),再發布給每一支手機,之後才加入的也收得到。
  4. 把 surface/… → param 路由加進映射器(已經有的配對會跳過)。
  5. 每秒大約 10 次把參數值送回手機,讓推桿跟著時間軸和其他控制器一起動。
modules.remote 選項預設意思
room頁面網址裡的 ?room=,沒有就是 'default'房間名稱
auto{}傳給 autoSurface 的選項(pairs、meters、style、perPage、smooth、title)
surfaceworld.surface指定的版面(比世界自帶的版面優先)
feedbackHz10每秒回送幾次參數值
relay由 pickRelay() 決定'wss://host/relay' 用你自己的中繼,false 不要遙控。沒設的話:本機或區域網路用同源 /relay,靜態主機用公開中繼。網址上的 ?relay= 會蓋過它
url同上relay 的別名(也是 mountRemoteHost() 吃的選項:它會自己補上 role、room、id)

感測器的路由在寫作品時就寫好,用 phone/any/… 這個別名,因為沒人能事先知道別人手機的裝置 id(範例 08):

js
await createShow({
  world: bloomWorld,
  routes: [
    { source: 'phone/any/tilt/x', target: 'drift', inMin: -1, inMax: 1, outMin: 0, outMax: 2, smooth: 0.12 },
    { source: 'phone/any/knock', target: 'burst' },
  ],
  modules: { keys: { base: 48 }, remote: { auto: { pairs: [['cx', 'cy']], meters: ['density'] } } },
});

show.remote 就是這個演出端主機:{ relay, layout, routes, bindings, room, publish(), frame(dt, state), connect(), dispose() }。

控制面板元件#

控制面板把手指的動作變成有名字、正規化的訊號。每個元件都發布在 surface/<page>/<id> 底下。元件的範圍不是 0..1 時,另外會用 …/raw 送出未縮放的原始值。

類型發布說明
fader<id>orient: v、h 或 auto(跟著格子的形狀)· 點兩下回到 def
knob<id>抓外圈是轉動,抓中間是拖曳
encoder<id>(相位,轉滿一圈會繞回)和 <id>/delta(這一下轉了幾圈)可以無限轉
button<id> 1 / 0按住才有作用,pulse 參數在按下的瞬間(上升緣)觸發
toggle<id> 1 / 0
xy<id>/x、<id>/y、<id>/downspring: true 放手後回到中心
bank<id>/1 … <id>/Ncount、labels。一根手指劃過去,就能一路畫過好幾個通道
radio<id> = 索引 / (n − 1),raw = 索引options: [...]
pads<id>/hit 脈衝 { pad, row, col, vel },按住時 <id>/<n> 是力度rows、cols(預設 4 × 4)、labels。n 從 0 起算,力度看你打在哪裡(上輕下重)
keyboardmidi/note/on、midi/note/off、midi/cc/64和硬體鍵盤用的名字一樣
number<id>− / + 按鈕(按住會連續變動)和一個輸入欄
text<id>,一個字串脈衝按 Enter 或 ↵ 送出
label、meter無只負責顯示,數值由 surface.feedback(name, value) 餵進來

共用欄位:id、type、label、min、max、def、step、unit、color(cyan amber magenta lime violet coral white),以及給手寫版面用的 target(一個參數的 key,xy 和 bank 則是陣列)。

手機鍵盤送出的音符是 { note, vel, velocity, ch: 1, device: 'surface' }。

版面 JSON#

版面跟路由一樣是資料:可以存成檔案分享,可以交給 AI 代理寫,也可以由世界發布。

json
{ "version": 1, "title": "Bloom",
  "pages": [{
    "id": "main", "title": "Main", "grid": { "cols": 8, "rows": 4 },
    "widgets": [
      { "id": "hue",  "type": "knob",   "label": "Hue", "x": 0, "y": 0, "w": 2, "h": 2, "min": 0, "max": 360, "def": 205, "color": "cyan", "target": "hue" },
      { "id": "pos",  "type": "xy",     "x": 2, "y": 0, "w": 4, "h": 4, "target": ["cx", "cy"] },
      { "id": "go",   "type": "button", "label": "Burst", "x": 6, "y": 0, "w": 2, "h": 1, "target": "burst" }
    ],
    "portrait": { "grid": { "cols": 4, "rows": 8 }, "place": { "pos": { "x": 0, "y": 2, "w": 4, "h": 4 } } }
  }] }

手機會轉來轉去,所以每個頁面照這個順序決定怎麼排:

  1. 如果頁面有對應目前方向的 portrait 或 landscape 變體,就用它的格線(沒寫在它 place 裡的元件,留在原本的位置,或填進空格)。
  2. 沒有變體,但基本格線的形狀本來就對,就直接用。
  3. 都不符合,就自動重排:同樣的元件,一列一列重新排進一半(直向)或兩倍(橫向)的欄數。

列數是個數目,不是像素,所以格線永遠填滿螢幕,畫面永遠不會捲動。沒有 x/y 的元件,會依類型給一個預設大小,排進空格。validateLayout(layout) 回傳一份問題清單(空的就是沒問題)。遇到有問題的版面,new Surface() 會帶著這份清單丟出錯誤。

autoSurface#

autoSurface(params, options) 把世界的參數變成三樣東西:一份版面、驅動這些參數的路由,以及回送數值用的綁定:

js
import { autoSurface, feedbackFor } from '@openav/surface';

const { layout, routes, bindings } = autoSurface(world.params, { pairs: [['cx', 'cy']], meters: ['density'] });
routes.forEach((r) => mapper.addRoute(r));   // surface/main/hue → hue, …
feedbackFor(state, bindings);                // [{ name, value }] to echo back to the phone

每個參數會變成哪種元件:

參數元件
pulse: true按鈕
step: 1,範圍是 1(兩個值)開關(toggle)
step: 1,有三到七個值單選(radio,標籤取自 options,沒有就用數字)
列在 pairs 裡的一對一個 xy 觸控板,同時驅動兩個參數
其他連續參數在六個以內用推桿,超過六個就用旋鈕
參數上寫了 surface: { type, color, label }照它寫的

選項:pairs、meters(另外以唯讀方式顯示的參數)、style('auto'、'fader'、'knob')、perPage(預設 8,要捲動的頁面就算失敗)、smooth(連續路由預設 0.04 秒,用來抹平網路每秒 30 次更新的階梯感)、title。每個參數 group 各自一頁。

手寫版面#

給元件一個 target,routesFromLayout(layout, params) 就會寫出它的路由(形狀和 autoSurface 產生的一樣):xy 把 x 接到第一個目標、y 接到第二個,bank 把第 i 個通道接到第 i 個目標。世界可以把版面放在 world.surface 一起帶著走,這時演出端就用它,不再自動產生。

主題與手機輔助函式#

每個控制元件都讀 :root 上的 CSS 自訂屬性(THEME_VARS:--oav-bg、--oav-surface、--oav-accent、--oav-radius、--oav-touch-min(44 px)…)。覆寫它們,整個控制面板就換了外觀。設計規則是:深色底、觸控目標 ≥ 44 px、即時數值永遠看得到、按下時用元件自己的顏色亮出邊框和光暈、支援 navigator.vibrate 的裝置就震動。

@openav/surface 也匯出幾個手機輔助函式:lockViewport()(禁止捲動和縮放)、keepAwake()(Wake Lock)、toggleFullscreen()、canFullscreen()、haptic(ms)。

中繼#

用戶端連到 ws://<host>/relay?role=controller|runner|monitor|leader|follower&room=<name>&id=<device>。房間就是一個名字,不同房間的連線彼此聽不到。

發送端接收端內容
controller(手機)runner + monitorsignal 和 batch
runner(演出)monitorsignal 和 batch
runnercontrollers + monitorsfeedback(儀表、推桿回送)、config(控制面板版面,之後加入的手機也會補收到一份)
monitor不送給任何人
leader(演出頁面)followerssync(frame,以及回給從屬端的 state)
follower(演出頁面)leaderssync(hello)

訊息是 JSON:{"type":"signal","name":"phone/ab12/tilt/x","value":0.3,"t":…,"pulse"?:true}、{"type":"batch","items":[…]}、ping/pong、status(各角色的連線數)、feedback、config、sync。用戶端遇到不認得的類型就略過。runner 離開時,房間會清掉它的 config。超過 256 KB 的訊息直接略過,超過 1 MB 的 frame 會讓連線直接關閉。不再回應 ping 的手機(螢幕鎖定、Wi-Fi 斷了),大約 40 秒內會被移除。 attachRelay(server, { maxMessageChars, maxBytes }) 可以把這兩個上限調高。

演出頁面也用同樣的房間一起演同一場:主控端的 sync 訊息({"type":"sync","v":1,"kind":"frame",…};"to":"<id>" 指定單一對象)送給房間裡的從屬端,從屬端的訊息送給主控端,其他人都聽不到(好幾個頁面,一場演出)。

js
import { RelayClient, bindSignals } from '@openav/relay';

const show = new RelayClient({ role: 'runner', room: 'main' }).connect();
bindSignals(show, signals);                        // phone signals → Signals, + phone/any/… alias
show.feedback('surface/main/level', 0.4);          // runner → phones
show.config('surface', { layout });                // runner → phones, kept for late joiners

const phone = new RelayClient({ role: 'controller', room: 'main' }).connect();
phone.set('phone/me/tilt/x', 0.3);                 // continuous: batched at 30 Hz, re-sent every second
phone.send('midi/note/on', { note: 60 }, true);    // pulse: immediate, never coalesced

連續值每秒重送一次,所以晚加入的手機,或演出中途重新載入的演出頁面,都不會卡在過時的預設值上。脈衝永遠不批次、不重送:一個 note-on 送到兩次就是 bug。用戶端會自己重新連線(從 0.5 秒開始,每次加倍,最長 5 秒)。

fileSignal(signals, name, value, { pulse }) 是這套傳輸格式的接收端:一個名字第一次出現時,先宣告它(signalMeta() 知道 phone/…、surface/…、midi/… 這些名字的範圍),音符訊息缺哪一種力度寫法就補上哪一種(vel 0..1 或 velocity 1..127),然後觸發脈衝或設定數值。

不靠 serve.js,單獨跑中繼:node packages/relay/server.js [port](預設 7458,健康檢查在 /health),或用 @openav/relay/server 的 attachRelay(server, { path: '/relay' }) 掛到你自己的 Node 伺服器上。

演出頁面跑在手機上#

演出本身跑在手機上時,不用中繼,就能讀這支手機自己的動作感測器。localSensors(signals) 用同樣的名字發布在 phone/local/… 底下,也複製一份到 phone/any/…,所以替「最新的那支手機」寫的路由,兩種情況都能用。.start() 要在使用者點擊時呼叫(iOS 的權限規定):

js
import { localSensors } from '@openav/remote';

const own = localSensors(show.signals);
button.onclick = async () => { await own.start(); if (own.denied) alert('motion access denied'); };

安全性#

中繼沒有身分驗證。同一個網路裡,任何知道房間名稱的人,都能以 controller 身分加入,動你的參數。正式演出時,請用封閉的網路,或取一個沒人猜得到的房間名稱。公開中繼上的房間是隨機的、寫在 QR code 裡,它方便你試玩,不是一把鎖。

訊號一覽#

14原始檔: docs/zh/signals.md

訊號是輸入層唯一的通用貨幣:有名字、經過正規化、不分來源。這一頁列出內建輸入套件發布的每一個訊號。

慣例:

  • 除非另外註明,範圍都是 0..1
  • pulse(脈衝)訊號觸發的是事件,它的值就是事件帶的資料(payload)
  • 只要對演出來說比較直覺,y 軸就會反轉(1 = 舉高),數值絕不會是原始像素
  • <n> 是數字,<ch> 是 MIDI 頻道 1..16,<id> 是裝置 id,<slug> 是轉成網址安全格式的裝置名稱

@openav/midi#

每一則硬體訊息,都會同時發布舊式名稱和分頻道的名稱。

訊號種類範圍意義
midi/note/on脈衝{note, vel, velocity, ch, device}按下琴鍵:vel 0..1,velocity 1..127,ch 1..16,device = 連接埠的 slug
midi/note/off脈衝{note, ch, device}放開琴鍵
midi/cc/<n>連續0..1第 n 號控制器(任何頻道)
midi/bend連續-1..1彎音(任何頻道)
midi/ch/<ch>/cc/<n>連續0..1單一頻道上的第 n 號控制器
midi/ch/<ch>/note/<n>連續0..1按住音 n 時是它的力度,放開時為 0
midi/ch/<ch>/bend連續-1..1單一頻道上的彎音
midi/ch/<ch>/pressure連續0..1頻道觸後(channel aftertouch)
midi/ch/<ch>/poly/<n>連續0..1音 n 的複音觸後(polyphonic aftertouch)

接了兩個以上的 MIDI 輸入時,每台裝置也會用自己的 slug 再發布一份(slug 取自連接埠名稱:Arturia MiniLab 3 → arturia-minilab-3,名稱重複的依序加上 -2、-3):

訊號種類範圍意義
midi/<slug>/note/on脈衝{note, vel, ch}在那台裝置上按下琴鍵
midi/<slug>/note/off脈衝{note, ch}在那台裝置上放開琴鍵
midi/<slug>/cc/<n>連續0..1那台裝置的第 n 號控制器
midi/<slug>/bend連續-1..1那台裝置的彎音

螢幕上的控制器(modules.midi.controllers),每個控制項發布一個 midi/<device>/<control>(例如 midi/minilab3/knob1),打擊墊另外發 /hit 脈衝,也有 /raw 原始值。完整列表在 MIDI 控制器與嵌入。

@openav/keys#

螢幕鋼琴、電腦鍵盤演奏和模擬演奏者,發布的是舊式的音符名稱,帶的資料比較少:

訊號種類範圍意義
midi/note/on脈衝{note, vel, ch: 0}按下琴鍵(vel 0..1)
midi/note/off脈衝{note, ch: 0}放開琴鍵

@openav/chord#

訊號種類範圍意義
chord/consonance連續-1..1最近一次彈奏的和聲協和度
chord/count連續0..10最近一次彈奏有幾個音
chord/root連續0..127最近一次彈奏裡最低的 MIDI 音
chord/event脈衝完整分析結果{notes, count, root, vel, pcs, consonance, isConsonant, isDissonant, isTriad, thirdsFraction, dissonanceLevel, chordType}

chordType:single · major · minor · sus2 · sus4 · dim · aug · maj7 · min7 · dom7 · halfdim7 · maj9 · min9 · dom9 · six · min6 · cluster(非常不協和的一堆音)· chord(其他所有情況)。轉位和弦會把音級(pitch class)輪轉一遍,認回原位和弦的名稱。

dissonanceLevel:0 沒有 · 1 輕微(暴風雨警報,用來預示)· 2 嚴重(真正的音堆,整個換成衰敗的語彙)。會分成這三級,是因為台北 IRCAM × C-LAB 演出時,有觀眾真的這樣回饋:「不協和的偵測不夠嚴格。」

@openav/audio#

訊號種類範圍意義
audio/rms連續0..1音量(經過平滑)
audio/peak連續0..1瞬間峰值
audio/band/low連續0..120–250 Hz 的能量
audio/band/mid連續0..1250 Hz–2 kHz 的能量
audio/band/high連續0..12–8 kHz 的能量
audio/centroid連續0..1頻譜亮度
audio/onset脈衝{rms}高過自動調整底線的暫態(冷卻 100 ms)
audio/kick脈衝{level}20–120 Hz 的暫態(冷卻 90 ms)
audio/snare脈衝{level}150–800 Hz 的暫態(冷卻 90 ms)
audio/hat脈衝{level}6–14 kHz 的暫態(冷卻 60 ms)
audio/kick/env /snare/env /hat/env連續0..1每種鼓各自的衰減波封(可以直接映射到參數)

@openav/pose#

預設左右鏡像(把鏡頭當成鏡子)。y 軸反轉:1 = 舉高。

訊號種類範圍意義
pose/present連續0/1畫面裡有人
pose/hand/left/x /y連續0..1左手腕(觀看者的左邊)
pose/hand/right/x /y連續0..1右手腕
pose/hand/left/v right/v連續0..1手腕移動速度
pose/hands/spread連續0..1兩手腕之間的距離
pose/height連續0..1鼻子的高度(蹲下 ↔ 站起)
pose/lean連續-1..1肩線傾斜

@openav/pose — HandTracker(21 個關鍵點的精細控制)#

每隻手有兩個捏合距離,兩隻手加起來就是四個精準的連續控制器。數值依手掌大小正規化,所以手離鏡頭遠或近,捏合的值都不變。

訊號種類範圍意義
hand/left/present right/…連續0/1看得到這隻手
hand/left/x /y連續0..1手掌位置(y:1 = 舉高)
hand/left/pinch/index連續0..1拇指指尖 ↔ 食指指尖(0 = 碰在一起)
hand/left/pinch/middle連續0..1拇指指尖 ↔ 中指指尖
hand/left/spread連續0..1食指指尖 ↔ 小指指尖張開的距離

(hand/right/* 是同樣的一組。兩種追蹤器都提供 skeleton(ctx, w, h) 骨架疊圖。)

@openav/leap#

透過這台電腦的橋接程式讀 Leap Motion/Ultraleap。位置是手掌或指尖在互動空間裡的位置,正規化並夾在 0..1(x 往右、y 往上、z 朝向演出者)。<side> 是 left 或 right,<finger> 是 thumb index middle ring pinky 其中之一。

訊號種類範圍意義
leap/status連續0..30 沒有橋接 · 1 有橋接、沒有追蹤服務 · 2 沒有裝置 · 3 追蹤中
leap/hands連續0..2看得到幾隻手
leap/hand/<side>/present連續0/1看得到這隻手
leap/hand/<side>/x /y /z連續0..1手掌位置
leap/hand/<side>/pinch /grab連續0..1捏合與握拳的強度(手不見了就歸 0)
leap/hand/<side>/roll /pitch /yaw連續-π..π手的轉向,單位弧度
leap/hand/<side>/speed連續0..1手掌速度,1 = 每秒 1 公尺
leap/hand/<side>/<finger>/x /y /z連續0..1指尖位置
leap/both/distance連續0..1兩個手掌的距離,1 = 40 公分
leap/hand/<side>/pinch-start /pinch-end脈衝{side, x, y, z, strength}捏超過 0.86 開始,低於 0.5 結束
leap/hand/<side>/grab-start /grab-end脈衝{side, x, y, z, strength}握拳超過 0.8 開始,低於 0.5 結束
leap/both/pinch-start /pinch-end脈衝{x, y, z, distance}兩手都捏超過 0.8 進入,任一手低於 0.5 離開

@openav/drums(模擬器,訊號形狀和分析器相同)#

鼓機發布的訊號,跟音訊分析器的長得一模一樣,所以接到大鼓的世界分不出那是麥克風還是鼓機(做這台模擬器就是為了這個)。音序器的每一擊也會以 midi/note/on 送出(頻道 10,GM 音符編號)。

訊號種類範圍意義
drum/kick /snare /hat /clap脈衝{level}音序器打了一下
drum/kick/env …連續0..1每一軌的衰減波封(可以直接映射到參數)
midi/note/on脈衝{note, vel, ch: 10}大鼓 36 · 小鼓 38 · 拍手 39 · 閉合 hi-hat 42

@openav/sound(輸出事件)#

頁面裡的樂器會聽 midi/note/on|off 和延音踏板 midi/cc/64,自己也會發出一個事件。

訊號種類範圍意義
sound/instrument脈衝{id, name}換了樂器(從選單、程式或場景提示)

@openav/record(MIDI 錄音的播放)#

TakePlayer 用原本的名稱(midi/note/on、midi/ch/<ch>/note/<n>、midi/cc/<n>……)發布錄下來的事件,跟鍵盤當時發布的一模一樣,另外有兩個自己的訊號。

訊號類型範圍意義
take/playingcontinuous0 / 1正在播放時是 1;暫停、停止,或讓位給現場演奏時是 0
take/positioncontinuous0..1播到哪裡了

@openav/remote · @openav/surface#

手機感測器(/packages/remote/ → 感測)。<id> 是裝置 id。phone/any/… 的值永遠來自最後送出數值的那支手機,所以還沒有手機連上,就能先寫好世界的路由。

訊號種類範圍意義
phone/<id>/tilt/x /y連續-1..1從校正過的靜止姿勢算起 ±45°,以螢幕座標為準(x 向右,y 朝向你)
phone/<id>/accel/x|y|z連續m/s²含重力
phone/<id>/rot/alpha|beta|gamma連續deg/s旋轉速率
phone/<id>/orient/alpha|beta|gamma連續deg原始的 deviceorientation
phone/<id>/knock脈衝{strength, delta, t}加速度突然一震、超過門檻(冷卻 130 ms)
phone/<id>/light連續0..1前鏡頭畫面的平均亮度(luma)
phone/<id>/touch/x /y /down連續0..1第 0 根手指。n ≥ 1 用 touch/<n>/…,另有 touch/count
phone/local/…——演出頁面本身跑在手機上時,同一套感測器名稱(localSensors(signals),不經過中繼,也會複製一份到 phone/any/…)

控制面板元件(正規化到 0..1,範圍不是 0..1 的元件,另用 …/raw 帶未縮放的原始值):

訊號種類意義
surface/<page>/<id>連續fader · knob · number · toggle · button(0/1)· radio(idx/(n-1))· encoder 的相位
surface/<page>/<id>/x /y /down連續xy pad
surface/<page>/<id>/<1..N>連續bank 的各個通道
surface/<page>/<id>/hit脈衝 {pad,row,col,vel}pads。按住時 …/<n>(n 從 0 起算)保持力度值
surface/<page>/<id>/delta連續encoder 每一步的轉動量,單位是圈
surface/<page>/<id>(text)脈衝在 text 元件裡輸入的字串
midi/note/on /off、midi/cc/64脈衝/連續琴鍵分頁和 keyboard 元件,名稱和形狀都跟 @openav/midi 一樣:{note, vel, velocity, ch: 1, device: 'surface'}

接收端:每一則中繼訊息都經過 fileSignal(signals, name, value, {pulse}) 寫進訊號(@openav/relay,bindSignals 用的就是它,自己開 socket 的宿主頁面也是,例如 lab 的 lab.js)。一個名稱第一次出現時,它會先宣告(signalMeta)。midi/…/note/on|off 的發送端少給了哪一種力度寫法,它就補上哪一種(vel 0..1 ⇄ velocity 1..127)。

自己命名訊號#

用路徑式的寫法,來源放最前面:breath/pressure、phone/{id}/gyro/x、weather/wind。先用 signals.define(name, {min, max}) 宣告範圍,儀表和 norm() 才算得對,之後只要 signals.set(name, v)。任何會變動的東西,都能拿來演出。

套件一覽#

15原始檔: docs/zh/packages.md

二十八個套件放在 packages/<name>/。每一個都是純 ES module,沒有任何相依套件。在網頁裡透過 import map,用 @openav/<name> 引入(照抄 examples/01-hello-particles/index.html 裡那份就好)。目前還沒有發布到 npm。

層套件
L1 輸入midi · audio · chord · pose · leap · keys · drums
L2 映射mapping · chop
L3 世界stage · world-webtoe
L4 輸出sound · osc · out · record · fab(MIDI 輸出在 midi 裡)
主軸timeline · score · pattern · console · monitor · sync
手機relay · surface · remote
膠水core · show · mcp

子路徑入口(@openav/remote/host、@openav/relay/server、@openav/surface/layout、@openav/surface/auto)在瀏覽器裡要各自在 import map 加一行,例如 "@openav/remote/host": "../../packages/remote/host.js?v=1f11cf5e"。

@openav/core#

膠水 · 共用的語言:Signals、Params、Loop、Bus。

匯出簽章
Signalsnew Signals() · define(name, { kind, min, max, unit, description, source }) · set(name, value) · pulse(name, payload = 1) · get(name) · norm(name) → 0..1 · on(name, cb(value, name)) → 取消訂閱函式 · onAny(cb(name, value, meta)) → 取消訂閱函式 · list() → [{ name, value, at, kind, min, max, … }]
Paramsnew Params(schema = []) · add(entries) · get(key) · clamp(key, v) · override(key, v) · clearOverride(key) · clearAllOverrides() · isOverridden(key) · firePulse(key) · onPulse(key, cb) → 取消訂閱函式 · resolve(base) → 狀態 · schema、overrides
Loopnew Loop(onFrame(dt, now), { maxDt = 0.1, clock, raf, manual = false, heartbeat }) · start() · stop() · step(dt) → boolean(跑一個長度 dt 秒的影格,不夾上限)· fps、running、manual。clock() → 毫秒(預設 performance.now),raf(cb) → 下一格(預設 requestAnimationFrame);注入 raf 或 manual 會關掉分頁藏起來時的 Worker 心跳(heartbeat: true 可打開)。見自己驅動影格
Busnew Bus() · on(event, cb) → 取消訂閱函式 · off(event, cb) · emit(event, payload)
js
import { Signals, Params, Loop } from '@openav/core';
const signals = new Signals();
signals.define('breath/pressure', { min: 0, max: 1 });
signals.on('breath/pressure', (v) => console.log(v));
signals.set('breath/pressure', 0.4);

@openav/show#

膠水 · createShow(options):呼叫一次,以一個世界為中心組好整場演出,再把每個部分交給你。選項、模組和回傳值見演出控制;loop、monitor、console(控台的 keys)決定誰來給影格、後台推送送去哪裡、哪些鍵操作控台。sync 讓這個頁面成為好幾個演同一場的頁面之一(主控端或從屬端,見 @openav/sync)。

js
import { createShow } from '@openav/show';
const show = await createShow({ world, modules: { keys: { base: 48 }, sound: true } });

@openav/midi#

L1 輸入與 L4 輸出 · Web MIDI 的輸入與輸出,可以同時接很多台裝置,還有照實體硬體做的螢幕控制器。

匯出簽章
Midinew Midi({ signals, filterOut = 'IAC', requestAccess, echoWindow = 40, prefer = [] }) · enable(preferredOut = '') → Promise<boolean> · devices() → [{ slug, name, listening }] · setListening(slug, on) · onDevices(fn) · onOutput(fn({ text, reason, next })) · listen(fn(bytes, port)) · selectOutput(name) → boolean(並記住成你的選擇)· outputFor(nameOrRegExp) · send(bytes) · noteOn(note, vel = 100, ch = 1) · noteOff(note, ch = 1) · cc(cc, val, ch = 1) · panic() · dispose() · hook:onCC、onNote、onMessage、onSend、onDeviceChange · out、outputs、preferredOut、echoDropped
輸出熱插拔、回音pickOutput(outputs, { preferred, prefer }) · reselectOutput({ current, outputs, preferred, prefer }) → { next, changed, reason, text } · EchoGuard({ window })(sent(bytes)、isEcho(bytes)):Midi 背後的純邏輯,見演出控制
總譜轉 MIDInew ScoreMidi({ midi, channel = 15, segment = { note: 36 }, cue = { note: 84 }, length, scrub, enabled }) · segment({ index, cause }) · cue({ name, n }):把段落切換和 cue 變成 note 與 CC,見總譜與導演
解析parseMessage(bytes) → 事件 · encodeMessage(event) → 位元組 · genericSignals(event, { device }) · publish(signals, list) · describe(event) · relativeDelta(value, mode)、relativeValue(delta, mode)、RELATIVE_MODES · bendToUnit、unitToBend、BEND_CENTER
控制器MidiController、MidiControllers、controllerRoutes(profile, bindings)、PROFILES、profileById(id)、ControllerView、mountMidiPanel(el, controllers, opts)、linkControllers,以及 profile 輔助函式(validateProfile、normalizeProfile、matchProfile…)
Web MIDI shimcreateVirtualMIDIAccess({ name, onOutput(bytes, timestamp), onClear })、virtualRequestMIDIAccess、splitMidi(bytes):它的輸出會連同每次送出的時間戳被聽到
MidiClock(clock.js)new MidiClock({ ppq = 24, beatsPerBar = 4 }) · feed(bytes, t) → 'clock'·'start'·'continue'·'stop'·'spp'·'dupe' · bpm · phaseAt(t) → { pos, bar, beat, bpm, running } · anchor() · state(t):跟著外部 MIDI 時鐘(和 Strudel 一起用)
嵌入createController(profile, { profiles, signals, channel, follow, midi, requestAccess, filterOut, telemetry }) → ControllerHost(on(event, fn)、set、press、release、values、mount(el)、learn()、dispose())· loadProfile(idOrUrl) · packages/midi/element.js 裡的 <oav-controller> 元素 · embed.js 裡的嵌入協定輔助函式
js
import { Midi } from '@openav/midi';
const midi = new Midi({ signals });
await midi.enable();
midi.noteOn(60, 100, 1);

訊號:見訊號一覽。控制器、profile 和 shim:見 MIDI 控制器與嵌入。

@openav/audio#

L1 輸入 · 麥克風(或任何音訊節點)的分析。

匯出簽章
AudioAnalyzernew AudioAnalyzer({ signals, fftSize = 2048, smooth = 0.7 }) · enableMic() · enableElement(mediaEl) · input() → 一個可以接進去的 AnalyserNode · 每個影格呼叫 update() → { rms, peak, low, mid, high, centroid, onset, kick, snare, hat }
js
import { AudioAnalyzer } from '@openav/audio';
const audio = new AudioAnalyzer({ signals });
await audio.enableMic();          // from a click
// every frame: audio.update();

@openav/chord#

L1 輸入(一種分析器)· 把彈下的音歸成一次一次的彈奏(gesture),發布協和度、三和弦和音堆。

匯出簽章
ChordDetectornew ChordDetector({ window = 80, onChord, signals }) · noteOn(note, vel = 0.8) · noteOff(note) · analyze(notes, vels) → 分析結果(純函式)
js
import { ChordDetector } from '@openav/chord';
const chord = new ChordDetector({ signals });
signals.on('midi/note/on', ({ note, vel }) => chord.noteOn(note, vel));
signals.on('midi/note/off', ({ note }) => chord.noteOff(note));
chord.analyze([60, 64, 67]).chordType;   // 'major'

@openav/pose#

L1 輸入 · 用 MediaPipe 從鏡頭追蹤身體和手,全部在本機運算。

匯出簽章
PoseTrackernew PoseTracker({ signals, mirror = true }) · enable({ videoEl })(要從點擊事件呼叫)· stop() · skeleton(ctx, w, h, { color, lineWidth }) · landmarks、running
HandTrackernew HandTracker({ signals, mirror = true }) · enable({ videoEl }) · stop() · skeleton(ctx, w, h, { colorLeft, colorRight, lineWidth }) · hands、running
js
import { HandTracker } from '@openav/pose';
const hands = new HandTracker({ signals });
button.onclick = () => hands.enable();

@openav/leap#

L1 輸入 · 透過這台電腦的橋接程式讀 Leap Motion/Ultraleap 的手(node packages/leap/bridge/leap-bridge.mjs,ws://127.0.0.1:6437)。同一支橋接也講舊的 LeapJS 協定,所以 2014–2021 年用 leap.js 寫的作品不用改就能跑。

匯出簽章
LeapInputnew LeapInput({ signals, url, reconnect = true, fingers = true, box, thresholds }) · connect() · disconnect() · simulate({ target }) → stop() · skeleton(ctx, w, h, { view, colorLeft, colorRight, lineWidth }) · mountPanel(el) · onFrame(fn) · onStatus(fn) · ingest(msg) · hands、frame、status、device
幀V6Converter(原始格式 → LeapJS v6)· handsOf(msg) · normalizePoint(p, box) · handAngles(direction, normal) · mockHand(o) · mockFrame(t)
手勢HandGestures · Hysteresis(on, off) · THRESHOLDS(單手捏 0.86/0.5、雙手捏 0.8/0.5、握拳 0.8/0.5)
js
import { LeapInput } from '@openav/leap';
const leap = new LeapInput({ signals }).connect();   // ws://127.0.0.1:6437/v6.json
leap.onFrame(() => leap.skeleton(ctx, w, h));          // joints in mm: leap.hands
// no sensor: leap.simulate() — mouse = right palm, press = pinch

@openav/keys#

L1 輸入 · 螢幕鋼琴、電腦鍵盤演奏和一位模擬演奏者,全都發布 midi/note/on|off。

匯出簽章
mountKeysmountKeys(container, { signals, chord, base = 48, octaves = 2, sim = true, capture = true }) → { piano, sim, update(dt), dispose(), captureBox }
KeysPianonew KeysPiano(container, { base, octaves, semitones, fill, keyWidth, velocity, minBase, maxBase, onNote, onOctave }) · press(note, vel01) · release(note) · releaseAll() · setBase(n) · handleKeyDown(e)、handleKeyUp(e) · captureEnabled
SimPlayernew SimPlayer({ press, release, base = 60, scale = [0, 2, 4, 7, 9], density = 1 }) · toggle(on) · update(dt)
PIANO_KEYMAP{ a: 0, w: 1, s: 2, … ';': 16 }
js
import { mountKeys } from '@openav/keys';
const keys = mountKeys(document.querySelector('#keys'), { signals, base: 48 });
// every frame: keys.update(dt);

@openav/drums#

L1 輸入與 L4 輸出 · 合成鼓組、16 步音序器和它的格狀介面。發布的 drum/* 跟麥克風偵測鼓點時的長得一樣。

匯出簽章
mountDrumsmountDrums(container, { signals, engine, autoEnableEngine = true, onStep, onHit, onTakeover, bpm = 112, pattern, clock = 'frame', lang }) → { seq, engine, root, clock, play(on), setPattern(p, { text }), setBpm(bpm), update(dt), deliver(), phase(), now(), info(), dispose() };clock: 'lookahead' 照鼓組的音訊時鐘提前排程(oav-p5 0.6 用這個),也能照寫的樣子打編譯好的一行節奏;lang: 'zh' 軌道名用中文;rhythm: <@openav/pattern>(或 useRhythm(mod))讓格子上方那一行可以直接改、點格子會改寫它,附 history/undo()、複製、在 Strudel 打開(0.7)
DrumSequencernew DrumSequencer({ onHit(lane, vel), onStep(i, n), bpm = 112, swing = 0.12, humanize = 0.35, pattern = 'four on floor' }) · setPattern(nameOrGrid) · toggleCell(lane, i) · toggle(on) · update(dt) · grid、bpm(逐幀推進的時鐘)
DrumScheduler、DrumTransport提前排程的時鐘:格子或編譯好的一行節奏 → 帶時間的事件,小節位置用速度錨點換成秒(不累積漂移);外層是 Web Worker 心跳、音訊時鐘、聽到時才告訴頁面的步與鼓;follow({ pos, at, bpm }) 跟著外部時鐘打(小誤差用速度慢慢拉回,大誤差直接跳到它的格線上)、followInfo()、unfollow()
drumEnginedrumEngine({ samples }) → 一個聲音引擎(見聲音);noteOn(note, vel, time) 在自己 AudioContext 的 time 響,回傳 { time, cancel() }
PATTERNS、GM節奏型預設,以及 General MIDI 鼓的音符編號 { kick: 36, snare: 38, clap: 39, tom: 45, hat: 42, openhat: 46 }
js
import { mountDrums } from '@openav/drums';
const drums = mountDrums(document.querySelector('#drums'), { signals });
// every frame: drums.update(dt);

@openav/mapping#

L2 映射 · 從訊號接到參數的路由,含曲線、平滑、learn,以及可以存檔的設定組(profile)。

匯出簽章
Mappernew Mapper({ signals, params, profile = 'default', onChange, onLearn, base }) · addRoute(route) · removeRoute(id) · routesFor(target) · learn(target) · update(dt) · toJSON() · fromJSON(routes) · save() · load() · dispose() · routes、learnTarget
LearnWizardnew LearnWizard({ mapper, keys, onChange }) · start() · skip() · back() · stop() · sync() · active、current、index、total、done、added:「依序對應旋鈕」,見總譜與導演
js
import { Mapper } from '@openav/mapping';
const mapper = new Mapper({ signals, params });
mapper.addRoute({ source: 'midi/cc/74', target: 'bloom', curve: 'exp', smooth: 0.1 });
// every frame: mapper.update(dt);
// a knob that nudges the timeline instead of replacing it, and gives the param back when you let go:
// mapper.base = () => timeline.state();
// mapper.addRoute({ source: 'midi/cc/71', target: 'bloom', mode: 'trim', outMin: -0.3, outMax: 0.3, release: 4 });

完整說明:見映射。

@openav/chop#

L2 映射 · 數值隨時間的變化,像 TouchDesigner 的 CHOP 那樣塑形:Lag、Trigger(這裡叫 envelope)、Speed、Spring、Trail、Slope、Count。純邏輯,沒有自己的時鐘:每一步都告訴它過了幾秒,並在那段時間裡精確求解,所以 30 fps 和 144 fps 畫出同一條曲線。參數意義參考 TouchDesigner 官方文件(Derivative),程式由 OAV 自行實作。在 p5 草圖裡,oav-p5 把它們做成一行一個:見 p5 一行注入。

匯出簽章
approachapproach(current, target, seconds, dt) → 一極點 lag 的一步;seconds=跟上 63% 變化的時間(@openav/mapping 的 smooth 就是用它算)
Lagnew Lag({ up = 0.1, down = up }) · step(input, dt, up?, down?) → 輸出 · reset(v?):上升用 up、下降用 down(Lag CHOP 的 Lag 1/Lag 2),秒數是 TouchDesigner 的(大約跟上 90% 變化的時間)
envelopeenvelope(times, t, attack = 0.01, decay = 0.3, peak = 1) → Trigger CHOP 在時間 t 的值(事件時間 times,秒,舊的在前):直線上升(0 → peak),decay 秒後剛好回到 0;還沒落完又觸發,從當下的高度接著走 · envelopeStage(elapsed, attack, decay, from, peak)
Speednew Speed() · step(rate, dt) → 位置:每秒加 rate
Springnew Spring({ stiffness = 100, damping = 6 }) · step(target, dt) → 位置(另有 velocity):掛在彈簧上的質點被拉向輸入,精確解 · springStep(x, v, target, k, c, dt) → [x, v]
Trailnew Trail({ seconds = 2, rate = 60 }) · step(value, dt) → 最近 seconds 秒,每秒 60 個值再加上最新的一個,舊的在前,長度固定
Slopenew Slope() · step(value, dt) → 每秒變化量
Countnew Count({ threshold = 0.5 }) · step(on, limit = 0) → 打開過幾次;給 limit 就在 0 … limit − 1 之間循環 · wrapCount(total, limit)
TD_LAG_RATIO、DEFAULTSMath.LN10:這裡有兩種秒數。Lag 與 lag() 收的是 TouchDesigner Lag CHOP 的秒數(大約是跟上 90% 變化的時間),所以 lag(x, 0.1) 動起來就像 Lag CHOP 設 0.1;Lag 內部再除以 TD_LAG_RATIO(2.3)換成時間常數。approach(…, seconds) 收的就是時間常數本身(跟上 63%,@openav/mapping 的 smooth 一向是這個意思);上面那些預設值
js
import { Lag, envelope } from '@openav/chop';
const vu = new Lag({ up: 0.03, down: 0.4 });       // opens at once, closes slowly
// every frame: r = 50 + vu.step(level, dt) * 300; pump = envelope(kickTimes, now, 0.01, 0.3);

@openav/stage#

L3 世界 · 世界的外殼:管生命週期、彙整參數,本身不負責繪圖。

匯出簽章
Stagenew Stage({ container, params, signals, io = {} }) · register(world) · activate(name)(非同步)· frame(dt, baseState) → 狀態 · active、activeName、worlds、io
createCanvascreateCanvas(container, { alpha = false }) → { canvas, ctx, fit() → { w, h }, dispose() }
js
import { Stage, createCanvas } from '@openav/stage';
const stage = new Stage({ container, params, signals });
stage.register(world);
await stage.activate(world.name);
// every frame: const state = stage.frame(dt, timeline.state());

@openav/world-webtoe#

L3 世界 · 把一張 WebToe 節點網路當成世界來演奏,參數會送進網路裡的 ext('name', fallback) 綁定。

匯出簽章
webtoeWorldwebtoeWorld({ name = 'webtoe', app = 'https://webtoe.openaudiovisual.com/', project, params = [], extra }) → 一個世界

見寫一個世界。

@openav/sound#

L4 輸出 · 頁面裡的樂器,背後是一份精簡的引擎介面約定。有 Salamander 平台鋼琴、敲擊琴、弦樂、風琴、合唱、豎琴和合成器音色,從選單挑,引擎的參數會變成 sound/* 參數。

匯出簽章
Soundnew Sound({ signals, params, engine, instrument, remember, picker }) · enable()(要從點擊事件呼叫)· 每個影格呼叫 update(state) · setInstrument(id) · instrument · status · onChange(cb) · dispose() · enabled
toneEnginetoneEngine({ instrument = 'synth/pad', baseUrl, instruments, cdn, drumChannel = 10 }) → 帶有 cutoff、space、volume 參數的引擎,再加上樂器自己的參數
registerInstrumentregisterInstrument({ id, name, category, params, defaults, credit, create(Tone, ctx) }, { replace }),另外還有 getInstrument、listInstruments、instrumentGroups、onInstrumentsChange
registerSynthPresetregisterSynthPreset({ id, name, voice, oscillator, envelope, filter, effects, … }) → synth/<id>
modalInstrumentmodalInstrument({ id, name, partials, strike, damp }) → 用資料寫成的敲擊類樂器
mountSoundPickermountSoundPicker(el, sound, { lang, className }) → 控台用的那個選單

引擎介面約定:{ params, enable(), noteOn(note, vel01), noteOff(note), set(key, value), dispose() }。樂器清單和怎麼加入新樂器,寫在聲音。

js
import { Sound, toneEngine } from '@openav/sound';
const sound = new Sound({ signals, params, engine: toneEngine({ instrument: 'piano' }) });
button.onclick = () => sound.enable();
// every frame: sound.update(state);

@openav/osc#

L4 輸出 · 透過一個小小的 Node 橋接程式,把 OSC 從瀏覽器送到 UDP。

匯出簽章
OscOutnew OscOut(url = 'http://127.0.0.1:7456') · enable() → Promise<boolean> · disable() · send(addr, args) · 每個影格呼叫 flush() · rate() → 上次呼叫之後送出的訊息數 · hook:onStatus(ok, info)、onMsg(addr, args)
橋接node packages/osc/bridges/osc-bridge.js [httpPort=7456] [targetHost=127.0.0.1] [targetPort=3456]

見演出控制。

@openav/out#

L4 輸出 · 把網頁作品的參數經一支本機橋接(node packages/out/bridge/out-bridge.mjs --config out.json,ws://127.0.0.1:6450/out)送到實體硬體:WLED 燈條(DDP)、序列埠馬達板、OSC。頁面安靜下來或最後一個連線離開時,看門狗會把每個通道退回設定好的安全值。

export簽名
OutClientnew OutClient({ url, id, schedule }) · connect() · simulate() · close() · set(ch, v) · batch({ ch: v }) · onStatus(fn) · status、last、bridge:同一通道每個 frame 只送一個值,斷線以退避重連,有心跳
橋接node packages/out/bridge/out-bridge.mjs [--port 6450] [--config out.json] [--no-watchdog] · sink:ddp serial osc udp-json log
實驗室meta.params[i].out: "light/1/r" 綁定參數(照 min–max 正規化到 0..1,outRaw 送原值);?out=sim · ?out=0 · ?out=ws://…

設定檔與看門狗規則見套件的 README。

@openav/record#

L4 輸出(影像分支)· 演出影片:作品和演奏者的鏡頭合成進一張尺寸精確的畫布(直式 1080×1920、4:5、2.7K、4K、橫式、方形),跟作品自己的聲音一起交給同一個 MediaRecorder 錄,所以畫面和聲音從結構上就是同步的;另外還有單獨的聲音檔、事件紀錄,以及 MIDI 錄音(錄下你彈的,再播回演出裡,.mid 可進可出)。

匯出簽章
Compositornew Compositor({ size = 'vertical-1080p', layout = 'stack', layoutOptions, getWorkCanvas, background, mirrorCam = true, maxFps = 60, onDraw(ctx, rects, comp) }) · start() · stop() · draw() · setSize(size) · setLayout(layout, options) · setCamera(stream | video | null) · drawOnCamera(fn(ctx, w, h)) · canvas、rects、video
Recordernew Recorder({ canvas, fps = 60, audioTracks = [], audioOnly = false, videoBitsPerSecond, mimeType }) · start({ timeslice = 1000, ondata(blob, seq), keep }) · stop() → Promise<{ mimeType, ext, bytes, durationMs, width, height, blob, … }> · t0
AudioTapnew AudioTap({ context, sources, captureDestination }) · add(node | stream | track, { bus }) · captureDestination() · addMicrophone() · level() · tracks(作品+麥克風)、workTracks(只有作品)
EventLognew EventLog({ now, filter, throttleMs }) · start(at) · stop() · add(name, value) · attach(signals) · toJSON() · toTake()
TakeRecorder · TakePlayernew TakeRecorder({ signals, filter = /^midi\//, overdub }) · start() · stop() → take · new TakePlayer({ signals, take, loop = true, speed = 1, yieldToLive, resumeAfter, clock }) · play() · pause() · stop() · seek(ms) · update(dt)
純函式layoutRects(layout, out, src, opts) · PRESETS · presetById · resolveSize · recommendedFps(w, h) · recommendedBitrate(w, h, fps) · pickMime(isTypeSupported, { audioOnly }) · extFor(mime) · normalizeTake · validateTake · trimSilence · quantizeTake · toMidiFile(take) → Uint8Array · fromMidiFile(bytes) → take
鏡頭openCamera({ deviceId, width = 1920, height = 1080, fps = 30 }) → MediaStream · listCameras() · listMicrophones()

版面:stack(作品在上、滿寬,鏡頭在下)、pip(鏡頭是角落的小窗)、side(作品在左、鏡頭在右)、work(只有作品)。大約 1080×1920 以內錄 60 fps,2.7K 和 4K 錄 30 fps;網路攝影機多半只到 1080p,所以 4K 畫面裡的鏡頭是放大的。

js
import { Compositor, AudioTap, Recorder, openCamera } from '@openav/record';
const comp = new Compositor({ size: 'vertical-1080p', layout: 'stack', getWorkCanvas: () => canvas });
comp.start();
await comp.setCamera(await openCamera());
const tap = new AudioTap({ context, sources: [workOutput] });
const rec = new Recorder({ canvas: comp.canvas, fps: 60, audioTracks: tap.tracks }).start();
// later: const { blob, mimeType } = await rec.stop();

套件說明(含 MIDI 錄音):packages/record。範例:10-record。

@openav/fab#

L4 輸出(實體分支)· 做得出來嗎?對任何網格出可製造性報告(水密、體積、懸空、最薄壁、PETG/PLA 估重,每個問題一句中文警告),並匯出 STL/OBJ/GLB;形狀來自 smlibwasm 的 Part/Shape 時還能出 STEP、DXF。smlibwasm 與 manifold-3d 不打包:smlib()/manifold() 第一次用到時才從網址 import()。

匯出簽章
Fabnew Fab({ urls: { smlib, manifold }, scale, importer, download, context }) · check(x, opts) → 報告 · export(x, fmt, opts) → Promise<{ bytes, mime, ext, report }>(stl obj glb step dxf)· save(x, fmt, { name, params, note }) 交給 saver(bytes, info),沒有就瀏覽器下載 · smlib() · manifold() · meshOf(x)
純函式checkMesh(mesh, { angle = 45, minWall = 1.2, bed = [320, 320, 325], wallSamples = 2000 }) · weldMesh(mesh) · meshOf(x, { scale })(TriMesh、smlibwasm Part、three.js Mesh/Object3D,Y 朝上轉 Z 朝上)· toStlBytes · toObjText · toGlbBytes

@openav/timeline#

主軸 · 自動化、場景和播放控制(transport),純邏輯。

匯出簽章
Timelinenew Timeline({ params, automation = {}, scenes = [], total = 600, score = null, start = null, loop = false, onCue = null, anchor = null }) · play()(放行 hold)、pause()、toggle()、seek(t)、jumpScene(d)、next()(放行 hold,否則往後一段)、prev()、release()、reset()(回到 start,預設 0)· advance(dt) · state(t)、valueAt(key, t) · sceneIndexAt(t)、currentScene(t)、sceneEnd(i) · onSceneChange(cb(i, scene, { cause }))、onSeek(cb(t, kind)) · layer(key, value, t) · 關鍵影格 [t, value, curve?]('linear'、'ease'、'in'、'out'、'step')· loop(true、'scene'、場景 id、{ from, to })、onLoop(cb) · cues()、onCue(cb(cue, { cause }))、fireCue(cue) · record(key, source)、stopRecording()、onRecord(cb)、mergeTake(key, take, opts) · 以段落為單位的自動化 { key: { 段落id: [[p, value, curve?], …] } }、lanePos(t)、laneTime(id, p)、lanePlan()、lanes() · exportAutomation({ keys, as, precision })、importAutomation(doc, { keys, replace, ignoreCut }) · anchor(epoch, opts)、unanchor()、drift()、onDrift(cb) · follow(source, opts)、unfollow()、following、followStatus()、onFollow(cb) · t、playing、holding、rate、total、start、score
compileLane、decompileLane、lanePos、laneTime、isLane、AUTOMATION_FORMAT段落 lane 的換算,寫成對段落表 [{ id, start, end }](score.rootSegments)操作的純函式,給沒有時間軸的工具用

關鍵影格的第三項,是「抵達這個影格的那一段」用的曲線;沒有寫就是線性,跟以前一模一樣。場景的 cues 在播放經過時觸發,seek 不會觸發。record() 在播放時,把一個數值來源(例如旋鈕的覆寫)寫進一條 lane。CURVES 也有匯出。曲線可以改成以段落為單位來寫、存成 JSON 再讀回來,時間軸也能盯著牆鐘:見 Lane、存取 automation、牆鐘,也能去追另一條時間軸的時鐘:見追另一條時鐘。

見演出控制。

@openav/score#

主軸 · 總譜與導演:把演出寫成段落長度,再由模組去演出每一段。純邏輯,不碰 DOM。

匯出簽章
Scorenew Score({ cuts, cut }) · table() · total · segmentAt(T)、indexAt(T) · locate(T)、timeAt(id, p) · cueTime('seg.name') · cuesBetween(T0, T1) · cues() · scenes() · validate() · cuts、cut、segments(每段帶著自己的 meta)、startT、scale、baseTime(T)、rootSegments、allSegmentIds()
ScoreError總譜不合法時丟出,problems 列出每一個原因
Directornew Director({ score, modules, api, onStatus, onCue, maxStep }) · update(T, dt, { holding, playing }) · param(key, value, T) · seek(T) · reset() · status() · register(module)
js
import { Score, Director } from '@openav/score';
const score = new Score({ cuts, cut: 'full' });
const director = new Director({ score, modules, api });
// every frame, after timeline.advance(dt):
director.update(timeline.t, dt, { holding: timeline.holding, playing: timeline.playing });

完整說明:總譜與導演。

@openav/pattern#

主軸 · 一行字寫節奏:把 mini-notation(TidalCycles 與 Strudel 寫節奏的方式)解析成每一小節的鼓點。純邏輯。依公開文件與論文獨立實作,寫法來自 TidalCycles 與 Strudel。

匯出簽章
compilecompile(src, { words = WORDS }) → { ok, error, src, voices, layers, period, eventsInBar(bar, { seed = 0 }) },不丟例外 · eventsInBar(小節從 1 起算)→ 依 pos(小節內 0..1)排序的 [{ word, voice, n, pos, dur, vel, layer, token: { start, end } }] · error → { code, index, length, message, hint },code 是 empty unclosed unexpected bad-number bad-euclid unknown-word unsupported 其中之一
parseparse(src) → { ok, tree } 或 { ok: false, error }:節點 step rest seq layer alt fast slow euclid maybe,每個都帶字元範圍
WORDSbd 大鼓 · sd 小鼓 · hh 鈸 · oh 開鈸 · cp 拍手 · rim/rs · lt mt ht 中鼓 · cr 碎音鈸 · rd 疊音鈸 · cb 牛鈴,也接受鼓組自己的名字
euclideuclid(pulses, steps, rotate = 0) → 布林陣列(Toussaint 2005)
fromGridfromGrid(grid, { steps = 16, words, order }) → 照人會寫的樣子把格子寫成一行、打出來一模一樣:bd*4、[~ sd]*2、bd(3,8,2),其他一拍一拍寫 bd [~ ~ ~ bd] bd*2 ~(0.7)
toGridtoGrid(srcOrCompiled, { bar = 1, steps = 16, seed = 0, bars = 16 }) → { ok, grid, words, voices, exact, lost: { offGrid, stacked, varies, random, samples } }:第 bar 小節放上格子,以及格子放不下的東西;seed 決定每個 ?(跟 eventsInBar 一樣),bars 是往後看幾小節來判斷其他小節有沒有不同(lost.varies)(0.7)
fromStrudelfromStrudel(code) → { strudel, ok, src, bpm, ignored, unsupported }:從 strudel.cc 複製來的 s("…")/sound("…"),.fast/.slow 併進那一行,setcpm/setcps 當速度(0.7)
toStrudel、strudelUrlstrudelUrl(src, { bpm, comment }) → https://strudel.cc/#…(寫成 s("…")、前面加 setcpm(bpm/4),# 後面是 base64);用新分頁開(0.7)

寫法:空白(等分一小節)· ~ - 休止 · [ ] 細分 · , 疊層 · *n 加快 · /n 放慢、跨小節 · < > 每小節輪一個 · (k,n,r) 歐幾里得 · !n 與 ! 重複 · @n 與 _ 拉長 · ? ?0.3 隨機省略(有種子)· bd:2 取樣編號。. | { } 會回錯誤與提示(休止請用 ~ 或 -)。

js
import { compile } from '@openav/pattern';
const p = compile('bd*4, [~ sd]*2, hh*8');
p.eventsInBar(1);   // kick 0 .25 .5 .75 · snare .25 .75 · hat every 1/8

@openav/console#

主軸 · 導演控台:播放控制、各層面板、可以 learn 的參數、訊號儀表、演出模式。

匯出簽章
mountConsolemountConsole(el, app, { layers, signals, learnOrder, keys, curves }) → { render(state), perf, director, curves, wizard, keys, dispose() }。app = { timeline, params, mapper, signals, stage, midi?, midiPanel?, sound?, audio?, hands?, pose?, loop?, osc?, score?, director? }
曲線面板curves:false 不要這個面板,{ open: true } 一開始就打開;desk.curves → { toggle(force?), open, info() }(curves: false 時是 null)。整場演出每個有 automation 的參數一條曲線、播放頭、覆寫與 ↩ 和 ↩ all、點一下就跳過去:曲線面板
鍵盤keys:{ play, next, prev, reset, perf, fullscreen, midi, cancel, curves } → 一個鍵或一串鍵('F6'、'KeyR'、'Shift+T'),false = 關掉;keys: false = 不要任何快捷鍵 · DEFAULT_KEYS · resolveKeys(keys) · keyLabel(keys, action):挪動快捷鍵

見演出控制。

@openav/monitor#

主軸 · 後台頁面,以及餵資料給它的 WebSocket 中繼。

匯出簽章
MonitorFeednew MonitorFeed({ url = 'ws://<page host>:7457', hz = 15, extra }) · connect() · frame(snapshot) · extra(fn) → off() · connected、onStatus
snapshotOfsnapshotOf({ timeline, params, signals, stage, loop, extra? }, state) → 一份 JSON 快照;作品自己的數字(extra、目前啟用的世界的 monitor())放在快照的 extra 下
cleanExtracleanExtra(x) → 把作品的數字整理成 JSON 帶得走的樣子(每個欄位是數字、字串、布林、null 或 { v, min, max, warn }),沒有任何欄位時回傳 null
伺服器node packages/monitor/server.js [port=7457]:後台頁面在 /,另有 /health

見演出控制。

@openav/sync#

主軸 · 好幾個頁面,一場演出:主控端和它的從屬端之間的那條線,走 BroadcastChannel 或房間中繼。從屬端的時間軸用 timeline.follow() 去追主控端。

匯出簽章
createSynccreateSync({ role, channel, url, timeline, score, follow, extra, state, hz, info, accept, onFrame, onState, onGap, id, now, transport }) → SyncLeader 或 SyncFollower;從屬端的時間軸會被接上去追它。每個影格在 timeline.advance(dt) 之後呼叫 sync.frame();sync.close() 放手
SyncLeadernew SyncLeader({ timeline, transport, id, cut, extra, state, hz, now, onHello }) · frame() · sendState(to?) · status() · monitor() · close()
SyncFollowernew SyncFollower({ transport, id, now, timeline, info, accept, onFrame, onState, onGap, resync = true, helloEvery = 1000, takeoverAfter = 1500, resyncAfter = 1000 }) · latest()(timeline.follow() 的來源)· hello(reason) · frame() · status() · monitor() · close()
傳輸BroadcastTransport({ channel }) · RelayTransport({ url, room, role, id }) · createTransport({ role, channel, url, id }):每一個都是 { send(msg), onMessage(cb), onOpen(cb), open, close() },送的是 JSON
SYNC_VERSION1,每則訊息的 v

訊息有 frame(主控端送給從屬端,每一幀)、hello(從屬端送給主控端)和 state(主控端送給某一個從屬端);作品自己的資料放在 extra。見演出控制。

@openav/relay#

手機 · 以房間為範圍的 WebSocket 中繼(伺服器),以及它的瀏覽器用戶端。

匯出簽章
RelayClientnew RelayClient({ role, room, id, url, batchHz = 30, resendMs = 1000, onStatus, onSignal, onFeedback, onConfig, onSync }) · connect() · close() · set(name, value) · send(name, value, pulse, extra) · feedback(name, value) · config(key, data) · sync(msg) · status、latency、peers;role 是 controller、runner、monitor、leader 或 follower
訊號輔助函式bindSignals(client, signals, { alias = 'any' }) · fileSignal(signals, name, value, { pulse }) · signalMeta(name, { pulse }) · aliasOf(name) · normalizeValue(name, value) · deviceId()
@openav/relay/serverattachRelay(httpServer, { path = '/relay', log, heartbeatMs = 20000, maxMessageChars = 262144, maxBytes = 1048576 }) → { hub, close() }。單獨執行用 node packages/relay/server.js [port=7458]
MidiLink(link.js)new MidiLink({ url, room, delay = 0, onMessages(list, from), onStatus }) · connect() · send(bytes, whenMs) · info() → { state, peers, rtt, trip, diff, lead, late, sent, received } · close();LinkTiming:同一個房間的頁面之間傳 MIDI,在送出那頁響的那一刻演奏(和 Strudel 一起用)

見手機、中繼與控制面板。

@openav/surface#

手機 · 類似 TouchOSC 的控制元件、版面 JSON、主題,以及 autoSurface(params)。

匯出簽章
Surfacenew Surface(el, { layout, sink(name, value, info), haptics = true, tabs = true, orientation, onPage }) · setLayout(layout) · setPage(id) · feedback(name, value) · widget(page, id) · dispose()
signalSinksignalSink(signals) → 一個寫進本機 Signals 的 sink
auto(自動產生)autoSurface(params, { perPage, style, pairs, meters, smooth, title }) → { layout, routes, bindings } · feedbackFor(state, bindings) · routesFromLayout(layout, params) · widgetTypeFor(param)
layout(版面)validateLayout、normalizeLayout、resolvePage、autoArrange、signalNames、DEFAULT_SIZE、WIDGET_TYPES、planKeyboard
平台與主題lockViewport、keepAwake、toggleFullscreen、canFullscreen、haptic、injectTheme、THEME_VARS、COLOR_NAMES、WIDGET_CLASSES
js
import { Surface, autoSurface, signalSink } from '@openav/surface';
const { layout, routes } = autoSurface(world.params);
new Surface(document.querySelector('#panel'), { layout, sink: signalSink(signals) });
routes.forEach((r) => mapper.addRoute(r));

見手機、中繼與控制面板。

@openav/remote#

手機 · 手機/iPad 上的 app,以及演出端的轉接器。

匯出簽章
mountRemotemountRemote(el, { room, relayUrl, surfaceUrl, metaUrl }) → 手機 app(/packages/remote/index.html 呼叫的就是它)
PhoneSensorsnew PhoneSensors({ set, send }, { onKnock, onSample, notify }) · start()(要從觸控事件呼叫)· stop() · calibrate() · setCamera(on) · denied
localSensorslocalSensors(signals, { prefix = 'phone/local/', alias = 'any' }) → PhoneSensors
attachTouchPadattachTouchPad(el, io, { onMove, onEnd })
@openav/remote/hostmountRemoteHost({ signals, params, mapper, world, room, auto, surface, feedbackHz = 10, url, mode, controllers }) → host 物件 · mountJoinCard(parent, host)(網址、QR code、狀態)
@openav/remote/relay-pickpickRelay({ hostname, search, declared, storage }) → { mode: 'local'|'public'|'custom'|'off', url, room, shared } · isLocalHost(h) · PUBLIC_RELAY · phoneUrl({ base, room, relay })
@openav/remote/qrqrSvg(text, { ecc = 'M', margin = 2, scale }) → <svg> 字串 · qrMatrix(text, { ecc }) → { version, size, mask, rows }(byte 模式,版本 1–10)

見手機、中繼與控制面板。

@openav/mcp#

膠水 · 給 AI 代理用的零相依 MCP 伺服器,走 stdio:node packages/mcp/server.js。工具和引數見給 AI 代理。

給 AI 代理#

16原始檔: docs/zh/agents.md

世界就是一段畫出畫面的程式碼,而程式代理很會寫程式碼。人描述一場表演(「一個遇到和諧和弦就綻放的水母世界」),代理寫出這個世界,放進已經處理好 MIDI、映射、時間軸、控台和後台的外殼裡。代理要把這件事做好,需要知道的東西都在這一章。

兩條規則#

  1. 連續控制一律走參數,離散事件可以用訊號。 不要在 update() 裡用 signals.get(…) 讀連續變化的東西。宣告一個參數,讓路由把訊號接過去。
  2. 外殼永遠不知道作品。 不要為了讓某一個範例好看,去改 packages/*。改框架,就要讓每一件作品都變好。

背後的道理寫在核心概念。

從 AGENTS.md 開始#

repo 根目錄的 AGENTS.md 就是任務簡報:框架是什麼、兩條規則、怎麼建立新作品、怎麼驗證改動,以及各項慣例。慣例包括原生 ESM + JSDoc、沒有建置步驟、沒有執行期相依套件、訊號名稱用路徑風格並以 signals.define 宣告,還有註解要寫演出上的考量(為什麼這顆旋鈕這樣才順手),不用解釋語法。

MCP 伺服器#

repo 內附一個 Model Context Protocol(MCP,讓 AI 工具呼叫外部功能的標準協定)伺服器:packages/mcp/server.js,零相依,在 stdio 上跑 JSON-RPC 2.0,一行一則 JSON 訊息。在 repo 裡打開 Claude Code,它會自動從 .mcp.json 讀到這個伺服器。其他客戶端這樣設定:

json
{
  "mcpServers": {
    "openav": {
      "command": "node",
      "args": ["/path/to/open-audiovisual/packages/mcp/server.js"]
    }
  }
}

它回應 initialize、tools/list 和 tools/call。initialize 回報伺服器名稱 openav、版本 0.1.0,協定版本照客戶端給的回送,客戶端沒給就用 2024-11-05。結果包成單一個文字項目回傳,物件會編碼成 JSON。呼叫失敗時,回傳代碼 −32000 的 JSON-RPC 錯誤,附一段訊息。

工具引數回傳
list_examples無[{ dir, title, summary }]:每個範例的資料夾、它 index.html 的 <title>,以及它 main.js 的第一行註解
read_docdoc(必填):architecture、writing-a-world、signals、show-control、roadmap、agents、readmeMarkdown 文字。agents 是 AGENTS.md,readme 是 README,其他的是 docs/<name>.md
scaffold_worldslug(必填,kebab-case)、donor(預設 01-hello-particles){ created, next_steps }。把 examples/<donor>/ 的每個檔案複製到 examples/<next number>-<slug>/
run_checks無執行 node --test tests/*.test.js(逾時 60 秒)得到的 { pass, fail, ok },或是附上失敗那幾行的 { ok: false, output }
list_controllers無{ count, controllers: [{ id, short, name, maker, kind, controls, unverified, url }], imported: […] }:每一台內建的 MIDI 控制器設定檔、控制項組成({ knob: 8, pad: 8, keys: 25 })、還標著未確認的數量,以及詳細頁 https://openaudiovisual.com/controllers/<id>/
read_profileid(必填):設定檔 id 或它的 short{ id, url, unverified, profile, mapping }:內建的設定檔 JSON(有的話包含 sysex、palette、verifications,每個控制項另有 evidence:hardware、source 或 unconfirmed),加上一份讀得懂的 MIDI 對照(控制項、型態、CC 74, ch 1、訊號 midi/<short>/<id>、是否確認)
validate_profileprofile(必填):物件或 JSON 字串{ ok, problems, conflicts }:validateProfile 找到的問題,加上和內建設定檔的衝突(同 id、同 short、match.ports 重疊)
scaffold_profilemaker、model、controls(都必填):[{ type, count, from? }]{ profile, problems, unverified, next_steps }:一份能過 validateProfile 的骨架,每個數字都是佔位值、標 "verified": false,附上「找出處、登記」的下一步。不會寫任何檔案

適合給 scaffold_world 當底的範例:01-hello-particles(最精簡的 2D canvas)、02-chord-garden(和弦驅動)、03-pose-field(鏡頭、手)、05-prebiotic-flake(p5 加聲音)。先 read_doc agents,再 read_doc writing-a-world。

llms.txt 與 llms-full.txt#

  • /llms.txt 是 llmstxt.org 格式的簡短索引:這是什麼、核心概念、怎麼開始、每一份文件和每一個範例。
  • /llms-full.txt 把 README、AGENTS.md 和所有文件合成一個檔,給喜歡一次讀完的代理。
  • 這本手冊在 /docs/ 是純 HTML(繁體中文版在 /zh/docs/),不開 JavaScript 也讀得到每一個字。每一節都有固定的錨點,例如 /docs/#mapping-curves。

create-world 技能#

.claude/skills/create-world/SKILL.md 是一個 Claude Code 技能,把一段描述變成可以執行的範例。它的步驟:抽出輸入、3 到 6 個可演奏的參數、事件和幕 → 複製一個當底的範例 → 寫世界 → 把組裝接起來 → 在瀏覽器裡驗證 → 交回網址、參數清單、場景清單,以及世界會反應的訊號。

探查執行中的演出#

每個用 createShow() 做出來的演出,都會把 window.openav 設成整個演出物件,所以操作瀏覽器的代理可以檢查它、操控它:

js
openav.signals.list()                                   // every signal, its value and range
openav.params.resolve(openav.timeline.state())          // the current param values
openav.signals.pulse('midi/note/on', { note: 60, vel: 0.8, ch: 1 });   // play a note
openav.timeline.seek(40); openav.timeline.play();       // jump to a scene and play
openav.mapper.routes                                    // the wiring

一段可以直接貼上的提示詞#

text
Clone https://github.com/frank890417/open-audiovisual and read AGENTS.md first.
Run `node serve.js` and open http://localhost:8080/examples/01-hello-particles/ to see the smallest complete show.
Create examples/27-<name>/ by copying 01-hello-particles (or call the openav MCP tool scaffold_world), then write a World in its main.js for this piece:

  <describe the performance, e.g. "a jellyfish world that blooms on consonant chords">

Rules from AGENTS.md: continuous control goes through params, and the mapper routes signals to them. Never edit packages/* to make one example look right.
Done means: npm test passes, and the new example loads with zero console errors.

交回之前#

  • npm test 通過(或 run_checks 回報 ok)。
  • 範例載入時,主控台零錯誤。ws://…:7457 的連線被拒(因為沒有開後台監看)是預期中的。
  • 不接硬體,用螢幕鋼琴或電腦鍵盤彈,它也有反應。
  • 按 Space 播放時間軸,畫面裡有東西隨時間變化。
  • 回報網址、參數(哪些該接到旋鈕)、場景,以及世界在聽的訊號。

實驗室整合("lab" 欄位)#

17原始檔: docs/zh/lab-integration.md

cheyuwu-lab 用一般的 <script> 頁面執行作品(sketch),所以它會把需要的每個 OAV 套件,各打包成一份 classic script。實驗室的產生器(tools/lab-dev/build-modules.mjs)會掃描 packages/*/package.json,替每個宣告了 "lab" 欄位的套件建置模組,沒有寫死的清單。這個欄位通常是一個物件,一個套件要產出好幾個模組時,就寫成陣列。沒有宣告,就沒有模組。

key意義
module輸出名稱,產生 runtime/modules/<module>.js(小寫英文、數字、-)
kind"build"(預設,打包程式碼)或 "declare"(只宣告一個由實驗室自己實作的模組)
files要打包的原始檔,路徑相對於 packages/。檔案之間的相對 import 會解析好,JSON import 直接內嵌
exports掛在 window.OpenAV 上的名稱
wire選用的檔案(路徑相對於套件資料夾),在模組的作用域裡執行,lab 就是 window.lab。它負責把套件接上 lab.signals/lab.params
autowire一句話說明接線做了什麼(會寫進實驗室的 oav-manifest.json)
remoteTab選用的 {id, label, icon, entry}:在手機的 /remote app 加一個分頁
since版本或月份

規則:只用相對 import,不能有執行期相依套件,OAV 本身沒有建置步驟。產生器是冪等的(重跑幾次結果都一樣),並有 --check 模式(exit 3 表示 OAV 有新東西需要重新產生)。

單一真實來源:控制器與輸入都住在這裡#

2026-10-03 決定:實驗室用到的每一個控制器與輸入模組,都寫在 OAV 裡,只透過參照進到實驗室:

  • 產生的:由 "lab" 宣告產生的 runtime/modules/<module>.js(檔頭是 // GENERATED by tools/lab-dev/build-modules.mjs)。
  • 原樣提供的:實驗室的開發伺服器從 packages/remote/index.html 提供 /remote,並從這個 repo 提供 /oav/packages/*。

範圍包括:訊息格式(relay/signals.js:signalMeta、fileSignal、力度正規化)、虛擬 Web MIDI(midi/virtual-access.js)、控制器設定檔與面板(packages/midi)、手機頁面(感測 · 琴鍵 · 控制台 · MIDI:packages/remote、packages/surface、packages/keys)、作品執行頁本身的手機感測器(localSensors,實驗室模組 motion)、音訊、聲音、映射和 OSC(OSC 橋接是 packages/osc/bridges/osc-bridge.js)。要改哪一個,就在這裡改、在這裡測、推上 main,實驗室會重新產生(每晚跑的 tools/oav-sync/sync.sh,或手動執行 node tools/lab-dev/build-modules.mjs)。不要去改實驗室裡的那份副本。

實驗室不准長出第二份副本。它的關卡(node tools/lab-dev/modules-gate.mjs,同時是一項測試,也是 npm run deploy 的第一步)遇到兩種情況會失敗:某個 runtime/modules/*.js 沒有 GENERATED 檔頭(一份簡短、每一項都附理由的允許清單除外,目前是空的),或 runtime/modules/ 裡有子資料夾(手動複製進來的套件)。

留在實驗室的,只有薄薄一層宿主程式:必須在作品載入前就存在、或只認得實驗室自家頁面的程式碼。也就是 runtime/lab.js(lab 物件、它的中繼 socket,以及把 navigator.requestMIDIAccess 換成「延遲載入產生出來的 midi 模組」的那幾行)、/remote 的房間選擇器(runtime/remote-room.js:目前開著哪些實驗室作品)和錄製面板(runtime/rec-remote.js:實驗室自己的擷取/錄製 API),還有開發伺服器的中繼與路由。新種類的控制器或輸入,絕不從那裡開始寫。

疑難排解#

18原始檔: docs/zh/troubleshooting.md

這些都是排練和寫程式時真的遇過的問題,附上解法。

瀏覽器主控台出現 ws://…:7457 錯誤#

每個用 createShow() 做的演出,都會試著把資料串流到 ws://<the page's host>:7457 的後台監看。監看伺服器沒在跑時,瀏覽器會記下被拒絕的連線。這是預期中的,也無害:頁面會重試,間隔從大約 5 秒拉長到 30 秒,不會一直洗版。想讓它消失,就把監看伺服器跑起來:

bash
npm run monitor          # node packages/monitor/server.js

用 https 開的頁面(openaudiovisual.com、https 通道)不會去連:瀏覽器在 https 頁面上會擋掉 ws://,公開的網站旁邊也沒有監看伺服器。如果你的監看伺服器架在 TLS 後面,就自己把位址傳進去:createShow({ monitor: { url: 'wss://…' } }),自己組裝的演出則是 new MonitorFeed({ url: 'wss://…' })。完全不該去找監看伺服器的機器(沒有後台的演出電腦)就寫 createShow({ monitor: false }):不會建立推送、頁面也不開任何 socket,所以什麼都不會記。

Chrome 跳出「區域網路」或「這台裝置上的應用程式」的詢問#

Chrome 的 Local Network Access(區域網路存取)檢查,會在公開的 https 頁面要連你自己的電腦或網路時,先跳出權限詢問;從你自己這台機器提供的頁面不在範圍內(Chrome 部落格)。依 Chrome 版本,它管的範圍是(查證於 2026-10-15):

  • Chrome 142:fetch 請求(Chrome 部落格)。
  • Chrome 145:分成兩種權限,一種管區域網路,一種管這台裝置本身,也就是 loopback(Chrome Platform Status)。
  • Chrome 147:WebSocket 和 WebTransport 連線也管了(Chrome Platform Status)。
  • Chrome 154:new WebSocket(url, { targetAddressSpace }) 讓頁面說明它預期連的是哪一種位址(Chrome Platform Status)。

演出跑在 openaudiovisual.com 或別的 https 網站上時,我們有三樣東西會去連你的電腦:OSC 橋接(OscOut 送到 http://127.0.0.1:7456)、後台監看(ws://127.0.0.1:7457)和 Leap 橋接。第一次 Chrome 會問。選了「封鎖」,連線就失敗,主控台會出現 net::ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECKS(在 Chrome 154 上看到的,見 Leap 套件說明)。

怎麼辦:

  • 按允許。如果已經封鎖了,打開這個頁面的網站設定(網址列左邊的圖示),重新允許,再重新載入。
  • 或者從你自己的電腦打開頁面:node serve.js,然後開 http://localhost:8080/…。那個頁面不是公開網站,Chrome 不會問。排練或教 OAV → OSC → TouchDesigner 這條路,這是最穩的做法。
  • 在 <iframe> 裡,跨網域的框架要加 allow="loopback-network";同網域的框架會繼承;加了 sandbox 的框架拿不到(在 Chrome 154 上驗證過,見 Leap 套件說明)。
  • 裝置體檢有一顆按鈕,會試連橋接和後台監看,告訴你哪一個有回應。你按了才會連。

手機加入卡片顯示「relay offline」#

在你自己的電腦上,手機中繼住在 serve.js 裡(/relay)。所以頁面如果是從檔案、或從不是 node serve.js 的伺服器打開的,卡片就會寫「relay offline」:請用 node serve.js 跑,再從那裡打開。

在靜態主機(openaudiovisual.com、GitHub Pages)上,演出改用公開中繼,卡片會寫 relay ok · … · public relay,並附 QR code。如果寫的是 can't reach the relay (wss://remote.cheyuwu.com/relay) — retrying:

  • 網路擋了 WebSocket(有些學校和辦公室的 Wi-Fi 會):換成手機熱點,或在跟手機同一個網路的筆電上跑 node serve.js;
  • 公開中繼忙線或停了:它限制每個位址同時 24 條連線、每分鐘 30 次新連線,一整間教室躲在同一台路由器後面可能就撞到。自己跑一個(node packages/relay/server.js),打開演出時加上 ?relay=wss://your.host/relay;
  • 網址裡有 ?relay=off,遙控被關掉了(這時不會畫卡片)。

手機要開的是 QR code 裡的連結,它帶著房間和中繼。手機顯示已連線卻沒反應的話,檢查兩邊的 #room 是不是同一個,以及電腦上的頁面有沒有重新載入成新房間(房間是每個瀏覽器各記一個,換瀏覽器或用無痕視窗會得到另一間)。

看不到任何 MIDI 裝置#

先跑一次裝置體檢,它會告訴你這個瀏覽器到底有沒有 Web MIDI。

  • 請用 Chrome 或 Edge。Safari 沒有 Web MIDI(WebKit bug 107250,至今還開著),Firefox 要先裝它的網站權限附加元件才有(Firefox 108)。詳見用哪個瀏覽器。
  • 瀏覽器詢問時,允許 MIDI。從 Chrome 124 起,任何 MIDI 的使用都會問(Chrome 部落格)。權限依網站分開:在 localhost:8080 允許了,不代表 localhost:3000 也允許。
  • 裝置在頁面載入之後才接上:它應該會自己出現。沒出現的話,重新載入頁面。
  • 檢查 L1 · Input(輸入)面板:沒勾選的裝置是靜音的。
  • 可能有別的程式獨占了這個埠(Windows 上有些 DAW 和驅動程式會這樣)。把它關掉。

聽不到 IAC 匯流排上的 DAW#

Midi 引擎預設略過名稱含有 IAC 的所有輸入(filterOut: 'IAC'),不然演出透過 macOS 的 IAC 匯流排送出 MIDI,又會聽到自己的輸出,繞成迴圈。createShow() 用的就是這個預設。要透過 IAC 接收 DAW 送來的訊息,就關掉內建的引擎,自己建一個:

js
import { Midi } from '@openav/midi';

const show = await createShow({ world, modules: { midi: false } });
const midi = new Midi({ signals: show.signals, filterOut: null });   // or a narrower regex
await midi.enable();

你的引擎發出的是同一組訊號,所以路由和世界都不用改。(控台的裝置清單和 MIDI 儀表,只跟著 createShow() 建立的那個引擎走。)不要把 MIDI 送到你正在聽的同一條 IAC 匯流排。

另外有第二道防線,不用設定:任何輸入上,在 40 毫秒內收到一則和引擎剛送出的完全相同的訊息,就當作回音丟掉(new Midi({ echoWindow }),0 就關掉,midi.echoDropped 會計數)。

線被拔掉之後,DAW 就沒聲音了#

現在不會了。輸出埠被拔掉時,Midi 會換到次佳的可用埠,在 MIDI 紀錄和瀏覽器 console 各印一行(MIDI out: switched to "…" ("…" was unplugged)),L1 · Input 面板的 MIDI out → 那一列也會跟著變。你選的那個埠重新插上,輸出就換回去。如果那一行寫的是 no output left,就是現在什麼都沒插:訊息會被丟掉,直到有埠出現。用 midi.selectOutput(name)(或 enable(name))選好你的埠,換回來的就是它。再加上 new Midi({ prefer: ['IAC'] }) 指定誰先頂替。

接兩台控制器時,一條路由對兩台都有反應#

接兩個以上的 MIDI 輸入時,每台裝置會用自己的名稱(midi/<slug>/cc/74)發出訊號,同時也用共用的舊名稱(midi/cc/74)發出。接在 midi/cc/74 上的路由聽得到每一台裝置,把它的 source 改成那台裝置專屬的名稱就好。各裝置的 slug 會顯示在 L1 · Input 面板。

電腦鍵盤按了沒反應#

先勾選鋼琴上方的 keyboard(電腦鍵盤擷取)。擷取預設是關的,這樣打字才不會跟控台的快捷鍵打架。勾選之後,A W S E D F T G Y H U J K O L P ; 可以彈奏,Z/X 切換八度。

keyboard 勾著的時候,字母鍵歸鋼琴,所以控台的 R(重設)、T(提詞機)、F(全螢幕)都沒作用:T 和 F 本來就是琴鍵,而且你正在彈的時候,不小心按到 R 不該把整場演出倒帶。Space、方向鍵和 Esc 仍然有效,按 Esc 就離開擷取。

Learn 綁錯了訊號#

Learn 綁定的是第一個移動超過自身範圍 5% 的訊號,或第一個出現的脈衝(不分種類)。模擬演奏者和鼓機一直在送脈衝。先取消勾選 simulate performance(模擬演奏),停掉鼓機,再點一次 learn。用 L2 · Mapping(映射)面板裡的 ✕ 移除綁錯的路由。

時間軸不再推動某個參數#

碰過的滑桿或有映射的訊號會覆寫參數,而覆寫會黏住:樂譜讓位給人。用參數旁的 ✕ 清掉(或呼叫 show.params.clearOverride(key),要全部清掉就用 clearAllOverrides())。有平滑的路由只要訊號來過,就會一直寫入,就算已經靜音也一樣。要把參數交還給時間軸,就移除那條路由。詳見覆寫與時間軸。

在程式碼裡改了路由,卻什麼都沒變#

映射器把昨天的路由存在 localStorage,而儲存的 source → target 組合會蓋過程式碼裡宣告的那一條(新的組合仍然會加進來)。清掉設定檔,或在開發期間傳入 profile: false:

js
localStorage.removeItem('openav.map.<world name>');

接到 sound/cutoff 的路由只在 0 和 1 之間動#

outMin/outMax 的預設值,是路由加入當下目標參數的範圍。在 createShow() 裡,宣告的路由加入得比聲音引擎註冊 sound/* 參數還早,所以要明確給出範圍:{ source: 'midi/cc/74', target: 'sound/cutoff', outMin: 100, outMax: 8000 }。

鏡頭或麥克風啟動不了#

  • 頁面必須是安全環境(secure context):http://localhost 或 https://。用一般 http:// 連區域網路位址(http://192.168.1.20:8080)會被擋下來。
  • 🎤 mic、🖐 hands 和 🕺 body 按鈕要自己點,它們都不會自動啟動。按鈕顯示 ✗ retry 代表啟動失敗,原因印在瀏覽器的主控台。
  • 在 macOS 上,瀏覽器本身要在「系統設定 → 隱私權與安全性」裡取得相機和麥克風的權限。
  • 手部和身體追蹤第一次啟動時,會從 jsDelivr 和 Google 的儲存空間載入 MediaPipe 和它的模型。離線時無法啟動。

沒有聲音#

瀏覽器要點一下才會開始播放音訊。在 L4 · Output — sound(聲音輸出)面板按 🔊 enable sound(開啟聲音)。Tone.js 引擎在那一刻才從 jsDelivr 載入,所以第一次需要網路連線。第一次選鋼琴時,要載入大約 2 MB 的取樣,選單會顯示進度,鋼琴準備好之前,會繼續用前一個樂器彈。鼓機的鼓組,是勾選 drum machine(鼓機)之後、打下第一拍時才啟動。

加了那一行的 p5.js 草圖不對勁#

oav-p5 會把出了什麼事寫在畫面上:🎹 旁邊一張卡片,用瀏覽器的語言寫發生什麼、為什麼、按哪裡(出狀況的時候)。🎹 → 🩺 把版本、麥克風、MIDI、聲音、鼓機和接線放在同一張卡上,問人的時候截這張圖。常見的幾種:

  • 出現 knob1 is not defined:那一行沒載到(離線,或網址打錯)。它要放在草圖最前面,setup() 的上面。
  • 沒有聲音:瀏覽器要先點過頁面才出聲,按 MIDI 鍵盤上的鍵不算。點一下畫布,在那之前 🎹 按鈕上的 🔊 是黃色的。
  • 接藍牙喇叭時鼓慢半拍(0.15 到 0.25 秒):?oav_drumlatency=200 用毫秒手動設定延遲。
  • 錄出來的檔是 WebM:Firefox 和舊版 Chrome 寫不出 MP4,Instagram 不收 WebM。改用 Chrome 126 以後的版本、Edge 或 Safari 錄。
  • 草圖嵌進別的網頁,麥克風一直是 0:那個 <iframe> 要加 allow="microphone"(要接實體控制器再加 allow="midi")。

Strudel 收不到 OAV Virtual MIDI#

OAV 比 Strudel 的 midin() 晚載入,midin('OAV Virtual MIDI') 就收不到東西、也不報錯。把 await import('https://openaudiovisual.com/p5/oav-p5.js') 放進 Strudel 的 settings → prebake(網址用單引號),按 save 再重新整理:prebake 會在你的程式之前跑。在那之前 🩺 會寫「沒有程式向 OAV Virtual MIDI 要過 MIDI」。詳見和 Strudel 一起用。

在 iPhone 上,手機的傾斜和敲擊都沒作用#

iOS 只把動作感測器開放給 https:// 頁面,而且要先點一下「開始」。在區域網路上用一般 http:// 連線時,觸控、琴鍵和控制面板仍然能用。要用感測器,就透過 HTTPS 通道連到 serve.js。如果曾經拒絕過權限,iOS 會記住,要到「設定 → Safari → 動作與方向取用」改回來,再重新載入。

部署之後,網站還在跑舊的程式碼#

GitHub Pages 讓瀏覽器把 JavaScript 快取好幾個小時,HTML 卻幾分鐘就過期,所以訪客可能拿到新的 HTML,配上舊的模組。部署前執行 node tools/stamp-version.mjs:它會在範例、套件和首頁的模組網址後面加上 ?v=<commit>。在本機不會發生這種事:serve.js 會送出 Cache-Control: no-store。

視窗退到背景時,演出變慢#

瀏覽器會在隱藏的分頁暫停 requestAnimationFrame。這時 Loop 改由 Web Worker 帶著,以大約每秒 15 格繼續跑,所以時間軸、映射的訊號和後台資料流都不會停,只是畫面更新變慢。投影視窗要一直留在畫面上,放在它自己的螢幕,開全螢幕(F)。

用到 CDN 的範例,連網時能跑,離線就不行#

p5(範例 05、06)、Tone.js(聲音)、MediaPipe(手、身體)和 WebToe app(範例 04)都從網路載入。到離線的場地演出,先把它們下載下來,再把 script 標籤、import map 或模組選項(toneEngine({ cdn })、webtoeWorld({ app }))指到本機的副本。

連接埠已經被佔用#

node serve.js 8081 會改用另一個埠,OSC 橋接也接受埠號參數:node packages/osc/bridges/osc-bridge.js 7470(再用 new OscOut('http://127.0.0.1:7470'))。後台監看是例外:用 createShow() 做的頁面,除非你另外指定,否則會串流到自己主機的 7457 埠,所以要把這個埠空出來,或用 createShow({ monitor: { url: 'ws://host:7460' } }) 指到別處(自己組裝的演出則是 new MonitorFeed({ url: 'ws://host:7460' })),再用 node packages/monitor/server.js 7460 啟動中繼。

路線圖#

19原始檔: docs/zh/roadmap.md

指導原則:真實演出要求過的功能,框架才長。(核心就是這樣來的:這裡的每個模組,都先撐過一場真正的演出,才整理成通用的形式。)

v0.x — 底盤(現在)#

  • 四層:輸入(midi/audio/chord/pose)→ 映射 → 世界 → 輸出
  • 時間軸:場景、負的待命時間、cue 掛鉤
  • 導演控台+演出模式
  • 後台監看(零相依的 WS 中繼,支援區域網路裡的裝置)
  • OSC 橋接、MIDI 輸出(走同一個看得到的出口,附 panic)
  • 所有純邏輯都有測試(和弦、時間軸、映射、參數)
  • 映射設定檔的匯入/匯出介面(JSON 檔案、拖進頁面、?map=<網址>,每個世界各記一份)
  • 範例:由現場樂器(麥克風)驅動、隨聲音反應的世界,06-cylinder-earth
  • 鼓機,送出的訊號跟分析器的長得一樣(@openav/drums)
  • 螢幕上的 MIDI 控制器,跟著真實硬體同步動作(@openav/midi,範例 09)
  • 文件網站:openaudiovisual.com/docs
  • oav-p5:任何 p5.js 草圖加一行,就有控制器、手機、麥克風、聲音、能用一行字寫節奏的鼓機、小節與 cue、錄影,版本號自己算(更新紀錄)
  • 一行節奏:TidalCycles/Strudel 式的 mini-notation(@openav/pattern)
  • 像 TouchDesigner 的 CHOP 那樣處理隨時間變的數值:lag、包絡、速度、彈簧、trail(@openav/chop)
  • 和 Strudel 並排:程式送進 OAV Virtual MIDI 的音、外部 MIDI 時鐘、link=房間名 跨分頁也跨電腦(和 Strudel 一起用)
  • 整場的 automation 在控台上攤成曲線、以總譜的段落為單位寫曲線、automation 存成 JSON 再讀回來、時間軸錨定在牆上的時鐘(演出控制)
  • 會在時間軸上微調、或等你轉到位才接手的對應,用完把參數還回去(@openav/mapping)
  • 好幾個頁面演同一場:一個主控和它的從屬端,同一個瀏覽器或跨機器(@openav/sync)
  • 整個框架有版本號,和一個永遠不變的網址。一個檔就是一場演出,不用 clone(固定一個版本)
  • 用它做的:跑在它上面的作品,每一筆都是作者自己加的

讓這一層不用再有人重做#

目標是:在網頁上做一場演出,從這裡開始,就像架網站從一台別人已經在顧的伺服器開始。一層東西要做到這樣,得讓人不用問就能蓋在上面。需要的東西,和每一項現在的位置:

項目現在有的接下來
可以依賴的版本0.9.0、固定的網址、更新紀錄1.0:世界的約定、訊號名稱和設定檔格式,沒有換主版本就不再變
不用 repo 的入口一個檔加一個 import控制器頁面和手機遙控也有一樣的入口
別人讀得懂的格式附 JSON Schema 的控制器設定檔、匯出成 QLC+ 與 Mixxx、對應檔、總譜每種格式有自己的版本號。設定檔格式成為其他工具也採用的格式
信得過的控制器55 份設定檔,每個數字都有出處,還有一頁能用手驗實機第一批在實機上驗過的設定檔,更多來自手上有那台的人
現場的食譜OSC 送到 TouchDesigner、燈光與空間音訊畫面送進 TouchDesigner、OBS 和投影機。場地清單(展示用的 iPad、沒有網路)
證明它出身的那幾場演出用它做的上有別人的作品
發問的地方issue、要一台控制器的表單、登記作品的表單幾天內有回音

v1.x — 演出長大#

  • 觀眾裝置輸入:經典控制器已經上線(@openav/relay、@openav/surface、@openav/remote):零相依的房間伺服器、phone/{id}/* 感測器、一組類似 TouchOSC 的控制元件、版面 JSON、autoSurface(params)、回饋到手機。接下來:
    • 加入卡片上的 QR code(@openav/remote/qr,約 150 行、零相依的編碼器):在靜態主機上,演出改用公開中繼加隨機房間,所以 openaudiovisual.com 上的範例也能接手機
    • 實驗性的控制面板:手勢/物理控制元件、多人共用的控制面板、觀眾模式(很多支手機 → 彙整成 crowd/tilt/mean 這類訊號)
    • 麥克風當作手機感測器、每台裝置各自的設定檔、版面編輯器/匯入匯出介面
  • 總譜與導演:已經上線(@openav/score):用段落長度寫成的版本、衍生版本、cue、hold、壞了只停自己的段落模組、提詞機上的 acts、總譜轉 MIDI 標記。接下來:
    • 收 MIDI clock:@openav/midi 的 MidiClock 跟著 start、stop、song position 走,oav-p5 的鼓機和 drumPhase 也跟著它(0.7)
    • 總譜跟著外部時鐘走,以及送出 clock 與 transport,讓 DAW 當總譜的主時鐘,或跟著總譜走
    • cut 裡的 clocks 表,只有哪一場演出需要引擎跑在兩條不同的時間線上才做(見總譜與導演)
    • 導演台上的總譜編輯器:拖一段的長度,看每個 cue 跟著移動
  • 訊號錄製與重播:MIDI 錄音已經上線(@openav/record:TakeRecorder、TakePlayer,.mid 可進可出;EventLog 已經能在錄影時記下任何訊號)。接下來:把完整的訊號流(手、身體、聲音分析)重播給任何一個世界。演奏者不在也能排練。存下來的不只影片,還有手勢。
  • 把 @openav/* 發布到 npm,等 1.0 說清楚哪些東西不再變(在那之前:固定一個版本),文件頁面本身也能用這套框架來演奏。
  • WebGPU 世界轉接,等 WebGPU compute 成熟,給粒子與群體代理類的世界用。

v2.x — 舞台變寬#

  • 畫面進入影像流程:先用現成的工具寫成食譜(OBS 的 Browser Source 加 NDI 輸出、TouchDesigner 的 Web Render TOP)。那些做不到、而且有演出需要的時候,才做自己的閘道(headless 瀏覽器 → NDI)。
  • 分散式演出:透過 WebRTC data channel 同步多個瀏覽器的訊號:好幾台電腦、一個訊號空間、分處各地的合奏團。時鐘的那一半已經做好了:好幾個頁面演同一場,從屬端透過 BroadcastChannel 或房間中繼追著主控端的時間軸(@openav/sync)。訊號則仍然留在收到它的那個頁面。
  • AI 代理演奏者:由 LLM 驅動的代理訂閱訊號、寫入參數,在人旁邊一起即興(來歷:《The Last Input 終局之前》裡自主行動的城市代理)。

不做的事#

  • 節點式的視覺編輯器(cables.gl 已經做得很好,我們是函式庫)
  • 自己的一套合成工具(Tone.js 是鄰居:@openav/sound 把它包在一份精簡的引擎介面約定後面,audio.input() 也接受它的 node)
  • 變成一個平台:你的演出就是你的 repo,不是我們伺服器上的一個帳號

↑ 回到頂端