内容
# TouchDesigner AI Brain
一个公开、实用的工具包，旨在帮助 AI 编程代理构建实时的 TouchDesigner 系统：投影映射、VJ 搭建、音频反应视觉效果、交互式装置和演出控制工作流程。
目标不是取代 TouchDesigner 工艺。目标是为 AI 助手提供足够的架构、文档、安全检查和实时控制界面，以便在实际的 TD 会话中变得有用。
## 这是什么
TouchDesigner 是视觉的、实时的和有状态的。这使得它对于普通的编程代理来说很不适应，它们在可以读取和编辑文本文件时最为开心。这个存储库是连接这些世界之间的桥梁。
它收集了：
- 用于实时 TouchDesigner 自动化的推荐 MCP/控制堆栈，
- 当前 TouchDesigner AI/MCP 工具和有用的社区组件的审计，
- 用于 VJ 和投影映射工作的项目架构，
- 用于审查的 `.tox`、`.toe`、MCP 和参考项目的源注册表，
- 用于演出准备和第三方资产接收的检查清单，
- 可以构建可重用网络的 TD Python 启动器脚本。
## 核心思想
使用多个控制层，每个层都适用于其最佳部分：
| 层 | 工具 | 最适合 |
| --- | --- | --- |
| 实时构建桥 | [Embody / Envoy](https://github.com/dylanroscover/Embody) | 创建运算符，连接网络，设置参数，导出 `.tdn`，检查错误，捕获输出 |
| 参考桥 | TouchDesigner 文档 MCP | 运算符/API 查询，版本感知指导，Python 文档，工作流程模式 |
| GUI 回退 | 计算机使用自动化 | 调色板 UI，对话框，校准视图，视觉验证，参数窗格 |
| 持久回退 | TD Python 构建脚本 | 可复制的脚手架，修复脚本，Textport/DAT 执行 |
对于实时工作，最有前途的路径是：
1. 运行 TouchDesigner。
2. 添加嵌入式 MCP 桥，如 Envoy。
3. 让 AI 通过 MCP 检查和编辑实时网络。
4. 将重要网络导出为 `.tdn`、`.tox` 或 Python，以便更改可审查和重复。
## 为什么这很重要
投影映射和 VJ 项目通常不仅仅是一个酷炫的视觉效果。它们需要一个完整的系统：
- 音频分析，
- 控制器/MIDI/OSC 输入，
- 场景库，
- 特效架，
- 媒体播放，
- 实时监控，
- 投影仪校准，
- 紧急熄灯和绕过路径，
- 可以在演出压力下生存的版本补丁。
这个存储库是使用 AI 助手构建该系统的起点，该助手可以推理补丁，修改它并验证它。
## 存储库地图
```text
.
├── AGENTS.md # 本存储库的代理行为规则
├── checklists/
│ └── live-build-checklist.md # 演出和资产安全检查清单
├── docs/
│ ├── architecture.md # 建议的 AI + TD 项目架构
│ └── toolkit-audit.md # 当前 MCP/工具/组件审计
├── mcp/
│ └── .mcp.example.json # 示例本地 MCP 客户端配置
├── registry/
│ └── sources.yml # 审查的源注册表
└── touchdesigner/
└── brain_vj_builder.py # TD Python 启动器
```
## 快速入门
克隆存储库：
```bash
git clone https://github.com/sarveshsea/touchdesigner-ai-brain.git
cd touchdesigner-ai-brain
```
审查审计：
```bash
open docs/toolkit-audit.md
```
将 MCP 示例配置复制到 AI 客户端期望的格式：
```bash
cp mcp/.mcp.example.json .mcp.json
```
然后安装并启用您选择的 TouchDesigner MCP 桥。目前推荐 [Embody / Envoy](https://github.com/dylanroscover/Embody) 作为主要的实时控制层，[8beeeaaat/touchdesigner-mcp](https://github.com/8beeeaaat/touchdesigner-mcp) 作为一个更简单的 WebServer DAT 备份。
## 第一个示例
[Spotify Fluid Map V1](examples/spotify-fluid-map) 是此存储库中的第一个公开示例。它目前使用 Spotify Desktop 获取正在播放的元数据，BlackHole 将系统音频环回至 TouchDesigner，并使用 TD Python 构建器构建 1920x1080 流体反馈投影映射器。
它故意是一个个人/本地原型。对于公共演出或录制作品，请将音频源替换为具有版权清除的本地文件、DJ 源或音频接口输入。
## 启动网络脚手架
`touchdesigner/brain_vj_builder.py` 中的第一个脚本创建一个顶级 `brain_vj` COMP，包含子系统壳：
- `audio_in`
- `audio_analysis`
- `control_bus`
- `scene_bank`
- `fx_rack`
- `mixer`
- `mapper`
- `monitor`
- `safety`
在 TouchDesigner 的 Python 环境中：
```python
exec(open('/path/to/touchdesigner-ai-brain/touchdesigner/brain_vj_builder.py').read())
build()
```
这故意是一个脚手架。下一步是用 Envoy、TD Python 或手动策划的 `.tox` 组件替换每个子系统壳。
## 有用的第一方 TouchDesigner 区域
Derivative 的内置调色板和文档是在引入社区组件之前的第一站：
- [调色板组件](https://docs.derivative.ca/Category:Palette)
- [投影映射](https://docs.derivative.ca/Projection_Mapping)
- `audioAnalysis`
- `moviePlayer` / `movieEngine`
- `kantanMapper`
- `camSchnappr`
- `projectorBlend`
- `stoner`
- `quadReproject`
- `particlesGpu`
- `feedback`
- `opticalFlow`
- `probe`
## 要评估的社区组件
这些并未在此处列出。它们作为候选项在 `registry/sources.yml` 中跟踪，并且对于 Spotify 示例，在一个驱动下载器中，该下载器将文件存储在忽略的运行时存储中：
```bash
python3 examples/spotify-fluid-map/scripts/fetch_community_toolkit.py --list
python3 examples/spotify-fluid-map/scripts/fetch_community_toolkit.py
```
当前的 Spotify 工具包候选项包括：
- [Embody / Envoy](https://github.com/dylanroscover/Embody)
- [RayTK](https://github.com/t3kt/raytk)，锁定到 TD-2023 版本
- [有用的 TouchDesigner Toxes](https://github.com/aaronmylespereira/TD-Toxes)
- [13 Tap Bloom](https://github.com/EnviralDesign/TD-13TapBloom)
- [ISF TouchDesigner](https://github.com/marcinbiegun/isf-touchdesigner)
- [VIDVOX ISF 文件](https://github.com/Vidvox/ISF-Files)
- [MaxMainio TD_ 组件](https://github.com/MaxMainio/TD_)
- [TouchDesigner 主导色](https://github.com/raganmd/touchdesigner-dominant-color)
- 可选的本地候选项，例如 [okVJ Shared](https://github.com/ok-vj/okVJ-Shared)
有关摄入顺序和许可证说明，请参见 [examples/spotify-fluid-map/docs/community-toolkit.md](examples/spotify-fluid-map/docs/community-toolkit.md)。
## 安全模型
将 `.toe`、`.tox` 和 MCP 桥视为可执行的本地代码。
在采用任何第三方资产之前：
- 记录其源 URL、作者、许可证和下载日期，
- 记录其保存的 TouchDesigner 版本，
- 检查它是否使用 Python、网络、编译插件或外部文件，
- 在空白项目中进行烟雾测试，
- 验证运算符错误、FPS、输出分辨率和崩溃行为，
- 然后将其移入生产演出文件。
对于 MCP 桥：
- 尽可能绑定到 localhost，
- 除非您故意设计一个安全的演出控制网络，否则不要将 TD 自动化端口暴露给 LAN，
- 不要在 DAT、参数、`.env` 或提交的 MCP 配置文件中存储 API 密钥或凭证。
## 路线图
- 添加 Codex 和其他 MCP 客户端的完整 Envoy 设置指南。
- 添加最小的音频反应 TOP 网络构建器。
- 添加具有场景库、特效架、混音器、输出映射器和安全控件的 VJ 房屋模板。
- 添加用于 `.tox` 引入的烟雾测试模板。
- 连接实时 Envoy 项目后添加 `.tdn` 示例。
- 添加投影映射和输出捕获的视觉验证说明。
- 构建 TD 版本、MCP 工具和社区组件的公共兼容性矩阵。
## 贡献
欢迎贡献，特别是：
- 可复制的 TD Python 构建器，
- `.tdn` 示例，
- 安全的 MCP 设置说明，
- 投影映射工作流程说明，
- 组件审计报告，
- 性能测试结果，
- 具有明确许可证的源可用 `.tox` 工具的链接。
请避免提交二进制演出文件，除非它们很小、源代码清晰且故意作为示例。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
TouchDesigner 是 Derivative 的产品。该项目是独立的、面向社区的。
