Metadata-Version: 2.4
Name: vdeconstruct
Version: 1.9.2
Summary: AIGC-VideoDeconstruct: 纯本地、可校正、模板驱动的视频逆向拆解与创作资产工作台
Author: AIGC-VideoDeconstruct Contributors
License: Apache-2.0
Keywords: video,deconstruct,storyboard,aigc,shot-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pyyaml>=6.0
Provides-Extra: basic
Requires-Dist: opencv-python-headless<5,>=4.7; extra == "basic"
Requires-Dist: scenedetect-headless>=0.6.4; extra == "basic"
Requires-Dist: colour-science>=0.4.4; extra == "basic"
Provides-Extra: asr
Requires-Dist: faster-whisper>=1.0; extra == "asr"
Provides-Extra: audio
Requires-Dist: demucs>=4.0; extra == "audio"
Requires-Dist: silero-vad>=5.0; extra == "audio"
Requires-Dist: panns-inference>=0.0.8; extra == "audio"
Requires-Dist: librosa>=0.10; extra == "audio"
Provides-Extra: diarize
Requires-Dist: pyannote.audio>=3.1; extra == "diarize"
Provides-Extra: av
Requires-Dist: av>=12.0; extra == "av"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: jsonschema>=4.20; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.27; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Requires-Dist: httpx>=0.27; extra == "web"
Provides-Extra: all
Requires-Dist: opencv-python-headless<5,>=4.7; extra == "all"
Requires-Dist: scenedetect-headless>=0.6.4; extra == "all"
Requires-Dist: colour-science>=0.4.4; extra == "all"
Requires-Dist: faster-whisper>=1.0; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn>=0.27; extra == "all"
Requires-Dist: python-multipart>=0.0.9; extra == "all"
Requires-Dist: httpx>=0.27; extra == "all"
Requires-Dist: pytest>=7.4; extra == "all"
Requires-Dist: jsonschema>=4.20; extra == "all"
Requires-Dist: demucs>=4.0; extra == "all"
Requires-Dist: silero-vad>=5.0; extra == "all"
Requires-Dist: panns-inference>=0.0.8; extra == "all"
Requires-Dist: librosa>=0.10; extra == "all"
Requires-Dist: av>=12.0; extra == "all"
Dynamic: license-file

# AIGC-VideoDeconstruct

> 纯本地、可校正、模板驱动的**视频逆向拆解与创作资产工作台**。

把参考视频转换为可持续编辑和复用的资产：镜头拆解数据、角色板、叙事分镜板、字幕与视听特征、AIGC 提示词，以及 JSON / CSV / Markdown / SVG 等导出产物。

核心模式纯 CPU、无需任何模型即可运行；增强模型（ASR / 人物聚类 / 音频解析 / 可选 VLM）为可选能力，缺失时优雅降级。已支持 Wan / 可灵 / Runway / Pika 四类适配器、本地 Web 编辑器（含模板编辑器与三版本比较）、真实授权素材基准与性能优化。

## 设计原则

- **本地优先**：核心功能 100% 可离线运行，默认无联网、无遥测。
- **CPU 友好**：基础模式仅依赖 `numpy` + `opencv`，无需 GPU。
- **数据契约先行**：所有类型发布 JSON Schema，采用语义版本。
- **分析 / 修订分离**：原始分析结果只读，人工修改保存为非破坏性补丁（`revisions/patches.json`）。
- **不确定即 `null`**：未知结果不猜测填充；推断字段必须附带 `method`、`confidence` 与证据引用。

## 功能概览

### 镜头拆解内核

- **镜头检测**：内容变化检测（主路径）+ 帧差回退；过渡识别（`hard` / `dissolve` / `fade_in` / `fade_out`）。
- **关键帧与运动**：单遍解码完成 shots / color / motion / keyframes；关键帧候选实时保留（零 seek）；光流 + 径向分量检测推拉（`push_in` / `pull_out`）。
- **真实色彩**：L\*a\*b\* + k-means 主色板（`palette`），用于风格匹配。
- **错误隔离与缓存**：单模块异常不中断整条流水线；结果可缓存。

