open-audiovisual
搜尋 GitHub

01 · 彈奏

MIDI 控制器圖鑑

每一顆旋鈕、打擊墊、琴鍵按下去送出什麼 MIDI 訊息,這個數字出自哪一份手冊,這裡都查好寫清楚了。用滑鼠或手指直接彈,接上你手邊的控制器,畫面會跟著你的手動,也可以用一行程式碼放進自己的網頁。

以前每換一套軟體,就要把手上的控制器重新對一次,CC 幾號、哪個頻道,每個人都在翻同一本手冊。這裡把每一台查一次、建好模型、附上出處,之後大家直接拿去用。

台裝置
21
種通用版面
6
個裝置上的控制項
1141
份引用出處
80

其中 214 個控制項標了未確認,還沒找到文件證實,數字先照目前的判讀。對不上的話,按「學習」再動一下那顆鈕,就會重新對應。

MINILAB 3MiniLab 3ShiftHoldOct−Oct+PitchModMainKNOBS12345678FADERSS1S2S3S4PADS

最後一則訊息轉一顆旋鈕試試,它的訊號和 MIDI 訊息會出現在這裡。

Arturia MiniLab 3 48 個控制項 規格表 全螢幕 ↗

拖曳旋鈕和推桿 · 點打擊墊和琴鍵 · 也可以用 Tab 和方向鍵

02 · 目錄

目前收錄的控制器

卡片上的面板就是元件本身,可以直接拖、直接按。底下的標籤寫著這一台的數字是從哪裡查來的。

篩選:有這些控制的

裝置 21

通用版面 6

找不到你那一台的話,先挑一個最接近的版面,按「學習」,再照順序把你手上的旋鈕和推桿各動一次。

來自 QLC+ 28

取自 QLC+ 的輸入設定檔(Apache-2.0):訊息和 LED 值是它們的,版面由這個專案自動產生。這裡還沒有人在實機上確認過,所以每個控制項都是未確認。每台都有自己的頁面,也能用你的機器驗證。

AKAI Professional
APC Mini · APC20 · APC40
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
M-VAVE
SMC-Mixer · SMC-PAD
Novation
Launch Control · Launchpad MK2 · Launchpad Pro · Launchpad
PMJ
9 Faders Controller · Circus · MidiKey
ShowTec
ShowMaster 24
Worlde
Easypad.12 · Orca PAD16
Zoom
R16

沒有你那台?

開一張 issue,寫廠牌型號、手上有沒有這台、手冊的連結。設定檔就是一個 JSON 檔,想自己寫的話,步驟在加入你的控制器。

03 · 怎麼選

你彈的東西,要哪一台?

這張表的數字都是從設定檔數出來的,不會跟各台的頁面對不上。按下你需要的,表裡就只留下有這個的機型。

我要
每一台上面有什麼,從設定檔數出來
控制器琴鍵打擊墊旋鈕無段旋鈕推桿按鈕LED未確認出處適合
AKAI LPD8 (mk2)AKAI Professional –88––– – 8 4 打點觸發 · 調很多參數
AKAI APC mini mk2AKAI Professional –64––917 有 – 6 打點觸發 · 混音推桿
AKAI MIDImixAKAI Professional ––24–919 有 – 3 調很多參數 · 混音推桿
AKAI MPK mini mk3AKAI Professional 2588––– – 25 6 彈旋律 · 打點觸發 · 調很多參數
AKAI APC40 mkIIAKAI Professional –401621071 有 40 5 打點觸發 · 調很多參數 · 混音推桿
Arturia MiniLab 3Arturia 258814– – 1 4 彈旋律 · 打點觸發 · 調很多參數 · 混音推桿
Arturia KeyStep 37Arturia 37–4––1 – 41 2 彈旋律
Arturia BeatStepArturia –16–16–– – – 4 打點觸發 · 調很多參數
Behringer X-TOUCH MINIBehringer –––8124 – – 3 調很多參數
DJ TechTools Midi Fighter TwisterDJ TechTools –––16–22 有 6 2 調很多參數
Korg nanoKONTROL2KORG ––8–835 有 – 4 調很多參數 · 混音推桿
Korg nanoKEY2KORG 25––––2 – 25 3 彈旋律
Novation Launchpad Mini MK3Novation –64–––16 有 8 4 打點觸發
Novation Launch Control XL (MK2)Novation ––24–824 有 – 5 調很多參數 · 混音推桿
Novation Launch Control XL 3Novation –––24816 – – 7 調很多參數 · 混音推桿
Novation Launchkey Mini MK3Novation 25168––– – 34 6 彈旋律 · 打點觸發 · 調很多參數
Novation Launchkey 25 MK4Novation 25168––1 – 8 6 彈旋律 · 打點觸發 · 調很多參數
Novation Launchkey 37 MK4Novation 37168––1 – 8 6 彈旋律 · 打點觸發 · 調很多參數
Novation Launchpad Pro MK3Novation –64–––41 有 – 2 打點觸發
ODD BallODD –34–3– – 10 1 –
OP-1 fieldteenage engineering 24––4–33 – – 2 彈旋律
通用 8 旋鈕 + 8 打擊墊通用版面 –88––– – – 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 份寫了:

