N Tech Flow

イマーシブ 配信 API ​

イマーシブ（Z-3）の演出システムと、プリセットを選ぶ制御プログラムのあいだのやりとり。 HTTP（REST）／MQTT／OSC（UDP）の 3 系統で構成される。

本ページはモック実装の API 契約を記述する。 動いている実装サンプルを読んで起こしたもので、 実機の仕様ではない。とくに OSC のアドレス体系は受信側の仕様が未確定のため暫定（実装サンプル側にも その旨の記載がある）。確定次第、本ページを合わせる。

演出コンテンツそのもの（プリセット・AI アナウンス音声・POV 映像・キーワード）の データモデルは コンテンツ管理 を参照。

系統用途向き
HTTP（REST）演出データの取得、プリセット選択の受付制御プログラム・タブレット → サーバ
MQTTいま選ばれているプリセットと進行状態の配信サーバ → 購読側（タブレット等）
OSC（UDP）当日の進行の signal（プリロード・開始・アナウンス・映像・キーワード・終了）サーバ（MD-2） → MD-8（TouchDesigner）

HTTP（REST） ​

  • ベースパス: /api/immersive
  • Basic 認証の対象外
  • 該当なしは 404 ＋ { error, url, statusCode, statusMessage, message }
  • レスポンスは全て schemaVersion を持つ（現在 "1.0"）
#メソッドパス用途状態変化
IMM-API-1GET/api/immersive/presetsプリセット一覧。?language=ja / ?language=en で絞れるなし
IMM-API-2GET/api/immersive/presets/{preset_id}演出データ取得（アナウンス台本・キーワード・movieSet）なし
IMM-API-3GET/api/immersive/audio/{audio_id}AI アナウンス音声の取得（audio/mp4）なし
IMM-API-4GET/api/immersive/sessionいま選ばれているプリセットと進行状態なし
IMM-API-5POST/api/immersive/sessionプリセットを選ぶ（ready）。body は { presetId }あり
IMM-API-6DELETE/api/immersive/session選択を解除して idle へ戻す。OSC は送らないあり

プリセット一覧（IMM-API-1） ​

json
{
  "schemaVersion": "1.0",
  "presets": [
    { "presetId": "ja-1", "language": "ja", "name": "通常版",
      "movieSet": "default", "displayOrder": 1 }
  ]
}
  • ja-1〜ja-8 / en-1〜en-8 の 計 16（コンテンツ管理の「日英それぞれ 8 種類」と一致）
  • movieSet は default / business / capability / internal の 4 種。POV 映像 4 本から 1 つを選ぶ指定にあたる

演出データ取得（IMM-API-2） ​

json
{
  "schemaVersion": "1.0",
  "presetId": "ja-1", "language": "ja", "name": "通常版", "movieSet": "default",
  "announces": [
    { "index": 1, "part": "intro", "text": "…", "audioUrl": "…/api/immersive/audio/audio-ja-1-intro-2" }
  ],
  "keywords": [
    { "slot": 1, "keywordId": 1, "name": "人手不足",
      "headline": "…", "problem": "課題：…", "solution": "対策：…" }
  ]
}
要素内容
announces6 本。index 1〜6 は台本の通し番号で、OSC /immersive/announce の引数、および操作キー対応表の通番と一致する。part は intro（1〜3）／launch（4〜6）
keywords常に 12 要素（slot 1〜12）。name ／ headline ／ problem（課題）／ solution（対策）は キーワードマスターの列に対応する。未割り当ての枠は keywordId を含む全フィールドが null（12 枠すべてを埋める必要はない / 2026-08-21 確定）
audioUrl音声の実体は IMM-API-3 から audio/mp4 で取れる

セッション取得（IMM-API-4） ​

json
{
  "schemaVersion": "1.0",
  "status": "ready", "presetId": "ja-1", "language": "ja",
  "revision": 1786279677339,
  "updatedAt": "2026-08-19T18:43:22.556+09:00"
}

MQTT を張れないときの取得口。同じ内容が MQTT でも配信される。

MQTT ​

  • エンドポイント: wss://<host>/mqtt（MQTT over WebSocket）
  • トピック: immersive/session（QoS 1・retained）
  • ペイロードは IMM-API-4 と同じ

retained なので購読した瞬間に現在の選択が 1 通届く。 切断から復帰したときもこれで復元できる。

  • 受信側は revision が手元の値以下なら捨てる。自分が叩いた HTTP のレスポンスと retained の到着は前後する
  • updatedAt は前後関係の判定に使わない（ミリ秒が衝突しうる）
  • 再接続のたびに手元の revision を戻し、接続後の最初の 1 通は必ず採用する（サーバ再起動で振り直されても追従できる）

