# FS1R Performance Selector (M4L)

A Max for Live MIDI effect device that lets you select and browse
performances on a YAMAHA FS1R FM tone generator directly from Ableton Live —
512 performances (INT + PR-A/PR-B/PR-C banks) with a category search, direct
CoreMIDI connection to the hardware, front-panel ATTACK/RELEASE/FORMANT/FM/
REV knob control, and correct recall when you save and reload a Live Set.

## Features

- A single integrated front panel (700×168px) drawn entirely in the device —
  Bank/Perform display, Channel, Device#, Port, Category, Preset list, and
  Status are all part of the panel; there are no separate dropdown menus or
  text fields to open elsewhere in the device UI
- Bank / Perform / Channel controls that automatically send Bank Select MSB
  (CC0 = 63) → Bank Select LSB (CC32, 64–67 depending on bank) → Program
  Change in the correct order
- VALUE ▲▼ steppers: a single continuous index (0–511) that scrolls through
  every bank in hardware order (INT → PR-A → PR-B → PR-C), fully synced
  with Bank/Perform and automatable/MIDI-mappable in Live
- Category search: the FS1R's own SEARCH mode ignores Program Change while
  active (verified on hardware), so search is implemented entirely on the
  M4L side instead — filter by category from a popup, then jump straight to
  a performance by name, with the FS1R staying in ordinary PLAY mode the
  whole time
- ATTACK / RELEASE / FORMANT / FM front-panel knobs that send CC73 / CC72 /
  CC80 / CC81 — Formant and FM controller numbers are re-read from the
  FS1R's own SYSTEM setting on Fetch, so the knobs track the unit's actual
  assignment even if it's been changed
- A fifth **REV** (Reverb Return) knob that controls the Performance Edit
  Buffer's Reverb Return level directly via a SysEx parameter change
  (there is no CC for this parameter on the FS1R)
- On-panel LCD that shows the performance name instantly from the bundled
  database, then refreshes with the real name via SysEx (picks up
  user-renamed INT performances)
- Direct CoreMIDI I/O via a bundled `midibridge` helper — no virtual MIDI
  cable or extra routing required, just pick the port from the device
