# video-creation

**Repository Path**: mango77/video-creation

## Basic Information

- **Project Name**: video-creation
- **Description**: video-creation
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视频创作工作台 · Motion Video Production Workspace

把一个产品的**截图**和一段**文案**，自动组装成一条带声音的演示视频。

> 客户传什么顺序，就出什么顺序；客户自定义什么画面，就出什么画面。

---

## 这是什么

一条两阶段的生产流水线：

```
原始截图  ──Stage A──▶  干净的运动素材  ──Stage B──▶  带解说的成片
```

| 阶段 | 应用 | 职责 |
|---|---|---|
| **A · 素材** | `apps/material-studio` | 把原始截图处理成可复用的运动素材（卡片动效、转场素材、背景） |
| **B · 装配** | `apps/film-assembler` | 编排时序、镜头漫游、字幕、配音、BGM、音效，产出成片 |

技术栈：**Remotion 4** + **React 19** + **TypeScript**，npm workspaces 单仓双应用。

---

## 核心设计

### 1. `scenes[]` 输入契约

视频**不再按固定编号组织**。客户端传入一个场景列表，每个场景有自己的类型和数据，
系统遍历列表按序渲染——**顺序由外部输入决定，不由代码里的编号决定**。

```json
{
  "voice": {"src": "voice.wav", "script": "……"},
  "scenes": [
    {"id": "s1", "type": "statement", "data": {"caption": "把所有工具收进一块无限画布"}},
    {"id": "s2", "type": "screenshotWorld", "data": {"assetId": "asset-06-node-workflow", "route": "flow"}},
    {"id": "s3", "type": "custom", "compose": { "world": {}, "layers": [], "camera": {} }}
  ]
}
```

三个决定性的设计选择：

- **时长不进契约** —— 由口播稿时间决定（`voiceEnergy` 主时钟），客户不指定时长
- **类型可自定义组合** —— 内置类型 = 预置的 compose 模板；`type:'custom'` 走**同一条渲染路径**
- **`script.md` 与 `scenes[]` 并存** —— script.md 是"源码"，scenes[] 是编译产物（IR）

### 2. 真实截图漫游（"外截内矢"）

L2 世界层 = **真实产品截图**，相机在其上推近、平移、拉远；
矢量只用来**叠加动效**（数据流、聚焦框、连线光效）。

> 不是重画一套矢量假节点——那样产出的只是"示意图"。

### 3. 截图标注机制

相机对焦需要真实截图里的节点坐标，手工读坐标不可持续。
解法：**一次标注，永久复用**。

```tsx
// 导演层写 semantic spot，不写像素坐标
{frame: 78, spot: 'text2', zoom: 2.0}
        ↓ 渲染时解析
{x: 595, y: 325, zoom: 2.0}
```

标注改动后，**所有引用它的场景自动跟随**。标注工具：`apps/film-assembler/dev/annotate.html`

### 4. 两条相机铁律

| 铁律 | 原因 |
|---|---|
| **zoom 始终 ≥ 1.0** | 真实用户在无限画布上**从不"看到全图"**，他们永远在某个局部靠平移漫游 |
| **相机必须有边界约束** | 对焦靠边元素时，视口会大量越出图外 → 画面出现大片黑边 |

---

## 快速开始

```bash
# 安装
npm install

# Stage A 类型检查
npm run stage-a:typecheck

# Stage B 类型检查
npm run stage-b:typecheck

# 架构边界测试（双应用不得互相重建引擎）
npm run test:architecture
```

### 生成一条成片

```bash
cd apps/film-assembler

# 1) script.md → scenes[]（作者 DSL 编译成输入契约）
npm run scenes

# 2) 校验输入契约（schema + L1-L13 美学 lint）
env -u NODE_OPTIONS npx tsx scripts/lint-scenes.ts src/scenes.json

# 3) 只传素材 + 文案，自动编排（推荐引擎）
env -u NODE_OPTIONS npx tsx scripts/recommend-scenes.ts \
  --assets ../assets/materials/xxx/01.png,../assets/materials/xxx/06.png \
  --script dev/voice-script.txt \
  --out dev/recommended-scenes.json

# 4) scenes[] → 时间线
env -u NODE_OPTIONS npx tsx scripts/scenes-to-timeline.ts dev/recommended-scenes.json src/scenes-timeline.json

# 5) 渲染成片
env -u NODE_OPTIONS npx remotion render src/index.ts SceneSequence out/film.mp4 --codec=h264
```

> **注意**：本项目所有 Remotion / tsc 命令都需要 `env -u NODE_OPTIONS` 前缀，
> 否则会被注入的 node shim 干扰（webpack 递归 mkdir 报 EEXIST）。

### 标注新截图

```bash
cd apps/film-assembler
npm run annotate   # 打开标注工具
# 点空白新增节点 / 拖圆点移动 / 拖框改尺寸 / 一键复制 JSON
# 把 JSON 存到 src/annotations/，并在 scenePresets.ts 的 ANNOTATIONS 登记
```

---

## 目录结构

```
├── apps/
│   ├── material-studio/      # Stage A：素材生产
│   └── film-assembler/       # Stage B：成片装配
│       ├── src/
│       │   ├── compiler/     # 契约与编译（scenes / annotations / parse / slots / validate）
│       │   ├── components/
│       │   │   ├── scene/    # 矢量场景原语（CameraRig / CanvasGrid / NodeCard / FlowLine …）
│       │   │   ├── shots/    # 镜头族组件
│       │   │   └── primitives/  # UI 原子
│       │   ├── renderer/     # 渲染层（SceneRenderer / SceneSequence / scenePresets / Root）
│       │   └── annotations/  # 截图标注数据
│       ├── scripts/          # compile / lint-scenes / recommend-scenes / scenes-to-timeline
│       └── dev/              # 标注工具、样例输入
├── assets/                   # 素材与音频
├── docs/                     # 设计文档（00–26）
├── constraints/              # 硬约束
└── tests/                    # 架构边界测试
```

---

## 文档

设计文档在 `docs/`，按编号演进。几个入口：

| 文档 | 内容 |
|---|---|
| `00-project-charter.md` | 项目章程：范围、边界 |
| `02-architecture.md` | 两阶段架构与 Material Chain Rule |
| `21-mag-canvas-compiler.md` | 编译链实现权威 |
| `22-mag-canvas-v2-plan.md` | 视觉设计原则与数值配方 |
| `25-cinematic-layer-plan.md` | 电影层：意图 / 场景 / 运动三层 |
| **`26-scenes-input-contract.md`** | **`scenes[]` 输入契约（本项目当前主线）** |

`AGENTS.md` 是项目运作规则（读什么、什么 Gate 才允许做什么、变更纪律）。

---

## 当前状态

| 能力 | 状态 |
|---|---|
| `scenes[]` 输入契约 + 编译链 | ✅ |
| 截图标注机制（工具 + schema + 校验） | ✅ 6 张截图已标注 |
| 真实截图漫游（`screenshotWorld`） | ✅ 端到端 9/10 场景 |
| 推荐引擎（素材 + 文案 → 自动编排） | ✅ |
| **配音** | ⬜ **时长仍是字数估算，成片无声** |

---

## 许可

私有项目，未经许可请勿分发。