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 会显式警告并基于未修订数据生成。

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}]

# 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 权重、色板色块）；模板只读取该上下文，绝不访问项目目录之外文件。

vdeconstruct template list
vdeconstruct template inspect general-film-analysis

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

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 默认不含源视频与完整关键帧（仅结构数据 + 低分辨率预览）；导入做路径穿越 / 超解压 / 体积校验。

# 启动本地编辑器（浏览器打开 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），消费于字幕/描述模块。

# 增强分析（人物聚类 + 叙事分段 + 字幕）
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 类）识别掌声/脚步/爆炸/笑声等。

# 先 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。

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

契约迁移

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

vdeconstruct migrate examples/legacy_project

性能优化

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

安装

# 基础拆解（镜头检测 + 关键帧 + 运动 + 色彩）
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 缺依赖时对应能力自动探测并降级，不崩溃。

快速开始

# 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：

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