open-audiovisual
搜尋 GitHub

open-audiovisual 網頁原生的影音表演框架,開源,給所有人當地基。

琴鍵、旋鈕、人聲、手勢、手機,都會變成有名字的訊號(signal)。映射(mapping)把訊號接到參數(param),你的世界(world)讀這些參數,變成畫面和聲音。在瀏覽器分頁、投影機、舞台上都一樣。

oav-p5 0.8 · 框架 0.9 · MIT 授權 · 零建置 · 零相依

01 · 彈奏 這台樂器就是框架本身在跑

A 到 L 彈奏 · Z/X 換八度 · 拖曳畫面

舞台上的世界是一台擺錘繪圖機(harmonograph),用擺錘把音程畫成圖形的老機器。你彈的每個音,會依音高擺動一支擺錘。和弦分析器讀你按住的音,把協和度經過一條路由 chord/consonance → order 送進世界:三和弦畫出乾淨的圖形,音堆畫出一團糾纏的線。 看這台樂器的原始碼 →

02 · 運作方式

四層,各自分開

一場表演有四個部分:發生了什麼、它代表什麼、世界怎麼反應、結果怎麼離開瀏覽器。open-audiovisual 讓這四層各自分開,換掉其中一層,其他三層照常運作。

  1. L1 輸入

    “正在發生什麼”

    MIDI 琴鍵、麥克風、一個和弦、鏡頭前的一隻手、在空中傾斜的手機。每一種都會變成訊號:一個名字加一個數值,通常在 0 到 1 之間。

    pointer/x = 0.50數值來自上面那台樂器

    midi audio chord pose keys drums remote

  2. L2 映射

    “它代表什麼”

    路由把訊號接到參數,每一條都能設曲線、範圍和平滑。一顆旋鈕可以同時推三個參數。按下 learn,隨便動一樣東西,線就接好了。

    pointer/x → hue smooth 0.25數值來自上面那台樂器

    mapping

  3. L3 世界

    “系統怎麼表現”

    你的作品。它只讀參數,不碰輸入,用什麼畫都可以:canvas、p5、three.js、WebToe 節點網路。

    hue = 14數值來自上面那台樂器

    stage world-webtoe

  4. L4 輸出

    “怎麼離開瀏覽器”

    螢幕,還有聲音:頁面裡的樂器、送到硬體和 DAW 的 MIDI、送到 Spat、Reaper、TouchDesigner 或燈光的 OSC。

    screen · 60 fps數值來自上面那台樂器

    sound osc midi

四層之外

時間軸 Timeline
整場演出的樂譜:參數自動化、場景與 cue。手一抓住控制,樂譜就讓位。
控台 Console
導演桌:播放控制、推桿、learn、儀表,按 T 進入演出模式。
後台監看 Monitor
同一個網路裡的手機或筆電都能當後台:時鐘、場景、每個訊號、FPS,舞台畫面斷線時會警示。
手機 Phones
手機和 iPad 當控制器:傾斜和敲擊感測、琴鍵,還有依世界的參數自動長出來的控制面板。

兩條規則

  1. 訊號是輸入唯一的通用貨幣。 一顆旋鈕、一隻舉起的手、一個和弦的協和度,在框架裡地位相同,各有名字。所以它們可以混在一起用。
  2. 世界永遠不知道誰在演奏它。 世界只讀參數。同一個世界,可以由鋼琴家、舞者,或一條自動化曲線來演奏。

這一頁用到的詞

訊號 Signal
一個有名字的數值,說明正在發生什麼,例如 midi/cc/74、audio/rms。通常在 0 到 1 之間。脈衝訊號(pulse)帶的是事件,例如一個音被按下。
參數 Param
世界在聽的數值,例如 hue、bloom。由世界宣告,由時間軸、推桿或路由來設定。
映射、路由 Mapping, route
一條從訊號接到參數的線,可以設曲線、範圍和平滑。路由本身就是資料,存成 JSON,接線方式可以帶到下一個場地。
世界 World
作品本身:一個帶有 params、init、update、render、dispose 的物件。整套框架裡,唯一一定要自己寫的部分。
時間軸 Timeline
隨時間變化的自動化與場景。手和旋鈕一動,就會蓋過它。
演出 Show
一個世界,加上一次 createShow() 呼叫,輸入、映射、時間軸、控台、聲音和後台就一起組好。

