# Hypit → 剪映：可编辑工程交接

该工作流保留独立的画面、声音和文字，按 Hypit 工程的时间安排生成剪映多轨草稿。
它不是官方直连接口，也不是任意 Hypit 项目到剪映的无损转换。当前已有真实项目的单向转换案例，
尚没有随仓库分发的通用 Hypit 工程导出器；转换脚本需要理解具体项目的画面结构。

## 实际案例：约 50 秒的 IG 滚动动画教程

案例使用已完成的 Hypit 成片归档及其独立素材，展示基础时间线和可编辑图层的交接。

| 项目 | 核实结果 |
| --- | --- |
| 时长 / 画幅 | 50.233333 秒，30 fps，对应 1507 帧；1080 × 1920 |
| 素材 | 39 份视频、图片和音频，按内容哈希校验并复制 |
| 画面 | 8 条轨道、38 段，包括人物与可独立替换的补充画面 |
| 声音 | 1 条独立音轨、7 段已对齐配音 |
| 文字 | 14 条轨道、109 段可编辑文字 |
| 合计 | 23 条轨道、154 段内容 |
| 素材处理 | 复用已有归档，无需重新调用生成模型 |

### 哪些已经验证

- **11.4.2 历史记录（2026-09-18）**：构建、逐文件校验和本机首页登记通过；原生界面打开，
  媒体库、人物、补充画面和文字轨可见，无素材丢失提示；界面时长为 `00:00:50:07`。
- **11.5.0 本次实测（2026-09-19）**：只读回查同一 Hypit 成片归档，剪辑结构与保存的交接快照一致；
  39 份源素材及其交接副本逐项哈希相符。换新草稿名，在独立目录重新构建并通过 `verify-build`；
  仍为 23 轨、154 段、50.233333 秒，源素材未变，未覆盖已有剪映草稿。
- **本机首页与播放**：独立草稿登记、原生打开通过；实际播放至 `00:00:50:07`，观察到人物、插入画面、
  独立文字轨和音量电平，无素材丢失提示。这不等于逐帧视觉或完整主观听感全部合格。
- **剪映原生导出**：1080×1920、30 fps、H.264/AAC，1507 / 1507 帧、50.233332 秒，
  完整解码与来源 build 不变检查通过；约 35.9 秒完成。没有补帧或用外部编码替代原生输出。
- **保存与冷重开**：正常退出确认进程结束，重新启动并打开同一独立草稿，从开头播放至
  `00:00:50:07`，未见素材丢失提示。再次正常退出后的最终回读通过：23 轨、154 段、
  39 份媒体、50.233333 秒，保存格式为 `187.0.0`，四份活动镜像一致，来源文件未变。
- **音频对齐检查**：7 段原配音与导出音轨逐段数值对照，相关系数为 0.9871–0.9999，
  最佳对齐偏移不超过 0.0625 ms（16 kHz 检查采样率的一帧采样）。
  这项检查不包含完整主观听感；重采样浮点音频存在少量超过满量程的峰值，响度仍需试听确认。
- **尚未完成**：完整主观视听验收。字体、裁切和补充画面差异仍存在，不宣称视觉一致或全部合格。