### 适配器（Wan / 可灵 / Runway / Pika）

- **厂商无关的 `PromptIntent`**：每镜头携带语义字段（`subject` / `action` / `scene` / `shot_size` / `style` …）+ 结构化 `camera`（`movement` / `direction` / `speed`）+ `characters`（含 `lora_id` / `lora_weight`）。`assemble_prompt()` 负责把结构化字段拼装为自然语言。
- **运镜即参数**：`CameraMotion` 把 `pan_left_speed=0.5` 规范化为 `{movement:"pan", direction:"left", speed:0.5}`；无独立运镜字段的厂商（Runway / Pika / 万相托管）将运镜写入 `prompt` 并保留结构化 `camera_movement` 供自部署端点。
- **角色 LoRA 映射**：角色板 `characters[].lora = {model_id, weight}` 由人工填写，适配器原样输出到请求的 `loras`；官方托管 API 以参考图一致性替代 LoRA 时记录降级提示并保留 `loras` 供兼容端点。
- **Revisions = 首选输入**：`adapt` 默认合并「分镜板 + 角色板 + 补丁」作为适配器输入；`--no-revisions` 会显式警告并基于未修订数据生成。

```python
from vdeconstruct.core.intent import PromptIntent, CameraMotion, CharacterIntent
from vdeconstruct.adapters import get_adapter

intent = PromptIntent(
    subject="小红", action="奔跑", shot_size="全景", style="电影感", duration="5s",
    camera=CameraMotion("pan", "left", 0.5),
    characters=[CharacterIntent("Char001", "小红", "redcoat_v3", 0.7)],
)
req = get_adapter("kling").build(intent)
# req.to_dict() -> 含 camera_movement + loras（经 adapter_request Schema 校验）
# native_payload(req) -> 可灵原生 body：camera_control.config.pan=-5 + loras:[{redcoat_v3,0.7}]
```

```bash
# CLI：输出到各厂商
vdeconstruct adapt --target kling --project examples/project --out examples/kling_request.json
vdeconstruct adapt --target wan   --project examples/project --out examples/wan_request.json
vdeconstruct adapt --target runway --project examples/project --out runway.json
vdeconstruct adapt --target pika  --project examples/project --out pika.json
```

### 声明式模板引擎与官方模板包

- **纯声明式、安全**：模板为纯声明式，引擎绝不执行任意代码。表达式求值走 AST 白名单（字典/列表索引、算术、比较、布尔短路及少量白名单函数/字符串方法），文本模板默认自动转义；SVG 不采用原始 XML 文本模板而用版式描述（卡片 + 元素绑定），所有生成的 SVG 必经 `svg_sanitize` 剥离 `script` / 外部链接 / `on*` 事件处理器。
- **三套官方模板包**（位于 `src/vdeconstruct/templates/`，随包发布，许可 CC BY 4.0）：
  - `general-film-analysis`：通用专业拉片、镜头语言与叙事结构。
  - `vertical-short-drama`：竖屏短剧、人物关系、情绪节拍（9:16 竖版分镜板）。
  - `product-commercial`：商品展示、卖点镜头、品牌色彩与广告节奏（含品牌色条）。
  - 每包含：模板清单 `template.yaml`（经 `template_manifest` Schema 校验）、`layouts/`（storyboard / character_board 的 SVG·Markdown·JSON）、`analysis_config.json`、自带示例项目。
- **渲染上下文**：`build_render_context(project_dir)` 由「修订后分镜板/角色板 + 分析结果」组装模板可引用的字典（镜头时间码、结构化运镜中文化短语、角色 LoRA 权重、色板色块）；模板只读取该上下文，绝不访问项目目录之外文件。

```bash
vdeconstruct template list
vdeconstruct template inspect general-film-analysis

# 用模板渲染（默认消费 Revisions 首选输入；可 --no-revisions 绕过并告警）
vdeconstruct render examples/project \
    --template general-film-analysis --layout storyboard --format svg
```

```python
from vdeconstruct.template import list_packages, load_package, build_render_context

pkg = load_package("general-film-analysis")
ctx = build_render_context("examples/project")   # 默认 apply_revisions=True
svg = pkg.render(ctx, "svg", "storyboard")
```