OSC（UDP） ​

  • OSC 1.0（UDP）。受信側は TouchDesigner 製のクライアントで、イマーシブPC MD-8 で動く（2026-08-21 確定）
  • 送信先は環境変数 IMMERSIVE_OSC_HOST / IMMERSIVE_OSC_PORT（既定ポート 9000）
  • 未設定時は動作確認用の内部レシーバへ送り、画面から宛先を追加すればそこへも同報する（最大 8 件）
アドレス引数送る契機
/immersive/session/ready,s preset_idプリセットが選ばれたとき（タブレットのタップ、または IMM-API-5）。演出はまだ始まらない。同じ preset_id で何度でも届く（再送は「読み直し」の指示）
/immersive/session/start,s preset_idready のあとスタートしたとき。1 セッションにつき 1 回
/immersive/announce,i index（1〜6）アナウンスの操作をしたとき。index は announces[].index と一致
/immersive/movie/startなし映像開始の操作をしたとき。どの動画かは movieSet で決まる（引数には載らない）
/immersive/keyword/showなしキーワード表示の操作をしたとき。出す内容は keywords（12 スロット）
/immersive/keyword/backなし詳細を見たあと、別のキーワードを選べるよう一覧へ戻すとき。本演出では使わない（2026-08-21 確定。プロセス C）
/immersive/session/endなし終了の操作をしたとき。締めのアナウンス（launch の最後）を /immersive/announce で鳴らしてから、このアドレスを送る 2 通構成
/immersive/session/restartなし強制停止のあと、最初からやり直すとき
/immersive/session/stopなし進行を中断するとき。締めのアナウンスは鳴らさない

ready と start で送る preset_id を IMM-API-2 にそのまま渡すと、その回に流す中身が取れる。 ready を取りこぼしていても start で取りに行けるよう、未ロードならその場で読み込む実装にしておく。

本システムでの扱い（2026-08-21 確定）: MD-2 から OSC で飛ぶのは /immersive/session/ready だけ。 スタート以降の進行（start / announce / movie/start / keyword/show / end / stop / restart）は、 操作キーを MB-2 → MD-8 のローカル直結で受けて MD-8 が処理する。 実装サンプルはこれらもサーバから送るが、本システムでは経路を分ける （利用プリセットの指定元）。

進行状態（status）の移り変わり ​

idle → ready → playing → stopped の 4 状態。

状態意味
idle選択なし。初回起動時
readyプリセットが選ばれ、受信側が読み込み中／読み込み済み
playing演出の進行中
stopped終了または強制停止で締めた状態
  • 選ぶ・再選択・選び直しは IMM-API-5、解除は IMM-API-6。 スタート・終了・強制停止・リスタートは操作タブレットで行う
  • 同じプリセットへの再選択も受理し、そのたびに OSC の ready を送り直す
  • playing のあいだは POST も DELETE も 409 session_in_progress で弾く。 走行中の公演を外から差し替えさせないため、また OSC を送らない解除を受理すると受信側は流れたままサーバだけ選択を失うため。終了か強制停止で締めてから選び直す
  • 選択が無いまま開始すると 409 session_not_ready。逆に ready を経ない開始そのものは受理する（当日の運用を止めないため）
  • サーバを再起動しても status は保たれる（選択していたプリセットが消えていた場合だけ idle に戻る）

本リポジトリの記述との差分 ​

実装サンプルを読んで判明した差分は、すべて解消した（2026-08-21）。

解消済み

  • 強制停止・リスタートは設ける（2026-08-21。プロセス B 例外・補足）
  • キーワード一覧へ戻す操作（/immersive/keyword/back）は演出に入れない（2026-08-21。プロセス C）
  • プリセット指定の経路はサーバ経由（HTTP POST → MQTT retained → OSC）で決着（2026-08-21。利用プリセットの指定元）
  • OSC の受信側は MD-8（TouchDesigner クライアント）で決着（2026-08-21。MD-8 / MD-9 の役割分担）
  • 当日の操作キーはサーバを経由しない。MB-2 → MD-8 のローカル直結のまま（2026-08-21。経路を 1 本にまとめる必要はないという判断）
  • AI アナウンスの通番は (1)〜(6) に揃えた。締めの挨拶が (6)（2026-08-21。操作キー対応表）
  • キーワードは 12 枠固定で本リポジトリと一致していた（差分ではなかった）。あわせて 12 枠すべてを埋める必要はなく、空き枠は null で返ることを確認（2026-08-21。コンテンツ管理）
  • プリセット名は実装サンプルを踏襲（2026-08-21。コンテンツ管理 — プリセット）