TiXL（t3）项目设置（Project Settings）完全指南：Timing、Audio、Proxies、Recording 与 Export 配置详解
【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3
TiXL（仓库代号 t3）是一款开源实时动态图形创作软件。Project Settings（项目设置）是与合成（composition）一起"随身携带"的每项目配置面板，涵盖 Timing（时间与节拍）、Audio（音频）、Video Proxies（视频代理）、Recording（录制）与 Export（导出）五大部分。本文以该面板为核心，逐项讲解每个配置项的用途、参数语义与默认值，并结合仓库源码（CompositionSettings.cs、BarPhaseTracker.cs、AudioReaction.cs 等）说明这些配置在引擎底层的落点，读完即可独立完成一个实时演出或可复现动画项目的完整配置。
项目设置的继承模型：设置住在合成上
项目设置的第一个核心概念是继承：设置保存在合成（composition）上，并被其内部的一切内容继承。面板顶部的复选框（原文为"Specify settings for …"）决定当前合成是自定义自己的设置，还是从父级合成继承。取消勾选即回退到继承，勾选则写出一份属于自己的设置。
从源码看，这套机制对应CompositionSettings类：它被序列化进.t3符号文件中（键名为ProjectSettings，旧项目兼容PlaybackSettings旧键名），并通过面包屑式遍历沿图表层级向上查找，最终由Animation.Playback.Current?.Settings ?? CompositionSettings.Defaults提供当前生效值（见 CompositionSettings.cs）。也就是说：任何运行中的合成在任何时刻都有一个"当前生效的项目设置"，未启用设置的合成自动落到全局默认值上。Defaults中的默认值（BPM=120、Resync Threshold=0.04s、ProRes 代理、1920×1080 等）在 CompositionSettings.cs 中一一可见。
Timing：项目如何运行、时间如何计量
Project Setup：动画型 vs 现场型
Project Setup决定项目整体运行方式，二选一：
- Animation—— 面向可复现的、时间轴驱动的作品：有已知时长、有关键帧动画。
- Live / Interactive—— 面向现场演出（VJ set）、装置艺术等实时交互场景。
两种模式共用同一套时间底座，差别主要在同步与交互能力上（见下文 Sync Mode）。
BPM：一切时间都以"小节"为单位
TiXL 的一个关键设计是：所有时间都以音乐小节（musical bars）而非秒运行，因此BPM直接控制整个项目的动画速度——把 BPM 调准，能让程序化动画严格锁定在节拍上。播放引擎侧，BpmProvider以单例形式存在，编辑器每帧轮询TryGetNewBpmRate(out float bpm)获取新的 BPM 值并触发节拍更新（见 BpmProvider.cs）；配置侧，PlaybackConfig.Bpm默认 120，序列化字段名即Playback.Bpm。
Timeline Display则只影响时间轴标尺（ruler）的显示单位：Bar（小节）、Seconds（秒）或 Frames（帧）三选一，属于显示层偏好，不改动底层数据。
On BPM Change：改 BPM 时对剪辑与关键帧做什么
修改 BPM 时，项目里已有的剪辑（clip）和关键帧有两种处置方式：
- Stretch with Beat（默认）—— 保留它们的小节数值不动，于是所有内容随节拍一起变快或变慢。适合音乐驱动的作品。
- Keep Seconds—— 重缩放本合成的剪辑位置、关键帧和循环范围，让它们停留在相同的秒数上，只有网格（grid）移动。适用于"BPM 当初测错了需要修正"或"这是一个叙事剪辑而非音乐剪辑"的场景。
两个重要边界（原文明确）：
- 嵌套合成永远不会被重缩放——因为它们可能在其他地方被复用；
- 视频/音频的修剪（trims）在两种模式下都以秒为单位，所以内容本体永远不会位移。
无论哪种模式，一次 BPM 编辑都只算一个撤销步骤。源码中两种模式对应枚举BpmChangeModes { StretchWithBeat, KeepSeconds }（见 CompositionSettings.cs）。
Sync Mode（仅 Live / Interactive 模式）
现场模式下可选的时钟源：
- Timeline—— 项目仍跑在自己的时间轴上，使用固定的 BPM 速率。
- Tapping—— 每拍敲一下 Sync 按钮（或热键），实时设定速度。配合audio beat lock（音频节拍锁定），编辑器会监听音频输入中的瞬态（transients），持续微调播放速度以咬合到来的节拍。
关于节拍锁定，源码提供了比文档更细的两条分析路径（枚举BeatLockSources，见 CompositionSettings.cs）：
- Onset Detection（瞬态检测）——跟随瞬态/起音，需要一次敲击重同步来找到小节起点；
- Phase Model（相位模型）——使用神经网络（DanceAi 的 bar-phase 模型）自主找速度和起始拍，并回报置信度（
ExpectedPhaseError，值越低越自信）。实现见 BarPhaseTracker.cs：模型文件位于可执行文件旁的dance-phase/目录（本仓库见 Dependencies/dance-phase），捕获回调只做降混与重采样入队，推理（每 16ms 音频约 4ms）跑在独立后台线程上，绝不阻塞音频驱动；锁相逻辑通过 BPM 微调渐进修正（slew），播放永不跳变。
Beat Sync Offset微调相位偏移——当视频处理设备让画面输出延迟时，用它把节拍相位往前挪来补偿。对应字段BeatLockAudioOffsetSec，默认 0 秒，另有BeatLockSmoothing（0=紧贴模型、抖动快；1=信任运行节奏、平滑但响应慢，默认 0.5）可在面板中调节。
Audio：主音量、音频分析与反应性
Main Volume设置项目整体音频输出电平（源码中对应AudioMixConfig.SoundtrackVolume/OperatorVolume等混音参数的总体表现）。Resync Threshold（重同步阈值）控制音频播放相对动画允许漂移多大才触发重同步——文档给出正常区间0.02–0.05 秒，源码默认值AudioResyncThreshold = 0.04f（见 CompositionSettings.cs）。
Audio Analysis and Reactivity：驱动音频反应型算子
这一节配置驱动 AudioReaction 这类音频反应型算子的信号：
- Input Device（输入设备）——留空则使用机器的默认设备；该选择按机器存储（
AudioInputDeviceName字段），因此共享项目在任意机器上都能正常工作。面板上显示为 "Default Audio Input"。 - Gain（增益）——补偿各设备不一的输入电平，源码字段
AudioGainFactor默认 1。 - Decay（衰减）——塑造反应回落的速度，源码字段
AudioDecayFactor默认 0.9（0.9 意味着较快的回落）。 - 电平表（level meter）——显示的是经过增益之后的输入信号。
反应型算子底层消费的是统一的音频分析数据：AudioReaction.cs 提供Level、WasHit、HitCount输出，以及一个可插入音频图的Result（AudioGraphNode）通道——把它插在某个 [AudioBus] 之前，就能只对那一部分音源做反应，而不是整个混音。分析侧的 FFT 与频段参数在 AudioConfig.cs 中以编译期常量定义（FFT 缓冲 1024、32 个频段、低频/高频分离截至 250Hz/2000Hz 等），说明音频分析管线是预分配的、低延迟友好的。
主声道（Main Soundtrack）与时间轴音频
自 TiXL 4.3 起，音频以普通算子的形态活在时间轴上：把音频文件从 Asset Library（资源库）或系统文件管理器拖到时间轴，它就变成一个 [AudioClip]——可以像任意剪辑一样拖动、修剪、分割、循环、静音，且一个项目可并行播放多个音频剪辑。
其中一个剪辑可以成为主声道（main soundtrack），它有三个作用：
- 渲染为时间轴后面的全宽背景图像；
- 驱动音频反应型算子；
- 决定导出可执行文件的时长。
两种设置入口：在项目设置中点击Create Soundtrack（已有主声道时变为Select and focus Main Soundtrack），或右键时间轴上的任意音频剪辑选择Set as main soundtrack。
主声道的几个行为细节：
- 它总是横跨其完整源内容；
- 它的剪辑块会从时间轴图层中隐藏——背景图像就是它的表现形式；
- 要重新定位它或把它变回普通剪辑，把该算子的Display参数改回Clip即可。
源码侧，CompositionSettings.TryGetMainSoundtrack()会在启用的设置列表中找IsMainSoundtrack == true的剪辑；同时兼容"主声道是图表中的算子"的情况——AudioClip算子的 Display 为 BackgroundImage 时即把自身标记为主声道，且该判断不依赖设置是否启用（见 CompositionSettings.cs）。播放端，主声道通过 BASS 解码流接入 SoundtrackMixer：现场播放路径为Stream → SoundtrackMixer → GlobalMixer → Soundcard，导出时则直接从流读取数据（见 SoundtrackClipStream.cs），这也解释了"听到什么就导出什么"的保证。
路由与混音
把剪辑的AudioReference输出接到 [AudioBus] 即可完成路由——可以直接接，也可以经过 [CombineAudio] 分组以及 [AudioReverb]、[AudioEcho]、[AudioCompressor] 等效果链。链路上任意位置挂一个 [AudioLevel] 抽头都能测量信号，例如配合 [DuckAudioLevel] 实现"人声出现时压低音乐"的闪避（ducking）。
- 在总线或分组上启用AutoCollectClips，未接线（unwired）的剪辑会自动加入该总线。
- 关键保证：你听到的一切，也正是导出到视频和可执行文件中的内容。
Video Proxies：预览用的降采样代理
代理（Proxy）是视频剪辑的降采样、快寻址副本，仅供预览使用——渲染输出永远使用全分辨率原片（这也意味着代理绝不会影响最终成片质量）。
工作流：
- 从视频算子的右键上下文菜单生成代理；
- 在项目设置中勾选Use proxies for preview，预览/拖拽（scrub）时即使用代理。
参数说明：
| 配置项 | 含义与建议 |
|---|---|
| Proxy Format | 代理编码格式。ProRes是均衡的默认值；Hap 系列拖拽最快但文件更大（对应源码ProxyConfig.Format，默认VideoExportCodec.ProRes；注释明确代理一律采用 all-intra/LGPL 编码，绝不使用 GPL 的 H.264/HEVC） |
| Proxy Resolution | 代理尺寸为源分辨率的几分之一，默认 0.5（即半分辨率，源码ProxyConfig.Resolution = 0.5f）；越小寻址越快、越省磁盘 |
| Storage | 显示已生成代理占用的磁盘空间——按项目统计与跨项目总计，并提供一键清理；清理不影响源片，代理可随时重新生成 |
ProxyConfig的三个字段（Format / Resolution / UseForPreview）与Audio、Export一样，序列化在ProjectSettings.Proxy节点下（见 CompositionSettings.cs），并整体保存在项目的.t3文件中随项目走。
Recording：时间轴 Record 按钮捕获什么
Recording区决定时间轴上的Record（录制）按钮捕获哪些来源：
- Capture Audio—— 录制当前激活的音频输入设备（即上文 Audio 区选择的 Input Device）。
- Capture IO—— 把进入的MIDI 和/或 OSC 事件录制到音频剪辑旁的一个数据文件里，使一次现场演出（live take）事后可以回放并精修。
录制输入输出实现位于 IoServices 项目（如 MidiDataRecording.cs、OscDataRecording.cs、IoDataSetRecorder.cs），数据文件落点与命名规则可参考 RecordingPaths.cs（录制路径定义在 Core 音频目录下）。
Export：导出可执行文件的默认值
Export区设置导出为独立可执行文件时的默认值（真正执行导出通过 [ui:PlayerExporter|export dialog] 即"导出对话框"，菜单 File → Export as Executable）：
- Title / Author—— 窗口标题与启动对话框中显示的作者行；留空则回退到算子和包名（源码
ExportConfig.Title/Author默认空字符串）。 - Window Mode—— 可执行文件启动时是全屏还是窗口（源码默认
WindowMode.Fullscreen）。 - Preferred Width / Height—— 可执行文件启动时的渲染分辨率（默认 1920×1080）；若启用启动对话框，则优先让观看者从显示器原生模式中选择。
- Skip Startup Dialog—— 直接按这些设置启动，不再询问显示器、分辨率和窗口模式；观看者仍可用
--dialog参数强制弹出对话框。 - Show Log Messages—— 在可执行文件旁打开一个带日志输出的控制台窗口（默认关闭）。
- Strip Unused Operators—— 只打包连接到导出输出的算子（外加自动播放的音频算子）及其所需库；若导出后内容缺失，可关闭此项重试（默认开启）。
- Enable Playback Control—— 观看者可用方向键跳转时间、空格暂停（对应源码
EnablePlaybackControlWithKeyboard，默认 true）。
导出时长由主声道的长度决定（与 Audio 区联动）。面板底部的Export按钮导出当前合成——前提是该合成位于某个父合成之内且具有 Texture2D 输出；旁边的文件夹图标打开上次导出位置。
快速参考：关键默认值一览
以下默认值均来自 CompositionSettings.cs 的Defaults实例与字段初始化：
| 配置 | 默认值 |
|---|---|
| BPM | 120 |
| On BPM Change | Stretch with Beat |
| Resync Threshold | 0.04 s（推荐区间 0.02–0.05 s） |
| Audio Gain | 1.0 |
| Audio Decay | 0.9 |
| Beat Lock Source | OnsetDetection（可选 PhaseModel / PhaseModelRaw） |
| Beat Lock Smoothing | 0.5 |
| Beat Sync Offset | 0 s |
| Proxy Format | ProRes |
| Proxy Resolution | 0.5（源分辨率的一半） |
| Use proxies for preview | 开 |
| 导出分辨率 | 1920×1080 |
| 导出窗口模式 | Fullscreen |
| 键盘播放控制 | 开 |
| Strip Unused Operators | 开 |
面板中每个字段旁的(?)悬停提示可随时查阅简短的字段解释（见 ProjectSettings_Timing.md 等嵌入式帮助页）。整套设置随合成写入.t3文件并支持新旧格式自动迁移（旧键PlaybackSettings、旧版"BPM 存在剪辑上"的迁移逻辑见 CompositionSettings.cs），这让项目设置真正做到了"随项目旅行、跨机器可用"。
【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
