Softswitcher module master

HybridSwitcher — ハイブリッドIP映像スイッチャー

既存機材（ATEM Mini）と自作ハードウェア（自作スイッチングモジュール群 + Pico 2W）、 ネットワーク技術（SRT / NDI / WebAPI）を融合した、次世代のハイブリッドIP映像スイッチャーシステム。

PC上に常駐する制御アプリを「脳」とし、複数プロトコル（UVC / NDI / SRT）の映像入力・PiP合成・ 仮想カメラ出力・タリー送出・外部機材（ATEM）の遠隔制御を一元化する。DIYでありながらプロ用 スイッチャーに匹敵する多人数オペレーション（メイン/サブ分業）と拡張性を目指す。

全体仕様は docs/specs/00-system-overview.md（親仕様書）を参照。

システム構成

[ サブ ATEM Mini ] ──(SRT/HDMI/NDI)──→ [ メインPC (常駐App) ] ──(仮想WebCam/HDMI)──→ [ 配信/録画/OBS等 ]
        ▲                                    ▲        │
        │ (ATEM遠隔制御: UDP 9910)            │        │ (UDPタリー: 9999 ブロードキャスト)
        └────────────────────────────────────┘        ▼
                                             ▲   [ ワイヤレスタリー子機(ESP32) ]  [ 赤/緑 LED ]
                                             │ (WebSocket / WebAPI: 8080)
                                    (USB/HID/Serial)
[ 自作コントローラー: Pico 2W ] ──┬── (USB直結) ──→ メインPC
        │                         └── (USB-OTG) ──→ [ スマホ (Web App) ] ──(Wi-Fi/WebSocket)──→ メインPC
        │
        ├─(内部制御: 後日詳細化)──→ [ 各スイッチングモジュール内マイコン ]
        └─(HDMI DDC/I2Cスニッフィング)──→ [ 物理タリー抽出 ]

コンポーネント

PC常駐アプリの .NET プロジェクト構成（src/）

libobs 移行: 旧 Switcher.Media(GStreamer/DirectX 合成) / Switcher.VirtualCam(自作仮想カメラ) は廃止し、映像パスは libobs に一本化した（docs/specs/libobs-engine-migration.md）。ネイティブ switcher-engine.dll は Windows + OBS でのみビルド/実行し、.sln には含まない（テストは FakeVideoEngine 注入でヘッドレス実行）。

リポジトリ構成

.
├── src/                       # PC常駐アプリ (.NET 9) — HybridSwitcher.sln
├── native/switcher-engine/    # ネイティブ映像エンジン (C/C++ + libobs, CMake, .sln外)
├── tests/                     # 上記各プロジェクトのユニットテスト
├── apps/phone-bridge/         # スマホWebブリッジ & 設定UI (React/TS)
├── firmware/pico2w-controller/# Pico 2W コントローラー / タリー抽出ファーム
├── docs/
│   ├── specs/                 # 仕様書（親仕様書 + コンポーネント別）
│   └── tasks/                 # マルチエージェント実装計画・タスク指示書
├── softswitcher*/             # 既存KiCadハードウェア設計（参考資産）
└── HybridSwitcher.sln         # .NET ソリューション

セットアップ（clone 直後に一度）

./setup.sh          # 共通（.NET / phone-bridge / firmware）

.\setup.ps1         # Windows で映像エンジンまで動かす場合（追加で実行）

clone しただけの状態では、次の理由で初回ビルドが必ず落ちる。setup.sh がこれを一括で潰す。

主なオプション（何度実行しても同じ結果になる）:

未解決の問題が残ると終了コード 1 で終わるので、CI からそのまま呼べる（./setup.sh --ci）。

Windows でネイティブ映像エンジンまで用意する（setup.ps1）

Visual Studio で F5 したときの DllNotFoundException / 0x8007007E は、ネイティブの switcher-engine.dll が未ビルドなことが原因。この DLL は .sln 外の CMake ビルドで、さらにその手前に libobs の import lib obs.lib が要る。obs.lib は OBS のインストーラには含まれず、OBS 本体をソースからビルドしないと手に入らない。

setup.ps1 はその依存の連鎖を通しで面倒を見る。

インストール済み OBS を検出 → 同じ版の obs-studio を clone
  → libobs だけビルド → obs.lib
    → .env に LIBOBS_* を記録
      → build.bat → switcher-engine.dll
        → Switcher.App.csproj が App 出力へ自動コピー（既存の仕組み）