模板仅做风格级呈现，不宣称复原真实调色参数；纯 CPU、可离线。

### 本地 Web 编辑器

- **架构**：`vdeconstruct web <项目目录>` 启动 FastAPI 本地服务（仅监听 `127.0.0.1`），前端为无构建、可离线的单页应用（纯 ES 模块 + vanilla JS，符合「默认无联网」红线）。
- **叙事分镜板编辑器**：以卡片编辑每个镜头的景别/机位/构图/运镜/转场；支持新增/删除/复制/重排镜头、把角色板角色绑定到镜头、每镜编辑 `PromptIntent`；切换模板实时预览 SVG 分镜板。
- **角色板编辑器**：匿名聚类（`Char001`）、手动命名，编辑外貌/服饰/表情/气质与 `lora` 权重映射；展示证据帧，可点选设为基准图；切换角色板模板实时预览。
- **非破坏修订**：保存只写 `boards/*.json`（分析只读结果 `analysis/result.json` 永不被改动），并追加字段级增量补丁到 `revisions/patches.json`（可审计、可迁移）。
- **版本比较**：对比「原始分析 ↔ 人工修订」，按镜头高亮字段级差异。
- **三版本比较**：对比「原始分析 → 人工修订 → 二创」三列演进（需先 `vdeconstruct derive` 生成二创分镜 `boards/derivative.json`）；差异单元格高亮、每镜带存在性徽标、可切换「仅显示差异字段」。
- **模板编辑器**：在线编辑/预览/校验/导出官方模板包（`manifest` 与 `layouts` 原文）；首编复制 bundled 包为用户目录副本，绝不修改官方 bundled 包；导出经路径穿越/超解压校验。
- **导入 / 导出 + 隐私检查**：导出分享包 zip 默认不含源视频与完整关键帧（仅结构数据 + 低分辨率预览）；导入做路径穿越 / 超解压 / 体积校验。

```bash
# 启动本地编辑器（浏览器打开 http://127.0.0.1:8000）
vdeconstruct web examples/project --port 8000
```

编辑器仅修改规划数据，不裁剪/转码源视频；不识别现实人物身份；默认不联网、不遥测。

### 增强分析（可选依赖、优雅降级）

`vdeconstruct enhance <项目>` 一次性跑「人物聚类 + 叙事分段 + 字幕」，三类产物均写入独立新文件，绝不改动只读的 `analysis/result.json`，也不覆盖人工修订板。

- **人物聚类**：OpenCV 内置 Haar 级联（BSD，离线）+ numpy 灰度 L2 描述子 + 贪心聚类；写入 `boards/clusters.json`，缺失时生成 `boards/characters.json` 草稿。（注：OpenCV 5.0 已移除内置 Haar，离线聚类需 `opencv-python-headless<5`；cv2≥5 时自动跳过并提示。）
- **叙事分段与节奏**：硬切 / 色相跳变 / 亮度跳变处切分段落，输出 `analysis/narrative.json`（段落 + 节奏指标）。
- **字幕 / 描述**：默认离线规则版（由 subject/运镜/主色调/台词拼装）；可传入本地 VLM 钩子走模型描述，异常自动回退规则版，输出 `analysis/captions.json`。
- **ASR 台词转写**：默认 faster-whisper（MIT，纯 CPU/离线），回退 openai-whisper；非破坏落盘 `analysis/transcript.json`（段级 `confidence`），消费于字幕/描述模块。

```bash
# 增强分析（人物聚类 + 叙事分段 + 字幕）
vdeconstruct enhance examples/project
# 仅事后补做转写
vdeconstruct enhance examples/project --no-cluster --no-narrative --no-caption
```

### 音频与音色解析（可选）

把「参考视频的音色资产」也纳入可拆解/可复用范围——角色音、旁白音、背景音乐、音效。四条能力锚定成熟开源、各自可选、缺依赖优雅降级，非破坏落盘 `analysis/audio.json`：

