ucmix

ucmix — StudioLive ミキサーの制御

ucmix は、ミキサー独自のネットワークプロトコル（UCNET）を使用して、PreSonus StudioLive Series III ミキサーのあらゆるパラメーターを読み書きします。PreSonus のソフトウェアは不要で、使用もしません。ミキサーの制御ポートに直接接続します。

最初の確認

command -v ucmix
ucmix --version
ucmix profile ls        # is a mixer saved?

ucmix が見つからない場合は、インストールします。

brew install steveclarke/tap/ucmix

ミキサーが設定されていない場合は、ミキサーを検索して保存します（ミキサーは LAN 上で自身をアナウンスします）。

ucmix discover          # list mixers on the network
ucmix setup             # interactive: pick one, name it, save it as the current profile
# or, if you already know the address:
ucmix profile add foh --host 192.168.1.50 --use

以降の各コマンドでは、現在のプロファイルが使用されます。コマンドごとに上書きするには、-p <name> または --host <ip> を指定します。

モデル — 1 つの名前空間に対する 2 つの動詞

ミキサーは、各要素が path → value 形式の、約 20,000 個のパラメーターからなる単一のフラットな名前空間です。

line/ch1/username        = "Drums"      # channel 1 name
line/ch1/48v             = true         # phantom power
line/ch1/volume          = -6           # fader, dB
aux/ch1/limit/threshold  = -6           # monitor-mix limiter, dB
fx/ch1/plugin/reflection = 0.79         # a reverb knob (raw)

ミキサーで実行できる操作は、すべてこれらのパスのいずれかで表されます。すべての操作は、次の 2 つの動詞で行えます。

• ucmix get <path> — 1 つの値を読み取ります
• ucmix set <path> <value> — 1 つの値を書き込みます。1 回の接続で複数の値を書き込むには、set p1=v1 p2=v2 … または set -f <file>（各行に path value を指定）も使用できます

パスの構文（グループ、チャンネルのインデックス付け、各パラメーターファミリーの値の形式）については、reference/paths.md を参照してください。特定のミキサーで現在使用できる正確なパスを確認するには、ucmix dump（すべて）または ucmix dump <prefix>（フィルター適用）を実行します。

人間向けの値と生の値

一般的なコントロールでは人間向けの値を指定でき、ツールがワイヤー形式に変換します。

