01 · 彈奏
MIDI 控制器圖鑑
每一顆旋鈕、打擊墊、琴鍵按下去送出什麼 MIDI 訊息,這個數字出自哪一份手冊,這裡都查好寫清楚了。用滑鼠或手指直接彈,接上你手邊的控制器,畫面會跟著你的手動,也可以用一行程式碼放進自己的網頁。
以前每換一套軟體,就要把手上的控制器重新對一次,CC 幾號、哪個頻道,每個人都在翻同一本手冊。這裡把每一台查一次、建好模型、附上出處,之後大家直接拿去用。
- 台裝置
- 21
- 種通用版面
- 6
- 個裝置上的控制項
- 1141
- 份引用出處
- 80
其中 214 個控制項標了未確認,還沒找到文件證實,數字先照目前的判讀。對不上的話,按「學習」再動一下那顆鈕,就會重新對應。
最後一則訊息轉一顆旋鈕試試,它的訊號和 MIDI 訊息會出現在這裡。
拖曳旋鈕和推桿 · 點打擊墊和琴鍵 · 也可以用 Tab 和方向鍵
02 · 目錄
目前收錄的控制器
卡片上的面板就是元件本身,可以直接拖、直接按。底下的標籤寫著這一台的數字是從哪裡查來的。
裝置 21
通用版面 6
找不到你那一台的話,先挑一個最接近的版面,按「學習」,再照順序把你手上的旋鈕和推桿各動一次。
來自 QLC+ 28
取自 QLC+ 的輸入設定檔(Apache-2.0):訊息和 LED 值是它們的,版面由這個專案自動產生。這裡還沒有人在實機上確認過,所以每個控制項都是未確認。每台都有自己的頁面,也能用你的機器驗證。
- American DJ
- MIDICON-2
- Behringer
- BCF2000 (Mackie mode) · BCF2000 · BCR2000 · LC2412 · X-Touch Compact · X-Touch Extender
- Elation
- MIDIcon
- KORG
- nanoKONTROL Studio · nanoKONTROL · nanoPAD · NanoPAD2
- Novation
- Launch Control · Launchpad MK2 · Launchpad Pro · Launchpad
- PMJ
- 9 Faders Controller · Circus · MidiKey
- ShowTec
- ShowMaster 24
- Worlde
- Easypad.12 · Orca PAD16
- Zoom
- R16
03 · 怎麼選
你彈的東西,要哪一台?
這張表的數字都是從設定檔數出來的,不會跟各台的頁面對不上。按下你需要的,表裡就只留下有這個的機型。
| 控制器 | 琴鍵 | 打擊墊 | 旋鈕 | 無段旋鈕 | 推桿 | 按鈕 | LED | 未確認 | 出處 | 適合 |
|---|---|---|---|---|---|---|---|---|---|---|
| AKAI LPD8 (mk2)AKAI Professional | – | 8 | 8 | – | – | – | – | 8 | 4 | 打點觸發 · 調很多參數 |
| AKAI APC mini mk2AKAI Professional | – | 64 | – | – | 9 | 17 | 有 | – | 6 | 打點觸發 · 混音推桿 |
| AKAI MIDImixAKAI Professional | – | – | 24 | – | 9 | 19 | 有 | – | 3 | 調很多參數 · 混音推桿 |
| AKAI MPK mini mk3AKAI Professional | 25 | 8 | 8 | – | – | – | – | 25 | 6 | 彈旋律 · 打點觸發 · 調很多參數 |
| AKAI APC40 mkIIAKAI Professional | – | 40 | 16 | 2 | 10 | 71 | 有 | 40 | 5 | 打點觸發 · 調很多參數 · 混音推桿 |
| Arturia MiniLab 3Arturia | 25 | 8 | 8 | 1 | 4 | – | – | 1 | 4 | 彈旋律 · 打點觸發 · 調很多參數 · 混音推桿 |
| Arturia KeyStep 37Arturia | 37 | – | 4 | – | – | 1 | – | 41 | 2 | 彈旋律 |
| Arturia BeatStepArturia | – | 16 | – | 16 | – | – | – | – | 4 | 打點觸發 · 調很多參數 |
| Behringer X-TOUCH MINIBehringer | – | – | – | 8 | 1 | 24 | – | – | 3 | 調很多參數 |
| DJ TechTools Midi Fighter TwisterDJ TechTools | – | – | – | 16 | – | 22 | 有 | 6 | 2 | 調很多參數 |
| Korg nanoKONTROL2KORG | – | – | 8 | – | 8 | 35 | 有 | – | 4 | 調很多參數 · 混音推桿 |
| Korg nanoKEY2KORG | 25 | – | – | – | – | 2 | – | 25 | 3 | 彈旋律 |
| Novation Launchpad Mini MK3Novation | – | 64 | – | – | – | 16 | 有 | 8 | 4 | 打點觸發 |
| Novation Launch Control XL (MK2)Novation | – | – | 24 | – | 8 | 24 | 有 | – | 5 | 調很多參數 · 混音推桿 |
| Novation Launch Control XL 3Novation | – | – | – | 24 | 8 | 16 | – | – | 7 | 調很多參數 · 混音推桿 |
| Novation Launchkey Mini MK3Novation | 25 | 16 | 8 | – | – | – | – | 34 | 6 | 彈旋律 · 打點觸發 · 調很多參數 |
| Novation Launchkey 25 MK4Novation | 25 | 16 | 8 | – | – | 1 | – | 8 | 6 | 彈旋律 · 打點觸發 · 調很多參數 |
| Novation Launchkey 37 MK4Novation | 37 | 16 | 8 | – | – | 1 | – | 8 | 6 | 彈旋律 · 打點觸發 · 調很多參數 |
| Novation Launchpad Pro MK3Novation | – | 64 | – | – | – | 41 | 有 | – | 2 | 打點觸發 |
| ODD BallODD | – | 3 | 4 | – | 3 | – | – | 10 | 1 | – |
| OP-1 fieldteenage engineering | 24 | – | – | 4 | – | 33 | – | – | 2 | 彈旋律 |
| 通用 8 旋鈕 + 8 打擊墊通用版面 | – | 8 | 8 | – | – | – | – | – | 1 | 打點觸發 · 調很多參數 |
| 通用 8 推桿通用版面 | – | – | – | – | 8 | – | – | – | 1 | 混音推桿 |
| 通用 16 打擊墊通用版面 | – | 16 | – | – | – | – | – | – | 1 | 打點觸發 |
| 通用 25 鍵鍵盤通用版面 | 25 | – | – | – | – | 1 | – | – | 1 | 彈旋律 |
| 通用 49 鍵鍵盤通用版面 | 49 | – | – | – | – | 1 | – | – | 1 | 彈旋律 |
| 通用 61 鍵鍵盤通用版面 | 61 | – | – | – | – | 1 | – | – | 1 | 彈旋律 |
旋鈕送出的是絕對位置;無段旋鈕可以一直轉,送出的是一格一格的變化。橫線代表沒有。「未確認」是數字只是我們目前的判讀、還沒找到文件證實的控制項。
「適合」是依控制項數量自動分的:有琴鍵 → 彈旋律;打擊墊 8 個以上 → 打點觸發;旋鈕加無段旋鈕 8 個以上 → 調很多參數;推桿 4 支以上 → 混音推桿。這是經驗法則,不是評測。
LED 回饋
LED 回饋是控制器自己的打擊墊和按鈕會亮燈。設定檔寫了這一項,就會註明哪個音符或 CC 讓哪個控制項亮、什麼數值是亮與滅。27 份設定檔裡有 8 份寫了:
- AKAI APC mini mk2
- AKAI MIDImix
- AKAI APC40 mkII
- DJ TechTools Midi Fighter Twister
- Korg nanoKONTROL2
- Novation Launchpad Mini MK3
- Novation Launch Control XL (MK2)
- Novation Launchpad Pro MK3
接上其中一台的時候,控制項一變動,OAV 就把這些訊息送到它的輸出埠,裝置連上時也會先送一次,所以燈可以跟著畫面上發生的事一起亮。
其餘 19 份還沒有 LED 訊息:OAV 不會讓它們亮燈,但每個控制項照樣可以彈、照樣送出各自的訊息。設定檔在每個控制項上可以加一項 led。
04 · 規格表
每一台都有自己的頁面
每台控制器一頁,附完整 MIDI 對照表、出處、嵌入碼,以及在 p5.js 裡各個旋鈕叫什麼名字。頁面在建置時直接從 JSON 檔產生,跟元件實際送出的訊息一定對得上。
| 控制器 | 廠牌 | 面板上有 | 頁面 |
|---|---|---|---|
| AKAI LPD8 (mk2) | AKAI Professional | 8 個打擊墊 · 8 顆旋鈕 | MIDI 對照表 → |
| AKAI APC mini mk2 | AKAI Professional | 64 個打擊墊 · 9 支推桿 · 17 顆按鈕 | MIDI 對照表 → |
| AKAI MIDImix | AKAI Professional | 24 顆旋鈕 · 9 支推桿 · 19 顆按鈕 | MIDI 對照表 → |
| AKAI MPK mini mk3 | AKAI Professional | 8 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 2 個滾輪 | MIDI 對照表 → |
| AKAI APC40 mkII | AKAI Professional | 40 個打擊墊 · 16 顆旋鈕 · 2 顆無段旋鈕 · 10 支推桿 · 71 顆按鈕 | MIDI 對照表 → |
| Arturia MiniLab 3 | Arturia | 8 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 1 顆無段旋鈕 · 4 支推桿 · 2 條觸控條 | MIDI 對照表 → |
| Arturia KeyStep 37 | Arturia | 37 個琴鍵 · 4 顆旋鈕 · 1 顆按鈕 · 2 條觸控條 | MIDI 對照表 → |
| Arturia BeatStep | Arturia | 16 個打擊墊 · 16 顆無段旋鈕 | MIDI 對照表 → |
| Behringer X-TOUCH MINI | Behringer | 8 顆無段旋鈕 · 1 支推桿 · 24 顆按鈕 | MIDI 對照表 → |
| DJ TechTools Midi Fighter Twister | DJ TechTools | 16 顆無段旋鈕 · 22 顆按鈕 | MIDI 對照表 → |
| Korg nanoKONTROL2 | KORG | 8 顆旋鈕 · 8 支推桿 · 35 顆按鈕 | MIDI 對照表 → |
| Korg nanoKEY2 | KORG | 25 個琴鍵 · 2 顆按鈕 · 1 條觸控條 | MIDI 對照表 → |
| Novation Launchpad Mini MK3 | Novation | 64 個打擊墊 · 16 顆按鈕 | MIDI 對照表 → |
| Novation Launch Control XL (MK2) | Novation | 24 顆旋鈕 · 8 支推桿 · 24 顆按鈕 | MIDI 對照表 → |
| Novation Launch Control XL 3 | Novation | 24 顆無段旋鈕 · 8 支推桿 · 16 顆按鈕 | MIDI 對照表 → |
| Novation Launchkey Mini MK3 | Novation | 16 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 2 條觸控條 | MIDI 對照表 → |
| Novation Launchkey 25 MK4 | Novation | 16 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 1 顆按鈕 · 2 個滾輪 | MIDI 對照表 → |
| Novation Launchkey 37 MK4 | Novation | 16 個打擊墊 · 37 個琴鍵 · 8 顆旋鈕 · 1 顆按鈕 · 2 個滾輪 | MIDI 對照表 → |
| Novation Launchpad Pro MK3 | Novation | 64 個打擊墊 · 41 顆按鈕 | MIDI 對照表 → |
| ODD Ball | ODD | 3 個打擊墊 · 4 顆旋鈕 · 3 支推桿 | MIDI 對照表 → |
| OP-1 field | teenage engineering | 24 個琴鍵 · 4 顆無段旋鈕 · 33 顆按鈕 | MIDI 對照表 → |
| 通用 8 旋鈕 + 8 打擊墊 | 通用版面 | 8 個打擊墊 · 8 顆旋鈕 | MIDI 對照表 → |
| 通用 8 推桿 | 通用版面 | 8 支推桿 | MIDI 對照表 → |
| 通用 16 打擊墊 | 通用版面 | 16 個打擊墊 | MIDI 對照表 → |
| 通用 25 鍵鍵盤 | 通用版面 | 25 個琴鍵 · 1 顆按鈕 · 2 個滾輪 | MIDI 對照表 → |
| 通用 49 鍵鍵盤 | 通用版面 | 49 個琴鍵 · 1 顆按鈕 · 2 個滾輪 | MIDI 對照表 → |
| 通用 61 鍵鍵盤 | 通用版面 | 61 個琴鍵 · 1 顆按鈕 · 2 個滾輪 | MIDI 對照表 → |
05 · 嵌入
放進你的網頁
一行 HTML、一個 iframe,或一段 JavaScript 都可以。先選機型和選項,預覽和下面每一段程式碼會跟著換。
即時預覽
最後一個事件,你的程式收到的樣子
彈一下預覽,它的 control 事件會出現在這裡。
-
一行,任何網頁
不用 import map,不用建置。Shadow DOM 讓你網頁的 CSS 進不來,控制器的 CSS 也出不去。
<script type="module" src="https://openaudiovisual.com/packages/midi/element.js"></script> <oav-controller profile="akai-lpd8" readout></oav-controller> -
iframe
給只能放 iframe 的地方。每個事件都會用
postMessage傳出來,你也可以把set、ingest傳回去。<iframe src="https://openaudiovisual.com/embed/controller/?profile=akai-lpd8&readout" width="720" height="216" style="border:0;max-width:100%" allow="midi" title="AKAI LPD8 (mk2)"></iframe> <script> // every control the visitor plays arrives here addEventListener('message', (e) => { if (e.data?.source !== 'openav' || e.data.type !== 'control') return; console.log(e.data.detail.signal, e.data.detail.value); }); </script> -
JavaScript,任何框架
createController()就是不帶元素的元素:React、Vue、Svelte 或純 JS 都能用。不畫面板也能跑。import { createController } from 'https://openaudiovisual.com/packages/midi/index.js'; const ctl = createController('akai-lpd8'); ctl.mount(document.querySelector('#controller')); // optional: headless works too ctl.on('control', (e) => console.log(e.signal, e.value)); ctl.connectHardware(); // optional: follow the real one (asks for Web MIDI) -
聽它
事件會冒泡,也會穿過 shadow root。每個事件內容都是單純的 JSON:控制項、數值、訊號名稱、MIDI 訊息和位元組。
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: 64 } 'ui' | 'hardware' }); el.addEventListener('noteon', (e) => console.log(e.detail.note, e.detail.velocity)); await el.ready; el.set('k1', 0.5); // move a control: fires 'control', reaches MIDI out el.set('pad1', 1); el.set('pad1', 0); // strike and release el.ingest([0xb0, 70, 64]); // MIDI from anywhere (a WebSocket, another tab) -
拿它彈你的 DAW
在螢幕上彈的,會變成真的 MIDI 送出去,進到 Ableton Live、TouchDesigner、Resolume,或任何收 MIDI 輸入的軟體。
<!-- what you play on this controller → the IAC bus (macOS) → Ableton, TouchDesigner, Resolume --> <script type="module" src="https://openaudiovisual.com/packages/midi/element.js"></script> <oav-controller profile="akai-lpd8" midi-out="IAC" readout></oav-controller> <!-- Windows: midi-out="loopMIDI" · let the visitor pick a port: midi-out="ask" -->
元素一覽
| 名稱 | 種類 | 做什麼 |
|---|---|---|
profile | 屬性 | 哪一台:id、短名稱,或一個設定檔 JSON 的網址 |
layout | 屬性 | auto、face(照實物的樣子)或 stack(為直式畫面重新排) |
hardware | 屬性 | 跟著實體裝置動:on、ask(顯示按鈕)或埠名稱 |
midi-out | 屬性 | 把彈的內容送到輸出埠:埠名稱、/正規表示式/,或 ask |
channel | 屬性 | 1–16:把每個控制項移到你機器設定的頻道 |
picker · readout · learn · follow | 屬性 | 裝置選單、最後一則訊息、學習按鈕、接上哪台就切到哪台 |
control | 事件 | 任何控制項動了:id、type、value、raw、signal、message、bytes、source |
noteon · noteoff | 事件 | 打擊墊、琴鍵和送音符的按鈕,附音高和力度 |
connect · disconnect · status | 事件 | 硬體埠接上或拔掉,以及硬體與 MIDI 輸出的狀態 |
set(id, value) · get(id) · values() · reset() | 方法 | 用程式轉一個控制項、讀一個、全部讀、全部歸零 |
ingest(bytes) · send(bytes) | 方法 | 從任何地方餵 MIDI 進來(面板會跟著動)· 把位元組送到輸出埠 |
on(name, fn) | 方法 | 訂閱事件,回傳取消訂閱的函式 |
06 · 自己建一台
加入你的控制器
一台控制器就是一個 JSON 檔。手冊裡有 MIDI 實作表,就照著抄,數字會完全準確。手冊沒寫的,就在檔案裡註明是怎麼查到的。
- 從最接近的檔案開始 複製一台長得像你那台的裝置,或一個通用版面。面板是用面板單位排在格線上的區塊,所以螢幕上的版本看起來就像桌上那台。
- 寫下每個控制項送什麼 類型、訊息(
cc、note、pitchbend)、頻道、編號。無段旋鈕寫明相對值怎麼編碼,按鈕寫是按住還是切換,有 LED 就寫哪個訊息會點亮它。 - 每個數字都要有出處 每份出處都有標題、連結,以及它證實了什麼。沒人確認過的數字,標上
"verified": false並寫一句說明。 - 驗證
validateProfile()會用文字列出每一個問題,沒有問題就回傳空陣列。測試會對每個內建設定檔跑一次。 - 送出前先試
<oav-controller profile="./my-pads.json">可以從網址載入設定檔,先在你自己的網頁上彈彈看。 - 開一個 pull request 把檔案放進
packages/midi/profiles/,在profiles/index.js加上它。告訴我們你在哪台機器、哪個韌體上確認過。
設定檔長這樣
{
"id": "my-pads", "short": "mypads", "name": "My Pads", "maker": "…", "kind": "device",
"match": { "ports": ["my\\s*pads"] },
"sources": [{ "title": "My Pads manual, MIDI implementation chart", "url": "https://…",
"note": "pads: notes 36–43 on channel 10" }],
"face": { "w": 100, "h": 30, "label": "MY PADS" },
"sections": [{ "id": "pads", "x": 2, "y": 4, "w": 60, "h": 24, "cols": 4, "rows": 2,
"controls": ["pad1", "pad2", "…"] }],
"controls": [
{ "id": "pad1", "type": "pad", "msg": "note", "ch": 10, "note": 36, "label": "1" },
{ "id": "k1", "type": "knob", "msg": "cc", "cc": 70, "label": "K1",
"verified": false, "note": "default not printed in the manual" }
]
}檢查它
// check.mjs — run: node check.mjs
import { validateProfile } from './packages/midi/profiles.js';
import p from './packages/midi/profiles/my-pads.json' with { type: 'json' };
console.log(validateProfile(p)); // [] = valid; otherwise every problem, in words控制項類型
| 類型 | 送出 | 訊號數值 |
|---|---|---|
knob · fader | CC,絕對值 0–127 | 0..1 |
encoder | CC,相對值(offset64、offset16、twos、signbit) | 位置 0..1,另有 /delta 步數 |
pad | 帶力度的音符(或 CC),可能有觸後 | 按住時是力度,放開是 0,另有 /hit |
button | 音符或 CC,按住或切換 | 0 或 1 |
keys | 一段音域 | /on、/off 脈衝,按住時 n<音高> |
wheel · strip | CC 或彎音,可能會回彈 | 0..1,雙極時 −1..1 |
沒有說明書?用學習模式
選一個通用版面,按「學習」,照順序動一次你的控制項,版面會自己填上你那台送出的訊息。exportMapping() 把結果存成 JSON,就是一份設定檔的起點。
手上有機器?來驗證
驗證頁會一格一格亮起,比對機器送出的訊息和檔案。對上的標成已驗證,旁邊寫上你的名字、日期和韌體,對不上的變成一筆修正。