接上其中一台的時候,控制項一變動,OAV 就把這些訊息送到它的輸出埠,裝置連上時也會先送一次,所以燈可以跟著畫面上發生的事一起亮。

其餘 19 份還沒有 LED 訊息:OAV 不會讓它們亮燈,但每個控制項照樣可以彈、照樣送出各自的訊息。設定檔在每個控制項上可以加一項 led。

04 · 規格表

每一台都有自己的頁面

每台控制器一頁,附完整 MIDI 對照表、出處、嵌入碼,以及在 p5.js 裡各個旋鈕叫什麼名字。頁面在建置時直接從 JSON 檔產生,跟元件實際送出的訊息一定對得上。

控制器廠牌面板上有頁面
AKAI LPD8 (mk2)AKAI Professional8 個打擊墊 · 8 顆旋鈕MIDI 對照表 →
AKAI APC mini mk2AKAI Professional64 個打擊墊 · 9 支推桿 · 17 顆按鈕MIDI 對照表 →
AKAI MIDImixAKAI Professional24 顆旋鈕 · 9 支推桿 · 19 顆按鈕MIDI 對照表 →
AKAI MPK mini mk3AKAI Professional8 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 2 個滾輪MIDI 對照表 →
AKAI APC40 mkIIAKAI Professional40 個打擊墊 · 16 顆旋鈕 · 2 顆無段旋鈕 · 10 支推桿 · 71 顆按鈕MIDI 對照表 →
Arturia MiniLab 3Arturia8 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 1 顆無段旋鈕 · 4 支推桿 · 2 條觸控條MIDI 對照表 →
Arturia KeyStep 37Arturia37 個琴鍵 · 4 顆旋鈕 · 1 顆按鈕 · 2 條觸控條MIDI 對照表 →
Arturia BeatStepArturia16 個打擊墊 · 16 顆無段旋鈕MIDI 對照表 →
Behringer X-TOUCH MINIBehringer8 顆無段旋鈕 · 1 支推桿 · 24 顆按鈕MIDI 對照表 →
DJ TechTools Midi Fighter TwisterDJ TechTools16 顆無段旋鈕 · 22 顆按鈕MIDI 對照表 →
Korg nanoKONTROL2KORG8 顆旋鈕 · 8 支推桿 · 35 顆按鈕MIDI 對照表 →
Korg nanoKEY2KORG25 個琴鍵 · 2 顆按鈕 · 1 條觸控條MIDI 對照表 →
Novation Launchpad Mini MK3Novation64 個打擊墊 · 16 顆按鈕MIDI 對照表 →
Novation Launch Control XL (MK2)Novation24 顆旋鈕 · 8 支推桿 · 24 顆按鈕MIDI 對照表 →
Novation Launch Control XL 3Novation24 顆無段旋鈕 · 8 支推桿 · 16 顆按鈕MIDI 對照表 →
Novation Launchkey Mini MK3Novation16 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 2 條觸控條MIDI 對照表 →
Novation Launchkey 25 MK4Novation16 個打擊墊 · 25 個琴鍵 · 8 顆旋鈕 · 1 顆按鈕 · 2 個滾輪MIDI 對照表 →
Novation Launchkey 37 MK4Novation16 個打擊墊 · 37 個琴鍵 · 8 顆旋鈕 · 1 顆按鈕 · 2 個滾輪MIDI 對照表 →
Novation Launchpad Pro MK3Novation64 個打擊墊 · 41 顆按鈕MIDI 對照表 →
ODD BallODD3 個打擊墊 · 4 顆旋鈕 · 3 支推桿MIDI 對照表 →
OP-1 fieldteenage engineering24 個琴鍵 · 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 都可以。先選機型和選項,預覽和下面每一段程式碼會跟著換。

版面
顯示
配色

即時預覽

AKAI LPD8PADSKNOBSK1K2K3K4K5K6K7K8

最後一個事件,你的程式收到的樣子

彈一下預覽,它的 control 事件會出現在這裡。
  1. 一行,任何網頁

    不用 import map,不用建置。Shadow DOM 讓你網頁的 CSS 進不來,控制器的 CSS 也出不去。

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

    給只能放 iframe 的地方。每個事件都會用 postMessage 傳出來,你也可以把 set、ingest 傳回去。

    html
    <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>
  3. JavaScript,任何框架

    createController() 就是不帶元素的元素:React、Vue、Svelte 或純 JS 都能用。不畫面板也能跑。

    javascript
    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)
  4. 聽它

    事件會冒泡,也會穿過 shadow root。每個事件內容都是單純的 JSON:控制項、數值、訊號名稱、MIDI 訊息和位元組。

    javascript
    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)
  5. 拿它彈你的 DAW

    在螢幕上彈的,會變成真的 MIDI 送出去,進到 Ableton Live、TouchDesigner、Resolume,或任何收 MIDI 輸入的軟體。

    html
    <!-- 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" -->