パスファミリー	指定する値	ワイヤー上の生の値ではありません
.../48v、.../mute、.../*on*、.../link	on / off	（ブール値）
.../volume、.../aux{n}、.../FXA～.../FXH、.../limit/threshold	dB、例：-6dB
.../limit/release	ms、例：400
.../username	文字列、例："Vox Steve"
.../color	16 進数、例：4ed2ff	読み取り時は、小文字の RGBA 8 桁（4ed2ffff）として返されます
.../iconid	アイコン ID、例：vocals/leadvocals
.../adc_src（入力パッチ）	入力番号、例：5

それ以外のパスには人間向けの変換レイヤーがありません。ミキサーが期待するワイヤー上の生の値を指定してください。通常は 0..1 の浮動小数点数（例：fx/ch1/plugin/lpf 0.869）、整数のインデックス、または列挙型の数値です。get <path> は生の値を返します。get <path> --raw を指定すると、人間向けの値に対応するパスでも生の値が返されます。取得した設定を再現する場合は、生の値を読み取り、その値をそのまま書き戻してください。

コマンド

フラグを確認するには ucmix <command> --help を実行してください。CLI は変更されるため、この一覧を完全なものとして信頼せず、--help で確認してください。

• get <path> / set <path> <value> — 1 つのパラメーターを読み取る／書き込む
• set p1=v1 p2=v2 … / set -f <file> — 1 回の接続で複数のパラメーターを書き込む
• channel <n> <verb> <value> / mix <name|n> <verb> <value> / send <ch> <mix> <dB> — よく使うチャンネルストリップ、モニターミックス、センド操作を set で行うための 人間向けショートカットです（薄いラッパーであり、生の set パスモデルですべての操作を行えます）。キーボードを使う人向けに 作られているため、エージェントは以下の生の get／set を引き続き使用してください。
• dump [prefix] — すべてのパス（またはプレフィックス以下のパス）を読み取ります。--as-config を指定すると YAML を出力します
• verify <config.yml> / apply <config.yml> — ボードをコードとして扱い、設定全体の差分を確認／書き込みます
• store <project> <name> — 現在の状態を新しいシーンとして保存します（既存のシーンを上書きするには --replace を指定）。 recall <project> <scene> — 保存済みのシーンを読み込みます。 rename <project> <scene> <new-name> — シーンの名前を変更します。 delete <project> <scene> — シーンを削除します（破壊的操作のため、--yes または確認プロンプトが必要です）。 プロジェクトとシーンの引数には、表示名（"135 Main Live"、"Opening"）またはボード上のスロット名 （"03.135 Main Live.proj"、"04.Opening.scn"）を指定できます
• reset — 工場出荷時の状態にリセットします（破壊的操作のため、--yes が必要です）
• ls projects — ボード上のプロジェクトを一覧表示します。ls scenes <project> — プロジェクトのシーンを一覧表示します。<project> には ls projects で表示される名前を指定します（例：01.Sevenview Live.proj）。どちらも --json を指定できます。
• project ls — プロジェクトとそのタイトルを一覧表示し、ボードに読み込まれているプロジェクトを示します
• filters ls [scene|advanced|project] / filters set <group> <tile> <on|off> — 保存、呼び出し、リセットで適用する範囲を決める スコープフィルターです
• discover / setup / profile / config — ミキサー接続を検出／保存／管理します

エージェントのルール

• 出力を解析するコマンドには --json を、プレーンテキストには --no-color を使用してください。
• 書き込み後は、新たに get を実行して確認してください。 set が報告するのは値を送信したことだけであり、 ボードが実際にその状態になったことではありません。値を読み戻して確認してください。
• パスの種類が対応している場合は、人間向けの値（-6dB、on、入力番号など）を優先してください。それ以外は、 生の 0..1 のワイヤー値を使用してください。
• あるボード／状態から別のボード／状態へ設定をコピーするには、get <path> --raw を実行し、 set <path> <that raw value> を実行してください。raw 値なら正確に往復できます。
• set を繰り返すのではなく、set p1=v1 p2=v2 … または set -f <file> を使って、1 回の呼び出しで複数のパラメーターを書き込んでください。 バッチ処理では 1 回の接続を再利用し、コミットも 1 回で済みます。set を別々に実行すると、書き込みごとに再接続され、 短時間に再接続を繰り返すと書き込みが失われる可能性があります。
• reset と apply --reset は破壊的操作です。明確な対象を指定し、--yes を付けた場合にのみ実行してください。
• パスが存在すると決めつけないでください。dump <prefix> または実機での get で確認してください。

シーン — 保存、呼び出し、名前変更

store は UC Surface と同じ方法で、次の空きシーンスロットを自動的に割り当てます。また、--replace を指定しない限り、 同じ名前の既存シーンを上書きしません。1 つのプロジェクトには 20 個のシーンスロットがあります。ErrNoFreeSlot は スロットがすべて使用中であることを意味します（UC Surface でシーンを 1 つ削除してください）。

store と recall はボードから操作の確認が返るまで待機し、確認が返らない場合は失敗します。成功が報告された保存は、 実際にディスクに保存されています。これは、基盤となるリクエストが応答を待たずに実行されるため重要です。以前のバージョンでは、 バイト列を送信した直後に成功を表示していたため、ボードが破棄したシーンも保存されたように見えました。store がエラーになった場合は、 シーンが保存されていないものとして扱ってください。

ボードの応答を待つため、どちらのコマンドも数秒かかります。これはボードがフラッシュメモリに書き込んでいる時間であり、 ハングしているわけではありません。

ucmix store "135 Main Live" "Opening"                 # new scene, next free slot
ucmix store "135 Main Live" "Opening" --replace        # overwrite it deliberately
ucmix rename "135 Main Live" "Opening" "Opening Set"   # retitle, keeps its slot
ucmix recall "135 Main Live" "Opening Set"
ucmix delete "135 Main Live" "Opening Set" --yes      # destructive, frees the slot

delete はシーンのスロットを解放し、次回の store でそのスロットが再利用されます。store や recall と同様に、 ボードから確認が返るまで待機します。実行前に確認を求めます。--yes を指定すると確認を省略できます。ターミナルがない場合は --yes が必須です。

プロジェクトレイヤーとスコープフィルター

プロジェクトとは、シーンの基盤となる設定です。入力ソースとパッチング、AVB/SD/USB ルーティング、フレックスモード、GEQ、ソロが含まれます。シーンはプロジェクト内にあります。project ls はプロジェクトを一覧表示し、読み込まれているプロジェクトに印を付けます。プロジェクトを単位として保存または呼び出す機能は未実装です。そのために UC Surface が送信するリクエストはまだキャプチャされておらず（issue #6）、project store / project recall は形式を推測せず、その説明を表示して失敗します。

スコープフィルターは、保存、呼び出し、リセットで実際に対象となる範囲を決める青いタイルです。各タイルは通常のパラメーターなので、get/dump で読み取り、set で書き込みます。filters は、それらを名前で操作するためのインターフェースです。

ucmix filters ls                       # every tile in every group, with its state
ucmix filters ls scene --json          # one group, machine-readable
ucmix filters set scene 48v on         # include phantom power in a store/recall
ucmix filters set project inputpatching off

グループは scene（Scene Filter、global/fltr*）、advanced（Advanced Scene Filter、 advancedscenefilters/*）、project（Project Filter、projectfilters/*）です。タイル名にはボード本来のキー名が使われるため、タイル名は書き込むパラメーターを表します。- と _ は相互に置き換え可能です。filters set は新しい接続でタイルを読み戻し、ボードに保持されている値を報告します。これは set や名詞形の動詞と同じです。

ボードでは、シーンフィルターの 48v タイルは除外された状態で出荷されます。そのため、シーンを呼び出してもファンタム電源の状態は変わりません。フィルターを変更すると、それ以降のすべての保存と呼び出しの対象が変わります。これはグローバル設定であり、コマンドごとのフラグではありません。

既知の制限事項

• ls projects / ls scenes は、FR/FD ファイルリクエストプロトコル（UC Surface が使用するものと同じ）を介してボードのプリセットを一覧表示します。応答しないボードの場合は、処理がハングする代わりに、明確なタイムアウトとヒントが表示されて失敗します。空のスロットとプロジェクト設定ファイルは出力から除外され、使用中のプロジェクトとシーンのみが表示されます。
• apply はライブラリのコミットバリアを使って1つの接続上で書き込み、新しい接続で検証（新しい get）します。set -f <file> は、検証を行わない同じ一括書き込み経路です。
• rename はボードからの確認応答ではなく、プロジェクトを再度一覧表示して確認します（ボードは名前変更への確認応答を送りません）。store、recall、delete はすべて実際の確認応答を待ちます。reset は依然として未確認のファイア・アンド・フォーゲットです。ボードが処理したことではなく、リクエストを送信したことを報告します。
• スコープフィルターの読み取りは 32R（ファームウェア 3.4.0）でハードウェア確認済みです。また、タイルを1つ切り替えて読み戻すことで、書き込み経路も確認済みです。プロジェクトの保存／呼び出しにはキャプチャされたリクエストがなく、未実装です。
• ハイパスフィルターは較正済みです。ボードの 24 Hz ～ 1 kHz の範囲で Hz 単位、対数スケール、0 = オフです。リミッターのリリースカーブとリバーブタイプの列挙値は較正されていないため、人が読みやすい値への変換は概算です。正確さが重要な場合は、生の値を使用してください。
• UCNET パラメーターの中には、UC Surface に操作項目がないものがあります（例：FX リターンの Main/LR アサイン、fxreturn/chN/lr）。これを書き込むと、オペレーターがコンソールから確認も取り消しもできない状態にボードがなります。UC Surface で見える操作項目に対応する変更を優先してください（例：LR の割り当て解除ではなく、FX リターンのフェーダーを下げてメインをドライにする）。また、書き込みに UI 上の同等項目がない場合は、その旨を明記してください。