TiXL Time Clip 时间重映射全算子一致性评估：从视频剪辑播放、Slip/Stretch 到帧精确导出的完整验证指南

TiXL Time Clip 时间重映射全算子一致性评估从视频剪辑播放、Slip/Stretch 到帧精确导出的完整验证指南【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3导读本文围绕 TiXL 4.3 中 Time Clip 的核心行为变更——时间剪辑现在对整个算子operator统一重映射时间而不再只作用于拉取其输出的消费者——展开技术解析与手工验证。文章以仓库中 .tests-manual/time-clip-evaluation.md 的 8 组评估步骤为主体骨架结合 TimeClip.cs、TimeClipSlot.cs、VideoClip.cs、_ProcessVideoClips.cs 等源码实现讲透时间重映射的数据模型与评估机制并给出可直接照做的回归验证操作清单帮助开发者与内容创作者确认[VideoClip]上的动画参数随剪辑移动/滑动、[MidiClip]不再通过Values输出二次重映射、拉伸剪辑会拉伸其内部关键帧——这些日常剪辑工作流在 4.3 中保持行为一致。评估背景为什么需要整算子统一重映射在 TiXL 的时间线中Time Clip 由[TimeClip]、[VideoClip]、[AudioClip]等算子输出它们只在当前播放时间落入剪辑的TimeRange内才被求值详见 .help/docs/using/Timeline.md 的 Working with time clips 一节。本次 4.3 变更的核心是重映射的作用范围变更前重映射只作用于拉取 time-clip 输出的那个消费者导致同一个剪辑的不同输出路径可能拿到不一致的时间。变更后重映射作用于整个算子——无论哪个消费者、哪条输出路径求值该剪辑得到的都是同一份剪辑本地时间clip-local time。由此带来三项用户可见的行为[VideoClip]上已动画化的参数会跟随剪辑一起移动move或滑动slip[MidiClip]旧版[_MidiClip_Old]不再通过Values输出二次重映射时间拉伸stretch剪辑时剪辑内部的关键帧随之拉伸。本评估手册scope: timeline随 4.3 于 2026-08-08 加入就是用来验证重映射在所有输出上一致应用且日常剪辑工作流行为不变的回归测试集。评估前置条件原文档明确列出了 3 项前置条件照做才能让下面的步骤可复现前置条件说明Composition Settings需打开一个启用了自身 Composition Settings 的项目用于确定剪辑所在组合的 BPM视频文件磁盘上准备一段 5–30 秒的短视频.mp4或类似格式MIDI 文件可选若想验证 MIDI 步骤另备一段较短的.mid文件时间重映射的源码模型TimeClip 与 TimeClipSlot在动手验证之前先建立源码级的认知。时间重映射的全部数据与算法都封装在 Core/Animation/TimeClip.cs 与 Core/Operator/Slots/TimeClipSlot.cs 中。TimeClip两个时间区间 一个单位 一对仿射映射TimeClip的核心字段如下见 TimeClip.csTimeRange剪辑在父时间线上的放置区间以 bar 为单位表达见枚举ClipTimeUnits。SourceRange剪辑对应的源内容区间单位可能是 bars 或 seconds。SourceUnitSourceRange的单位——秒seconds用于墙钟媒体视频、音频bar 用于音乐内容嵌套合成、MIDI由所属算子的类型经TimeClipSlot推导。LayerIndex剪辑所在层。两个仿射映射函数构成了重映射的全部数学基础// 时间线 bar - 剪辑源时间 public double MapTimelineToSource(double timelineBars) { var pos timelineBars - TimeRange.Start; var duration TimeRange.End - TimeRange.Start; if (Math.Abs(duration) 0.0001f) pos * (SourceRange.End - SourceRange.Start) / duration; return pos SourceRange.Start; } // 剪辑源时间 - 时间线 bar逆映射 public double MapSourceToTimeline(double sourceBars) { /* 对称实现 */ }见 TimeClip.cs。两者都是仿射且无界的——越界由调用方自行钳制或门控。重映射的速率剪辑的速度定义为Speed |SourceRange.Duration / TimeRange.Duration|见 TimeClip.cs例如 4 bar 时间线承载 2 bar 源内容即为 50% 速度。对秒单位的媒体剪辑实际播放速率还需乘以 BPM 因子GetPlaybackSpeed() Speed * playbackBpm / 240.0TimeClip.cs。TimeClipSlot求值期的范围门控 时间改写TimeClipSlotT是剪辑算子的输出槽类型它把UpdateAction包装为UpdateWithTimeRangeCheck见 TimeClipSlot.cs在每次求值时范围门控若context.LocalTime落在TimeRange之外且未开启EvaluateOutsideRange则跳过更新标记为Suspended或Inactive。时间改写在调用真正的更新动作前把context.LocalTime与LocalFxTime通过MapTimelineToSource改写为剪辑本地时间更新完成后恢复原值。这一改写再恢复的模式正是重映射作用于整个算子的机制剪辑内部子图看到的LocalTime已是源时间因此所有输出、所有内部参数求值天然共享同一时间基准。两类特殊标记接口IContentTimeClip标记源区间以秒为单位锚定源起点 0与项目 BPM 无关的媒体剪辑如[VideoClip]、[AudioClip]见 TimeClipSlot.cs。编辑器在创建时将其SourceRange默认为[0, duration]。变更项目 BPM 不会移动这类剪辑在 bar 上的位置媒体仍从文件的同一时刻开始。IPreventingTimeRemap标记像[TimeClip]这类子元素中没有嵌套内容的算子拖动时不把源区域链接到剪辑区域对应TimeClip.UsedForRegionMapping标志见 TimeClip.cs。旧文件兼容SourceUnit 迁移SourceUnit字段是后加的旧文件没有它。读取时若缺失该字段TimeClipSlot会置位NeedsSourceUnitConversion并在知道算子类型后一次性完成转换把 bar 单位的源区间按240 / BPM换算为秒同时调用Animator.ScaleKeyTimesOfChild缩放该子节点的关键帧时间见 TimeClipSlot.cs。TimeClip对象被该符号子节点的所有实例共享因此这个标志天然防重复转换。关键帧在哪个时间空间里动画曲线的采样与写入都在剪辑本地时间进行。Animator提供了两条路径GetLocalAnimationTime(instance, globalTimeInBars)从最外层到最内层依次组合每层ITimeClipProvider输出的MapTimelineToSource把全局播放时间换算成某实例动画输入被采样时的本地时间见 Animator.cs。GetGlobalAnimationTime(instance, localTimeInBars)逆映射用于把关键帧的 U 值映射回其生效的全局播放时间Animator.cs。这保证了在播放时间 t 做的值修改也必须在时间 t 播放回来——无论剪辑如何拉伸或滑动。配套的GetLocalTimeTolerance约 1/100 bar 的容差则用于把位于播放头附近的关键帧吸附到既有关键帧避免因浮点误差插入重复键Animator.cs。回归验证步骤详解以下 8 组步骤全部来自 .tests-manual/time-clip-evaluation.md每组均给出Action操作与Expected预期并补充对应源码依据。时间线的通用操作slip、stretch、trim、缩放、吸附、快捷键可参考 .help/docs/using/Timeline.md。步骤 1视频剪辑正常播放回归操作把视频文件拖入时间线的剪辑区创建一个[VideoClip]将其接入[VideoClipPlayer]或开启播放器的 AutoCollect。跨剪辑播放来回 scrub。预期视频严格沿剪辑的区间播放从第一帧开始Scrub 时显示对应的帧无历史偏移。源码依据[VideoClip]的纹理输出本身就是一个TimeClipSlotTexture2D且EvaluateOutsideRange true见 VideoClip.cs——媒体剪辑必须允许在剪辑窗口外被拉取以便解码器预卷和首末帧钳制。求值时context.LocalTime已由槽改写为源时间秒随后被钳制到SourceRange内再向VideoPlaybackEngine请求帧VideoClip.cs。这解释了为什么视频从第一帧开始、无偏移——因为播放时间的映射是仿射且精确的。步骤 2Slipping 让画面、缩略图与源区域一致操作把播放时间停在剪辑中间记下输出中显示的帧按住Ctrl Alt在剪辑体内向右拖动约一个小节slip 滑动素材检查输出、剪辑两侧边缘缩略图、以及标尺中的源区域指示。预期画面跟随鼠标向右滑动后停在原播放时间的输出显示视频中更早的帧剪辑左右边缘缩略图更新为新的 in/out 帧标尺中的源区域随拖动量右移——内容、缩略图、区域三者讲述同一件事Ctrl Z恢复原播放时间的帧。源码依据slip 只改SourceRange而不动TimeRangeMapTimelineToSource的几何含义即把时间线窗口映射到源素材上滑动。Timeline 文档的 Source region and slipping footage 一节明确拖拽源区域避开白色选区线的部分即 slip——素材在剪辑固定的时间窗下滑动位置与速度不变按住Shift可绕过吸附。边缘缩略图对应剪辑 in/out 点的源帧Timeline.md因此必须与新 in/out 帧同步更新这正验证了内容、缩略图、区域一致。步骤 3动画参数随剪辑一起移动操作在[VideoClip]上对Color的 alpha 做淡入动画Alt click参数在剪辑起点和一 bar 处添加关键帧确认淡入播放正常然后把整个剪辑在时间线上向后拖两个 bar再次播放。预期淡入发生在新的剪辑起点——关键帧随剪辑移动Dope sheet 中关键帧显示在其剪辑内部位置。源码依据关键帧存于剪辑本地时间空间。_ProcessVideoClips在合成每个活动剪辑时会先把context.LocalTime改写为该剪辑的MapTimelineToSource结果再拉取该剪辑的Color、BlendMode等 per-clip 参数见 _ProcessVideoClips.cs与TimeClipSlot的改写逻辑完全一致——animated values must be sampled in the clips local time, like everything the clip evaluates itself。因此剪辑整体平移时本地时间轴不变关键帧相对剪辑起点不动淡入自然跟随剪辑移动。步骤 4拉伸剪辑 拉伸动画操作保持淡入剪辑不变按住Alt拖动剪辑末端手柄stretch——内容缩放适配把剪辑长度翻倍跨剪辑播放。预期淡入从一 bar 变为两 bar——动画随内容一起被拉伸不按Alt时trim 只显示/隐藏素材、保持播放速率淡入仍保持原来的一 bar 时长。源码依据stretch 同步缩放SourceRange与TimeRange的比值关系Speed随之变化Speed SourceRange.Duration / TimeRange.Duration。由于关键帧以本地时间存储映射的拉伸自然把一 bar 的淡入变为两 bar。而 trim不按Alt只改变TimeRange边界、保持源映射与速度因此淡入时长不变。这与姊妹评估 .tests-manual/time-clip-keyframe-insertion.md 中拉伸后淡出发生在播放时间 2–4内容 bar 1–2 占据时间线 bar 2–4的预期完全一致——两篇手册互为印证。步骤 5Preroll 仍能预热解码器回归操作把两个[VideoClip]首尾相接放置硬切由同一个[VideoClipPlayer]绘制跨切点播放数次。预期切入剪辑的第一帧精确出现在切点——解码器启动期间没有透明/黑帧闪烁。源码依据_ProcessVideoClips将每个剪辑分类为Inactive / Active / Upcoming三态见 _ProcessVideoClips.cs。处于Upcoming的剪辑切点前PrerollSeconds 0.5秒内会被提前GetValue拉取预热其解码器_ProcessVideoClips.csEvaluateOutsideRange保证预热拉取不会触发范围门控。范围判断使用排他性末端localTime range.End与TimeClipSlot自身一致确保相邻剪辑在共享切点的同一帧不会同时绘制。步骤 6导出帧精确回归操作通过 Render-to-file 渲染切点附近以及淡入剪辑几秒视频逐步查看切点周围的结果。预期导出帧与编辑器预览一致切点落在同一帧淡入一致。源码依据VideoClip.Update在请求帧时传入context.Playback.IsRenderingToFile并仅在活动且帧未就绪时置位Playback.OpNotReady见 VideoClip.cs让导出管线等待帧就绪从而保证帧精确。这也意味着重映射在导出路径上与实时预览走同一份LocalTime改写逻辑导出的帧与编辑器所见逐帧对应。步骤 7[_MidiClip_Old]在所有输出上时序一致本步骤刻意使用已退役的[_MidiClip_Old]算子它直接输出通道值、被标记为 obsolete——它正是Values输出曾存在双重重映射 bug 的算子。现行的[MidiClip]基于 DataClip前身为[LoadMidiFile]从未受影响。操作无.mid文件可跳过创建[_MidiClip_Old]并载入 MIDI 文件把其Values输出接入任意消费者如[Value]读取某个通道记录播放中第一批事件触发的时刻。把剪辑拉伸到 50% 速度Alt拖末端手柄使长度翻倍。预期事件在播放头越过其在剪辑内位置时触发——50% 速度下原本在剪辑内 1 bar 处触发的事件现在在 2 bar 处触发拉伸被精确应用一次此前Values输出会应用两次事件以双倍速率漂移。源码依据修复后的_MidiClip_Old在Update中直接使用context.LocalTime作为 bar 时间注释明确写道LocalTime already arrives remapped into the clips source time (bars) — every output of a clip-shaped op gets the TimeClips remap, so no manual TimeRange→SourceRange math here见 _MidiClip_Old.cs。即重映射由TimeClipSlot统一完成一次算子内部不再手动换算——这正是整算子统一重映射修复的双重应用问题。MIDI 事件的触发条件为bars minRange bars minRange |SourceRange.Duration|本地时间直接与源区间比较_MidiClip_Old.cs。步骤 8禁用 / 重新启用剪辑回归操作选中[VideoClip]并禁用快捷键或上下文菜单再重新启用播放。预期禁用时剪辑不渲染重新启用后与之前完全一致地播放控制台没有关于 invalid time clip update action 的警告。源码依据TimeClipSlot.SetDisabled在禁用时会暂存原始更新动作与DirtyFlag.Trigger重新启用时经RestoreUpdateAction恢复——若不做暂存恢复动作会写空触发器导致Animated触发器丢失、重启用后槽永不重新求值见 TimeClipSlot.cs。此外UpdateAction的 setter 对null赋值会同时清空包装器避免重编译后残留一个每帧报警的无效时间剪辑更新动作包装TimeClipSlot.cs。合成器侧ClassifyClip对已禁用的剪辑直接返回Inactive——禁用的剪辑如同不存在而不是合成其冻结的最后一帧_ProcessVideoClips.cs。两方面共同保证禁用不渲染、启用照旧、无控制台警告。评估结论与验证矩阵把 8 组步骤汇总为一张验证矩阵便于回归时逐项勾选#场景核心验证点源码锚点1视频正常播放首帧起播、scrub 无偏移VideoClip.cs2Slipping画面/缩略图/源区域一致、可撤销TimeClip.cs3动画随剪辑移动关键帧位于剪辑本地时间Animator.cs、_ProcessVideoClips.cs4拉伸 拉伸动画Speed 语义、trim 与 stretch 区分TimeClip.cs5Preroll 预热切点无黑帧、Upcoming 态提前拉取_ProcessVideoClips.cs6导出帧精确IsRenderingToFile OpNotReady 等待VideoClip.cs7旧 MIDI 剪辑单次重映射事件在 50% 速度下于 2 bar 处触发_MidiClip_Old.cs8禁用/重新启用不渲染、恢复一致、无警告TimeClipSlot.cs常见问题与注意事项Ctrl Z的边界slip 与关键帧的撤销都在评估范围内步骤 2、3而重新插入关键帧不是撤销——插入始终捕获当前采样值要恢复原键应使用撤销详见 .tests-manual/time-clip-keyframe-insertion.md 第 4 步的注释。Shift C只作用于标量参数向量参数如 Color会被跳过防止敲击 step marker 破坏可见动画见 .help/docs/using/Timeline.md。媒体 vs 音乐的时间单位视频/音频源修剪以秒记忆改 BPM 不移动剪辑在 bar 上的位置、素材仍从文件同一时刻开始嵌套组合类剪辑则全程使用 barTimeline.md。remap 与关键帧编辑的交互Timeline 文档提醒remap 后的时间与关键帧编辑的交互有时出人意料提交 remap 前先考虑是否真的必要Timeline.md。Not Connected? 提示未被任何播放器管理的剪辑不会渲染并显示提示——这是正常的提示信息而非本次回归的失败Timeline.md。完成以上 8 组验证且全部符合预期即可确认当前构建的时间重映射在所有输出上应用一致、日常剪辑工作流行为不变——这正是 .tests-manual/time-clip-evaluation.md 这份评估手册的全部目的。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考