> ## Documentation Index
> Fetch the complete documentation index at: https://comfytv.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 表达式 (Expression)
> 把一条数学表达式变成动画曲线——一条逐帧数值轨道，可用来驱动某个 FX 参数，类似 Nuke/AE 的表达式或 wiggle。
## 这个节点是做什么的
**Expression（表达式）** 随时间求值一条数学表达式，输出一条关键帧轨道（`COMFYTV_TEXT`）。你写形如 `sin(t*2)*10` 或 `noise(t*2)*20` 的表达式、选它驱动哪个字段、设采样率和时长，节点即采样曲线。卡片会在你输入时实时绘制曲线预览（有防抖，表达式非法时显示错误信息）。点 **▶ 运行** 输出关键帧。
表达式在安全沙箱里求值：只允许数字字面量、算术/比较/布尔运算符、内置变量和内置函数（不允许属性访问、不允许关键字参数、最长 2000 字符）。
### 可用变量与函数
* **变量：** `frame`、`t`（秒）、`duration`、`fps`，以及常量 `pi`、`e`。
* **函数：** `sin cos tan asin acos atan atan2 exp log sqrt pow abs floor ceil round min max sign degrees radians`；阶跃/插值 `boxstep linearstep smoothstep gaussstep remap mix clamp`；噪声 `noise snoise fbm turbulence cellnoise pnoise random hash`。`seed` 参数为噪声/随机函数播种。
## 适用场景
* 给参数加自然抖动（`noise(t*3)*5`），而非手打关键帧。
* 驱动循环运动（`sin(t*2)*30`）做上下浮动、摆动或脉动。
* 生成斜坡或缓动曲线，喂给某 FX 阶段的关键帧输入。
## 参数说明
### expression（表达式）
要求值的数学表达式。默认 `sin(t*2)*10`。使用上述变量/函数。
### field（字段）
曲线驱动哪个动画字段：`v`、`scale`、`opacity`、`x`、`y`、`rotation`。默认 `v`。这也是写入输出轨道的键名。
### rate（每秒关键帧）
从曲线采样的每秒关键帧数，1–60，默认 10。越高轨道越平滑、关键帧越多。
### duration（时长）
曲线长度（秒），0.05–3600，默认 5。**若接入视频，其真实时长会覆盖此值**（卡片会隐藏 Duration 滑块）。
### fps（帧率）
用于计算 `frame` 变量的每秒帧数，1–120，默认 24。**接入视频的真实 fps 会覆盖此值。**
### seed（种子）
噪声/随机函数的种子，0–99999，默认 0。换值得到不同随机图案。
## 输入与输出
| 接口 | 类型 | 含义 |
| ----------------- | --------------- | --------------------------------------------- |
| **video**（输入） | `COMFYTV_VIDEO` | 可选；存在时其时长和 fps 覆盖滑块 |
| **keyframes**（输出） | `COMFYTV_TEXT` | 采样出的关键帧轨道（每帧 `{t, , interp:"linear"}`） |
## 使用提示
* 接入视频可把曲线锁定到该片段精确的时长和 fps——连接视频后 Duration 滑块会消失。
* 快速变化的曲线调高 `rate` 得到更平滑更密的关键帧；轻量轨道调低。
* 只允许列出的名称——未知名称、关键字参数或非数字常量都会让表达式报错（预览里显示）。
* `t` 是秒，`frame` 是 `t*fps`；按表达式更自然的那个用。
## 类型与 Bridge
`COMFYTV_TEXT` / `COMFYTV_VIDEO` 是 ComfyTV 项目快照，不是 ComfyUI 原生类型。用 **Bridge**（`ComfyTV/Bridge`）与原生节点互通。详见 [bridges.md](https://github.com/jtydhr88/ComfyTV/blob/main/docs/bridges.md)。
## 相关节点
* **FX Chain（FX 链）**——烧录其参数可被表达式轨道驱动的 FX 链。
* 任意接受关键帧轨道的 ComfyTV **VideoFX** 阶段。