MIDI 輸出到 Ableton、TouchDesigner、Resolume

  1. macOS:打開音訊 MIDI 設定 → 視窗 → 顯示 MIDI 工作室,雙擊 IAC 驅動程式,勾選「裝置已上線」。
  2. Windows 11:內建的 Windows MIDI Services 有 loopback 埠(我們沒有實測)。舊版 Windows:安裝 loopMIDI,新增一個埠。
  3. Ableton Live:設定 → Link, Tempo & MIDI → 把 IAC 或 loopMIDI 輸入的 Track 和 Remote 打開。TouchDesigner:在那個裝置上放一個 MIDI In CHOP。Resolume:Preferences → MIDI。

Chrome 和 Edge 有 Web MIDI,Firefox 會先問你是否允許這個網站。Safari 和 iPad 沒有:控制器照樣能彈、每個事件照樣送出,MIDI 輸出會顯示無法使用。

不會繞成迴圈。引擎本來就不聽 IAC 輸入,跟輸出同名的輸入(loopMIDI 自己的回音)也會靜音。實體控制器的動作不會再轉送一次,因為你的軟體本來就收得到那台。

使用統計:每個嵌入在載入頁面時送出一筆匿名紀錄(哪種嵌入、哪台控制器、網頁的網域,不寫 cookie,也不送你彈了什麼)。加上 telemetry="off" 就關掉。實際送了哪些內容。

iframe 訊息

iframe 會把每個事件傳給上層網頁,也接受幾個指令。加上 &frame=名稱 可以分辨多個 iframe,加上 &origin=https://你的網站 就只和你的網頁溝通。

postMessage
// iframe → your page, for every event
{ source: 'openav', v: 1, type: 'control', frame: 'pads',
  detail: { id, type, value, raw, signal, message, bytes, source } }
// type: ready · control · noteon · noteoff · connect · disconnect · status · profilechange · error

// your page → iframe
const win = document.querySelector('iframe').contentWindow;
win.postMessage({ target: 'openav', type: 'set', id: 'k1', value: 0.5 }, '*');
win.postMessage({ target: 'openav', type: 'ingest', bytes: [0xb0, 70, 64] }, '*');
win.postMessage({ target: 'openav', type: 'get' }, '*');   // answers with type 'values'
// also: press · release · reset · profile · layout

元素一覽

名稱種類做什麼
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)方法訂閱事件,回傳取消訂閱的函式

全部的細節,包括每個事件的每個欄位:套件的 README →

06 · 自己建一台

加入你的控制器

一台控制器就是一個 JSON 檔。手冊裡有 MIDI 實作表,就照著抄,數字會完全準確。手冊沒寫的,就在檔案裡註明是怎麼查到的。

  1. 從最接近的檔案開始 複製一台長得像你那台的裝置,或一個通用版面。面板是用面板單位排在格線上的區塊,所以螢幕上的版本看起來就像桌上那台。
  2. 寫下每個控制項送什麼 類型、訊息(cc、note、pitchbend)、頻道、編號。無段旋鈕寫明相對值怎麼編碼,按鈕寫是按住還是切換,有 LED 就寫哪個訊息會點亮它。
  3. 每個數字都要有出處 每份出處都有標題、連結,以及它證實了什麼。沒人確認過的數字,標上 "verified": false 並寫一句說明。
  4. 驗證 validateProfile() 會用文字列出每一個問題,沒有問題就回傳空陣列。測試會對每個內建設定檔跑一次。
  5. 送出前先試 <oav-controller profile="./my-pads.json"> 可以從網址載入設定檔,先在你自己的網頁上彈彈看。
  6. 開一個 pull request 把檔案放進 packages/midi/profiles/,在 profiles/index.js 加上它。告訴我們你在哪台機器、哪個韌體上確認過。

設定檔長這樣

packages/midi/profiles/my-pads.json
{
  "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
// 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 · faderCC,絕對值 0–1270..1
encoderCC,相對值(offset64、offset16、twos、signbit)位置 0..1,另有 /delta 步數
pad帶力度的音符(或 CC),可能有觸後按住時是力度,放開是 0,另有 /hit
button音符或 CC,按住或切換0 或 1
keys一段音域/on、/off 脈衝,按住時 n<音高>
wheel · stripCC 或彎音,可能會回彈0..1,雙極時 −1..1

沒有說明書?用學習模式

選一個通用版面,按「學習」,照順序動一次你的控制項,版面會自己填上你那台送出的訊息。exportMapping() 把結果存成 JSON,就是一份設定檔的起點。

手上有機器?來驗證

驗證頁會一格一格亮起,比對機器送出的訊息和檔案。對上的標成已驗證,旁邊寫上你的名字、日期和韌體,對不上的變成一筆修正。