gmux 設定ヘルプ
gmux 設定ヘルプ
このドキュメントは 設定ウィンドウ の視点から gmux の中核概念と、組み込みホットキーの使い方・役割を解説します。トレイアイコン → 「設定」を開くと、以下で言及するすべてのページを確認できます。
サイドバーは上から順に ディスプレイ / ディスプレイプロファイル / レイアウト / ホットキー / システム / ヘルプ。この 6 ページは「まず gmux にどのディスプレイがあるか教える」→「ディスプレイを名前付きプロファイルに組み合わせる」→「プロファイル用にレイアウトを書きホットキーをバインドする」→「トリガーキーを調整する」というワークフローに対応しています。
一、主要概念
gmux のすべての機能は 5 つの概念を中心に展開します。それらは互いに依存し、関係は次のとおり。
ディスプレイ（Display）── 登録 ──▶ ディスプレイプロファイル（Profile）
▲
│ 参照
│
バインディング（Binding）── 複数含む ──▶ バリアント（Variant）
│
└── 参照 ── レイアウトカテゴリ（category）+ スロット（slot）
└── 参照 ── アプリ（app）
トリガーの流れ: バインディングのホットキーを押す → エンジンがその binding の複数 variant から現在のディスプレイに合うものを選ぶ → variant で宣言されたアプリを対応スロットに配置する。
1. ディスプレイ（Display）
対応する設定ページ: ディスプレイ。
「ディスプレイ」は gmux における物理モニターの命名登録です。新規インストール後の初回起動時に、gmux は接続中のすべてのモニターを自動検出して登録します。
各ディスプレイレコードに含まれるフィールド:
| フィールド | 意味 |
|---|---|
id |
物理 ID（EDID シリアル番号 + モデル）。同型の複数モニターをこれで区別する。__PRIMARY__ は「現在のプライマリディスプレイ」のプレースホルダ |
name |
ユーザーが付ける名前（main、vertical、laptop など）。以後、ディスプレイプロファイルやバリアントではこの名前を参照する |
orientation |
向き: landscape（横向き）/ portrait（縦向き） |
なぜ物理 ID を直接使わず名前を登録するのか: 機種変更やモニター交換後も、同じ名前で再登録すれば既存の参照は変更不要だからです。同じモニターでも回転後は別レコードとして扱われます（横向き版 + 縦向き版を別々に登録できます）。
ページ操作:
- 再検出: 現在接続中の物理モニター一覧を更新。同時に各モニター上に対応番号を一時的に表示して識別を助ける。
- ディスプレイ番号を非表示: その番号 OSD を手動で閉じる。
- 未命名カード → 登録: 名前を入力して保存すると、そのモニターは「登録済み」エリアに移動。
- あるディスプレイプロファイルから参照されている 場合、そのカードは直接編集・削除できません。先にディスプレイプロファイルページで関連付けを解除する必要があります。
2. ディスプレイプロファイル（Profile）
対応する設定ページ: ディスプレイプロファイル。
「ディスプレイプロファイル」= 登録済みディスプレイの順序付き集合で、ある 物理的な使用環境 を表します。例えば:
solo—— プライマリのみhome—— プライマリ + 右側の縦向きoffice—— 左 + プライマリ + 右側のラップトップ
各バインディングの「バリアント」は必ずいずれかのプロファイルに紐付きます。エンジンはバインディング発動時、現在 実際に接続中のモニター に従って一致するプロファイルに対応するバリアントを選び出します。
各プロファイルレコードに含まれるフィールド:
| フィールド | 意味 |
|---|---|
name |
プロファイル名（home など） |
displays |
ディスプレイの順序付きリスト。ドラッグ順で保存される。UI に表示される番号はこのリストのインデックス |
first_as_default |
リスト先頭のディスプレイを「デフォルトディスプレイ」として扱う。prefix+w パネルや split のフォールバック先に影響する |
quick_swap |
オプションのディスプレイペア。prefix+mm ホットキーで専用に交換される |
ページ操作:
- 新規ディスプレイプロファイル作成: 登録済みディスプレイのプールから一組をプレビューエリアにドラッグし、想定する配置順に並べ替える。
- プロファイルカードのドラッグ並べ替え: OSD リストでのプロファイル表示順を決定する。
- 設定ロード時、エンジンは現在の物理モニターと照合し、一致したプロファイルは「オンライン」と表示される。そうでなければロックマークが付き、どのバインディングが参照していて一時的に編集不可かを示す。
3. バインディング（Binding）
対応する設定ページ: レイアウト（左カラムの各エントリがバインディング）。
「バインディング」= 1 つの ホットキー + 説明 + 一組のバリアント。バインディングのキーはキーピッカー内の任意の単一キー —— 数字 0-9、アルファベット a-z、ファンクションキー F1–F24、名前付きキー（Space、Enter、Tab、矢印キー、Home/End など）、または OEM 記号（; / [ ] など）で、合計 85 個。（数字とアルファベットはデフォルトで表示され、ファンクションキー・名前付きキー・記号はピッカーの折りたたみセクション内。）prefix + <key> を押すとそれが発動する（デフォルトの prefix は Ctrl+M なので、Ctrl+M 1 / Ctrl+M a のような形式になる）。
各バインディングに含まれるフィールド:
| フィールド | 意味 |
|---|---|
id |
トリガーキー（1 や a など） |
description |
バインディングの説明（左カラムに表示されるタイトル。「開発」「会議」「シングルディスプレイ閲覧」など） |
variants |
1 つ以上のバリアント。エンジンは現在のディスプレイ構成に応じて 1 つを選んで実行する |
ページ操作:
- 新規バインディング作成: 説明を入力 + トリガーキーを選択。既に使用中のトリガーキーはセレクター上でグレーアウトされる。
- バインディング削除: すべてのバリアントごと削除。トリガーキーは再び利用可能になる。
- リネーム: 右上の ✎ アイコンで description を変更（トリガーキーは変わらない）。
- 左カラムの並べ替え: prefix+w リストでのバインディング表示順を決定する。
無料版の上限は 9 個のバインディング。それ以上はアップグレードまたは試用が必要です。
4. バリアント（Variant）
対応する設定ページ: レイアウト（右側詳細エリア内の「バリアントカード」）。
「バリアント」= 同一バインディングの 特定ディスプレイプロファイル下 での具体的なレイアウト記述。1 つのバインディングは複数のバリアントを持ち、それぞれを異なるプロファイルに紐付けることができ、エンジンが現在接続中のモニターに応じて自動的に選択します。
例: バインディング「開発」に 3 つのバリアントを掛けることができる —— デュアルディスプレイの
homeでは左に IDE / 右にドキュメント、トリプルディスプレイのofficeでは左 IDE / 中央 Chrome / 右 Slack、シングルディスプレイのsoloではプライマリ全画面で IDE。外出時にラップトップだけを持っている場合はsoloのみマッチし、Ctrl+M 1を押すと solo のセットが走る。
各バリアントに含まれるフィールド:
| フィールド | 意味 |
|---|---|
profile |
バリアントが紐付くディスプレイプロファイル名 |
categories |
プロファイル内の各ディスプレイに指定する レイアウトカテゴリ（横向き / 縦向きそれぞれ 12 個の組み込みカテゴリ + 共通の full） |
regions |
アプリとスロットの対応表: どのアプリをどのディスプレイのどのスロットに配置するか |
レイアウトカテゴリ（category）+ スロット（slot） はジオメトリのテンプレート:
- カテゴリは 1 つのディスプレイがどのように分割されるかを決める（
quad_h= 4 象限、halves_h= 左右二分、thirds_v= 縦 3 分割など）。 - スロットは分割後の各小領域の名前（
tl/tr/bl/br、left/right、top/middle/bottomなど）。 - 1 つのディスプレイに 1 つのカテゴリを選び、カテゴリがどのスロットを埋められるかを決める。
- 組み込みカテゴリは合計 25 個（横向き 12 + 縦向き 12 + 共通
full）でカスタマイズ不可 —— 固定にしておくことで GUI エディタが常に設定を「認識」できる。
ページ操作:
- ディスプレイプロファイルとの関連付け: バインディング詳細エリアで + をクリックして新規バリアントを作成。プロファイルを選ぶ → 各ディスプレイにカテゴリを選ぶ → アプリをスロットにドラッグ。
- 編集: バリアントカード右上の「編集」アイコンでドロワーに入る。
- 現在有効なバリアントはカードに「現在有効」のマークが付く。現在の物理モニターに一致しないバリアントは「不一致」のマークが付く。
- アプリは「登録済み」エリアから選ぶこともできるし、システムのスタートメニュー / UWP リストから選ぶこともでき、初回選択時に自動的にアプリレジストリに書き込まれる。
無料版の制限: 各バリアントは 1 ディスプレイのみ対象。マルチディスプレイバリアントには Premium が必要です。
5. ひとことで通す
マシンに何のディスプレイを接続するか → 「ディスプレイ」として登録。 複数のディスプレイがある使用環境を構成する → 「ディスプレイプロファイル」として命名。 どのホットキーで作業姿勢を切り替えたいか → 「バインディング」を作成。 同じバインディングが異なるプロファイル下で異なる動作をする → 複数の「バリアント」を書く。 各バリアントは各ディスプレイをいくつに分割し、誰がどこに行くかを記述 → カテゴリ + スロット + アプリ。
二、システムプリセットホットキー
対応する設定ページ: ホットキー（左カラム「prefix キー」「アクションコード」「アドバンスト」の 3 ブロック）。
gmux は prefix + chord システムです: まず prefix を押して「次のキー待ち」状態に入り、続いて 1 つのキーを押してアクションを発動します。Prefix のデフォルトは Ctrl+M で、すべての組み込みアクションは事前に prefix を押す必要があります。
「設定 → ホットキー」ページでは prefix の変更、各アクションの第 2 キーの変更、タイムアウトの調整ができます。以下に列挙するのはすべて 初回起動時のデフォルト値 です。
各項目に独立した詳細ドキュメント があり、すべての可能な使用分岐、キャンセル条件、拒否条件を記述しています。下表のアクション名をクリックでジャンプできます。
2.1 Prefix（プレフィックスキー）
| 設定項目 | デフォルト値 | 役割 |
|---|---|---|
prefix |
Ctrl+M |
「chord 待ち」状態に入るマスタースイッチ |
| Win キーを修飾キーとして有効にする | オフ | チェックすると Win を prefix の修飾キーとして使用可能になる |
| PREFIX タイムアウト | 2000 ms | prefix を押した後、第 2 キーを待つ最長時間 |
変更方法: 「ホットキー → prefix キー」の編集ボタンをクリックし、新しい組み合わせを押して保存。Prefix には少なくとも 1 つの修飾キー（Ctrl / Alt / Shift / Win）が必要で、単独のアルファベット数字は許可されません。
ヒント: トレイアイコンが赤くなったら、prefix が他のアプリに奪われたことを意味します。別の組み合わせに変えるか、奪取者を先に閉じてからトレイの「prefix を再試行」をクリックしてください。
完全な説明: hotkeys/prefix-ja.md
2.2 バインディングの発動
prefix を押した後にバインディング key を入力すると対応するレイアウトが発動します:
| キーシーケンス | 役割 |
|---|---|
prefix <バインディングキー> |
bindings.<key> を発動（0-9、a-z、F1–F24、名前付きキー、または OEM 記号）—— エンジンが一致するバリアントを選び、ウィンドウを所定位置に配置 |
バインディングリストの現在の key は「レイアウト」ページの左カラムにあります（「⌃M·1」は Ctrl+M の後に 1 を押すという意味）。バインディング発動の詳細（prefix モードのキャンセルセマンティクスを含む）は hotkeys/prefix-ja.md を参照。
2.3 レイアウトナビゲーション系アクション
ページ分類: 「ホットキー → アクションコード → レイアウトナビゲーション」。
| アクション名 | デフォルトキー | 完全シーケンス | 役割 |
|---|---|---|---|
next_layout |
n |
Ctrl+M n |
「次の」レイアウトに切り替え。連続押下ですべての binding 間をサイクル |
prev_layout |
p |
Ctrl+M p |
「前の」レイアウトに切り替え。逆順サイクル |
last_layout |
l |
Ctrl+M l |
前回使用したレイアウトにジャンプ（2 つのレイアウトを行き来する場合に最適） |
restore |
r |
Ctrl+M r |
現在のレイアウトをもう一度適用: 一時フルスクリーンをクリアし、手動で動かしたウィンドウ位置を戻す |
show_desktop |
space |
Ctrl+M Space |
デスクトップを表示 / 復元（システムレベルの Win+D 相当だが prefix 経由） |
list_layouts |
w |
Ctrl+M w |
OSD を表示してすべてのレイアウトを列挙。hjkl で選択、Enter で確定、Esc でキャンセル |
2.4 領域操作系アクション
ページ分類: 「ホットキー → アクションコード → 領域操作」。
「リージョン（region）」= 現在のバリアントのある 1 ディスプレイ × ある 1 スロット。例えば 4 象限の左上、左右二分の左半分など。これらのアクションはどれも事前にリージョンを選択するか、アクション中でリージョンを指定する必要があります。
| アクション名 | デフォルトキー | 完全シーケンス | 役割 |
|---|---|---|---|
show_regions |
q |
Ctrl+M q <digit> または Ctrl+M q q <digits> Enter |
画面上にすべての region 番号を描画。数字で選択（≥10 の場合は複数桁入力モードに入る） |
cycle_region |
f |
Ctrl+M f |
選択中の region で、現在の app の次のウィンドウを順次表示 |
fullscreen |
z |
Ctrl+M z |
選択中の region を一時フルスクリーン。もう一度押すと復元（同ディスプレイ単一フルスクリーン） |
focus_region |
g |
Ctrl+M g |
選択中の region のウィンドウにフォーカス + マウスを移動（ウィンドウ位置は動かさない） |
split_region |
c |
Ctrl+M c 後にアプリピッカーが表示 |
選択中の region 内に追加でアプリを入れる（リージョンが分割される） |
close_window |
x |
Ctrl+M x |
選択中の region の現在のウィンドウを閉じる（非同期 WM_CLOSE） |
collapse_region |
d |
Ctrl+M d |
選択中の region を回収し、ウィンドウを最小化——閉じない、取り消し可能 |
swap_displays |
m |
Ctrl+M m m または Ctrl+M m <digit><digit> |
2 つのディスプレイのレイアウト全体を交換 |
swap_displays は chord の中で最も分岐が多いものです。hotkeys/swap-displays-ja.md に 3 種類の使い方（mm / m+数字+数字 / キャンセル）の完全な説明があります。
2.5 ヘルプ
| アクション名 | デフォルトキー | 完全シーケンス | 役割 |
|---|---|---|---|
open_help |
? |
Ctrl+M ? |
「ヘルプ / チートシート」ウィンドウを開く。エンジン内では ? は / キーと等価で、Shift を押す必要はない |
設定ウィンドウは表示中に F1 でも直接「ヘルプ」ページを開けます。
2.6 アドバンストタイミング
「ホットキー → アドバンスト」では 4 つの ms レベルのタイムアウトと並列上限を調整できます:
| 設定項目 | デフォルト値 | 役割 |
|---|---|---|
サイクルタイムアウト（cycle_timeout_ms） |
3000 ms | next/prev 連続押下時に同じサイクルセッションとみなされる最長間隔 |
LAYOUT LIST OSD 上限（layout_list_timeout_ms） |
30000 ms | list_layouts OSD の自動クローズ時間 |
コマンドキー後の入力タイムアウト（input_timeout_ms） |
3000 ms | prefix+q 領域選択 / prefix+m ディスプレイ交換で、コマンドキー後の各キーのタイムアウト；キーごとにリセット |
REGION OSD クリーンアップ間隔（region_cleanup_interval_ms） |
1000 ms | region OSD 内部クリーンアップ tick |
起動並列上限（max_parallel_launches） |
0（自動） | 1 回のバインディング発動時に同時にコールドスタートするアプリ数; 0 = CPU により自動計算、1–32 = 固定値 |
2.7 サイレント操作トースト
「ホットキー → サイレント操作トースト」をオンにすると、ホットキーを押したが前提条件が満たされない場合（使用可能な layout がない、region が小さすぎる、領域が選択されていないなど）、デフォルトディスプレイ中央に短いヒントが 1 行表示され、「反応がないと思ったら実はサイレントに破棄されていた」を回避できます。同じヒントは 3 秒以内に 1 回しか表示されません。
2.8 ワンクリックでデフォルトに戻す
「ホットキー」ページ右上の「デフォルトに戻す」ボタンは、prefix、すべてのタイムアウト、14 個のアクション chord をすべて初回起動時のデフォルト値にリセットします。デフォルト値が既存のバインディングとキー競合する場合、リセットは拒否され競合一覧が表示されるので、先に手動でキーを変更してください。
三、その他の設定ページの概要
| サイドバーエントリ | 主な役割 |
|---|---|
| アプリマッチング（システムページ下部「アドバンスト」を展開） | 各登録済みアプリの起動方法とウィンドウマッチング信号を確認。ウィンドウ形態が変わった場合に再マッチング |
| システム → 言語 | 界面言語の切り替え（システムに従う / 中文 / English / 日本語） |
| システム → ログ | ログレベル、ディレクトリ、ローテーションポリシーの設定、診断パッケージのエクスポート |
| ヘルプ | 現在の prefix、すべてのバインディングのトリガーキー、すべてのアクション chord をすばやく確認 —— ホットキー変更後にいつでも戻って確認できる |
四、設定ファイルの場所
すべての GUI 変更は最終的に 1 つの TOML に書き込まれます:
%APPDATA%\gmux\config.toml
このファイルを直接編集して トレイ → 設定を再読み込み をトリガーしても有効になります。GUI は「もう一つの入口」であり、必須経路ではありません。設定は git / Dropbox に放り込んで同期できますが、display_profiles 内の EDID シリアル番号は 特定マシン固有 なので、マシンを跨ぐ場合はディスプレイを再検出するか、両方のマシンで対応するモニターに事前に同じ name を付ける必要があります。