初回は数十分かかる（obs-studio の clone が数 GB、libobs のビルドがその後）。2 回目以降は済んだ工程を飛ばす。

バージョンは固定していない。 マネージド側（ObsRuntime.cs）は libobs 30.0〜32.99 を受け入れ、範囲外でも警告を出すだけで拒否しない。setup.ps1 もそれに合わせ、インストール済み OBS の版を検出してその版のソースをビルドする。OBS が入っていない場合だけ既定の 32.0.4（実機検証済み）を使う。

⚠️ obs.lib（ビルド時）と obs.dll（実行時）の版が食い違うと起動失敗・クラッシュする。バージョンを検出に任せるのはこの事故を避けるため。手動で -ObsVersion を指定してインストール済みの版と食い違う場合は警告が出る。

エンドユーザーは OBS のインストールが不要。 ObsRuntime.Locate() は実行ファイルの隣の obs-runtime\ を最優先で見る（ObsRuntime.cs:83-90）ので、-Bundle で同梱した配布物は自己完結する。OBS インストールが要るのはビルドする側だけ。

GPL: obs-runtime\ を同梱した配布物は GPL-2.0 になる。LICENSE / THIRD-PARTY-NOTICES.md 参照。

環境変数（.env）

ツールチェーン関連の変数は .env.example をひな形に .env へ書く（setup.sh が無ければ自動生成する）。.env は gitignore 済み。既に export 済みの環境変数が .env より優先されるので、CI の env: / secrets が上書きされることはない。

⚠️ .env に書けるのはビルド/ツールチェーンの変数だけ。アプリの動作設定（AtemIp / WebPort / ProjectorDisplayIndex 等）は src/Switcher.App/appsettings.json を System.Text.Json が直接読む実装で、環境変数は見ない（Configuration/AppConfigLoader.cs）。

ビルド & テスト

PC常駐アプリ（.NET 9）

./setup.sh 済みでも、dotnet が PATH に乗るのは setup.sh の中だけ。呼び出し元のシェルには以下を前置きする。

export DOTNET_ROOT=$HOME/.dotnet PATH=$HOME/.dotnet:$PATH

dotnet build HybridSwitcher.sln     # 全プロジェクトのビルド
dotnet test  HybridSwitcher.sln     # 全ユニットテスト

Switcher.App は WPF (net9.0-windows) だが EnableWindowsTargeting によりLinuxでもCIでも コンパイルは可能。ただしネイティブ switcher-engine(libobs) ランタイムは Windows 限定で、 実行には Windows 10/11 と下記の起動順が必要。

ネイティブ映像エンジン（libobs）のビルド & Windows 実起動 — 起動順

switcher-engine.dll（native/switcher-engine/）は Windows + OBS 専用で .sln 外。以下が検証済みの順序 （詳細は switcher-engine README / L-002 タスク）。

以下は手順の内訳。通常は setup.ps1 が 1〜2 を自動でやるので、手で追う必要があるのは仕組みを確認したいときだけ。

前提: Windows / Visual Studio 2022（「C++によるデスクトップ開発」）/ CMake ≥ 3.24 / インストール済み OBS（版は問わない。libobs 30.0〜32.99 が対象）。 以下はすべて 「x64 Native Tools Command Prompt for VS 2022」 から実行する（cmake/cl に PATH が通る。通常の cmd/PowerShell 不可）。

1. libobs dev files を用意（採用 OBS と同一版のソースをビルド。インストール済み OBS アプリだけではヘッダ/obs.lib が無い）

   git clone --recursive https://github.com/obsproject/obs-studio.git
   rem <version> はインストール済み OBS に合わせる（obs.dll のファイルバージョン）。
   cd obs-studio && git checkout <version> && git submodule update --init --recursive
   cmake --preset windows-x64
   cmake --build build_x64 --config Release --target libobs

   → build_x64\libobs\Release\{obs.lib,obs.dll}、生成ヘッダ build_x64\config\obsconfig.h、公開ヘッダ libobs\。

2. switcher-engine.dll をビルド（リポジトリルートで。ヘッダは公開＋生成の2フォルダを ; 区切りで渡す）

   set OBS=<obs-studio のパス>
   set LIBOBS_INCLUDE_DIR=%OBS%\libobs;%OBS%\build_x64\config
   set LIBOBS_LIB=%OBS%\build_x64\libobs\Release\obs.lib
   native\switcher-engine\build.bat

   Switcher.App.csproj がビルド時に switcher-engine.dll を App 出力へ自動コピーする（VS F5/Rebuild でも維持）。

