ESP-Mosaico 轮滑动画编排台：拍点吸附、完整动作编辑与工程保存
做音乐驱动动画时，自动分析可以先排出一条动作序列，但"这个转体往后挪一拍会不会更合适"，仍然要反复听和看。早期我直接修改轮滑项目里的参数，再等待它播放到对应位置。问题出在歌曲中间时，观察和修改之间的间隔尤其明显。
我给这个黑胶轮滑项目做了一个电脑编排台：先单独查看动作，再拖进音乐时间线，调整位置和拍数，最后保存为能够继续编辑的工程。本文重点记录时间线背后的数据规则，以及为什么没有照搬视频剪辑软件的自由裁切方式。
1. 界面负责操作，模型负责修改规则
编排台采用 Python 桌面界面，动作库、预览区、时间线和属性面板分别负责选择、观察、安排和精确调整。项目里几个关键模块的分工如下：
动作库 / 属性面板 / 时间线
↓ 编辑意图
EditorProject：拍数校验、覆盖、历史、保存
↓ 当前编排计划
音频播放位置 → C / WebAssembly 渲染 → 画面studio/timeline.py 处理鼠标命中、拖动预览和拍点查找；studio/model.py 中的 EditorProject 负责真正改变编排。拖动时先画出待放置动作的预览，松开鼠标才提交修改，避免鼠标移动的每一帧都产生一条历史记录。
这种分工还有一个实际好处：从时间线拖动，或者在右侧填写起始拍和时长，最后都走同一套模型校验。界面不能绕过规则，直接写入一个放不下的动作。
2. 先看完整动作，再决定放在哪里
动作库当前可选 52 套预制动作。资源中登记了 55 套，其中低滑下压、舒展摆臂和前后轮摆转已经停用；界面只统计启用项。预制指动作过程已经写好，导入音乐时是在挑选和安排这些动作，不是重新训练人物。
动作可以按等级筛选，也可以搜索名称、英文名或相关脚法。点击卡片后，预览会切到该动作的完整循环，演示速度可选 80、100、120、150 BPM。
动作库搜索与完整动作演示。单独演示为静音，便于观察身体姿态。
这里把两种播放方式分开了：单独演示会暂停歌曲，以独立时钟循环当前动作；回到编排并播放，才检查这个动作与音乐的关系。放慢动作有助于观察膝盖、手臂和朝向变化，但最终仍要放回歌曲里判断。
3. 用真实拍点定位，不用固定 BPM 重新铺网格
音乐计划里保存了每个拍点对应的音频采样位置。时间线先把鼠标横坐标换算为采样位置，再用二分查找找到附近拍点，比较前后距离后吸附到最近的一拍。
因此，动作条的起止位置来自拍点数组：起点取第 first_beat 个拍点，终点取第 first_beat + beat_count 个拍点。两者的采样差除以采样率，才是动作占用的秒数。
这个顺序对于变速音乐很重要。八拍并不天然等于四秒，必须看这八拍在当前歌曲中实际经过了多久。移动动作也只改变它引用的拍点下标，音乐里的拍点位置保持原样。
把完整动作拖入时间线。波形、拍点和动作范围可以放在一起观察。
例如，这次保存的连续转体位于 6.25 至 10.25 秒，占八拍。这是当前测试工程里的对应关系，不是编辑器对所有歌曲规定的固定时长。
拍点吸附也不等于音乐分析一定正确。它保证的是动作落在已有拍点上；如果听起来整条网格都偏离了音乐，仍要回到分析结果检查。拍点、鼓点和动作片段在数据里各有作用，不能因为某处出现一个鼓声，就把它直接当成所有动作都应该开始的位置。
4. 为什么动作条不能随意剪成半截
视频剪辑可以保留素材前半段，再接上另一段画面。这套预制动作不适合直接这样处理：一个动作如果刚抬起腿就被截断，下一段从中性姿态开始，身体会突然换位置。
模型用 allowed_counts() 给每套动作生成合法拍数。它既考虑动作自身的编写规则，也检查当前位置到歌曲末尾还剩多少拍。当前连续转体要求八拍，一些动作允许四拍或八拍；具体选项由动作规则决定，并非所有动作都能任意选同一组长度。
所以，调整右边缘的含义是选择允许的完整动作时长。右侧同时修改起始拍与拍数时，也会先按新位置、新时长一起校验；校验失败就不提交，避免位置已经移动、时长却没有改成功。
重叠处理同样采取完整片段规则。EditorProject._put() 中查找重叠的条件，下面只整理了换行，省略后续验证与提交：
overlaps = [
old for old in self._placements
if old["id"] != item["id"]
and old["first_beat"] < item["end_beat"]
and item["first_beat"] < old["end_beat"]
]首尾刚好相接不会被视为重叠；时间范围确有交集时，旧动作整段移除，新动作加入。编辑器不会替旧动作保留一截残片。放错以后可以撤销，再重新选择位置。
5. "整理衔接"的实现范围
保存片段并不等于已经获得一条连续表演。模型在 build_plan() 中按时间顺序遍历动作，将没有安排内容的拍点区间补为完整滑行。较长空白分段填充，原音乐拍点继续保留。
这些预制动作在编写时采用共同的中性首尾姿态，尽量在动作完成后回到可连接的位置。整理依靠的是完整片段、约定的首尾和空白补齐，没有针对任意两个人体姿势现场求出一段受力过渡。
因此，"时间线没有空洞"和"整段表演自然"要分开判断。连续大转体后立刻跳跃，数据上可以接起来，视觉上仍可能太赶。我的处理方式是从动作之前开始播放，把进入、完成和滑出一起看，必要时留一段滑行。
撤销、重做在这里很有用。模型保存编辑状态快照，修改失败不提交历史；试过一版密集安排后，可以回到之前的状态比较，而不必凭记忆逐块移回去。
6. 音乐播放与预览共用一条时间参照
歌曲编排播放时，画面根据音频播放位置查询当前动作。暂停、定位、继续播放以后，渲染仍然回到同一条音频时间线取状态。
如果让画面简单按界面刷新次数推进，某次绘制变慢之后，动作与声音就可能逐渐错开。这里把"当前播到了哪里"交给音频播放位置，渲染负责画出这个位置对应的状态，便于反复比较同一处。
人物绘制复用项目的 C 渲染代码，通过 WebAssembly 在电脑端执行，而没有另做一套只在桌面近似表演的小人。这样，修改动作或绘制逻辑后，可以先在编排台里查看同一套逻辑的结果。
7. 工程文件与音频为什么分开保存
保存产生 .vskproj 工程，它实际是 JSON，包含动作位置、分析数据、编排计划以及背景、唱片颜色、脚边特效等设置。当前人物选择属于预览界面状态，没有保存进工程，不能把所有界面选项都理解成已持久化。
保存编排后可以重新打开。工程与相邻 WAV 音频需要一起保留。
音频另存为同目录的 WAV。文件名由工程名和 PCM 内容 SHA-256 的前十二位组成，工程中记录音频文件名、完整校验值、采样数和采样率。这里的 WAV 采用 16 kHz、单声道、16 位 PCM。
这样设计后，再次保存可以复用已经校验正确的音频。写入时先生成临时文件，再替换目标文件，减少半写入状态。重新打开工程时，还会检查音频格式、PCM 校验、长度和采样率，避免编排误配到另一首音乐。
搬动工程时必须把相邻 WAV 一起带走。实际检查时，我复制了最终工程和对应音频再重新读取，连续转体仍保持在 6.25 至 10.25 秒。这里核对的是保存后的编排数据，不只是看一个"保存成功"提示。
8. 我现在怎样用这套编排台
我的修改顺序是：先搜索并单独看动作，再拖到拍点；从进入动作之前播放，调整位置和合法拍数；整理空白后再整体回看，最后保存并重新打开。
遇到问题时也可以按同一条链路排查。放不下动作，先看剩余拍数和允许时长；旧片段突然消失，先检查是否发生整段覆盖；工程打开后找不到音乐，先确认相邻 WAV 是否一起复制；整理后仍然生硬，则回到动作顺序和准备时间继续调整。
自动编排提供一版起点，电脑工作台提供继续修改的入口。它的价值在于把"某一拍感觉不对"变成可以定位、试改、撤回和保存的操作。下一步我准备继续拆解脚下轨迹，看看滑行、腾空和落地怎样影响留下的线条。
我是阿白，感谢你的观看。