- Bank/Perform/VALUE/Channel/Device/knob values are saved as Live device
  parameters, so your selection is recalled correctly when a Live Set is
  reloaded (including graceful handling of the "midibridge not yet
  connected" moment right after load)

## Requirements

- macOS (verified on Apple Silicon; see Known limitations for Intel/Windows)
- Ableton Live 11 or later, with Max for Live installed
- A YAMAHA FS1R connected via CoreMIDI — either a USB-MIDI interface, a
  MIDI interface's DIN ports, or a network MIDI session that exposes a
  CoreMIDI port for the FS1R
- The FS1R's MIDI IN must be reachable from the Mac; SysEx name fetch also
  requires the FS1R's MIDI OUT to be routed back in

## Installation

1. Unzip the downloaded package.
2. Double-click **Install.command**.
   - Approve any macOS security prompt if one appears (see Troubleshooting).
   - This copies the device's dependency files into
     `~/Documents/Max 9/Library/cotofu/` (and also
     `~/Documents/Max 8/Library/cotofu/` if a Max 8 folder exists), and
     clears the macOS quarantine flag on the bundled `midibridge` binary.
3. Move `FS1R Perform Select.amxd` into your Ableton Live **User Library**
   (Live > Places > User Library, typically
   `~/Music/Ableton/User Library/Presets/MIDI Effects/Max MIDI Effect/`).
4. In Live, drag the device onto a MIDI track routed to the FS1R.

## Usage

1. **PORT**: click the Port row to open a popup and pick the CoreMIDI
   output port connected to your FS1R. The device connects directly — no
   separate MIDI routing in Live's I/O is required for sending performance
   changes. On load, the device auto-connects to any port whose name
   contains "FS1R".
2. **FETCH**: click to request the FS1R's System settings via SysEx. This
   reads back the performance MIDI channel into Ch, the Formant/FM CC
   assignment for the knobs, and the current performance's name. Note the
   FS1R does not expose which bank/number is currently selected over
   SysEx, so Fetch cannot sync the Bank/Perform display itself — that stays
   at whatever the device last sent.
3. Select a performance either by:
   - the **VALUE ▲▼** steppers (single continuous scroll across all 512
     performances), or
   - the **Bank / Pfm** display directly, or
   - the **Category / Preset** search — pick a category from the popup to
     filter, then pick a performance by name from the filtered list; the
     bank/perform change is sent immediately.
4. **ATTACK / RELEASE / FORMANT / FM** knobs: drag up/down to send the
   corresponding CC live, mirroring the FS1R's own front panel.
5. **REV** knob: drag up/down to send a SysEx parameter change that sets
   Reverb Return on the Performance Edit Buffer directly (no CC involved).
6. **RESEND**: click to resend the current Bank/Perform/Channel selection —
   useful after power-cycling the FS1R or reconnecting MIDI.
7. Bank, Perform, Channel, Device, Value, and all five knob values are
   saved as Live device parameters: automate them, MIDI-map them to a
   hardware controller, and they will be recalled when you reload the Live
   Set (the device waits for the bridge to reconnect before re-syncing, so
   a saved selection is not silently overwritten).

## Getting sound

This device **selects performances and sends front-panel CCs only — it
does not carry notes or audio.** To play and hear the FS1R, set up sound
the usual way for external hardware. The simplest is Live's built-in
**External Instrument** device on the same track:

- *MIDI To*: the MIDI port your FS1R is connected to
- *Audio From*: the audio interface inputs the FS1R's outputs are wired to

Alternatively, monitor the FS1R through your mixer and just use this
device for performance selection and knob control.

## Separate MIDI in/out ports

The Port menu opens the input and output that share the same port name.
If your setup needs *different* ports for each direction (for example,
sending through one interface and receiving through another), use Live's
own routing instead:

1. Set Port to **"Track (Live routing)"**
2. Choose the *input* with the track's **MIDI From**
3. Choose the *output* with an **External Instrument** device placed
   after this device (**MIDI To** → the port your FS1R is connected to)

Program/bank changes work over any Live version this way. SysEx features
(Fetch etc.) over track routing require **Live 11.1+**, and passing SysEx
through External Instrument may depend on your Live version — if Fetch
does not respond in this configuration, patch selection still works.

## Known limitations

- **Direct connection is verified on macOS (Apple Silicon) only.** The
  Port popup's direct CoreMIDI connection is implemented via a compiled
  Swift helper (`midibridge`); there is no Windows build of it, and it has
  not been tested on Intel Macs. On Windows or Intel Macs, set Port to
  **"Track (Live routing)"** and route the track's MIDI output to your
  FS1R — performance selection works over normal Live routing, and SysEx
  features require Live 11.1+. This mode is currently untested; reports
  welcome.
- The FS1R does not report which bank/performance is currently selected
  over SysEx, so Fetch can only sync Channel, the Formant/FM knob CC
  assignment, and the current performance's name — never the Bank/Perform
  display itself.
- This device assumes the FS1R's **Program Change Mode is set to "pfm"**
  (performance switching), which is how the reference unit was configured.
  If your unit's Program Change Mode is "multi" (per-part Voice PC
  instead), bank/performance selection will not behave as expected.
- Voice bank selection (MSB 63 / LSB 0–11, addressed to the Part Receive
  Channel rather than the performance channel) is not implemented.
- The **REV** knob's SysEx parameter-change format (address confirmed from
  the FS1R data list) has not yet been verified against real hardware;
  reports of unexpected behavior are welcome.
- Category names and performance names come from a database captured from
  a real unit's factory content. If you've renamed an INT-bank performance
  on the hardware, only the *name* is picked up automatically (via SysEx on
  selection) — the category shown for it is still the factory default.

## Troubleshooting

**Device shows "not connected" / PORT popup is empty**
- Confirm the FS1R is powered on and its MIDI interface is visible in
  Audio MIDI Setup (Applications > Utilities > Audio MIDI Setup > MIDI
  Studio) before opening Live.
- Reselect the port from the PORT popup, or click **Resend**.
- If the PORT popup never populates, quit and reopen Live (the `midibridge`
  process needs to start and enumerate CoreMIDI endpoints once per Live
  session).

**macOS blocks `midibridge` from running (Gatekeeper warning)**
- Run **Install.command** again — it clears the quarantine flag on the
  binary. If macOS still refuses, open System Settings > Privacy & Security
  and allow the blocked item, or run in Terminal:
  `xattr -d com.apple.quarantine ~/Documents/"Max 9"/Library/cotofu/midibridge`

**SysEx name / channel never updates after Fetch**
- Verify the FS1R's MIDI OUT is physically connected and routed back to
  the Mac (SysEx receive requires this; sending performance changes does
  not).
- Check the FS1R's System settings for Bank Select Rx and Program Change
  Rx being enabled, and that its Device# matches the Dev# field on the
  device.

**Bank/Perform reverts to an old value right after loading a Live Set**
- This is expected for a few hundred milliseconds while `midibridge`
  reconnects; the saved VALUE parameter is the source of truth and the
  display will settle once the bridge reports ready and the recall fires
  (about 800ms after the post-connect auto-fetch response).

