WebSocket DAT 完全ガイド | 使い方・パラメータ解説【TouchDesigner】

記事更新の通知はXでアナウンス٩(๑❛ᴗ❛๑)
→ @maru6o6をフォロー

概要 📖 – サーバーと常時接続で通信

WebSocket DATは、WebSocket サーバーへ接続し、テキストやバイナリのメッセージをリアルタイムに送受信する DATです。受信したメッセージは表として出力され、応答処理は Callbacks DAT パラメータに指定した DAT 内の Python コールバックを通して行います。

主な用途 🎯

WebSocket サーバーとのリアルタイム双方向通信
クラウドや外部サービスからのライブデータ受信
複数の TouchDesigner 間でのメッセージ同期
Web アプリやスマートフォンからの遠隔操作の受け付け
TLS (wss) による暗号化された安全な接続

データフロー 🔄

入力: WebSocket サーバーから届くテキスト / バイナリメッセージ
 ↓
処理: Callbacks DAT の Python コールバックで受信内容を解析
 ↓
出力: メッセージ一覧テーブルや TouchDesigner 内のパラメータへ反映

Tips

初心者の方は、以下日本語書籍も手元にあると安心です。

リンク

まる。

実際の案件事例まで踏み込んで紹介されていて、効率よくスキルアップするなら必携の二冊です！

パラメータ解説 ⚙️

Connect Page 📋

接続設定 🎛️

WebSocket サーバーへの接続先と接続状態を制御するパラメータ

Active .active ✅
– Active (有効化) — オンのときネットワークポートへ届く情報を受信します。
– オフのときは更新が止まり、ポートへ届いたデータは失われます。

Network Address .netaddress 🌐
– Network Address (接続先アドレス) — サーバー側コンピュータのネットワークアドレスを指定します。
– foo.bar.com のような WWW アドレスや 100.123.45.78 のような IP アドレスを入力できます。
– localhost を指定すると接続の相手側が同一コンピュータ上にあることを意味します。

Network Port .port 🔌
– Network Port (接続ポート) — DAT がメッセージを受け付けるポート番号です。
– ポート 443 は安全な接続を意味します。

Connection Timeout .timeout ⏱️
– Connection Timeout (接続タイムアウト) — WebSocket DAT がサーバーへの接続を待つ時間 (ミリ秒) です。

Received Messages Page 📥

コールバックと出力 🐍

受信メッセージの処理ロジックと、表として出力されるメッセージ一覧を制御するパラメータ

Callbacks DAT .callbacks 🐍
– Callbacks DAT (コールバック参照) — メッセージが届くたびに 1 回実行される Python コールバックを記述した DAT への参照です。

Execute from .executeloc 📍
– Execute from (実行場所) — スクリプトをどの場所から実行するかを決定します。

From Operator .fromop 🔗
– From Operator (対象オペレータ) — Execute from が「Specified Operator」のとき、状態変化が DAT のスクリプト実行のきっかけとなるオペレータです。
– このオペレータは、スクリプトが実行される際のパス基点も兼ねます。

Clamp Output .clamp 📏
– Clamp Output (出力数の制限) — DAT はデフォルトで 100 メッセージに制限されますが、これをオンにすると無制限を含む任意の値に設定できます。

Maximum Lines .maxlines 🔢
– Maximum Lines (最大行数) — メッセージ数を制限します。
– 上限を超えると古いメッセージから順に一覧から削除されます。

Clear Output .clear 🧹
– Clear Output (出力をクリア) — 見出し行を除く全ての行を削除します。
– Python スクリプトからクリアするには op( "opname" ).par.clear.pulse() を使います。

Bytes Column .bytes 🔣
– Bytes Column (バイト列の列) — メッセージの生のバイト列を別の列として出力します。

実践アイデア 💡

Example 1: ライブデータの受信 📡

WebSocket DAT → Callbacks DAT (onReceiveText) → JSON DAT → パラメータ反映

外部の WebSocket サーバーへ接続し、Callbacks DAT のテキスト受信コールバックで届いたメッセージを解析し、JSON DAT で構造化して TouchDesigner 内のパラメータへ反映する基本フローです。

WebSocket DAT に Network Address と Network Port を設定して Active をオン
Callbacks DAT の受信コールバックで届いたテキストを取得
受信内容を解析して TouchDesigner 内のパラメータやチャンネルへ反映

Example 2: 双方向のメッセージ送信 🔁

TouchDesigner → WebSocket DAT (sendText) → サーバー → 他クライアント

WebSocket DAT の sendText メソッドを Python から呼び出してサーバーへメッセージを送信し、サーバーを介して接続中の他のクライアントへリアルタイムに配信する双方向通信の例です。

WebSocket DAT でサーバーへ接続を確立
Python から sendText でサーバーへメッセージを送信
サーバー経由で接続中の他クライアントへ配信

Example 3: 暗号化された安全な接続 🔐

wss:// 接続先指定 → Network Port 443 → 暗号化通信 → WebSocket DAT

Network Address に wss:// を付与しポート 443 を指定することで、TLS で暗号化された安全な WebSocket 接続を確立し、外部サービスとの通信を保護する構成例です。

Network Address の先頭に wss:// を付けて安全な接続を指定
Network Port を 443 に設定して暗号化された接続を確立

Info情報 📊

WebSocket DAT は Info DAT や Info CHOP による状態情報の取得に対応しています。

DAT 固有情報 📋

num_rows: DAT の行数
num_cols: DAT の列数
type: DAT の型 (table / text)
is_table: テーブル形式の場合 1、テキスト形式の場合 0

汎用オペレータ情報 🔄

total_cooks: プロセス開始からのクック回数
cook_time: 最後のクック時間 (ミリ秒)
cook_frame: 最後にクックされたフレーム番号
warnings: 警告数
errors: エラー数

共通情報 📡

total_cooks: オペレータが調理 (cook) された累計回数
cook_time: 直近の調理にかかった時間 (ミリ秒)
cook_frame: 最後に調理されたフレーム番号
cpu_cook_time: CPU 上での調理時間 (ミリ秒)

トラブルシューティング ⚠️

よくある問題と解決策 🔧

❌ Problem: サーバーに接続できない
✅ Solution:

Active がオンになっているか確認します。
Network Address と Network Port がサーバーの設定と一致しているか確認します。
ファイアウォールで指定ポートが許可されているか確認します。

❌ Problem: 暗号化接続 (wss) が確立できない
✅ Solution:

ポート 443 以外を使う場合は Network Address の先頭に wss:// が付いているか確認します。
サーバー側が安全な接続に対応しているか確認します。
Connection Timeout が短すぎて接続前に失敗していないか確認します。

❌ Problem: 受信メッセージが途中で消える
✅ Solution:

Clamp Output をオンにして上限を引き上げます。
Maximum Lines の値を増やして古いメッセージの削除を抑えます。
受信内容を保持したい場合は後処理として Table DAT に蓄積します。

参考資料 📚

その他 🔗

公式リソース 📖

TouchDesigner公式ドキュメント – WebSocket DAT