3. App を起動（obs.dll 等を PATH に通してから）

   • Visual Studio: 構成 Debug/x64 → Switcher.App をスタートアップに → プロパティ「デバッグ」→ デバッグ起動プロファイルUIで環境変数 PATH = C:\Program Files\obs-studio\bin\64bit;%PATH%（版一致のインストール済み OBS）→ F5。
   • コマンドライン:

     dotnet build src\Switcher.App\Switcher.App.csproj -c Release
     set PATH=%OBS%\build_x64\rundir\Release\bin\64bit;%PATH%
     src\Switcher.App\bin\x64\Release\net9.0-windows\Switcher.App.exe

前提/注意

• obs.dll + data\ + プラグイン + libobs-d3d11.dll が PATH 上で到達可能、かつ import lib(obs.lib) と同一版であること（不一致は起動失敗/クラッシュ）。
• L-002 未完のうちは engine_startup が obs_reset_video で失敗する（libobs データパス未配線。L-002 タスクの「実機検証で判明した実装ポイント」参照）。
• ネイティブ抜きで App を動かすなら DI（src/Switcher.App/Composition/ServiceCollectionExtensions.cs）を FakeVideoEngine に差し替える。

スマホWebブリッジ（React/TS）

cd apps/phone-bridge
npm install
npm run dev      # 開発サーバ
npm run build    # プロダクションビルド
npm test         # vitest

Pico 2W ファームウェア

I/Oに依存しないロジックはホストの gcc でユニットテスト可能（Pico SDK不要）。

cd firmware/pico2w-controller/test
make             # ビルド + 実行（全テスト green で終了コード0）

実機向けクロスビルド（Pico SDK / arm-none-eabi ツールチェーン必要）は firmware/pico2w-controller/README.md を参照。

CI（GitHub Actions）

.github/workflows/ci.yml が 全 PR（タスク → 親Epic の PR も含む）と main / develop への push で走る。すべて ubuntu-latest。

ブランチ保護の必須チェックには集約ジョブ All checks 1つを指定すればよい。

CI が走るのは個人リポジトリ（public）だけ。 ミラー先の NxTEND-THE-HACK/2026-Team-38 は Free org の private リポジトリで Actions のランナーが割り当てられず、どのジョブも 0 ステップの まま即座に失敗する（ワークフロー側の問題ではなく org の Actions 枠の問題で、修正には org 管理者 による支払い設定・repo の public 化・セルフホストランナー登録のいずれかが要る）。そのため全ジョブに if: github.repository_owner != 'NxTEND-THE-HACK' を付けて向こうでは skip させている。ジョブレベルの if はランナー要求より前に評価されるので、skip されたジョブは失敗扱いにならない。

CI 対象外（ローカル/Windows でのみ検証可能）:

• native/switcher-engine（libobs 依存・Windows + OBS 専用・.sln 外）と、それを要する App の実起動
• web/build-preview.ps1（Windows PowerShell 前提のパス処理）
• apps/phone-bridge の Prettier 整形チェック（既存ファイルが未整形のため未導入。npm run format で一括整形後に追加可能）

ミラー（個人リポジトリ → ハッカソン用リポジトリ）

開発を個人アカウントの public リポジトリ（oldsheeep3/TheHack）で行い、ハッカソン用 private リポジトリ（NxTEND-THE-HACK/2026-Team-38）へ push のたびに反映する。片方向（個人 → ハッカソン用）。

ミラー先へ書けるトークンは GitHub に預けない。 実際に push するのは tailnet 上の VPS（gh ログイン済み）で、自分の資格情報を使う。GitHub Actions はその VPS に SSH して起動をかけるだけ なので、この public リポジトリに置く secret は tailnet への参加情報と SSH 鍵だけで済む。

.github/ を含め、履歴をそのまま送る（コミット SHA も個人リポジトリ側と一致する）。ミラー先では CI を走らせないよう、ci.yml と mirror.yml の両方がリポジトリのオーナーを見てジョブを skip する。

手元 ── git push origin ──→ oldsheeep3/TheHack (public)
                              ├ Actions: ci.yml（green になったら↓を起動）
                              └ Actions: mirror.yml
                                  ├ tailscale/github-action で tailnet に参加
                                  └ ssh ──→ VPS: mirror-sync <branch>
                                              ├ 個人リポジトリから fetch（~/mirror/TheHack.git）
                                              └ mirror.sh  … mirror/X を push + PR 作成 + マージ
                                                              ↓
                                              NxTEND-THE-HACK/2026-Team-38 (private)