03 · 作品

二十六件作品,現在就能打開

每個範例都不需要硬體。螢幕鋼琴、電腦鍵盤、模擬演奏者或鼓機,可以先代替樂器。進到任何一個範例:空白鍵播放時間軸,T 是演出模式,F 是全螢幕。

  1. 黑底上,粒子拖著細細的綠色與紅色尾巴落下。

    01

    哈囉粒子

    演奏方式 螢幕鋼琴 · 電腦鍵盤 · 模擬演奏者

    最小的完整範例。把 main.js 從頭讀到尾,整套框架就懂了。

    ① 第一次打開

  2. 一朵綠黃色層層花瓣的花,周圍有彩色圓圈,還有四道紅、綠、藍色的光柱。

    15

    p5.js 一行指令

    演奏方式 MIDI 控制器 · 螢幕上的控制器 · 手機

    一份普通的 p5 草圖,第一行載入 oav-p5.js,就能用 MIDI 控制器、螢幕上的控制器或手機彈。

    ① 第一次打開

  3. 黑底上,綠、紫、紅色的粒子點一串串炸開,下方是螢幕上的 MiniLab 3 控制器,有琴鍵和聲音按鈕。

    16

    p5 彈出聲音

    演奏方式 MIDI 鍵盤 · 螢幕上的控制器 · 手機

    在 setup() 寫 startSound('piano'):MIDI 鍵盤、螢幕上的 🎹、手機彈的每個音都聽得到,也炸開一團粒子。

    ② 什麼都能當樂器

  4. 深藍底上一個大大的粉紅色圓,外面圍著一圈細細的灰色圓環。

    17

    p5 麥克風

    演奏方式 麥克風 · 鼓機(🥁)

    micLevel、bass、beat 像 mouseX 一樣讀麥克風:說話時圓會變大,不用 p5.sound。

    ② 什麼都能當樂器

  5. 左邊小小的綠色圓(micLevel),右邊比較大的黃色圓(lag 後),下面兩條曲線:綠色一下就掉,黃色慢慢落下。角落有一個小示波器。

    22

    p5 lag:讓跳動的數值變順

    演奏方式 麥克風 · 鼓機(🥁)

    lag(micLevel, 0.03, 0.4) 把跳動的數值變順,跟 TouchDesigner 的 Lag CHOP 一樣,秒數也一樣。scope() 在網頁角落畫出兩條線。

    ② 什麼都能當樂器

  6. 粉紅與藍色圓點排成螺旋,下方是螢幕上的 MIDI 鍵盤控制器。

    09

    MIDI 控制器

    演奏方式 MIDI 控制器,或螢幕上那一台

    螢幕上有 MiniLab 3、LPD8、Launchpad、nanoKONTROL2。接上實體控制器,螢幕上那台會跟著你的手一起動。

    ② 什麼都能當樂器

  7. 夜裡的花園,細長分岔的植物長著綠葉,枝端開出藍、紅、粉色的小花。

    02

    和弦花園

    演奏方式 螢幕鋼琴 · 電腦鍵盤 · 模擬演奏者

    一個音落下一顆種子,三和弦讓枝條開花,音堆讓花與葉垂下、落盡。枝條是《The Last Input》的 L-system 植物。世界聽的是和弦訊號,從來不看琴鍵。

    ② 什麼都能當樂器

  8. 一顆球體擠滿彩色圓柱,從端面看去像一把把傘。

    06

    Cylinder Earth

    吳哲宇,200412 3D Cylinder Earth,2020

    演奏方式 麥克風 · 鼓機

    2020 年用聲音控制的 WebGL 作品。低頻推動柱體,高頻讓旋轉閃爍,大鼓一下就換一組配色。

    ② 什麼都能當樂器

  9. 藍白色細線層層疊成的曼陀羅。

    03

    手的樂器

    演奏方式 鏡頭(手)· 螢幕鋼琴 · 鼓機

    手指就是樂器:一組捏合控制鬆緊,另一組長出手臂,兩手握拳就綻放。四種圖案輪流切換:曼陀羅、利薩如、萬花尺、蛛網。

    ② 什麼都能當樂器

  10. 黑底上,一副紫色的手骨架,上方是像雨一樣垂落的綠色與藍色墨跡。

    12

    Leap 雙手

    演奏方式 Leap Motion · 用滑鼠模擬手

    把 Leap Motion 當樂器,經本機橋接;沒開橋接時用滑鼠模擬手。

    ② 什麼都能當樂器

  11. 藍色和黃色的光束,從畫面下方中央向外爆開。

    08

    遠端控制面板

    演奏方式 手機或 iPad · 螢幕鋼琴

    手機就是樂器面板。世界只宣告參數,手機上的控制面板依參數自動長出來。需要在你的網路裡跑 node serve.js。

    ② 什麼都能當樂器

  12. 下半部一排顏色柔和的圓往上飄,細圓環裡一根黃色指針朝上,底下寫著房間名 oav-strudel-demo。

    23

    p5 跟 Strudel 一起

    演奏方式 另一個分頁的 Strudel · 螢幕上的控制器

    Strudel 在另一個分頁演奏,這份草圖畫畫面:Strudel 送到 OAV Virtual MIDI 的每個音都呼叫 notePressed(),它的時鐘推著 drumPhase 轉。

    ② 什麼都能當樂器

  13. 黑底上亮著黃色的圓、方、三角,分別標著 C4 = 60、E4 = 64、G4 = 67,下面寫著 G4 和 392.0 Hz。

    24

    p5 音名

    演奏方式 MIDI 鍵盤 · 螢幕上的控制器 · 手機

    noteIsDown('C4') 跟 noteIsDown(60) 一樣:收音符號碼的地方都能直接寫音名(C4、c#4、Db3)。noteNumber()、noteName()、noteFreq() 幫你換算。

    ② 什麼都能當樂器

  14. 一個青綠色的圓盤,中間有白色指針,外面一圈細圓環,圓心下面四顆點,角落的小示波器畫著彈跳的曲線;底下寫著 env、spring、count 現在的值。

    25

    p5 會動的數值

    演奏方式 麥克風 · 鼓機(🥁)

    env('kick')、spring()、speed()、count('kick', 4) 像 TouchDesigner 的 Trigger、Spring、Speed、Count 那樣讓數值動起來:大鼓撐開圓盤、彈簧把它彈回來、指針一直轉、每 4 下大鼓換一個顏色。

    ② 什麼都能當樂器

  15. 左邊一圈 16 格、一根白色指針;右邊是節奏那一行 bd ~ [~ bd] ~, ~ cp ~ cp, hh(5,8)、「改自:type」和更早的三行;底下寫著按鍵 1 到 4、Z、S 的用法。

    26

    p5 節奏實驗台

    演奏方式 按鍵 1–4、Z、S · 鼓機(🥁)

    OAVp5.drums.edit('bd(3,8), …') 像打字一樣換節奏,OAVp5.drums.undo() 回上一行,OAVp5.drums.strudelUrl 把這一行帶去 Strudel;rhythmChanged() 告訴你現在是哪一行。

    ② 什麼都能當樂器

  16. 節點編輯器裡有 noise、level、out 三個節點,旁邊是灰色雲霧材質。

    04

    WebToe 舞台

    演奏方式 螢幕鋼琴 · 模擬演奏者

    這個世界是一張 WebToe 節點網路,操作方式接近 TouchDesigner,透過 ext() 綁定來演奏。WebToe 是引擎,open-audiovisual 是演出。

    ③ 接上別的畫面引擎

  17. 發光的黃色鋸齒花瓣圍成一圈,中間有小圓圈。

    05

    Prebiotic Flake

    吳哲宇,230616 Prebiotic Flake,2023

    演奏方式 螢幕鋼琴 · 模擬演奏者 · 聲音

    2023 年的一件 MIDI 每日創作,搬進框架重新演奏。繪圖程式碼保持原樣,雪花現在透過 Tone.js 發出聲音。

    ③ 接上別的畫面引擎

  18. 青色和紫色的煙火,在垂落的彩色尾跡上炸開。

    07

    花火大會

    吳哲宇,210807 Firework 花火大會,2021

    演奏方式 鏡頭(手)· 螢幕鋼琴

    2021 年的作品。手指一捏合,煙火就從那隻手的位置升空。粒子系統是 2021 年的原始程式碼。

    ③ 接上別的畫面引擎

  19. 橘黃色圓點排成六邊形,下方是時間軸:五條曲線、場景區塊和一條播放頭。

    14

    時間軸

    演奏方式 什麼都不用做,它自己會播 · 螢幕旋鈕

    看得見的自動化。五條關鍵影格曲線帶動一圈光點,場景負責切換,cue 觸發一次性的閃光,你一碰旋鈕就接手,放開再還給曲線。把旋鈕的動作錄下來,就寫成一條新曲線。

    ④ 演出控制

  20. 長花瓣的黃橘色花朵,上方是一台 16 格的鼓機,有大鼓、小鼓、鈸、拍手四排。

    18

    p5 鼓機與小節

    演奏方式 鼓機 · 它的 16 格

    startDrums('breakbeat', 110) 在頁面上放一台 16 格的鼓機,kickDetected()、cueFired() 把它的鼓點和小節變成畫面。

    ④ 演出控制

  21. 藍色的圓,一根黃色指針繞著它轉,上方的鼓機卡寫著 bd*4, [~ sd]*2, hh*8 和它的 16 格。

    19

    p5 一行節奏

    演奏方式 鼓機 · 可以改的一行字

    startDrums("bd*4, [~ sd]*2, hh*8") 用一行字寫鼓,drumPhase、beatPhase 讓指針一小節轉一圈、圓在每一拍鼓起來。

    ④ 演出控制

  22. 同一個節奏在畫布上畫成三種樣子:一圈彩色格子加一根白色指針、最近四小節繞成的螺旋、一條有播放頭的 16 格,上方是鼓機卡。

    20

    p5 看得見的節奏

    演奏方式 鼓機 · 格子和那一行字

    drawRhythm() 把節奏畫在畫布上(格子、圓、螺旋三種),錄影錄得到。卡片上的格子和那一行字互相改。

    ④ 演出控制

  23. 藍色與青綠色的黃昏天空,有一輪淡色的月亮,角落寫著 dusk。

    13

    總譜與導演

    演奏方式 螢幕鋼琴 · 鍵盤:空白鍵、← →

    有結構的演出:「一天的天空」只寫一次段落長度;導演為每段跑一個模組,?cut=<id> 選版本,空白鍵放行 hold。

    ④ 演出控制

  24. 中間一顆粉紅色圓點,外面是發光的粉紅與黃色圓環往外擴散,上方是正在打 four on floor 的鼓機卡。

    21

    p5 錄成影片

    演奏方式 電腦鍵盤 A–K · 螢幕上的控制器 · 鼓機

    startRecording() 把畫布連同草圖自己的聲音錄成一支影片(瀏覽器能錄 MP4 就是 MP4)。🎹 面板上的 ⏺ 和 📷 不寫程式也能用。

    ⑤ 輸出與留存

  25. 深色畫面上,粉紅、黃與綠色的圓環層層疊疊向外擴散,每一圈都是一個被彈下的音。

    10

    演出影片

    演奏方式 螢幕鋼琴 · 電腦鍵盤 · 模擬演奏者 · 鏡頭(選用)

    演出影片:作品疊在鏡頭畫面上,連同作品自己的聲音錄成一個直式 1080×1920 到 4K 的檔案;MIDI 演奏可錄下再重播。

    ⑤ 輸出與留存

  26. 粉紅、紫與黃色的圓環層層交疊,旁邊是螢幕上的 MiniLab 3,下方寫著最後彈下的音。

    11

    控制器影片

    演奏方式 MIDI 控制器 · 螢幕鋼琴 · 電腦鍵盤 · 一段示範演奏

    不用鏡頭的演出影片:作品下方即時畫出正在彈的 MIDI 控制器(MiniLab 3 或任何設定檔),重播的演奏也會動。

    ⑤ 輸出與留存

依路線瀏覽所有範例 →

05 到 07 是吳哲宇 2020 到 2023 年的作品,在這裡當作示範。框架採 MIT 授權,作品的著作權仍屬藝術家,保留一切權利。

姊妹專案

WebToe
背後的引擎

做即時影像的節點式資料流引擎。在瀏覽器裡就能像用 TouchDesigner 那樣接運算子,跑在 WebGL2 或 WebGPU 上,沒有執行期相依套件,還能打開真的 TouchDesigner 專案。透過 @openav/world-webtoe,一張網路就能變成可以演奏的世界。WebToe 負責引擎,open-audiovisual 負責演出。

WebToe 編輯器:ramp 和 transform 運算子接到 composite、hsv adjust 和 out,每個節點都有即時預覽,右邊是輸出畫面。

04 · 開始

一分鐘跑起來

不用安裝、不用建置、沒有相依套件。clone 下來,跑一個檔案,打開瀏覽器。要用 Web MIDI 和鏡頭,請用 Chrome 或 Edge。

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

接著打開 http://localhost:8080/examples/01-hello-particles/,讀它的 main.js。

terminal
node packages/monitor/server.js           # backstage monitor (:7457)
node packages/osc/bridges/osc-bridge.js   # OSC → UDP bridge

需要的話,各開一個終端機:後台監看伺服器,以及把 OSC 送到 UDP 的橋接。

你只需要寫一個世界

宣告作品能被什麼演奏(參數),對事件做反應,然後畫出來。交給 createShow(),其他部分一起到位:鋼琴、映射、時間軸、控台、聲音、後台。旁邊放一個帶 import map 的 index.html,照範例 01 的寫法。

examples/27-pulse/main.js
import { createShow } from '@openav/show';
import { createCanvas } from '@openav/stage';

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

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

怎麼寫一個世界 →

二十八個套件,依層分類

全部是原生 ES module。用 import map 引入需要的套件,或交給 createShow() 組裝。

輸入

  • @openav/midiWeb MIDI 輸入與輸出,支援多台裝置與螢幕上的控制器
  • @openav/audio麥克風分析:音量、頻段、亮度、起音、鼓點
  • @openav/chord為演出設計的和弦偵測:協和度、三和弦、音堆
  • @openav/pose用鏡頭追蹤身體與手的 21 個點,全部在本機運算
  • @openav/keys螢幕鋼琴、電腦鍵盤演奏,以及模擬演奏者
  • @openav/drums合成鼓組與步進音序器,發出和音訊分析同樣形狀的訊號
  • @openav/leap透過本機的小橋接,把 Leap Motion 的手變成 21 點手部訊號

映射

  • @openav/mapping訊號到參數的路由:曲線、平滑、多對多、learn
  • @openav/chop數值隨時間的變化,像 TouchDesigner 的 CHOP:lag、包絡、速度、彈簧、軌跡、斜率、計數;任何幀率畫出同一條曲線

世界

輸出

  • @openav/sound頁面裡的樂器(Salamander 鋼琴、敲擊琴、弦樂、風琴、合成器音色),加一個檔案就能放進自己的聲音
  • @openav/osc透過一支小小的 Node 橋接,把 OSC 從瀏覽器送到 UDP
  • @openav/out把網頁作品的參數經一支本機橋接送到 WLED 燈條、序列埠馬達板和 OSC,斷線時看門狗退回安全值
  • @openav/record演出影片:作品疊在鏡頭畫面上、連同作品自己的聲音錄成一個檔;MIDI 演奏可錄下再重播
  • @openav/fab做得出來嗎?對任何網格做 3D 列印檢查(水密、懸空、最薄壁、重量),匯出 STL、OBJ、GLB、STEP

時間軸、控台、監看

  • @openav/timeline參數自動化、場景與 cue:整場演出的時鐘
  • @openav/score把演出寫成段落長度:版本、cue、hold,還有模組壞掉時讓演出不中斷的導演
  • @openav/pattern一行字寫節奏:TidalCycles/Strudel 式的 mini-notation 解析成每一小節的鼓點(歐幾里得節奏、每小節輪替、有種子的隨機)
  • @openav/console導演控台與演出模式
  • @openav/monitor網路裡任何裝置都能看的後台畫面
  • @openav/sync好幾個頁面演同一場:主控端跑時間軸,從屬端追它的時鐘,走 BroadcastChannel 或房間中繼

手機與平板

  • @openav/relay零相依的房間中繼,讓手機和 iPad 連進來
  • @openav/surface類似 TouchOSC 的控制元件,以及 autoSurface(params)
  • @openav/remote手機與 iPad 端的 app:感測器、琴鍵、控制面板

核心與代理

  • @openav/coreSignals、Params、Loop:每一層共用的語言
  • @openav/showcreateShow():一次呼叫組好整個外殼
  • @openav/mcp給程式代理用的 MCP 伺服器:列出、閱讀、建立、檢查

文件

常見問題

大家常問的

open-audiovisual 是什麼?

open-audiovisual 是零建置的 JavaScript 框架:把 MIDI 控制器、麥克風、手勢與手機變成訊號,驅動瀏覽器裡的 p5.js、WebGL 或 WebToe 世界,用於現場影音表演。MIT 授權。

延伸閱讀: 運作方式 →

可以用 MIDI 控制器玩 p5.js 草圖嗎?

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

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

p5 1.x、2.x 的全域模式都能用,setup() 裡不用呼叫任何東西。

延伸閱讀: p5.js 一行接上 →

p5.js 草圖能出聲音、打鼓、錄成影片嗎?

聲音:startSound('piano')。鍵盤、螢幕上的 🎹、手機彈的每個音都聽得到,面板上的 🔊 可以換樂器。

鼓機:startDrums(),16 格、四軌、五種節奏。

一行字寫節奏:startDrums("bd*4, [~ sd]*2, hh*8")。寫法來自 TidalCycles 與 Strudel,OAV 依公開文件獨立實作(@openav/pattern)。

錄影,連聲音一起:startRecording()、stopRecording()、recordingSaved(info)。🎹 面板上的 ⏺ 和 📷 不寫程式也能用。

延伸閱讀: p5.js 一行接上 →

數值跳來跳去,怎麼像 TouchDesigner 的 Lag CHOP 那樣變順?

像 TouchDesigner CHOP 的數值工具:lag(micLevel, 0.03, 0.4)(Lag CHOP,秒數跟 TouchDesigner 一樣:大約跟上 90% 的時間)、env('kick', 0.01, 0.3)(Trigger)、speed()、spring()、trail()、slope()、count(),draw() 裡一行一個,不用宣告。

docs/zh/p5.md
circle(width / 2, height / 2, 50 + lag(micLevel, 0.03, 0.4) * 300);   // a VU meter: opens at once, closes slowly

延伸閱讀: 數值隨時間 →

可以跟 Strudel 一起用嗎?

Strudel 是在瀏覽器裡即興寫音樂的 live coding 環境,TidalCycles 的 JavaScript 版。OAV 是另一個獨立的程式。

跟 Strudel 一起用:在 strudel.cc 載入這一行,旋鈕、手機、麥克風就能當 Strudel 的參數。

Strudel 的 .midi('OAV Virtual MIDI') 送來的音符照時間戳進到 notePressed(實測誤差最大 4.5 毫秒),它的節拍時鐘讓鼓機和 drumPhase 跟著走。

docs/zh/strudel.md
await import('https://openaudiovisual.com/p5/oav-p5.js')

OAV 不載入、也不呼叫 Strudel 的任何程式。

延伸閱讀: 和 Strudel 一起用 →

沒有硬體也能用嗎?

每個範例都不需要硬體。螢幕鋼琴、電腦鍵盤、模擬演奏者或鼓機,可以先代替樂器。

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

延伸閱讀: 範例 →

哪些瀏覽器支援 MIDI?

Chrome 和 Edge 有。演出請用它們。

Safari 和 iPad 沒有 Web MIDI,螢幕上的控制器和手機照樣能用。

鏡頭和麥克風只在安全環境(secure context)裡能用:http://localhost 或 https://。

延伸閱讀: 快速開始 →

支援哪些 MIDI 控制器?每台的 CC 對照表在哪?

open-audiovisual 把 MIDI 控制器寫成資料:每台裝置一個 JSON 檔,記下面板配置、每個控制項送出的 MIDI 訊息、LED 回饋、怎麼認出它的埠,以及每個數字出自哪一份文件。

同一個檔案可以變成螢幕上能彈的控制器,接上實體裝置時跟著動,也能放進任何網頁。

延伸閱讀: MIDI 控制器圖鑑 →

可以把控制器嵌進我自己的網站嗎?

docs/zh/controllers.md
<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 輸出這兩項會顯示無法使用。

延伸閱讀: MIDI 控制器與嵌入 →

AI 代理可以幫我做世界嗎?

世界就是程式碼,程式代理(coding agent)很會寫程式。人用文字描述一場表演,代理寫出世界,框架把演出跑起來。

repo 內附一個零相依、走 stdio 的 MCP 伺服器。

延伸閱讀: 給 AI 代理 →

要錢嗎?授權是什麼?

MIT 授權。

範例 05 到 07 收錄吳哲宇的作品,著作權屬藝術家,保留一切權利。

延伸閱讀: GitHub 上的授權 →

05 · 給 AI 代理

給 AI 代理

世界就是程式碼,程式代理(coding agent)很會寫程式。人用文字描述一場表演,代理寫出世界,框架把演出跑起來。

把這段貼給 Claude Code、Cursor 或任何程式代理

prompt
Clone https://github.com/frank890417/open-audiovisual,先讀 AGENTS.md。
執行 `node serve.js`,打開 http://localhost:8080/examples/01-hello-particles/,看最小的完整演出長什麼樣子。
把 01-hello-particles 複製成 examples/27-<名稱>/(或呼叫 openav MCP 的 scaffold_world 工具),在它的 main.js 為這件作品寫一個 World:

  <描述這場表演,例如「一個遇到和諧和弦就綻放的水母世界」>

AGENTS.md 的規則:連續控制一律走參數,由 mapper 把訊號接過去。不要為了讓某個範例好看去改 packages/*。
完成的條件:npm test 通過,新範例載入時主控台零錯誤。

接上 MCP 伺服器

repo 內附一個零相依、走 stdio 的 MCP 伺服器。在 repo 裡打開 Claude Code,會自動從 .mcp.json 讀到它。其他客戶端,把路徑指到這個檔案:

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

工具

list_examples
有哪些作品,每件附一行摘要
read_doc
架構、寫一個世界、訊號、演出控制、代理約定
scaffold_world
拿一個範例當底,建立新的編號範例
run_checks
跑測試,和 CI 是同一道關卡
list_controllers
所有 MIDI 控制器設定檔,附控制項組成與未確認數量
read_profile
讀一台完整的設定檔,附好讀的 MIDI 對照
validate_profile
檢查設定檔 JSON,抓出和內建機型的衝突
scaffold_profile
為新控制器產一份合法骨架,每個數字都標未確認

給機器讀的

06 · 來歷

從一場演出裡抽出來

open-audiovisual 的核心來自《The Last Input 終局之前》(吳哲宇,2026),IRCAM 聲鬥陣 × C-LAB 在台北的 49.4 聲道空間聲響演出,演奏者用鋼琴餵養一個活著的數位世界。時間軸、和弦語意、多對多的 MIDI learn、OSC 批次傳送,都先撐過一整場十四個場景的演出,才整理成這裡的通用框架。從那之後的規則:框架只長真實演出要求過的功能。

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

Hydra 給你即興,cables 給你平台,Tone 給你聲音。open-audiovisual 給你一場演出,以及演出底下那一層不用再重做的東西。

README

接下來,摘自路線圖

  1. 錄下一場演出完整的訊號流,再播給任何一個世界
  2. 發布 npm 套件,用這套框架本身做文件網站
  3. WebGPU 世界轉接,給粒子與群體代理類的世界
  4. NDI 閘道,讓瀏覽器的畫面進入專業影像流程
  5. 多台電腦透過 WebRTC 共用同一個訊號空間
  6. 訂閱訊號、和人一起演奏的 AI 演奏者

完整路線圖 →