**Performances don't change when using the FS1R's own SEARCH mode**
- That's expected FS1R behavior, not a bug in this device: the real unit
  ignores incoming Program Change while its front panel is in SEARCH mode.
  Leave the FS1R in PLAY mode — all searching happens on the M4L side using
  the bundled database, and only ordinary bank/PC messages are sent to the
  hardware.

---

# 日本語

## 概要

デバイス全体が単一の統合パネル(700×168px)として描画され、Bank/Perform
表示・Channel・Device#・Port・Category・Preset 一覧・Status はすべてこの
パネル内に収まっています。別ウィンドウで開くドロップダウンやテキスト欄は
ありません。

YAMAHA FS1R のパフォーマンス(音色)を Ableton Live から直接選択・ブラウズ
できる Max for Live MIDI エフェクトデバイスです。INT + PR-A/PR-B/PR-C 計512
パフォーマンスのカテゴリ検索、CoreMIDI 経由でのハードウェアへの直結、
ATTACK/RELEASE/FORMANT/FM/REV フロントノブの操作、Live セット保存/ロード時の
正しいリコールに対応しています。

## 動作要件

- macOS(Apple Silicon で検証済み。Intel/Windows は「既知の制約」参照)
- Ableton Live 11 以降、Max for Live インストール済み
- CoreMIDI で接続された YAMAHA FS1R(USB-MIDI インターフェース、MIDI
  インターフェースの DIN ポート、またはネットワーク MIDI 経由で CoreMIDI
  ポートとして見えていること)

## インストール手順

1. ダウンロードした zip を解凍する
2. **Install.command** をダブルクリックする
   - macOS のセキュリティ警告が出た場合は下記トラブルシューティングを参照
   - `~/Documents/Max 9/Library/cotofu/`(Max 8 フォルダがあれば
     `~/Documents/Max 8/Library/cotofu/` にも)へ依存ファイル一式がコピーされ、
     同梱の `midibridge` の quarantine 属性が解除されます
3. `FS1R Perform Select.amxd` を Ableton Live の User Library
   (Live > Places > User Library、通常は
   `~/Music/Ableton/User Library/Presets/MIDI Effects/Max MIDI Effect/`)
   に移動する
4. Live で MIDI トラックにドラッグして使用する

## 使い方

1. **PORT**: Port 行をクリックしてポップアップを開き、FS1R が繋がっている
   CoreMIDI ポートを選択する。デバイスが直接接続するため、パフォーマンス
   変更の送信に Live の MIDI ルーティングは不要。ロード時に「FS1R」を含む
   ポート名へ自動接続する。
2. **FETCH**: クリックすると FS1R の System 設定を SysEx で取得する。
   パフォーマンス受信チャンネルが Ch に反映され、ノブの Formant/FM の CC
   割り当ても実機の設定に追従し、現在のパフォーマンス名も更新される。
   ただし FS1R は現在選択中のバンク・番号を SysEx で公開していないため、
   Fetch では Bank/Pfm 表示は同期できない(デバイスが最後に送った値のまま)。
3. パフォーマンスの選択:
   - **VALUE ▲▼**(全512パフォーマンスを連続スクロール)
   - **Bank / Pfm** 表示を直接操作
   - **Category / Preset 検索**(カテゴリで絞り込み、名前で選択すると即座に
     送信される)
4. **ATTACK / RELEASE / FORMANT / FM** ノブ: 上下ドラッグで対応する CC を
   送信(実機のフロントノブ相当)。
5. **REV** ノブ: 上下ドラッグで Performance Edit Buffer の Reverb Return を
   SysEx パラメータチェンジで直接送信(CC は使わない)。
6. **RESEND**: 現在の選択を再送(電源入れ直し後など)。
7. Bank/Perform/Channel/Device/Value と5つのノブ値は Live のデバイス
   パラメータとして保存され、ロード時に復元される(bridge の再接続を
   待ってから同期するため、保存内容が勝手に上書きされることはない)。

## 音を出すには

このデバイスは**パフォーマンス切り替えとフロントノブの CC 送信専用**で、
ノートやオーディオは扱いません。FS1R を演奏して音を聴くには、外部
ハードウェアの通常のセットアップが必要です。いちばん簡単なのは同じ
トラックに Live 標準の **External Instrument** を置く方法です:

- *MIDI To*: FS1R がつながっている MIDI ポート
- *Audio From*: FS1R の出力をつないだオーディオインターフェースの入力

あるいはミキサー経由で FS1R をモニターし、このデバイスはパフォーマンス
選択・ノブ操作専用として使ってください。

