@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/animation.md

@@ -0,0 +1,221 @@
+# 动画参考
+
+基于时间的运动模式 — keyframes、LFO、timers、easing、表达式驱动的动画。
+
+在设置参数之前，务必针对 op 类型调用 `td_get_par_info`。以下参数名反映了 TD 2025.32 版本，但如果出现错误，请进行验证。
+
+---
+
+## 时间源
+
+TD 有三种时间参考 —— 请选择正确的一种。
+
+| Expression | Behavior | Use for |
+| --- | --- | --- |
+| `absTime.seconds` | TD 启动以来的挂钟时间（秒）。从不重置。 | 连续运动、GLSL `uTime`、无限循环 |
+| `absTime.frame` | 挂钟帧数。 | 精确到帧的触发 |
+| `me.time.frame` | 局部 component 帧数（播放/停止时重置）。 | 每个 COMP 独立的动画时间轴 |
+| `me.time.seconds` | 局部 component 秒数。 | 同上，以秒为单位 |
+
+**规则：** 对于着色器和连续运动，请使用 `absTime.seconds`。对于 COMP 内部的触发/循环动画，请使用 `me.time.*`。
+
+---
+
+## LFO CHOP — 循环运动
+
+最简单的周期性驱动器。快速、对 GPU 消耗低、易于在表达式中使用。
+
+```python
+lfo = root.create(lfoCHOP, 'rot_driver')
+lfo.par.type = 'sin'        # 'sin' | 'cos' | 'ramp' | 'square' | 'triangle' | 'pulse'
+lfo.par.frequency = 0.25    # cycles per second
+lfo.par.amplitude = 1.0
+lfo.par.offset = 0.0
+lfo.par.phase = 0.0         # 0-1, useful for offsetting parallel LFOs
+```
+
+**通过 export 驱动参数：**
+
+```python
+op('/project1/geo1').par.rx.mode = ParMode.EXPRESSION
+op('/project1/geo1').par.rx.expr = "op('rot_driver')['chan1'] * 360"
+```
+
+**多个同步的 LFO（具有 phase 偏移的 X/Y/Z 旋转）：**
+创建一个包含三个通道的 LFO 并分别设置 phase 偏移，或者使用三个 LFO 并偏移它们的 `phase` 参数 (0.0, 0.33, 0.66)。
+
+---
+
+## Timer CHOP — 触发序列
+
+用于单次运行动画、节拍锁定序列或基于阶段的逻辑。
+
+```python
+timer = root.create(timerCHOP, 'fade_timer')
+timer.par.length = 4.0       # cycle length in seconds
+timer.par.cycle = False      # run once vs. loop
+timer.par.outputseconds = True
+```
+
+输出通道：`timer_fraction`（在整个周期内从 0→1）、`running`、`done`、`cycles`。
+
+**启动计时器：**
+```python
+timer.par.start.pulse()
+```
+
+**驱动淡入淡出：**
+```python
+op('/project1/level1').par.opacity.mode = ParMode.EXPRESSION
+op('/project1/level1').par.opacity.expr = "op('fade_timer')['timer_fraction']"
+```
+
+**在计时器分数上应用缓动** —— 直接在表达式中应用：
+
+```python
+# Smoothstep: ease in/out
+expr = "smoothstep(0, 1, op('fade_timer')['timer_fraction'])"
+# Cubic ease-out: 1 - (1-t)^3
+expr = "1 - pow(1 - op('fade_timer')['timer_fraction'], 3)"
+```
+
+---
+
+## Pattern CHOP — 自定义曲线
+
+用于任意波形（锯齿坡度、缓动曲线、自定义包络）。
+
+```python
+pat = root.create(patternCHOP, 'envelope')
+pat.par.type = 'gaussian'    # 'gaussian' | 'ramp' | 'square' | 'sin' | etc.
+pat.par.length = 60          # samples
+pat.par.cyclelength = 1.0    # seconds at TD framerate
+```
+
+结合 `lookupCHOP` 通过自定义曲线重新映射 0-1 的驱动值。
+
+---
+
+## Animation COMP — 基于关键帧
+
+用于多关键帧运动图形。每个 animationCOMP 包含的通道可以在 Animation Editor 中编辑关键帧。
+
+```python
+anim = root.create(animationCOMP, 'intro_anim')
+# By default has channels chan1..chanN; access via:
+# op('intro_anim').par.length, .par.play, .par.cue, etc.
+
+# Drive a parameter from a channel
+op('/project1/text1').par.tx.mode = ParMode.EXPRESSION
+op('/project1/text1').par.tx.expr = "op('intro_anim/out1')['chan1']"
+```
+
+**关键帧通常在 UI（Animation Editor）中编辑**，但也可以在内部通过 `keyframes` 表进行设置。要以编程方式创建关键帧，请使用 `td_execute_python`：
+
+```python
+# Get the channel CHOP inside an animationCOMP
+ch = op('/project1/intro_anim/chans')
+# Insert a key (advanced API — verify with td_get_par_info(op_type='animationCOMP'))
+ch.appendKey('chan1', frame=0, value=0.0, expression=None)
+ch.appendKey('chan1', frame=120, value=1.0)
+```
+
+对于大多数使用场景，请使用 LFO/Timer/Pattern CHOP 来驱动参数 —— 更简单且易于编写脚本。
+
+---
+
+## 表达式中的缓动
+
+TD 的表达式求值器支持 Python 数学运算。常见的缓动形式：
+
+```python
+# Linear
+"t"
+
+# Smoothstep (classic ease-in-out)
+"smoothstep(0, 1, t)"
+
+# Ease-out cubic
+"1 - pow(1 - t, 3)"
+
+# Ease-in cubic
+"pow(t, 3)"
+
+# Ease-in-out cubic
+"3*t*t - 2*t*t*t"
+
+# Bounce (manual, simplified)
+"abs(sin(t * 6.28 * 3) * (1 - t))"
+```
+
+这里的 `t` 是 `op('fade_timer')['timer_fraction']` 或任何 0-1 的驱动器。
+
+---
+
+## Filter CHOP — 平滑现有通道
+
+在驱动视觉元素之前，平滑掉不稳定的数值（例如音频分析、传感器数据）。
+
+```python
+filt = root.create(filterCHOP, 'smooth')
+filt.par.filter = 'gaussian'   # or 'lowpass'
+filt.par.width = 0.5            # smoothing window in seconds
+filt.inputConnectors[0].connect(op('raw_signal'))
+```
+
+**警告：** 切勿在 timeslice 模式下对 AudioSpectrum 输出使用 Filter CHOP —— 它会膨胀采样数量并将频段平均值拉低至接近于零。请参阅 `audio-reactive.md`。
+
+---
+
+## Lag CHOP — 非对称的起效/释放
+
+为数值的上升和下降提供不同的速度。这是可视化音频包络的标准做法。
+
+```python
+lag = root.create(lagCHOP, 'env_smooth')
+lag.par.lag1 = 0.02   # attack (rise time, seconds)
+lag.par.lag2 = 0.30   # release (fall time, seconds)
+lag.inputConnectors[0].connect(op('raw_envelope'))
+```
+
+快速起效，缓慢释放 = 经典的 VU 表手感。
+
+---
+
+## 通过 Script DAT 实现逐帧驱动
+
+对于不适合使用表达式的复杂逐帧逻辑，请使用 `executeDAT`（`onFrameStart` 回调）或 `chopExecuteDAT`。
+
+```python
+# In an executeDAT (frameStart):
+def onFrameStart(frame):
+    t = absTime.seconds
+    op('/project1/circle').par.tx = math.sin(t * 2.0) * 3.0
+    op('/project1/circle').par.ty = math.cos(t * 2.0) * 3.0
+    return
+```
+
+繁重的逻辑依然应该放在 CHOP 中处理（CPU 消耗低、确定性强）。请将脚本留给一次性执行或非实时分支逻辑。
+
+---
+
+## 避坑指南
+
+1. **帧率依赖** —— `me.time.frame` 基于 TD 项目帧率（默认为 60）。如果你的项目帧率发生变化，运动速度也会改变。请使用 `seconds` 进行独立于速率的计时。
+2. **Cooking 预算** —— 每个驱动参数的 CHOP 每一帧都会进行 cook。合并你的驱动器（一个大型 mathCHOP 好过许多小型的）。
+3. **表达式模式** —— 参数默认为 `CONSTANT`。除非设置了 `par.X.mode = ParMode.EXPRESSION`，否则 `par.X.expr = ...` 会被忽略。
+4. **Animation editor 编辑** —— 通过 UI 设置的关键帧存在于 animationCOMP 的内部 keyframe 表中。它们在保存/重新打开后依然存在。通过 `appendKey()` 程序化创建关键点是可行的，但请先使用 `td_get_docs(topic='animation')` 验证 API。
+5. **循环动画** —— 要实现无缝循环，`length` 必须等于 `cyclelength`，并且首尾值必须匹配。否则会出现肉眼的跳帧。
+
+---
+
+## 快速秘诀
+
+| 目标 | 最简途径 |
+| --- | --- |
+| 连续旋转 | LFO CHOP `type='ramp'`, expr → `geo.par.rx` |
+| 2秒内淡入 | Timer CHOP `length=2`, smoothstep expr → `level.par.opacity` |
+| 随节拍脉冲 | 来自音频的 `triggerCHOP` → 通过 expression 驱动缩放 |
+| 3D Lissajous 轨道 | 两个不同频率的 LFO，驱动 `tx`/`ty`/`tz` |
+| 随机抖动 | 将 `noiseCHOP`（低频率）添加到位置上 |
+| 定时场景切换 | Timer CHOP → switchTOP/CHOP `index` |

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/audio-reactive.md

