MTX OSC / MIDI Bridge

OSC and MIDI bridge for Yamaha MTX3 and MTX5-D, with a web-based mapping GUI.

Overview

This project converts the Yamaha MTX remote control protocol into:

• OSC for bridge-to-bridge communication
• MIDI for controller input and feedback
• HTTP / WebSocket for a browser-based mapping UI

Current stack:

• Go: MTX <-> OSC bridge
• Node.js / TypeScript: MIDI <-> OSC bridge, HTTP API, WebSocket
• Vue 3: mapping GUI

This implementation is designed against the Yamaha remote control protocol specification:

• MTX3 MTX5-D MRX7-D XMV Series EXi8 EXo8 Remote Control Protocol Specifications V4.0.0
• Yamaha PDF (Japanese)

Architecture

Yamaha MTX3 / MTX5-D
  <-> TCP 49280
mtx-osc-bridge (Go)
  <-> OSC UDP 9000 / 9001
midi-osc-bridge (Node.js / TypeScript)
  <-> HTTP 3000 / WebSocket
gui (Vue 3 / Vite)

Protocol Flow

sequenceDiagram
    participant GUI as "Vue GUI"
    participant Node as "midi-osc-bridge"
    participant Go as "mtx-osc-bridge"
    participant MTX as "Yamaha MTX"
    participant MIDI as "MIDI Controller"

    Note over Go,MTX: Session startup
    Go->>MTX: TCP connect :49280
    loop until ready
        Go->>MTX: devstatus runmode
        MTX-->>Go: OK / NOTIFY devstatus runmode "normal"
    end
    Go->>MTX: scpmode encoding utf8
    Go->>MTX: scpmode valuetype normalized
    Go->>MTX: scpmode resolution 1000
    Go->>MTX: scpmode keepalive 30000
    Go->>MTX: getn for known parameters
    MTX-->>Go: OK getn / NOTIFY setn
    Go-->>Node: OSC state updates
    Node-->>GUI: WebSocket status / parameter snapshot

    Note over MIDI,MTX: Normal control path
    MIDI->>Node: CC / NOTE input
    Node->>Node: resolve mapping
    Node->>Go: OSC message
    Go->>MTX: setn
    MTX-->>Go: OK setn / NOTIFY setn
    Go-->>Node: OSC update
    Node-->>GUI: WebSocket parameter update

    Note over GUI,MTX: Resync path
    GUI->>Node: POST /api/osc/resync
    Node->>Go: /mtx/system/resync
    Go->>MTX: getn for known parameters
    MTX-->>Go: OK getn
    Go-->>Node: OSC updates
    Node-->>GUI: settled parameter snapshot

Loading

Features

• MTX startup handshake and keepalive
• setn / getn normalized parameter control
• Input and zone ON / FADER mapping
• STIN and FX RTN mapping support
• MIDI learn workflow in the browser
• toggle / latch mode for binary controls
• invert support
• Real-time MTX parameter display in the mapping UI
• Device mode switch for MTX3 / MTX5-D

Repository Layout

• mtx-osc-bridge
• midi-osc-bridge
• gui

Requirements

• A reachable Yamaha MTX device
• MTX remote control available on TCP port 49280
• Go
• Node.js
• pnpm
• A working native build environment if you want real MIDI I/O through @julusian/midi

Configuration

The Go bridge reads a local mtx-osc-bridge/config.json file. An example file is included here:

• mtx-osc-bridge/config.example.json

Example:

{
  "mtx_host": "127.0.0.1",
  "mtx_port": 49280,
  "device_mode": "mtx3",
  "keepalive_interval": "25s",
  "ready_timeout": "30s",
  "osc_listen_addr": ":9000",
  "osc_target_host": "127.0.0.1",
  "osc_target_port": 9001
}

Node runtime settings are stored locally in:

• midi-osc-bridge/config/settings.example.json

These local runtime files are intentionally ignored by git.

Running

Start everything:

cd /Users/funama/development/MTX3_OSC
pnpm dev

Start each part separately:

cd /Users/funama/development/MTX3_OSC
pnpm dev:go
pnpm dev:node
pnpm dev:gui

Endpoints:

• GUI: http://localhost:5173
• Node API: http://localhost:3000

Development Commands

Go:

cd /Users/funama/development/MTX3_OSC/mtx-osc-bridge
go build ./cmd/mtx-osc-bridge
go test ./...

Node:

cd /Users/funama/development/MTX3_OSC/midi-osc-bridge
pnpm install
pnpm build
pnpm dev

GUI:

cd /Users/funama/development/MTX3_OSC/gui
pnpm install
pnpm dev
pnpm build

OSC Address Scheme

Main address patterns:

• /mtx/input/ch/{1-16}/fader
• /mtx/input/ch/{1-16}/on
• /mtx/input/stin/{1l|1r|2l|2r|3l|3r}/fader
• /mtx/input/stin/{1l|1r|2l|2r|3l|3r}/on
• /mtx/input/fxrtn/{1l|1r|2l|2r}/fader
• /mtx/input/fxrtn/{1l|1r|2l|2r}/on
• /mtx/zone/out/{1-16}/fader
• /mtx/zone/out/{1-16}/on
• /mtx/preset/recall
• /mtx/system/resync

GUI Workflow

1. Open Mappings
2. Select MIDI input and output ports
3. Turn Mapping Mode on
4. Click a target cell
5. Move the MIDI control you want to assign

MIDI ports connect automatically when selected. Mappings are saved immediately after capture.

Additional options:

• Latch / Toggle for binary controls
• to 0dB / to +10dB for faders
• Invert

Value Handling

• MTX normalized range: 0-1000
• GUI / OSC fader range: 0.0-1.0
• Current to 0dB behavior uses 127 -> 0.805
• to +10dB uses 127 -> 1.0

API

Main endpoints:

• GET /api/status
• GET /api/midi/ports
• POST /api/midi/connect
• GET /api/mappings
• POST /api/mappings
• GET /api/osc/addresses
• GET /api/osc/params
• POST /api/osc/resync
• POST /api/osc/send
• POST /api/settings

Known Limitations

• CH17-24 for MTX5-D is still a TODO in the GUI
• Fader MIDI feedback is currently disabled
• MTX returned values do not always exactly match the sent value
• Yamaha MTX protocol documentation is not included in this repository

License

MIT