- **音源分离**：Demucs（htdemucs，MIT，纯 CPU/可离线）→ 人声/伴奏(BGM)/其他 分轨（可导出 wav）。
- **语音/音乐/静音分段**：Silero VAD（MIT，极轻量）定位语音区间；非语音间隙按能量粗分「音乐」与「静音」。
- **说话人分离**：pyannote.audio（代码 MIT）区分「谁在说」；预训练模型为 gated，需 HF token 首次下载，故单列 `diarize` extra。
- **音效事件识别**：PANNs CNN14（Apache-2.0，AudioSet 527 类）识别掌声/脚步/爆炸/笑声等。

```bash
# 先 analyze 生成 analysis/result.json（音频解析需要元数据）
vdeconstruct analyze examples/sample.mp4 --output examples/project --modules metadata,shots,keyframes
# 四层解析（需 [audio]；说话人需另装 [diarize] + HF_TOKEN）
vdeconstruct audio analyze examples/project
# 把说话人对齐回台词（默认写 transcript.speakers.json 旁挂）
vdeconstruct audio link-speakers examples/project
```

音频解析仅做风格级特征提取（分离/分段/标签），不宣称复原原片真实混音工程参数；纯 CPU、可离线、避 AGPL。

### 时间线导出

`vdeconstruct export <项目> --format edl|fcpxml|png|pdf`：

- **EDL（CMX3600）** 与 **FCPXML** 为标准库生成、零可选依赖。
- **PNG / PDF** 时间线缩略条门控于可选 Pillow。
- 优先读取 `boards/storyboard.json`（含人工修订），为空草稿时回退 `analysis/result.json`。

```bash
vdeconstruct export examples/project --format edl,fcpxml --output examples/project/exports
```

### 契约迁移

`vdeconstruct migrate <项目>` 非破坏地把老项目契约就地升级到当前版本（升级前为每个被改文件写 `<orig>.v<N>.bak` 备份，仅补齐向后兼容的可选字段）。兼容性矩阵见 `compatibility_matrix()` 与 `docs/`。

```bash
vdeconstruct migrate examples/legacy_project
```

### 性能优化

可选 PyAV 解码后端（`av` extra，`codec_context.options['lowres']` 解码期降分辨率）+ 降采样解码（`analyze_width`）+ 帧采样（`analyze_step`），使长视频分析满足耗时门槛。核心模式无强制重依赖，`av` 缺失自动回退 OpenCV。

## 安装

```bash
# 基础拆解（镜头检测 + 关键帧 + 运动 + 色彩）
pip install -e ".[basic]"
# 完整本地能力（分析内核 + Web 编辑器 + 开发/测试）
pip install -e ".[all]"
# 分能力按需安装
pip install -e ".[web]"      # 本地 Web 编辑器
pip install -e ".[asr]"      # faster-whisper 台词转写（默认后端）
pip install -e ".[av]"       # PyAV 加速解码（使长视频性能达标）
pip install -e ".[audio]"    # 音频/音色解析（Demucs + Silero VAD + PANNs，纯 CPU/可离线，依赖 torch）
pip install -e ".[diarize]"  # 说话人分离（pyannote，gated 模型需 HF token，可选）
```

> 核心模式无强制大模型依赖；`audio` / `diarize` 体积较大且为可选，按需安装。各 extra 缺依赖时对应能力自动探测并降级，不崩溃。

## 快速开始

```bash
# 1. 生成合成测试视频（纯 OpenCV，无需 FFmpeg）
python scripts/make_synthetic_video.py --output examples/sample.mp4 --scenes 5

# 2. 运行基础分析（带缓存与错误隔离）
vdeconstruct analyze examples/sample.mp4 \
    --output examples/project \
    --modules metadata,shots,keyframes,color,motion \
    --detail basic

# 3. 导出（支持 json / csv / markdown / svg / srt / vtt）
vdeconstruct render examples/project --format json,csv,markdown,svg,srt,vtt

# 4. 直接分析视频链接（自动下载直链到缓存目录；平台签名短链请先用 unified_parser 解析）
vdeconstruct analyze "https://example.com/clip.mp4" \
    --output examples/url_project \
    --modules metadata,shots,keyframes,color,motion

# 5. 把"人工修订后的项目数据"转换为 Wan / 可灵 API 调用
#    （默认消费 revisions/分镜板/角色板；--no-revisions 会警告并绕过首选输入）
vdeconstruct adapt --target kling --project examples/project --out examples/kling_request.json
vdeconstruct adapt --target wan   --project examples/project --out examples/wan_request.json

# 6. 启动本地 Web 编辑器（浏览器打开 http://127.0.0.1:8000）
vdeconstruct web examples/project --port 8000

# 7. 性能基准
python scripts/benchmark.py --scenes 6 --seconds 12
```