@@ -0,0 +1,175 @@
+# 音频驱动参考
+
+基于音频驱动视觉效果的 Pattern —— 频谱分析、节拍检测、包络跟随。
+
+## 音频输入
+
+```python
+# Live input from audio interface
+audio_in = root.create(audiodeviceinCHOP, 'audio_in')
+audio_in.par.rate = 44100
+
+# OR: from audio file (for testing)
+audio_file = root.create(audiofileinCHOP, 'audio_in')
+audio_file.par.file = '/path/to/track.wav'
+audio_file.par.play = True
+audio_file.par.repeat = 'on'       # NOT par.loop
+audio_file.par.playmode = 'locked'
+```
+
+---
+
+## 音频频段提取（已在 TD 2025.32460 验证）
+
+使用 `audiofilterCHOP` 进行频段分离（不要通过通道索引使用 `selectCHOP`）：
+
+```python
+# Audio input
+af = root.create(audiofileinCHOP, 'audio_in')
+af.par.file = path
+af.par.play = True
+af.par.repeat = 'on'
+af.par.playmode = 'locked'
+
+# Low band: lowpass @ 250Hz
+flt_low = root.create(audiofilterCHOP, 'flt_low')
+flt_low.par.filter = 'lowpass'
+flt_low.par.cutofffrequency = 250
+flt_low.par.rolloff = 2
+flt_low.inputConnectors[0].connect(af)
+
+# Mid band: highpass@250 → lowpass@4000
+flt_mid_hp = root.create(audiofilterCHOP, 'flt_mid_hp')
+flt_mid_hp.par.filter = 'highpass'
+flt_mid_hp.par.cutofffrequency = 250
+flt_mid_hp.par.rolloff = 2
+flt_mid_hp.inputConnectors[0].connect(af)
+
+flt_mid_lp = root.create(audiofilterCHOP, 'flt_mid_lp')
+flt_mid_lp.par.filter = 'lowpass'
+flt_mid_lp.par.cutofffrequency = 4000
+flt_mid_lp.par.rolloff = 2
+flt_mid_lp.inputConnectors[0].connect(flt_mid_hp)
+
+# High band: highpass @ 4000Hz
+flt_high = root.create(audiofilterCHOP, 'flt_high')
+flt_high.par.filter = 'highpass'
+flt_high.par.cutofffrequency = 4000
+flt_high.par.rolloff = 2
+flt_high.inputConnectors[0].connect(af)
+
+# Per-band: RMS → lag → gain → clamp
+for name, filt in [('low', flt_low), ('mid', flt_mid_lp), ('high', flt_high)]:
+    rms = root.create(analyzeCHOP, f'rms_{name}')
+    rms.par.function = 'rmspower'  # NOT 'rms'
+    rms.inputConnectors[0].connect(filt)
+
+    lag = root.create(lagCHOP, f'lag_{name}')
+    lag.par.lag1 = 0.05   # attack (NOT par.lagin)
+    lag.par.lag2 = 0.25   # release (NOT par.lagout)
+    lag.inputConnectors[0].connect(rms)
+
+    math = root.create(mathCHOP, f'scale_{name}')
+    math.par.gain = 8.0
+    math.inputConnectors[0].connect(lag)
+
+    # mathCHOP has NO par.clamp — use limitCHOP
+    lim = root.create(limitCHOP, f'clamp_{name}')
+    lim.par.type = 'clamp'
+    lim.par.min = 0.0
+    lim.par.max = 1.0
+    lim.inputConnectors[0].connect(math)
+
+    null = root.create(nullCHOP, f'out_{name}')
+    null.inputConnectors[0].connect(lim)
+    null.viewer = True
+```
+
+**TD 2025 关键修正：**
+- `analyzeCHOP.par.function = 'rmspower'` 而不是 `'rms'`
+- `lagCHOP.par.lag1` / `par.lag2` 而不是 `par.lagin` / `par.lagout`
+- `mathCHOP` 没有 `par.clamp` —— 须使用单独的 `limitCHOP`
+
+---
+
+## 节拍 / 起音检测
+
+### 底鼓检测（slope → trigger）
+
+```python
+slope = root.create(slopeCHOP, 'kick_slope')
+slope.inputConnectors[0].connect(op('out_low'))
+
+trig = root.create(triggerCHOP, 'kick_trig')
+trig.par.threshold = 0.12
+trig.par.attack = 0.005    # NOT par.attacktime
+trig.par.decay = 0.15       # NOT par.decaytime
+trig.par.triggeron = 'increase'
+trig.inputConnectors[0].connect(slope)
+
+kick_out = root.create(nullCHOP, 'out_kick')
+kick_out.inputConnectors[0].connect(trig)
+```
+
+---
+
+## 将音频传递给 GLSL
+
+```python
+glsl.par.vec0name = 'uLow'
+glsl.par.vec0valuex.expr = "op('out_low')['chan1']"
+glsl.par.vec0valuex.mode = ParMode.EXPRESSION
+
+glsl.par.vec1name = 'uKick'
+glsl.par.vec1valuex.expr = "op('out_kick')['chan1']"
+glsl.par.vec1valuex.mode = ParMode.EXPRESSION
+```
+
+```glsl
+uniform float uLow;
+uniform float uKick;
+float scale = 1.0 + uKick * 0.4 + uLow * 0.2;
+```
+
+---
+
+## 标准音频总线 Pattern
+
+推荐的结构：
+
+```
+audiodeviceinCHOP (audio_in)
+        ↓
+  [null_audio_in]
+        ├──→ audiofilterCHOP (lowpass@250) → analyzeCHOP → lagCHOP → mathCHOP → limitCHOP → null
+        ├──→ audiofilterCHOP (bandpass@250-4k) → analyzeCHOP → lagCHOP → mathCHOP → limitCHOP → null
+        ├──→ audiofilterCHOP (highpass@4k) → analyzeCHOP → lagCHOP → mathCHOP → limitCHOP → null
+        │
+        └──→ slopeCHOP → triggerCHOP (beat_trigger)
+```
+
+将整个总线保留在一个 `baseCOMP`（例如 `audio_bus`）内，并通过路径从视觉网络中进行引用。
+
+---
+
+## MIDI 输入
+
+```python
+midi_in = root.create(midiinCHOP, 'midi_in')
+midi_in.par.device = 0  # Check midiinDAT for device index
+# Outputs channels named by MIDI note/CC: 'ch1n60', 'ch1c74', etc.
+
+# Map CC to a parameter
+op('bloom1').par.threshold.mode = ParMode.EXPRESSION
+op('bloom1').par.threshold.expr = "op('midi_in')['ch1c74'][0]"
+```
+
+---
+
+## 严重警告：绝对不要使用 Lag CHOP 进行频谱平滑
+
+在 timeslice 模式下，Lag CHOP 会将 256 个采样的频谱扩展到 1600-2400 个采样，导致所有数值平均后接近于零（~1e-06）。Shader 将无法接收到任何可用数据。请直接使用 `mathCHOP(gain=8)`，或者在 GLSL 中通过带有 feedback texture 的 temporal lerp 进行平滑处理。
+
+已验证情况：
+- 不使用 Lag CHOP：低频段 = 5.0-5.4（信号强，可用）
+- 使用 Lag CHOP：所有频段 = 0.000001（死信号）