[查看原成片与剪映结果的画面对照](../README.md#画面对照)。

### 哪些没有原样保留

- 剪纸花字、特殊字体与逐词颜色动画，改成了普通可编辑文字。历史界面观察到字号偏小，仍需校准。
- 图片采用完整放入的方式；部分原工程裁切、边框、阴影没有转换。
- 个别插入画面的显示时机不同：同为第 37 秒，原 Hypit 成片与剪映输出显示不同补充画面。
  已确认原成片属于同一导入归档；差异原因尚未定位，不宣称视觉一致或已修复。
- 7 处视频源边界比完整帧跨度短 325 微秒，转换时限制读取范围并微调该段速度；
  目标位置和总时长不变，原素材没有转码。这是本例的具体处理，不应套用到所有项目。
- 剪映端后续手改不会回写 Hypit；重新导入需要新建副本，不覆盖人工修改。

因此，本案例证明“**素材和基础时间线可以接起来**”，不证明“**任何 Hypit 画面都能 1:1 还原**”。

## 工作流分工

| Hypit 交付内容 | 剪映中的结果 | 仍需注意 |
| --- | --- | --- |
| 分镜视频 / 图片 + 起止时间 | 可移动、裁剪、替换的独立画面片段 | 用真实素材时长，不用生成前估时 |
| 独立配音 / 音乐 / 音效 | 可单独调音量的音轨 | 本例实测是配音，音乐/音效须按实际项目验收 |
| 文字内容 + 起止时间 | 可改字、位置、字号的原生文字 | 字体与动画不能按 CSS 参数直接照搬 |
| 复杂排版或动画 | 若无法映射，可另行渲染成独立视频片段再接入 | 这是后续可选方案；片段内部不能在剪映逐层编辑，本例未验证该方案 |

## 可复现的交接步骤

1. 在 Hypit 中选定**已经完成的具体成片归档**，收集该版本实际使用的素材、文字和时间安排。
   不以当前 Source、占位预览或生成提示词猜测已交付成片。需要重新生成时另行确认费用。
2. 针对该项目转换为 `jy14-headless-plan/v1`：连续主画面、额外画面轨、独立音轨、独立文字轨。
   时间以整数微秒表示，帧边界统一换算；先报告无法保留的效果，不静默丢弃。
3. 复核素材文件和哈希、真实时长、主轨连续性、其他轨道边界，再构建独立剪映草稿。
4. 结构验证后，如需交付到剪映首页，先正常退出剪映，再执行本机 `publish`。
5. 实际打开、播放、保存、退出、冷重开，确认字幕、画面、声音及素材可继续编辑。
   只有另行要求成片时才导出，并检查实际帧数、首末画面及音频。

[最小交接计划](../examples/hypit-handoff.plan.json) 展示两段画面、独立配音与两段文字如何对应，
**它是另一个 4 秒格式示例，不是上面 50 秒案例的源工程，也不是 Hypit 原生文件格式**。
把其中绝对路径替换成自己有权使用的已有素材，并按真实时长调整；示例视频每段至少 2 秒、配音至少 4 秒。
该 JSON 不包含模型调用、API 密钥或会员素材。
本机已用同一案例的既有素材替换占位路径，实测该 4 秒示例的 11.5.0 构建和 `verify-build` 通过；
这项检查仍不包含 UI 或导出，记录在同一验证目录的 `example-build/` 及对应日志中。

在仓库根目录运行，`/absolute/path/to/plan.json` 表示已准备好的本次计划：

```bash
python3 skills/yichen-jianying-edit/scripts/headless_draft.py doctor
python3 skills/yichen-jianying-edit/scripts/headless_draft.py build \
  --plan /absolute/path/to/plan.json --out "$PWD/work/hypit-handoff-build"
python3 skills/yichen-jianying-edit/scripts/headless_draft.py verify-build \
  --build "$PWD/work/hypit-handoff-build"
```

输出目录必须不存在；本机首页登记、修改已有副本及导出方法见
[README](../README.md) 与 [计划格式](../skills/yichen-jianying-edit/references/headless-macos.md)。
无需安装或更新 Hypit 来读取一份已经准备好的交接计划；上述命令不会重新生成 Hypit 素材。

## 新建计划中的字体指定

项目转换脚本现在可以为每个文字片段传入可选的 `font_path`，把所选 Hypit 版本实际使用的
本地静态 OTF/TTF 直接交给新建草稿流程。例如在上述示例的字幕片段内加入：

```json
"font_path": "/absolute/path/SourceHanSerif-Bold.otf"
```

构建时即写入材料与富文本样式两处字体路径，并把字体文件按内容 hash 复制到草稿内。
同一字体不会随每条字幕重复复制，不需要先生成默认字体草稿再替换。未填写该字段时保留
原有行为；显式指定的字体缺失、损坏或格式不支持时会报错。

字体名和 CSS 字重不自动映射为文件。若标题、字幕使用不同字体，转换时分别指定文件；
当前不处理同一片段内的多字体富文本，也不提供通用 Hypit 工程解析器。
规则和完整步骤见 [Skill 字体交接说明](../skills/yichen-jianying-edit/references/hypit-handoff.md)。
此功能不改变上方历史案例的验证记录。独立字体样例已完成本机原生显示、可编辑性、保存重开及渲染检查；使用本机构建的 codec，完整编辑回读仍触发上游默认速度字段问题。环境与结果见 [字体验证记录](LOCAL-FONTS.md#native-acceptance-2026-09-20)，不代表上述 Hypit 案例的排版差异已经修复。

## 案例证据与分发边界

本机原始记录位于外层任务的 `work/ig-hypit-jianying-20260918/`：
`composition.snapshot.json`、`media-manifest.json`、`editable-plan-r2.json`、`publish-audit/result.json`
及导入说明。原一次性转换脚本读取已选 Build 的归档与内容寻址素材，并映射特定项目的图层；
它依赖该次归档结构，不能包装成适用于任意 Hypit 版本的稳定 API。

案例验证保留在忽略目录 `work/hypit-case-20260919/`：
`verification.json`、独立 `plan.json`、`build/`、`cold-reopen-final.json`、
`audio-check.json` 及构建与校验日志。
原工程、逐条字幕数据、39 份素材库、私人项目路径、数据库、账号配置与 Hypit 私有代码不加入源码分发。
演示媒体仅包含[压缩预览与六帧对照图](media/README.md)，画面内包含原有字幕；
不附带可编辑私人源工程。原生导出及其验证报告留在 `work/publication-ig-20260919/jianying-export/`。