## MIDI の入力と出力を別ポートにしたい場合

Port メニューは「同じ名前のポート」の入出力をまとめて開きます。方向ごとに
別のポートを使いたい場合は、Live 側のルーティングを使ってください:

1. Port を **"Track (Live routing)"** にする
2. **入力**はトラックの **MIDI From** で選ぶ
3. **出力**はこのデバイスの後ろに置いた **External Instrument** の
   **MIDI To** で選ぶ(FS1R がつながっているポート)

この方法でプログラム/バンクチェンジは確実に動作します。SysEx 系機能
(Fetch 等)をトラックルーティングで使うには **Live 11.1 以降**が必要で、
External Instrument 経由の SysEx 通過は Live のバージョンに依存する可能性
があります — この構成で Fetch が応答しなくても、パッチ選択自体は動きます。

## 既知の制約

- **直結機能の動作検証は macOS (Apple Silicon) のみです。** Port ポップアップの
  CoreMIDI 直結は Swift 製ツール `midibridge` によるもので、Windows 版は
  なく、Intel Mac での動作も未検証です。Windows / Intel Mac では Port を
  **"Track (Live routing)"** にしてトラックの MIDI 出力を FS1R にルーティング
  してください(パフォーマンス選択は通常の Live ルーティングで動作、
  SysEx 機能は Live 11.1 以降が必要)。この構成は未検証です。
- FS1R は現在選択中のバンク・番号を SysEx で公開していないため、Fetch で
  同期できるのはチャンネル・Formant/FM の CC 割り当て・現在のパフォーマンス
  名のみで、Bank/Pfm 表示自体は同期されません。
- このデバイスは FS1R の **Program Change Mode が "pfm"** (パフォーマンス
  切替)であることを前提にしています(検証機はこの設定)。"multi"(パート
  単位の Voice PC)の場合は想定どおり動作しません。
- Voice バンク選択(MSB 63 / LSB 0–11、パフォーマンスチャンネルではなく
  Part Receive Channel 宛て)は未実装です。
- **REV** ノブの SysEx パラメータチェンジ形式(アドレスはデータリストで
  確認済み)は実機での動作検証がまだ済んでいません。想定外の挙動を見つけた
  場合は報告してください。
- カテゴリ名・パフォーマンス名は実機の工場出荷コンテンツから収穫した
  データベースを使用しています。INT バンクのパフォーマンス名を実機で
  書き換えた場合、選択時の SysEx 取得で*名前だけ*は追従しますが、表示
  されるカテゴリは工場出荷時のままです。

## トラブルシューティング

**"not connected" と表示される / PORT ポップアップが空**
- FS1R の電源と MIDI 接続を確認する(Audio MIDI設定アプリで見えているか、
  Live を開く前に確認)。
- PORT ポップアップから選び直すか、RESEND を押す。
- ポップアップが空のままなら Live を再起動する(`midibridge` プロセスは
  Live セッションごとに起動して CoreMIDI エンドポイントを列挙する必要が
  ある)。

**Gatekeeper に `midibridge` がブロックされる**
- Install.command を再実行する。それでも改善しない場合はシステム設定 >
  プライバシーとセキュリティ から許可するか、ターミナルで次を実行する:
  `xattr -d com.apple.quarantine ~/Documents/"Max 9"/Library/cotofu/midibridge`

**Fetch してもパフォーマンス名/チャンネルが更新されない**
- FS1R の MIDI OUT がマシンに物理的に接続・ルーティングされているか確認
  する(SysEx 受信にはこれが必要。パフォーマンス変更の送信には不要)。
- FS1R の System 設定で Bank Select Rx / Program Change Rx が有効になって
  いるか、Device# がデバイスの Dev# フィールドと一致しているか確認する。

**Live セット読み込み直後に Bank/Pfm が古い値に戻る**
- `midibridge` の再接続中の数百ミリ秒はこれが正常動作。保存された VALUE
  パラメータが正となり、bridge の準備完了とリコール(接続後の自動 fetch
  応答から約800ms後)が済めば表示は落ち着く。

**FS1R 実機の SEARCH モードでパフォーマンスが切り替わらない**
- これは本デバイスの不具合ではなく実機の仕様です。実機はフロントパネルが
  SEARCH モードのとき Program Change を無視します(実測)。FS1R 側は常に
  PLAY モードのままにしてください — 検索はすべて M4L 側で同梱データベースを
  使って行われ、実機へは通常のバンク/PC メッセージのみ送信されます。

---

© 2026 Itsuki Doi (Cotofu). All rights reserved. Not affiliated with Yamaha
Corporation. YAMAHA and FS1R are trademarks of Yamaha Corporation.