Python API：

```python
from vdeconstruct import Analyzer, AnalysisConfig

# cache=True 命中缓存时跳过逐帧；单模块失败写入 result.errors 不中断
analyzer = Analyzer(AnalysisConfig(detail_level="basic"), cache=True)
project = analyzer.analyze("examples/sample.mp4", "examples/project")
project.export("markdown", "examples/project/exports")
```

> 合规红线：本项目**不宣称复原原视频使用的真实调色参数**，仅做风格级匹配并标注置信度。

## 项目文件夹格式

```
project/
├── project.json          # 项目元信息（版本、Schema 范围）
├── source.json           # 源文件只读探针信息
├── analysis/
│   └── result.json       # 原始分析结果（只读）
│   ├── transcript.json   # ASR 台词转写（非破坏）
│   └── audio.json        # 音频/音色解析（非破坏）
├── revisions/
│   └── patches.json      # 人工修订补丁（非破坏性）
├── boards/               # 角色板 / 分镜板
├── assets/               # 证据帧 / 预览图
└── exports/              # 导出产物
```

## 测试

全量测试（pytest）：`pip install -e ".[all]"` 后运行 `pytest`（详见 `tests/`）。核心覆盖：

- **真实视频端到端**（`tests/test_video_e2e.py`）：固定解码已入库的 `examples/sample.mp4`（848×480 / 30fps / 8s），验证镜头检测、关键帧落盘（非空 jpg）、逐镜色彩/运动、数据契约校验（analysis_result schema）、四格式导出跨格式一致（JSON/CSV/Markdown/SVG 镜号与时间码）、EDL/FCPXML 时间线事件与镜头数一致、PNG/PDF 缺 Pillow 时优雅降级，以及二创闭环（derive→compare→adapt）在真实视频上闭环。
- **真实素材复核回归**（`tests/test_video_benchmark.py`）：用已知硬切 ground-truth 的合成视频断言镜头检测 F1 门槛（flat / realistic 双模式）。
- **真实授权素材基准**（`tests/test_video_real_benchmark.py`）：入库 Blender CC-BY 三段拼接 `real_benchmark.mp4`（28s），断言 GT 召回 / 峰值内存 / F1 信息性下限。
- 其余：合成视频单遍/多遍对照、跨格式一致性、导入安全负向、Web 隐私校验、音频解析、派生/比较等。

> 缺可选依赖（Pillow / jsonschema / faster-whisper 等）时相关断言自动降级或跳过，核心视频链路不依赖它们。

## 路线图与后续

后续规划（按优先级）：

- Windows 一键安装包（轻量核心 basic+web+av 自包含，不捆绑 audio/diarize，避 AGPL）。
- 官方模板包归一化（补 locales/mappings/tests）。
- 前端 TypeScript 化（当前为 vanilla JS，符合「默认无联网」红线）。

## 许可

- 代码：`Apache-2.0`
- 官方模板与创作内容：`CC BY 4.0`
- 依赖许可披露：见 `docs/LICENSE-REPORT.md`（自动生成，含 PyAV LGPL 传递依赖说明）。

## 文档索引

- 架构与数据契约：`ARCHITECTURE.md`
- 安全说明：`SECURITY.md`
- 依赖与模型准入政策（含网络策略）：`DEPENDENCY_POLICY.md`
- 路线图与架构决策记录：`ROADMAP.md`
- 性能基准报告：`docs/benchmark.md`
- 用户手册：`docs/USER_GUIDE.md`
- 开发者手册：`docs/DEVELOPER_GUIDE.md`
- 许可合规报告（自动生成）：`docs/LICENSE-REPORT.md`
