文件
open-audiovisual 使用手冊
跑起來、寫作品、上台演出需要知道的事,都在這一頁。這裡寫到的 API 名稱、選項和訊號,都對照過原始碼,兩者對不上時,以程式碼為準。
19 章 · 202 節 · oav-p5 0.8 · 框架 0.9
內容以 Markdown 寫在 docs/zh/,這一頁由它產生。 GitHub ↗ · 給語言模型:/llms.txt · /llms-full.txt
簡介#
open-audiovisual(OAV)是一套在瀏覽器裡跑的 JavaScript 框架,給現場影音表演用。它只用原生的 ES module:不用建置、沒有相依套件、不用註冊帳號。把 repo clone 下來,跑一個檔案,打開一個網頁,就可以開始了。
每一場演出都要從頭重做的那一塊,由它來處理:MIDI 的底層接線、把輸入變成參數、有場景的時間軸、導演控台、給演奏者的演出模式,以及給舞台監督的後台頁面。你只要寫世界,也就是作品本身。框架的介紹、一台即時在跑的樂器,還有二十六件範例作品,都在首頁。
給誰用#
- 演奏者用 MIDI 鍵盤、麥克風、鏡頭、手機或螢幕鋼琴來彈範例,從控台操作一場演出。
- 寫程式的人大約二十行就能寫好一個世界,呼叫一次
createShow(),輸入、映射、時間軸、控台、聲音和後台就都有了。 - AI 代理先讀 AGENTS.md,接上 repo 內附的 MCP 伺服器,在一個已經能跑的底盤裡寫世界。見給 AI 代理。
四層與兩條主軸#
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。
快速開始#
三種進場方式#
挑一個最接近你手上東西的。越往下,東西越大。
- 在 p5.js 草圖裡加一行。 任何一份 p5.js 草圖(OpenProcessing、p5 編輯器、你自己的網頁)在最前面加一行,就能用 MIDI 控制器、螢幕上的控制器或手機來彈。讀 p5.js 一行接上,再玩帶著這一行的草圖: 範例 15。同一行還能出聲音、開一台能用一行字寫節奏的鼓機、聽麥克風、錄成影片,每一樣在範例裡都有一份現成的草圖(16 到 26)。
- 在網頁裡放一台控制器。
<oav-controller profile="akai-lpd8">把一台能彈的控制器放進任何網頁。讀 MIDI 控制器與嵌入,到控制器圖鑑挑你的那一台。 - 一整場演出。 一個世界加上一次
createShow()呼叫,輸入、映射、時間軸、控台、聲音和後台就一起組好。從 範例 01 開始,接著往下讀。
跑起來#
你需要 Node.js(目前任何一個版本都可以,CI 用 Node 22 跑測試)和一個瀏覽器。不用安裝任何東西:沒有 npm install,也沒有打包工具。
git clone https://github.com/frank890417/open-audiovisual.git
cd open-audiovisual
node serve.js # → http://localhost:8080serve.js 是關掉快取的靜態檔案伺服器(在舞台上跑到舊的程式碼,是一場惡夢),也在 ws://<host>:8080/relay 開好給手機用的中繼。想換連接埠,就把埠號傳進去:node serve.js 3000。這些指令也都寫成了 npm script:
| 指令 | 實際執行的是 |
|---|---|
npm start | node serve.js |
npm run monitor | node packages/monitor/server.js,後台監看,連接埠 7457 |
npm run bridge | node packages/osc/bridges/osc-bridge.js,OSC → UDP 橋接,連接埠 7456 |
npm test | node --test tests/*.test.js |
打開 http://localhost:8080/examples/01-hello-particles/。每個範例都不需要硬體就能跑。
一個檔,不用 clone#
做自己的演出不需要這個 repo。把 show.html 存下來(打開後另存網頁,或複製原始碼),用任何靜態伺服器開它所在的資料夾,再打開它:
python3 -m http.server 8080 # or any static server, or any static host這個檔是一頁加一個 import:你要改的世界,和一次 createShow() 呼叫。其他東西都從一個網址進來:
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.js | p5.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://頁面(見手機、中繼與控制面板)。
你看到的是什麼#
範例頁面分成兩部分:左邊是舞台(世界畫在這裡),右邊是側邊面板。側邊面板由上到下是:
- 鋼琴,附兩個核取方塊:keyboard(電腦鍵盤擷取)讓你用電腦鍵盤彈,simulate performance(模擬演奏)讓一位模擬演奏者自己彈,不用你動手。
- 播放控制:播放/暫停、上一個/下一個場景、重設、時鐘、目前的場景,以及一條拖曳軸,每個場景占一格。
- Layers(各層狀態):每一層現在在做什麼(每個輸入每秒幾個事件、啟用中的路由、世界和 FPS、哪些東西正從瀏覽器送出去)。
- L1 · Input(輸入):MIDI 裝置(取消勾選就把那台靜音),以及要點一下才會啟用的來源按鈕:🎤 mic(麥克風)、🖐 hands(手)、🕺 body(身體)。
- L2 · Mapping(映射):每一條路由,附一個靜音核取方塊,按 ✕ 刪除。
- L3 · Params(參數):每個參數一支推桿,按 ✕ 清除覆寫,按 learn 建立映射。
- L4 · Output — sound(輸出:聲音),演出有聲音時才會出現:按 🔊 enable sound(開啟聲音)。
- 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(),演出的其他部分就會圍著它組起來:
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,再轉一顆旋鈕。整個模型就是這樣:連續控制用參數,事件用訊號。
做一個新範例#
- 把
examples/01-hello-particles/複製成examples/<nn>-<name>/(用下一個還沒用的編號)。它的index.html已經替每個@openav/*套件寫好 import map。那些?v=後綴是快取戳記,部署前由tools/stamp-version.mjs寫進去。 - 在
main.js寫你的世界(寫一個世界)。 - 改掉
index.html裡的<title>。如果你用 p5 或其他繪圖工具,也在這裡加上 CDN 的 script 標籤。 - 打開
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…),可以自己動手戳戳看。
核心概念#
六個詞撐起整套框架:訊號、參數、路由、世界、時間軸、演出。這一章一個一個講清楚,最後講把它們綁在一起的兩條規則。
訊號#
訊號(signal)是一個有名字的數值,告訴你現在發生了什麼:一顆旋鈕的位置、房間裡的音量、手腕的高度、上一個和弦的協和度。每個輸入套件都把訊號發布到同一個登錄表(@openav/core 的 Signals),除此之外什麼都不做。訊號是輸入唯一的通用貨幣。
訊號有兩種:
| 種類 | 存放的是 | 範例 | 讀取方式 |
|---|---|---|---|
| 連續 | 目前的值,通常在 0..1 之間 | midi/cc/74 = 0.42 | signals.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 才知道怎麼縮放它:
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:
{ 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每一格畫面,每個參數都會解析成一個數字:
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)把一個訊號接到一個參數。路由就是單純的資料:
{ 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)。這一呼叫會建好訊號登錄表、參數、舞台、時間軸、映射器、你要的輸入、聲音、控台、後台資料流和畫面迴圈,然後全部回傳給你。每個範例都是一個世界加上這次呼叫,所以框架長出新模組時,每場演出只要宣告一下就能用。
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/*。改框架,就要讓每件作品都變好。換作品,就是換掉世界和它的資料,外殼留著不動。
架構#
open-audiovisual 是一套資料層框架。它的價值全在一件事:四層和兩條主軸分得乾乾淨淨,換掉其中任何一個,都不用碰到其他部分。這一章把每一層的介面約定講清楚。
畫面迴圈#
整套系統由一個 Loop(@openav/core)帶著跑。下面是 createShow() 每一格的執行順序(packages/show/index.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' }) 對整場演出做的就是這件事(自己驅動影格)。
參數解析的順序(整個設計的核心):
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)#
介面約定:把訊號接到參數的,只有它一個。路由就是資料:
{ 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 去執行負責每一段的模組(進一次、出一次,某個模組壞掉只會停用它自己)。時間軸的場景和總長都從總譜來,導演則以參數層的身分接在時間軸上:
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/*訊號。對映射器來說,它們只是多一個輸入。見手機、中繼與控制面板。
寫一個世界#
世界是整套框架裡,唯一一定要自己寫的部分。其他都是組裝。
介面#
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() 時設定:
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):
<script src="https://cdn.jsdelivr.net/npm/p5@1.9.4/lib/p5.min.js"></script>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:
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):
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 都可以。舞台只負責呼叫你的函式。
一場演出裡的多個世界#
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。演出建好之後,再把輸出用的物件加上去,每個世界都看得到:
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)接著在世界裡:
// 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) - 世界裡沒有任何地方直接讀時鐘:時間歸時間軸管
- 頁面載入時瀏覽器主控台零錯誤,只用螢幕鋼琴也跑得動
輸入#
每一種輸入只做一件事:發出訊號。用 createShow() 時,在 modules 裡打開需要的輸入就好。每一種輸入也都是普通的類別,可以單獨拿出來用。訊號的確切名稱和範圍,查訊號一覽。
| 輸入 | 套件 | modules 的 key | 預設 | 發出的訊號 |
|---|---|---|---|---|
| MIDI 硬體 | @openav/midi | midi | 開(設成 false 就關掉) | midi/… |
| 螢幕上的 MIDI 控制器 | @openav/midi | midi: { controllers } | 關 | midi/<device>/<control> |
| 螢幕鋼琴、電腦鍵盤、模擬演奏者 | @openav/keys | keys | 開(設成 false 就移除) | midi/note/on、midi/note/off |
| 鼓機 | @openav/drums | drums | 關 | drum/…,以及第 10 頻道的 midi/note/on |
| 麥克風 | @openav/audio | audio | 關 | audio/… |
| 和弦分析 | @openav/chord | chord | 關 | chord/… |
| 身體(鏡頭) | @openav/pose | pose | 關 | pose/… |
| 手(鏡頭) | @openav/pose | hands | 關 | hand/… |
| 手(Leap Motion) | @openav/leap | leap | 關 | leap/… |
| 手機與 iPad | @openav/remote | remote | 關 | 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(),單獨使用:
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)。
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 波封。
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 個半音所占的比例(「真正一層層疊上去的三度」) |
dissonanceLevel | 0 無 · 1 輕微(暴風雨的預兆)· 2 嚴重(真正的音堆) |
chordType | single、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() 的東西,都是輸入。下面把滑鼠/觸控指標當成樂器:
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、路由、手機控制面板)都不用改就能用。
映射#
在映射層,「發生了什麼」變成「它代表什麼」。把訊號接到參數的,只有 Mapper(@openav/mapping)這一個元件,它手上就只有一份路由清單。
路由#
一條路由就是一個普通物件。只有 source 和 target 是必填,其餘由 addRoute() 補上:
| 欄位 | 預設 | 意義 |
|---|---|---|
source | — | 訊號名稱,例如 midi/cc/74、hand/right/pinch/index、phone/any/tilt/x |
target | — | 參數的 key,例如 bloom、sound/cutoff |
inMin, inMax | 0, 1 | 取用訊號的哪一段,超出的值會壓在邊界上 |
outMin, outMax | 參數的 min、max | 寫進參數的範圍 |
curve | 'linear' | linear、exp、log 或 smooth |
invert | false | 在套用曲線之前,把正規化後的值翻過來(1 − x) |
smooth | 0 | 滑到新值所需的時間,單位是秒(0 = 立即到位) |
mode | (沒寫 = 'override') | 'override' 取代時間軸的值,'trim' 疊加在它上面,'pickup' 要旋鈕先碰到參數的值才接管:見微調、接管與放手 |
release | (沒寫 = 不放手) | 訊號靜止這麼多秒之後,路由放手、時間軸接回去 |
enabled | (沒寫 = 開啟) | 設成 false 就把這條路由靜音 |
id | 自動指定 | 一個數字,移除路由時用 |
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 相符的路由,都會依序跑這幾步:
- 輸入窗:
x = (value − inMin) / (inMax − inMin),限制在 0..1 之間。 - 反轉:如果有
invert,x = 1 − x。 - 曲線:
x = curve(x)。 - 縮放:
out = outMin + (outMax − outMin) · x。 - 寫入:
smooth: 0時,直接用out覆寫參數(並限制在參數的範圍內、對齊它的step)。smooth > 0時,out變成一個目標值,mapper.update(dt)每個影格把參數往它推近一點。trim路由寫的是時間軸的值加上out;pickup路由在旋鈕碰到參數之前什麼都不寫。
曲線#
| 曲線 | 公式 | 手感 |
|---|---|---|
linear | x | 手怎麼動,值就怎麼動 |
exp | x² | 起步慢、尾端快:低段可以細調 |
log | √x | 起步快、尾端慢:高段可以細調 |
smooth | x²(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 } 的函式:
const mapper = new Mapper({ signals, params, base: () => timeline.state() });
// a show made with createShow() already does this for youtimeline.state() 是還沒套用覆寫的值,而且總譜的段落模組已經套用過了,也就是沒有人碰它時參數會有的值。沒有 base 的話,映射器用參數的 def:對沒有任何自動化的參數是對的,對時間軸畫著曲線的參數就不對。base 丟出錯誤或回傳別的東西,就當作沒有,絕不會擋住演出。它要輕:trim 握著參數的每個影格都會問一次,trim 或 pickup 的旋鈕每次讀數也會再問。
trim:在時間軸上微調#
時間軸已經把整場演出畫好的作品,不該因為旋鈕轉到 0.9 就把曲線整條丟掉。trim 路由的 outMin/outMax 是偏移量的範圍,參數等於 時間軸的值 + 偏移,再夾在參數的範圍內。沒寫的話,旋鈕往兩邊各走參數範圍的一半(旋鈕在中間 = 不動):
// ±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);- 放手之後,路由要等來源再動才會接管:一直重送同一個值的來源拿不回參數;
- 它只清自己寫的。如果這段時間滑桿已經接手,就讓它留著。
// 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,各附一個核取方塊(靜音)和 ✕(移除)。用程式碼的話:
const r = show.mapper.routesFor('bloom')[0];
r.enabled = false; // mute
show.mapper.removeRoute(r.id); // remove儲存的設定檔#
映射器把路由存在 localStorage 的 openav.map.<profile> 底下。createShow() 用世界的名稱當設定檔名稱(或用 profile 選項),並且:
- 有儲存的路由就載入,沒有的話就加入宣告的
routes。 - 已經有儲存的設定檔時,宣告的路由裡
source → target組合還沒出現過的,也會補進去,所以程式碼裡新加的路由一定會出現。 - 每 3 秒存一次。
所以 learn 來的路由和你做的修改,重新載入之後都還在。反過來說:如果你在程式碼裡改了某條宣告路由的曲線或平滑,同一組 source → target 以儲存的版本為準。要從乾淨的狀態開始,就傳入 profile: false(每次載入都從程式碼讀路由,像範例 09 那樣),或刪掉儲存的設定檔:
localStorage.removeItem('openav.map.particles'); // 'particles' = the world's name要把一套接線帶到另一台電腦、或另一個世界,用對應檔(下一節)。
對應檔:匯出、匯入與分享#
L2 · Mapping 面板在「map knobs in order」下面有三個按鈕:
- ⬇ export:把目前的路由下載成
oav-map-<世界名>.json。 - ⬆ import:選一個對應檔。也可以把
.json拖進頁面任何地方。匯入會取代現有路由,新的這組馬上被記住。 - clear:移除全部路由(要點兩下)。下次載入時,世界宣告的路由會回來,跟第一次來一樣。
按鈕下面會寫最近一次匯入的結果:進來幾條、略過哪幾條、為什麼。讀不了的檔案會說明原因,而且不動任何路由。
格式#
{
"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=#
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:私密視窗或儲存被擋時什麼都不會壞,只是不會被記住。
程式裡:
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#
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 signalsonChange() 在路由變動時執行(給介面用),onLearn(route, signalName) 在 learn 綁定完成時執行。
演出控制#
把一張草稿變成一場演出,靠的是這一章的幾個部分:呼叫一次就組好的外殼、時間軸、控台、演出模式、後台監看,還有讓聲音和資料送出瀏覽器的幾種方式。
createShow#
createShow()(@openav/show)以一個世界為中心組好整場演出,再把每個部分交給你。它是 async,因為要等世界的 init 跑完。
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',
});| 選項 | 預設 | 意義 |
|---|---|---|
world | null | 要演出的世界,最先啟用 |
worlds | [] | 另外要註冊的世界(用 show.stage.activate(name) 切換) |
timeline | { total: 120 } | 給時間軸的 { total, automation, scenes } |
routes | [] | 要加進映射器的路由(映射) |
modules | {} | 要打開的輸入與輸出(見下表) |
artwork | null | { title, artist, year, note }:舞台上的一行作品署名,以及一個 <meta name="artwork"> |
hint | '' | 舞台左下角的一行 HTML |
map | 網址裡的 ?map= | 開始時載入的對應檔:同源或 https 網址。false = 忽略 ?map=(對應檔) |
profile | 世界的名稱 | 映射器儲存設定檔的名稱。false = 忽略儲存的路由(儲存的設定檔) |
onFrame | null | (dt, show) => {},每個影格執行一次,在時間軸前進之前 |
mount | 自動產生 | 要渲染進去的 { stage, side } 元素或選擇器,取代整頁版面 |
telemetry | true | 每次載入頁面送一筆匿名的 oav_show_start(見控制器章的〈使用統計〉),false 就不送 |
score | null | { cuts, cut, modules, api, midi, … }:把演出的結構寫成段落長度,由段落模組去演出。網址上的 ?cut=<id> 決定用哪個版本(總譜與導演) |
loop | 'auto' | 誰來給影格:'auto'(頁面的 requestAnimationFrame)、'manual'(你自己呼叫 show.loop.step(dt)),或 { clock, raf, maxDt, heartbeat },也就是 new Loop() 的選項(見下) |
monitor | true | 後台推送:false = 不推送(頁面不會開任何 socket),{ url, hz } = 換一個中繼位址或頻率 |
console | null | 控台的選項,也就是 mountConsole 的:{ keys, layers, signals, learnOrder };keys 用來挪動鍵盤快捷鍵 |
sync | null | 好幾個頁面演同一場:{ role: 'leader' | 'follower', channel, url, input, extra, state, follow }。一個頁面當主控端,其餘的追它的時鐘,從屬端自己不收任何輸入(見下) |
沒有 mount 時,頁面的 body 會變成兩欄的格線:一欄是舞台,一欄是 340 px 寬、放鋼琴和控台的側邊面板。
modules 的 key | 值 | 加入什麼 |
|---|---|---|
midi | 預設開啟,或 false | Midi 引擎(輸入與輸出) |
midi.controllers | true 或 { profile, profiles, open } | 一台停靠在舞台上的螢幕 MIDI 控制器、一個 🎹 按鈕和 M 鍵。網址加上 ?profile=<id> 可以指定裝置(控制器) |
keys | 預設開啟、false 或 { base, octaves, sim, capture } | 螢幕鋼琴、電腦鍵盤和模擬演奏者 |
drums | true 或 { engine, autoEnableEngine } | 鼓機 |
audio | 任何為真(truthy)的值 | 麥克風分析器(按 🎤 mic 啟動) |
chord | true 或 { window } | 對每個彈出的音做和弦分析 |
hands | true | 手部追蹤(按 🖐 hands 啟動) |
pose | true | 身體追蹤(按 🕺 body 啟動) |
remote | true 或 { room, auto, surface, feedbackHz, url } | 手機和 iPad 當控制器(手機) |
sound | true、樂器 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。
// '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)。
時間軸#
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 的參數不論寫什麼曲線都照舊守住。
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。
show.timeline.onCue((cue) => show.params.firePulse(cue.name)); // scenes: [{ …, cues: [{ name: 'flash', t: 20 }] }]錄製。 record(key, source) 把一條 lane 設為待錄。時間軸播放時,每個影格讀一次 source():回傳數字就寫進一段 take,回傳 null 表示沒人在碰,這一段就收尾。
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(換場時要觸發的燈光、音效等提示)清單,寫起來就是一個換場處理函式:
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。
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,之後再匯入這條時間軸或另一條:
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{ "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,毫秒),比較牆鐘走了多久、演出走了多少。不呼叫就什麼都不會發生:沒有錨定的時間軸從來不讀鐘。
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 optionsanchor(epoch?, opts):epoch 是演出時間 0 對應的牆鐘時刻,可以是毫秒、Date 或 ISO 字串。不給的話,第一個播放的影格就是時間 0:沒有什麼可以遲到,只計算那之後的停頓。
| 選項 | 預設 | 意義 |
|---|---|---|
mode | 'warn' | 'warn' 只計數和通知,絕不動 t。'catch-up' 把漏掉的追回來,超前時則等牆鐘 |
warnAt | 1 | 慢了幾秒時 onDrift 收到 'behind'(沒人聽就 console.warn);降到一半以下收到 'recovered' |
tolerance | 0.05 | 'catch-up':欠得比這少就不補 |
jump | 10 | 'catch-up':欠超過這麼多秒,用一次 seek 補上(cue 不會觸發,跟 seek 從不觸發 cue 一樣),不邊播邊追 |
wait | true | 'catch-up':epoch 在未來時,演出站著不動(播放中但不前進)等到那一刻 |
stall | 0.02 | 牆鐘時間比 dt 長超過這麼多秒的影格算一次停頓(只影響計數) |
now | Date.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() 就什麼都不會發生:從來不追的時間軸,行為跟以前一模一樣。
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。
| 選項 | 預設 | 意義 |
|---|---|---|
nudge | 0.05 | 追趕的時候,rate 是主控端的 rate 乘 1 ± 這個數:落後 0.3 秒的從屬端大約六秒追上,沒有人看得到跳動 |
deadband | 1/60 | 差不到一幀就不管。超過才開始推 rate,追到剩一半才放手,所以不會在邊緣上抖 |
jump | 0.5 | 差超過這麼多秒,就一次 seek(T, 'seek'):onSeek 聽得到,cue 不會觸發 |
lostAfter | 4 | 這麼多秒沒收到 frame,就當主控端不見了;Infinity 是永遠等 |
latency | 0 | frame 在路上花的秒數,數字或函式。不同機器的頁面要自己設(例如來回時間的一半) |
now | source.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 則關掉所有快捷鍵。
// 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' } },
});| 動作 | 預設 | 作用 |
|---|---|---|
play | Space | 播放/暫停(停在 hold 時:放行) |
next、prev | ArrowRight、ArrowLeft | 下一個/上一個場景(停在 hold 時,next 放行) |
reset | R | 回到開頭,並讓被停用的段落模組恢復 |
perf | T | 演出模式 |
fullscreen | F | 全螢幕 |
midi | M | 螢幕 MIDI 控制器面板 |
cancel | Escape | 結束對應精靈,或離開鍵盤鋼琴的捕捉 |
curves | C | 打開/收起曲線面板(沒有任何參數有 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 的參數,要畫的量大約和六個一樣。
它只讀時間軸和參數,所以任何演出都不用作品多說一個字就能用。
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 開成全螢幕的舞台。同一個頁面開兩個視窗,一個當控台,一個當舞台。
後台監看#
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() 的選項:
await createShow({ world, monitor: false }); // no backstage feed, no socket
await createShow({ world, monitor: { url: 'wss://stage.example.com/monitor', hz: 10 } }); // another relaymonitor: false 不會建立推送(show.monitor 是 null),頁面也不會開任何 socket。{ url, hz } 交給 MonitorFeed:一個 ws:// 或 wss:// 位址(null 會做出一個永遠不連線的推送),以及每秒送幾次快照(預設 15)。架在 TLS 後面的中繼要用 wss:// 位址,中繼本身仍然聽在你啟動它的埠(node packages/monitor/server.js 7460)。
如果演出是你手動組起來的:
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 面板裡;什麼都沒送時,面板是隱藏的。不送的演出,送出的快照跟以前完全一樣。
// 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 不同:
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 的編號。
{ 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。框架把它送到、每則一次、依序,從來不讀它。
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 輸出#
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 封包送出去。
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):
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。它跟其他輸出走同一個出口,一樣看得到。把它綁在一個摸黑也找得到的打擊墊上。每個演奏者遲早都會用到它,在這裡只要呼叫一次。
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 載入。
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/。萬一載不進來,鋼琴會改用電鋼琴彈,不會變成一片安靜。
選聲音#
可以在控台上選,也可以寫在程式裡:
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/* 完全不用改。
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>:
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 }],
});自己寫引擎#
引擎只是一個小物件,整個換掉也可以:
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() 只是圖個方便。需要自己的版面或迴圈時,就手動組裝各個部分。它做的事大致如下:
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 秒內回到演出狀態
總譜與導演#
一場演出長大之後,需要一個能跟著長大的結構。總譜(@openav/score)把演出寫成一段一段、只有「長度」的段落,導演則負責執行每一段的程式。兩者都是純邏輯、不碰 DOM。createShow() 會幫你把它們接上時間軸、控台和提詞機。
核心想法:只寫長度,不寫秒數#
把時間軸寫成一張絕對秒數的表,它就長不大。第二個場景拉長一點,後面每個場景、cue、曲線,還有程式裡的每一句 if (t > 466) 全都錯了,而且你只能在一次又一次排練裡一個一個找出來。在總譜裡你只寫每一段「多長」:
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#
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 名稱):
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#
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 的物件 |
api | enter/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 使用#
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 | 直接交給導演 |
midi | false(預設)、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() | 和 → 與 ← 一樣 |
cuts | cut 清單 |
導演台#
有總譜的時候,控台會多出這些:
- 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:
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。它預設關閉,要用才開:
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| 選項 | 預設 | 意義 |
|---|---|---|
channel | 15 | MIDI 頻道 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 標記 |
length | 0.15 | 標記音的 note-off 在幾秒之後送 |
scrub | false | 手動移動播放頭時也送標記。預設只有演出「在播放」(或 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#
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 控制器與嵌入#
open-audiovisual 把 MIDI 控制器寫成資料:每台裝置一個 JSON 檔,記下面板配置、每個控制項送出的 MIDI 訊息、LED 回饋、怎麼認出它的埠,以及每個數字出自哪一份文件。同一個檔案可以變成螢幕上能彈的控制器,接上實體裝置時跟著動,也能放進任何網頁。支援的裝置全部列在控制器頁面。
放進網頁#
<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 網址 |
layout | auto、face(照實物的樣子)或 stack(為直拿的手機重新排) |
hardware | on,或 ask 顯示一個按鈕:實體裝置會帶動螢幕上那一台 |
midi-out | 埠名稱(IAC、loopMIDI)、/正規表示式/ 或 ask:彈的東西送到這個埠 |
channel | 1–16,你的機器設在別的頻道時用 |
picker、readout、learn、follow | 裝置選單、最後一則訊息、學習按鈕、接上哪台認得的裝置就切到哪台 |
接收它的事件#
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。
不用自訂元素#
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 的地方:
<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#
- macOS:音訊 MIDI 設定 → 視窗 → 顯示 MIDI 工作室 → IAC 驅動程式 → 勾選「裝置已上線」。 Windows 11:內建的 Windows MIDI Services(2026-02-17 釋出,24H2、25H2 分批推送)讓各程式共用 MIDI 埠,並附有 loopback;微軟的公告寫明,用 Web MIDI 的網頁也能用(Windows 部落格)。我們沒有拿它跟 open-audiovisual 一起實測。舊版 Windows:安裝 loopMIDI,新增一個埠,這條路仍然可用。
<oav-controller profile="akai-lpd8" midi-out="IAC">(Windows 上填你建立的埠名,或 Windows 顯示的埠名)。- 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_start | createShow() 開始 | 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+ 輸入設定檔匯入的控制器,版面是自動產生的,每個控制項都標成未確認。
加入一台控制器#
- 從
packages/midi/profiles/複製最接近的檔案,或一個通用版面。 - 照說明書的 MIDI 實作表,寫下每個控制項的類型和訊息。
- 每一筆資料都寫上出處。還沒確認的,標上
"verified": false,再寫一句說明。"verified": true只給在實機上確認過的數字,而且要在verifications留一筆紀錄,寫明誰、哪一天、什麼韌體、作業系統和瀏覽器(沒有的話validateProfile不會過)。 validateProfile(profile)會列出所有問題,npm test會檢查每一個內建設定檔。- 用
<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 一行接上#
任何一份 p5.js 草圖(OpenProcessing、p5 編輯器、你自己的網頁)在最前面加一行,就能用 MIDI 控制器、螢幕上的控制器或手機來彈:
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 之前加一行:
<script src="https://openaudiovisual.com/p5/oav-p5.js"></script>這幾種寫法在 p5 1.x、2.x 的全域模式都能用,setup() 裡不用呼叫任何東西。帶著這一行、現在就能彈的草圖:範例 15。
速查表#
所有名稱一眼看完,照你要做的事分組:喊、敲、彈、讓數字好用。用法跟 p5 自己的名稱一樣:變數像 mouseX 那樣直接讀,函式像 keyPressed() 那樣你來寫、p5 來叫。每個名稱都連到它的參考條目。
速查表頁是同一張表單獨成頁,可以印成一張橫式 A4。
像讀滑鼠一樣讀它#
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):
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 內建)幫變數取名字、定範圍。頁面上有這一行,控制器就照宣告順序接上這些變數,不用一個一個對應:
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)」。
麥克風#
同一行也接得上麥克風,草圖讀它的方式一樣:讀變數。
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
}| 讀 | 值 |
|---|---|
micLevel | 0 到 1,聽起來多大聲:房間本身的底噪是 0,說話大約 0.4–0.6,大喊接近 1 |
bass、mid、treble | 0 到 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/。
聲音:彈什麼就聽到什麼#
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/。
鼓機#
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 | 鼓機有沒有在打 |
drumStep | 0 到 15,剛打到第幾格 |
drumBar | 1、2、3……,從 startDrums() 開始數第幾小節 |
drumBpm | 速度(格子上的滑桿也會改它) |
drumPhase | 0 到 1,這一小節走到哪,連續的、照聽到的時間算:rotate(drumPhase * TWO_PI) 一小節轉一圈 |
beatPhase | 0 到 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 版逐幀推進的鼓機。
一行節奏#
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是那個連結。
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() 把節奏畫在畫布上:
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() 開始數。宣告第幾小節要發生什麼:
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 畫出同一條曲線):
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 秒收回。第三行:旋鈕一甩,會衝過頭再彈回來停下。
| TouchDesigner | oav-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 CHOP | speed(rate) | 每秒加 rate:rotate(speed(TWO_PI)) 一秒轉一圈 |
| Spring CHOP | spring(value, stiffness, damping) | 像掛在彈簧上的東西一樣跟著走(100、6:彈兩三下;damping 20:不彈) |
| Trail CHOP | trail(value, seconds) | 最近 seconds 秒(2)的值,一個陣列,每秒 60 個,舊的在前、最新的在最後 |
| Slope CHOP | slope(value) | 每秒變化多少 |
| Count CHOP | count(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/。
錄影:畫面和聲音一起錄#
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 的箭頭函式每一格都會重讀變數:
await loadScript('https://openaudiovisual.com/p5/oav-p5.js')
osc(10, 0.1, () => knob1 * 2).out() // knob 1 sets the colour offsetosc(10, 0.1, () => 1 + micLevel * 3).out() // the microphone, asked for when this line first runsnote、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)。
細節#
- 為什麼用
prepend:p5 的友善錯誤檢查會把頁面上最後一個<script>當成你的草圖。這個檔放在最前面,就不會被誤當成你的程式。 - 為什麼非同步載入的一行就夠:p5 等到視窗的
load事件才開始全域模式,而頁面載入中插進來的 script 會讓load等它跑完,所以setup()裡就已經有knob1。 - 這一行沒載到時(沒網路、網址打錯),讀
knob1的程式會停在「knob1 is not defined」。 - 嵌到別的網站:OpenProcessing 自己的頁面允許草圖用 MIDI 和麥克風,它給的嵌入碼沒有。要讓嵌入的草圖聽實體控制器,在那個
<iframe>加上allow="midi";要它聽麥克風,加allow="microphone"。 - 選項、MIDI 層的寫法和測試:
p5/README.md。範例:p5/examples/particles/、p5/examples/opc/、p5/examples/mic/、p5/examples/keys/、p5/examples/drums/、p5/examples/rhythm/、p5/examples/rhythm-visual/、p5/examples/rhythm-lab/、p5/examples/record/、p5/examples/lag/、p5/examples/chop/、p5/examples/with-strudel/、p5/examples/note-names/。
和 Strudel 一起用#
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:
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 的名字就是函式可以回傳的數值。
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 的埠是虛擬的):
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 的埠:
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 個:
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:
window.OAV_P5 = { link: 'my-room' }
await import('https://openaudiovisual.com/p5/oav-p5.js')p5 草圖(OpenProcessing:寫在那一行之前;或在作品網址加 ?sketch_oav_link=my-room):
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:
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 |
clock | follow(外部 MIDI 時鐘推動 drumPhase 和鼓機)· off | follow |
strudel | auto(strudel.cc,或頁面上已經有 Strudel 的函式)· on · off | auto |
compact | on(面板是角落的小框)· off | Strudel 裡 on |
hardware | auto · click · off | Strudel 裡 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。
手機、中繼與控制面板#
手機和 iPad 可以當控制器,能用的有動作感測器、一台鋼琴,還有一個照世界的參數自動長出來、類似 TouchOSC 的控制面板。負責的是三個套件,每個都能單獨使用:
| 套件 | 角色 |
|---|---|
@openav/relay | 零相依、分房間(room)的 WebSocket 中繼,以及它的瀏覽器端用戶端 |
@openav/surface | 控制面板元件、版面 JSON、autoSurface(params) |
@openav/remote | 手機 app(分頁:感測 · 琴鍵 · 控制台 · MIDI),以及演出端的轉接器 |
對映射器來說,手機只是多一種輸入:它發出訊號,路由再把訊號接到參數。
架設#
- 在演出電腦上執行
node serve.js。它提供頁面,同時在/relay架起中繼,不需要其他東西。 - 打開一個宣告了
modules: { remote: true }的演出,例如http://localhost:8080/examples/08-remote-surface/。 - 舞台左上角的加入卡片會顯示手機該打開的網址,裡面已經填好演出電腦的區域網路位址(頁面會到
/__info向serve.js詢問)和房間:http://<lan-ip>:8080/packages/remote/?room=default。 - 用同一個網路裡的手機打開那個網址。卡片會顯示目前連上幾支手機。
卡片上同時畫出這個網址的 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()),演出端會做五件事,世界完全不必知道手機在不在:
- 以房間的 runner(演出端)身分加入中繼。
- 把每一個手機訊號放進
signals,並把phone/<id>/…複製一份到phone/any/…。phone/any的值永遠來自最後送出數值的那支手機。 - 建立控制面板:世界有附版面就用
world.surface,沒有就用autoSurface(world.params),再發布給每一支手機,之後才加入的也收得到。 - 把
surface/… → param路由加進映射器(已經有的配對會跳過)。 - 每秒大約 10 次把參數值送回手機,讓推桿跟著時間軸和其他控制器一起動。
modules.remote 選項 | 預設 | 意思 |
|---|---|---|
room | 頁面網址裡的 ?room=,沒有就是 'default' | 房間名稱 |
auto | {} | 傳給 autoSurface 的選項(pairs、meters、style、perPage、smooth、title) |
surface | world.surface | 指定的版面(比世界自帶的版面優先) |
feedbackHz | 10 | 每秒回送幾次參數值 |
relay | 由 pickRelay() 決定 | 'wss://host/relay' 用你自己的中繼,false 不要遙控。沒設的話:本機或區域網路用同源 /relay,靜態主機用公開中繼。網址上的 ?relay= 會蓋過它 |
url | 同上 | relay 的別名(也是 mountRemoteHost() 吃的選項:它會自己補上 role、room、id) |
感測器的路由在寫作品時就寫好,用 phone/any/… 這個別名,因為沒人能事先知道別人手機的裝置 id(範例 08):
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>/down | spring: true 放手後回到中心 |
bank | <id>/1 … <id>/N | count、labels。一根手指劃過去,就能一路畫過好幾個通道 |
radio | <id> = 索引 / (n − 1),raw = 索引 | options: [...] |
pads | <id>/hit 脈衝 { pad, row, col, vel },按住時 <id>/<n> 是力度 | rows、cols(預設 4 × 4)、labels。n 從 0 起算,力度看你打在哪裡(上輕下重) |
keyboard | midi/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 代理寫,也可以由世界發布。
{ "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 } } }
}] }手機會轉來轉去,所以每個頁面照這個順序決定怎麼排:
- 如果頁面有對應目前方向的
portrait或landscape變體,就用它的格線(沒寫在它place裡的元件,留在原本的位置,或填進空格)。 - 沒有變體,但基本格線的形狀本來就對,就直接用。
- 都不符合,就自動重排:同樣的元件,一列一列重新排進一半(直向)或兩倍(橫向)的欄數。
列數是個數目,不是像素,所以格線永遠填滿螢幕,畫面永遠不會捲動。沒有 x/y 的元件,會依類型給一個預設大小,排進空格。validateLayout(layout) 回傳一份問題清單(空的就是沒問題)。遇到有問題的版面,new Surface() 會帶著這份清單丟出錯誤。
autoSurface#
autoSurface(params, options) 把世界的參數變成三樣東西:一份版面、驅動這些參數的路由,以及回送數值用的綁定:
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 + monitor | signal 和 batch |
| runner(演出) | monitor | signal 和 batch |
| runner | controllers + monitors | feedback(儀表、推桿回送)、config(控制面板版面,之後加入的手機也會補收到一份) |
| monitor | 不送給任何人 | |
| leader(演出頁面) | followers | sync(frame,以及回給從屬端的 state) |
| follower(演出頁面) | leaders | sync(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>" 指定單一對象)送給房間裡的從屬端,從屬端的訊息送給主控端,其他人都聽不到(好幾個頁面,一場演出)。
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 的權限規定):
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 裡,它方便你試玩,不是一把鎖。
訊號一覽#
訊號是輸入層唯一的通用貨幣:有名字、經過正規化、不分來源。這一頁列出內建輸入套件發布的每一個訊號。
慣例:
- 除非另外註明,範圍都是 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..1 | 20–250 Hz 的能量 |
audio/band/mid | 連續 | 0..1 | 250 Hz–2 kHz 的能量 |
audio/band/high | 連續 | 0..1 | 2–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..3 | 0 沒有橋接 · 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/playing | continuous | 0 / 1 | 正在播放時是 1;暫停、停止,或讓位給現場演奏時是 0 |
take/position | continuous | 0..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)。任何會變動的東西,都能拿來演出。
套件一覽#
二十八個套件放在 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。
| 匯出 | 簽章 |
|---|---|
Signals | new 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, … }] |
Params | new 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 |
Loop | new 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 可打開)。見自己驅動影格 |
Bus | new Bus() · on(event, cb) → 取消訂閱函式 · off(event, cb) · emit(event, payload) |
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)。
import { createShow } from '@openav/show';
const show = await createShow({ world, modules: { keys: { base: 48 }, sound: true } });@openav/midi#
L1 輸入與 L4 輸出 · Web MIDI 的輸入與輸出,可以同時接很多台裝置,還有照實體硬體做的螢幕控制器。
| 匯出 | 簽章 |
|---|---|
Midi | new 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 背後的純邏輯,見演出控制 |
| 總譜轉 MIDI | new 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 shim | createVirtualMIDIAccess({ 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 裡的嵌入協定輔助函式 |
import { Midi } from '@openav/midi';
const midi = new Midi({ signals });
await midi.enable();
midi.noteOn(60, 100, 1);訊號:見訊號一覽。控制器、profile 和 shim:見 MIDI 控制器與嵌入。
@openav/audio#
L1 輸入 · 麥克風(或任何音訊節點)的分析。
| 匯出 | 簽章 |
|---|---|
AudioAnalyzer | new AudioAnalyzer({ signals, fftSize = 2048, smooth = 0.7 }) · enableMic() · enableElement(mediaEl) · input() → 一個可以接進去的 AnalyserNode · 每個影格呼叫 update() → { rms, peak, low, mid, high, centroid, onset, kick, snare, hat } |
import { AudioAnalyzer } from '@openav/audio';
const audio = new AudioAnalyzer({ signals });
await audio.enableMic(); // from a click
// every frame: audio.update();@openav/chord#
L1 輸入(一種分析器)· 把彈下的音歸成一次一次的彈奏(gesture),發布協和度、三和弦和音堆。
| 匯出 | 簽章 |
|---|---|
ChordDetector | new ChordDetector({ window = 80, onChord, signals }) · noteOn(note, vel = 0.8) · noteOff(note) · analyze(notes, vels) → 分析結果(純函式) |
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 從鏡頭追蹤身體和手,全部在本機運算。
| 匯出 | 簽章 |
|---|---|
PoseTracker | new PoseTracker({ signals, mirror = true }) · enable({ videoEl })(要從點擊事件呼叫)· stop() · skeleton(ctx, w, h, { color, lineWidth }) · landmarks、running |
HandTracker | new HandTracker({ signals, mirror = true }) · enable({ videoEl }) · stop() · skeleton(ctx, w, h, { colorLeft, colorRight, lineWidth }) · hands、running |
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 寫的作品不用改就能跑。
| 匯出 | 簽章 |
|---|---|
LeapInput | new 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) |
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。
| 匯出 | 簽章 |
|---|---|
mountKeys | mountKeys(container, { signals, chord, base = 48, octaves = 2, sim = true, capture = true }) → { piano, sim, update(dt), dispose(), captureBox } |
KeysPiano | new 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 |
SimPlayer | new 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 } |
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/* 跟麥克風偵測鼓點時的長得一樣。
| 匯出 | 簽章 |
|---|---|
mountDrums | mountDrums(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) |
DrumSequencer | new 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() |
drumEngine | drumEngine({ 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 } |
import { mountDrums } from '@openav/drums';
const drums = mountDrums(document.querySelector('#drums'), { signals });
// every frame: drums.update(dt);@openav/mapping#
L2 映射 · 從訊號接到參數的路由,含曲線、平滑、learn,以及可以存檔的設定組(profile)。
| 匯出 | 簽章 |
|---|---|
Mapper | new 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 |
LearnWizard | new LearnWizard({ mapper, keys, onChange }) · start() · skip() · back() · stop() · sync() · active、current、index、total、done、added:「依序對應旋鈕」,見總譜與導演 |
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 一行注入。
| 匯出 | 簽章 |
|---|---|
approach | approach(current, target, seconds, dt) → 一極點 lag 的一步;seconds=跟上 63% 變化的時間(@openav/mapping 的 smooth 就是用它算) |
Lag | new Lag({ up = 0.1, down = up }) · step(input, dt, up?, down?) → 輸出 · reset(v?):上升用 up、下降用 down(Lag CHOP 的 Lag 1/Lag 2),秒數是 TouchDesigner 的(大約跟上 90% 變化的時間) |
envelope | envelope(times, t, attack = 0.01, decay = 0.3, peak = 1) → Trigger CHOP 在時間 t 的值(事件時間 times,秒,舊的在前):直線上升(0 → peak),decay 秒後剛好回到 0;還沒落完又觸發,從當下的高度接著走 · envelopeStage(elapsed, attack, decay, from, peak) |
Speed | new Speed() · step(rate, dt) → 位置:每秒加 rate |
Spring | new Spring({ stiffness = 100, damping = 6 }) · step(target, dt) → 位置(另有 velocity):掛在彈簧上的質點被拉向輸入,精確解 · springStep(x, v, target, k, c, dt) → [x, v] |
Trail | new Trail({ seconds = 2, rate = 60 }) · step(value, dt) → 最近 seconds 秒,每秒 60 個值再加上最新的一個,舊的在前,長度固定 |
Slope | new Slope() · step(value, dt) → 每秒變化量 |
Count | new Count({ threshold = 0.5 }) · step(on, limit = 0) → 打開過幾次;給 limit 就在 0 … limit − 1 之間循環 · wrapCount(total, limit) |
TD_LAG_RATIO、DEFAULTS | Math.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 一向是這個意思);上面那些預設值 |
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 世界 · 世界的外殼:管生命週期、彙整參數,本身不負責繪圖。
| 匯出 | 簽章 |
|---|---|
Stage | new Stage({ container, params, signals, io = {} }) · register(world) · activate(name)(非同步)· frame(dt, baseState) → 狀態 · active、activeName、worlds、io |
createCanvas | createCanvas(container, { alpha = false }) → { canvas, ctx, fit() → { w, h }, dispose() } |
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) 綁定。
| 匯出 | 簽章 |
|---|---|
webtoeWorld | webtoeWorld({ name = 'webtoe', app = 'https://webtoe.openaudiovisual.com/', project, params = [], extra }) → 一個世界 |
見寫一個世界。
@openav/sound#
L4 輸出 · 頁面裡的樂器,背後是一份精簡的引擎介面約定。有 Salamander 平台鋼琴、敲擊琴、弦樂、風琴、合唱、豎琴和合成器音色,從選單挑,引擎的參數會變成 sound/* 參數。
| 匯出 | 簽章 |
|---|---|
Sound | new Sound({ signals, params, engine, instrument, remember, picker }) · enable()(要從點擊事件呼叫)· 每個影格呼叫 update(state) · setInstrument(id) · instrument · status · onChange(cb) · dispose() · enabled |
toneEngine | toneEngine({ instrument = 'synth/pad', baseUrl, instruments, cdn, drumChannel = 10 }) → 帶有 cutoff、space、volume 參數的引擎,再加上樂器自己的參數 |
registerInstrument | registerInstrument({ id, name, category, params, defaults, credit, create(Tone, ctx) }, { replace }),另外還有 getInstrument、listInstruments、instrumentGroups、onInstrumentsChange |
registerSynthPreset | registerSynthPreset({ id, name, voice, oscillator, envelope, filter, effects, … }) → synth/<id> |
modalInstrument | modalInstrument({ id, name, partials, strike, damp }) → 用資料寫成的敲擊類樂器 |
mountSoundPicker | mountSoundPicker(el, sound, { lang, className }) → 控台用的那個選單 |
引擎介面約定:{ params, enable(), noteOn(note, vel01), noteOff(note), set(key, value), dispose() }。樂器清單和怎麼加入新樂器,寫在聲音。
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。
| 匯出 | 簽章 |
|---|---|
OscOut | new 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 | 簽名 |
|---|---|
OutClient | new 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 可進可出)。
| 匯出 | 簽章 |
|---|---|
Compositor | new 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 |
Recorder | new 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 |
AudioTap | new AudioTap({ context, sources, captureDestination }) · add(node | stream | track, { bus }) · captureDestination() · addMicrophone() · level() · tracks(作品+麥克風)、workTracks(只有作品) |
EventLog | new EventLog({ now, filter, throttleMs }) · start(at) · stop() · add(name, value) · attach(signals) · toJSON() · toTake() |
TakeRecorder · TakePlayer | new 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 畫面裡的鏡頭是放大的。
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()。
| 匯出 | 簽章 |
|---|---|
Fab | new 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),純邏輯。
| 匯出 | 簽章 |
|---|---|
Timeline | new 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。
| 匯出 | 簽章 |
|---|---|
Score | new 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 列出每一個原因 |
Director | new Director({ score, modules, api, onStatus, onCue, maxStep }) · update(T, dt, { holding, playing }) · param(key, value, T) · seek(T) · reset() · status() · register(module) |
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。
| 匯出 | 簽章 |
|---|---|
compile | compile(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 其中之一 |
parse | parse(src) → { ok, tree } 或 { ok: false, error }:節點 step rest seq layer alt fast slow euclid maybe,每個都帶字元範圍 |
WORDS | bd 大鼓 · sd 小鼓 · hh 鈸 · oh 開鈸 · cp 拍手 · rim/rs · lt mt ht 中鼓 · cr 碎音鈸 · rd 疊音鈸 · cb 牛鈴,也接受鼓組自己的名字 |
euclid | euclid(pulses, steps, rotate = 0) → 布林陣列(Toussaint 2005) |
fromGrid | fromGrid(grid, { steps = 16, words, order }) → 照人會寫的樣子把格子寫成一行、打出來一模一樣:bd*4、[~ sd]*2、bd(3,8,2),其他一拍一拍寫 bd [~ ~ ~ bd] bd*2 ~(0.7) |
toGrid | toGrid(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) |
fromStrudel | fromStrudel(code) → { strudel, ok, src, bpm, ignored, unsupported }:從 strudel.cc 複製來的 s("…")/sound("…"),.fast/.slow 併進那一行,setcpm/setcps 當速度(0.7) |
toStrudel、strudelUrl | strudelUrl(src, { bpm, comment }) → https://strudel.cc/#…(寫成 s("…")、前面加 setcpm(bpm/4),# 後面是 base64);用新分頁開(0.7) |
寫法:空白(等分一小節)· ~ - 休止 · [ ] 細分 · , 疊層 · *n 加快 · /n 放慢、跨小節 · < > 每小節輪一個 · (k,n,r) 歐幾里得 · !n 與 ! 重複 · @n 與 _ 拉長 · ? ?0.3 隨機省略(有種子)· bd:2 取樣編號。. | { } 會回錯誤與提示(休止請用 ~ 或 -)。
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 的參數、訊號儀表、演出模式。
| 匯出 | 簽章 |
|---|---|
mountConsole | mountConsole(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 中繼。
| 匯出 | 簽章 |
|---|---|
MonitorFeed | new MonitorFeed({ url = 'ws://<page host>:7457', hz = 15, extra }) · connect() · frame(snapshot) · extra(fn) → off() · connected、onStatus |
snapshotOf | snapshotOf({ timeline, params, signals, stage, loop, extra? }, state) → 一份 JSON 快照;作品自己的數字(extra、目前啟用的世界的 monitor())放在快照的 extra 下 |
cleanExtra | cleanExtra(x) → 把作品的數字整理成 JSON 帶得走的樣子(每個欄位是數字、字串、布林、null 或 { v, min, max, warn }),沒有任何欄位時回傳 null |
| 伺服器 | node packages/monitor/server.js [port=7457]:後台頁面在 /,另有 /health |
見演出控制。
@openav/sync#
主軸 · 好幾個頁面,一場演出:主控端和它的從屬端之間的那條線,走 BroadcastChannel 或房間中繼。從屬端的時間軸用 timeline.follow() 去追主控端。
| 匯出 | 簽章 |
|---|---|
createSync | createSync({ 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() 放手 |
SyncLeader | new SyncLeader({ timeline, transport, id, cut, extra, state, hz, now, onHello }) · frame() · sendState(to?) · status() · monitor() · close() |
SyncFollower | new 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_VERSION | 1,每則訊息的 v |
訊息有 frame(主控端送給從屬端,每一幀)、hello(從屬端送給主控端)和 state(主控端送給某一個從屬端);作品自己的資料放在 extra。見演出控制。
@openav/relay#
手機 · 以房間為範圍的 WebSocket 中繼(伺服器),以及它的瀏覽器用戶端。
| 匯出 | 簽章 |
|---|---|
RelayClient | new 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/server | attachRelay(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)。
| 匯出 | 簽章 |
|---|---|
Surface | new Surface(el, { layout, sink(name, value, info), haptics = true, tabs = true, orientation, onPage }) · setLayout(layout) · setPage(id) · feedback(name, value) · widget(page, id) · dispose() |
signalSink | signalSink(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 |
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,以及演出端的轉接器。
| 匯出 | 簽章 |
|---|---|
mountRemote | mountRemote(el, { room, relayUrl, surfaceUrl, metaUrl }) → 手機 app(/packages/remote/index.html 呼叫的就是它) |
PhoneSensors | new PhoneSensors({ set, send }, { onKnock, onSample, notify }) · start()(要從觸控事件呼叫)· stop() · calibrate() · setCamera(on) · denied |
localSensors | localSensors(signals, { prefix = 'phone/local/', alias = 'any' }) → PhoneSensors |
attachTouchPad | attachTouchPad(el, io, { onMove, onEnd }) |
@openav/remote/host | mountRemoteHost({ signals, params, mapper, world, room, auto, surface, feedbackHz = 10, url, mode, controllers }) → host 物件 · mountJoinCard(parent, host)(網址、QR code、狀態) |
@openav/remote/relay-pick | pickRelay({ hostname, search, declared, storage }) → { mode: 'local'|'public'|'custom'|'off', url, room, shared } · isLocalHost(h) · PUBLIC_RELAY · phoneUrl({ base, room, relay }) |
@openav/remote/qr | qrSvg(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 代理#
世界就是一段畫出畫面的程式碼,而程式代理很會寫程式碼。人描述一場表演(「一個遇到和諧和弦就綻放的水母世界」),代理寫出這個世界,放進已經處理好 MIDI、映射、時間軸、控台和後台的外殼裡。代理要把這件事做好,需要知道的東西都在這一章。
兩條規則#
- 連續控制一律走參數,離散事件可以用訊號。 不要在
update()裡用signals.get(…)讀連續變化的東西。宣告一個參數,讓路由把訊號接過去。 - 外殼永遠不知道作品。 不要為了讓某一個範例好看,去改
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 讀到這個伺服器。其他客戶端這樣設定:
{
"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_doc | doc(必填):architecture、writing-a-world、signals、show-control、roadmap、agents、readme | Markdown 文字。agents 是 AGENTS.md,readme 是 README,其他的是 docs/<name>.md |
scaffold_world | slug(必填,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_profile | id(必填):設定檔 id 或它的 short | { id, url, unverified, profile, mapping }:內建的設定檔 JSON(有的話包含 sysex、palette、verifications,每個控制項另有 evidence:hardware、source 或 unconfirmed),加上一份讀得懂的 MIDI 對照(控制項、型態、CC 74, ch 1、訊號 midi/<short>/<id>、是否確認) |
validate_profile | profile(必填):物件或 JSON 字串 | { ok, problems, conflicts }:validateProfile 找到的問題,加上和內建設定檔的衝突(同 id、同 short、match.ports 重疊) |
scaffold_profile | maker、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 設成整個演出物件,所以操作瀏覽器的代理可以檢查它、操控它:
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一段可以直接貼上的提示詞#
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" 欄位)#
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),還有開發伺服器的中繼與路由。新種類的控制器或輸入,絕不從那裡開始寫。
疑難排解#
這些都是排練和寫程式時真的遇過的問題,附上解法。
瀏覽器主控台出現 ws://…:7457 錯誤#
每個用 createShow() 做的演出,都會試著把資料串流到 ws://<the page's host>:7457 的後台監看。監看伺服器沒在跑時,瀏覽器會記下被拒絕的連線。這是預期中的,也無害:頁面會重試,間隔從大約 5 秒拉長到 30 秒,不會一直洗版。想讓它消失,就把監看伺服器跑起來:
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 送來的訊息,就關掉內建的引擎,自己建一個:
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:
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 啟動中繼。
路線圖#
指導原則:真實演出要求過的功能,框架才長。(核心就是這樣來的:這裡的每個模組,都先撐過一場真正的演出,才整理成通用的形式。)
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這類訊號) - 麥克風當作手機感測器、每台裝置各自的設定檔、版面編輯器/匯入匯出介面
- 加入卡片上的 QR code(
- 總譜與導演:已經上線(
@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 clock:
- 訊號錄製與重播: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,不是我們伺服器上的一個帳號