Footswitch for macOS

Windows用ドライバしか付属していない安価なUSBフットスイッチを、macOSで自由に使えるようにするためのデスクトップアプリ。踏んだときに任意のショートカットキーやテキスト入力を実行させられる。

なぜ作ったか

手元にある USB フットスイッチ（GZIOT USBSW）は、付属ソフトが Windows 専用で、macOS ではキー割り当ての変更ができなかった。デバイス自体は単純な USB HID キーボードとして認識され、この個体は既定で pause キーを送ってくる（macOS では pause が「画面の輝度アップ」として解釈される）。これを macOS 側で好きなアクションに化けさせたい、というのが出発点。

市販の常駐アプリを入れて設定するより、仕組みを自分で把握できる小さな Electron アプリとして持っておいた方が、後から挙動を変えたり、別のデバイスに使い回したりしやすい。そういう「自分用の道具」として作った。

大前提：ペダルが送るキーはファームウェアで決まる（重要）

このペダルが「何のキーを送るか」はペダル本体のファームウェアに書き込まれており、書き換えられるのは付属の GZIOT Windows専用ツールだけ。この 1 点が全ての背景。

• Windows機が使えるなら、それが本筋で一番クリーン。 Windowsに繋いで付属ツールでペダルを「Enter」など好きなキーに再設定すれば、OSを問わず・追加ソフトなしでそのキーを送るようになる。macOS側で何も要らない。
• Windowsツールが使えない/使いたくない場合の回避策が、この macOS アプリ + Karabiner。 ペダル本体は書き換えず、Macに入ってきた pause を Mac 側で別のキーに変換する。本リポジトリはこちらの回避策。

「Karabinerも入れず完全に素の状態に戻したい」場合は、Macからは何も設定せず（Karabinerの該当ルールを消すだけ）、ペダルは pause（＝輝度アップ）を送る素の挙動に戻る。挙動を変えたければ Windows機で本体を再設定する。

対象デバイス

このアプリは特定のフットスイッチ 1 台に合わせて作ってある（他デバイスでも原理は流用可能）。

項目	値
製品名	USBSW
メーカー	GZIOT
Vendor ID	0x5131 (20785)
Product ID	0x2019 (8217)
形態	1ペダル / USB HID（Interface 0 = キーボード, Interface 3 = ベンダー独自）

npm run list-devices で接続中の HID デバイス一覧を出せるので、別のフットスイッチを使う場合はそこから VID/PID を確認する。

動作の仕組み（重要）

このアプリは Karabiner-Elements と組み合わせて動く。アプリ単体では動かないので注意。設計の中心はこの2段構えになっている。

フットスイッチを踏む
   │  デバイス既定で「pause」を送出（ファームウェア設定。macOSでは輝度アップ扱い）
   ▼
Karabiner-Elements
   │  「このデバイス(VID 0x5131 / PID 0x2019)のpause」だけをF13に変換
   │  ※ 他のキーボードには一切影響しない
   ▼
Footswitch for macOS（このアプリ）
   │  F13 をグローバルショートカットとして検知
   ▼
割り当てたアクションを実行（例: ⌘+C コピー / 任意テキスト貼り付け）

実際にペダルが送るキーは Karabiner-EventViewer で確認できる。この個体は pause。別個体・別設定なら異なる可能性があるので、必ず実機で確認して下記 from.key_code を合わせる。

なぜこんな回り道をするのか:

• フットスイッチは OS からはただのキーボードに見える。生の HID データを直接読む方式（footswitch-monitor.js に実装あり）も試したが、デバイスのパスが再接続のたびに変わる、Karabiner と HID を奪い合って競合するといった問題があった。
• そこで「デバイス固有の pause を Karabiner で F13 に変換 → アプリは F13 だけ見張る」という役割分担にした。Karabiner はデバイス単位でキーを差し替えられるので、このフットスイッチの入力だけを安全に横取りできる。F13 は通常のキーボードにほぼ存在しないため、誤爆もしない。

生 HID を直接読むコード（detectPedalState）も残してあるが、現在の主経路は上記の F13 ブリッジ。

必要な Karabiner 設定

~/.config/karabiner/karabiner.json の対象プロファイルの devices に、以下のデバイス指定を追加する（詳細と再構築手順は docs/KARABINER.md）。

{
  "identifiers": { "is_keyboard": true, "vendor_id": 20785, "product_id": 8217 },
  "simple_modifications": [
    { "from": { "key_code": "pause" }, "to": [{ "key_code": "f13" }] }
  ]
}

セットアップ

1. 前提

• macOS
• Node.js（開発・起動用）
• Karabiner-Elements（上記のキー変換に必須）

2. 依存関係のインストール

npm install

3. Karabiner にデバイスルールを追加

docs/KARABINER.md の手順に従って、フットスイッチの Enter → F13 変換を登録する。

4. 起動

npm start

初回はキー入力のシミュレートに アクセシビリティ権限 が必要。詳細は PERMISSIONS.md を参照。

使い方

1. アプリを起動する（メニューバーに常駐）。
2. ペダルに割り当てたいアクションを設定して「設定を保存」。
   • キー入力: 単一キー + 修飾キー（⌘/⇧/⌃/⌥）。例: c + ⌘ → コピー
   • テキスト入力: 任意の文字列（クリップボード経由で貼り付け）
3. フットスイッチを踏むと、そのアクションが実行される。

割り当てられるキーの一覧や具体例は USER_GUIDE.md を参照。

ドキュメント

ファイル	内容
docs/KARABINER.md	必読: フットスイッチ→F13 の Karabiner 設定と再構築手順
SETUP.md	セットアップ・ビルドの詳細
USER_GUIDE.md	ペダル割り当ての操作ガイドとキー一覧
PERMISSIONS.md	アクセシビリティ権限の設定
ARCHITECTURE.md	内部構造・データフロー

技術スタック

• Electron — デスクトップアプリの土台
• node-hid — HID デバイス列挙（直接読み取り経路で使用）
• electron-store — 設定の永続化
• AppleScript (System Events) — キーボード入力のシミュレート
• Karabiner-Elements — デバイス固有のキー変換（Enter → F13）

今後の展望

• デバイスパスではなく VID/PID でデバイスを識別し、再接続に強くする
• 複数ペダル / 押し方（長押し・ダブル）への対応
• Karabiner 設定の自動生成・自動投入（現状は手動）
• 署名・公証済みの .app として配布し、npm start なしで使えるようにする

プライバシー

• 完全にローカルで動作し、ネットワーク通信は行わない。
• 設定はローカル（electron-store）にのみ保存される。

ライセンス

MIT