ブランチ X を push すると:

0. まず CI が走り、green で終わったときだけミラーが起動する（workflow_run トリガー）。 赤い場合・CI が走らないブランチは、直さない限りミラーされない
1. .github/workflows/mirror.yml が tailnet に ephemeral ノードとして参加し、 VPS へ SSH して mirror-sync X を実行する（CI が通った X だけが対象）
2. VPS が個人リポジトリから X を fetch し、tools/mirror/mirror.sh を呼ぶ
3. ミラー先の mirror/X（ミラー専用ブランチ）へ push
4. mirror/X → X の PR を作成（既にオープンならそれを使う）し、マージコミットでマージする

起点が GitHub 側にあるので、どのマシンから push しても（GitHub 上で直接編集しても）ミラーされる。 同期するのは CI が通ったそのブランチだけ。全ブランチ + 全タグをまとめて送るのは手動実行のとき。

ミラー先の main / develop へ直接 push も force push もしない。force は「手元で rebase / amend して mirror/X が fast-forward できなくなった」場合のフォールバックとして mirror/* に対してのみ使う。 ミラー先の ref を削除することはないので、ブランチ削除は同期されない。

Actions が使えないとき（ワークフローの失敗、tailnet の不調、初回の一括コピー）は VPS 側で mirror-sync を直接実行すれば追いつく。

セットアップ:

# VPS 側（gh でログイン済み・gh auth setup-git 済みであること）
scp -r tools/mirror <vps>:~/mirror-install
ssh <vps> 'bash ~/mirror-install/install-vps.sh'

# CI 用の SSH 鍵を作って公開鍵を VPS に置く
ssh-keygen -t ed25519 -N '' -f mirror_ci
ssh-copy-id -i mirror_ci.pub <vps>

# 手動同期（全ブランチ + 全タグ / ブランチ指定）
ssh sheep 'bash -lc mirror-sync'
ssh sheep 'bash -lc "mirror-sync develop"'

個人リポジトリの Settings → Secrets and variables → Actions に登録する secret:

tailnet の ACL で tag:ci から VPS の 22/tcp を許可しておくこと。

• マージは マージコミットで行う（squash / rebase merge だと merge-base が進まず、次回の PR に同じコミットが再び載る）。ブランチ保護で弾かれた場合は gh pr merge --admin で通す。
• ミラー先に同名ブランチが無いと PR は作れない（mirror/X の push だけ行い notice を出す）。 その場合はミラー先で mirror/X からブランチを作る。
• 手動で mirror-sync を叩くときは Actions の実行と重ならないようにする（作業リポジトリを共有 していて、排他はしていない）。
• workflow_run はデフォルトブランチにあるワークフローファイルしか起動しない。mirror.yml は main にも入っている必要がある（develop だけに置いても発火しない）。
• CI の push トリガーは main / develop だけなので、作業ブランチを直接 push してもミラーは 起動しない（PR を出せば CI は走るが、pull_request 由来の実行はミラーの対象外）。作業ブランチを 今すぐミラーしたいときは VPS で mirror-sync <branch> を叩くか、Actions から手動実行する。
• ミラーの実行は concurrency で 1 本に絞っている。実行中 + 待機中がいる状態でさらに CI が green になると待機中が追い出され、そのブランチは次の CI green まで待つ。
• .github/workflows/ も同期するので、VPS の gh ログインには workflow スコープが要る （gh auth refresh -h github.com -s workflow）。無いと push が拒否される。
• タグは手動同期（引数なしの mirror-sync）のときにまとめて送る。ミラー先で既に別のコミットを 指しているタグは上書きしない。

共通プロトコル / ポート

各コンポーネントは親仕様書 §4 の共通定義に準拠する。

詳細（イベントペイロード・設定変更API・タリーペイロード）は docs/specs/00-system-overview.md §4 を参照。

ドキュメント

• 技術仕様（現行実装）: docs/spec/technical-overview.md（詳細） / docs/spec/summary.md（要約） / docs/slides/switcher.md（Marp）
• 配布サイト: web/ — LP + 使い方（web/build-preview.ps1 で1ファイルのプレビューを生成）
• ライセンス: GPL-2.0-or-later（LICENSE / THIRD-PARTY-NOTICES.md）
• 仕様書: docs/specs/ — 親仕様書 + コンポーネント別詳細仕様
• 実装計画 / タスク: docs/tasks/ — マルチエージェント実装のオーケストレーション計画とタスク指示書