# 极速分镜

**Repository Path**: luo-yinhe/speed-split-mirror

## Basic Information

- **Project Name**: 极速分镜
- **Description**: 一款灵感源自影视飓风闪电分镜、基于 zstar1003/mediastory 深度定制的 AIGC 分镜脚本工具，支持自定义属性列与 PDF 导出。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img width="100" height="100" src="public/logo.png" alt="Logo">
</p>

<h1 align="center"><b>极速分镜</b></h1>

<p align="center">
  一款灵感源自 <b>影视飓风·闪电分镜</b> 的 AIGC 分镜脚本工具。
</p>

<p align="center">
  基于 <a href="https://github.com/zstar1003/mediastory">zstar1003/mediastory</a> 二次开发，支持自定义属性列，灵活适配各类影视创作场景。
</p>

## ✨ 特性

- **📋 灵活的分镜编辑** — 表格化分镜编排，支持拖拽排序
- **⚙️ 自定义属性列** — 预置景别、运镜、焦距、光圈等 10 种影视常用属性，可按需开关与排序
- **➕ 自定义列** — 支持添加文本、数字、下拉选择、多行文本四种类型的自定义列
- **↔️ 列头拖拽** — 所有列均可左右拖动自由排列，顺序持久化保存
- **📦 素材箱** — 统一的图片/视频素材管理，支持跨分镜拖拽复用
- **✂️ 视频裁剪** — 内置 MP4Box 视频剪辑功能，无需后端
- **📄 批量导出** — 支持导出 PDF、PNG，及批量打包素材为 ZIP
- **💾 离线存储** — IndexedDB 本地持久化，无需网络
- **☁️ 云端协作**（开发中） — 基于 Socket.IO 的实时协作编辑

## 🚀 快速开始

环境要求：

- Node.js 20.19+、22.12+ 或更新版本
- 当前验证版本：Node.js 26.1.0 / npm 11.13.0

```bash
# 克隆项目
git clone https://gitee.com/luo-yinhe/speed-split-mirror.git
cd speed-split-mirror

# 安装前端依赖
npm install

# 启动开发服务器
npm run dev
```

构建生产版本：

```bash
npm run build
npm run preview
```

后端协作服务（可选）：

```bash
cd server
npm install
npm run build
npm run dev
```

后端需要 MongoDB，并可通过 `server/.env.example` 配置 `MONGODB_URI`、`JWT_SECRET`、`FRONTEND_URL` 等环境变量。

## ✅ 当前验证状态

最近一次验证环境：Node.js 26.1.0 / npm 11.13.0。

```bash
npm run lint
npm run build
cd server && npm run build
cd server && npm audit --omit=dev
```

以上检查均已通过，服务端生产依赖审计结果为 `found 0 vulnerabilities`。

## 🖥️ 技术栈

| 层面 | 技术 |
|------|------|
| 前端框架 | React 19 + TypeScript |
| 构建工具 | Vite 7 |
| 状态管理 | Zustand 5 |
| 样式 | Tailwind CSS 4 |
| UI 组件 | Radix UI + Lucide Icons |
| 本地存储 | IndexedDB (idb) |
| 导出 | html2canvas + jsPDF + JSZip |
| 视频处理 | MP4Box |
| 实时协作 | Socket.IO |
| 后端 | Express + MongoDB |

## 📝 使用说明

1. 创建项目后，点击表格上方的 **「管理属性列」** 按钮
2. 在对话框中勾选需要的属性列（景别、焦距、光圈等），所有列均可开关
3. **拖拽列头**左右排序，或添加自定义列
4. 在分镜表格中输入各分镜的画面描述、对白、属性值
5. 点击 **「导出PDF」** 按钮导出整张分镜表（A4 横向，含参考图缩略图）
6. 素材箱支持拖拽素材到分镜单元格，也可从分镜拖出到素材箱

## 📁 项目结构

```
├── src/                     # 前端源码
│   ├── components/          # UI 组件
│   │   ├── StoryboardTable.tsx  # 分镜表格（核心）
│   │   ├── AttributeCell.tsx    # 属性列单元格渲染
│   │   ├── ColumnConfigDialog.tsx # 列管理对话框
│   │   ├── ImageCell.tsx        # 图片单元格
│   │   ├── VideoCell.tsx        # 视频单元格
│   │   └── ...
│   ├── stores/              # 状态管理
│   │   ├── storyboardStore.ts
│   │   └── cloudStore.ts
│   ├── utils/               # 工具函数
│   │   ├── db.ts            # IndexedDB 操作
│   │   ├── export.ts        # 导出功能
│   │   └── projectIO.ts     # 项目导入导出
│   └── types/               # TypeScript 类型定义
├── server/                  # 后端（可选）
│   └── src/
│       ├── controllers/
│       ├── routes/
│       ├── models/
│       └── services/
│           └── websocket.ts
└── ...
```

## 🙏 致谢

- [影视飓风](https://space.bilibili.com/946974) — 闪电分镜创作理念
- [zstar1003/mediastory](https://github.com/zstar1003/mediastory) — 原始项目