CineCut-Agent

Narrative-aware Multimodal Video Editing Agent
多模态理解 + 长视频检索 + 多 Agent 粗剪 + 轻量偏好学习 + 可解释评测。

---

1. 项目简介 | Overview

CineCut-Agent 输入 10–60 分钟长视频 + 自然语言创作 brief，输出：

• 2–3 个（可扩展到 30/60/90）候选 rough cut（mp4）
• timeline JSON / EDL
• SRT 字幕
• 可解释报告（Markdown + HTML）
• baseline/full/ablation 的评测结果

This project focuses on editing orchestration, not video generation model training.

---

2. 技术架构说明 | Architecture

系统按阶段串联为一条可追踪主链路：

1. 输入层：接收长视频与自然语言 brief，并进行参数标准化。
2. 解析与规划层：Brief Parser 输出结构化约束；DirectorAgent 生成故事节拍计划（story beats）。
3. 记忆构建层：Memory Builder 生成 shot / scene / episode 三层记忆，融合 ASR、OCR、音频、运动、视觉标签信息。
4. 检索层：RetrieverAgent 基于节拍计划执行迭代检索（sub-queries），联合向量检索与结构化过滤。
5. 编辑层：EditorAgent 在时长约束下生成多候选时间线（语义优先、节奏情绪优先、叙事完整性优先）。
6. 评审与修订层：CriticAgent 从 brief 满足度、连贯性、节奏、冗余、镜头多样性等维度打分并给出修订建议。
7. 排序层：Reranker 使用规则弱标、合成偏好样本与人工 A/B 标注特征进行候选重排序。
8. 导出与评测层：输出 mp4/json/edl/srt 与解释报告，并通过 baseline/full/ablation 评测指标进行对比。

---

3. 核心模块 | Core Modules

• backend/app/services/memory_builder.py
  分层 memory（shot/scene/episode）构建，支持 PySceneDetect/faster-whisper/EasyOCR/librosa 的可选接入与 fallback。

• backend/app/agents/

  • DirectorAgent: brief -> story beats JSON
  • RetrieverAgent: iterative sub-query temporal retrieval
  • EditorAgent: Candidate A/B/C 生成
  • CriticAgent: 多维打分 + 修订建议

• backend/app/services/reranker.py
  pairwise logistic reranker + synthetic negatives（7 类）+ 特征工程。

• backend/app/evaluation/runner.py
  baseline/full/ablation 统一评测入口。

• frontend/gradio_app/app.py
  Gradio 交互页面：上传/brief、日志、候选预览、播放、解释、A/B 标注。

---

4. 目录结构 | Repo Tree

cinecut-agent/
  backend/app/
    api/ core/ models/ schemas/ services/
    agents/ memory/ retrieval/ editing/ evaluation/ providers/
  frontend/gradio_app/
  scripts/
  tests/
  configs/
  docs/
  sample_data/
  references/
  notes/
  outputs/

---

5. 快速开始 | Quick Start

5.1 环境

• Python 3.11+
• 建议安装 ffmpeg

5.2 安装

python -m pip install -e .
# 如果需要本地视频工具链
python -m pip install -e .[video]

5.3 启动 API

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --app-dir backend

5.4 启动 Gradio

python -m frontend.gradio_app.app

5.5 运行最小样例

python scripts/run_demo.py --provider stub

---

6. 样例运行流程 | Sample Run

1. 运行 python scripts/run_demo.py --provider stub。
2. 脚本自动生成 sample_data/generated/demo_input.mp4（若不存在）。
3. 执行 plan -> retrieve -> edit -> critique -> revise -> export -> report。
4. 输出位于 outputs/demo_run/：
   • A-*.mp4/B-*.mp4/C-*.mp4
   • *.timeline.json, *.edl, *.srt
   • report.md, report.html, result.json

---

7. Provider 接入方式 | Provider Integration

配置 .env（参考 .env.example）：

• PROVIDER_MODE=auto|stub|openai
• OPENAI_BASE_URL
• OPENAI_API_KEY
• OPENAI_MODEL

统一接口（ProviderBase）：

• caption_clip
• tag_shot
• summarize_scene
• plan_edit
• critique_timeline
• judge_pairwise

无 API Key 时自动 fallback 到 LocalStubProvider。

---

8. Reranker 训练 | Reranker Training

python scripts/train_reranker.py --pairs sample_data/preference_pairs.json

特征包含：

• semantic relevance
• narrative coverage
• emotion peak coverage
• dialogue density
• shot diversity
• aesthetic score
• redundancy penalty
• duration penalty
• brief constraint satisfaction

---

9. Eval 与 Ablation | Evaluation

python scripts/run_eval.py --benchmark sample_data/benchmark.json --system full_system
python scripts/run_eval.py --benchmark sample_data/benchmark.json --system baseline_transcript
python scripts/run_eval.py --benchmark sample_data/benchmark.json --ablation no_critic
python scripts/run_eval.py --benchmark sample_data/benchmark.json --ablation no_reranker
python scripts/run_eval.py --benchmark sample_data/benchmark.json --ablation no_cinematic_tags

指标：

• duration error
• redundancy ratio
• brief coverage score
• narrative coverage score
• shot diversity score
• judge preference win rate
• human preference win rate（接口预留）

---

10. 参考与许可边界 | References and License Boundary

参考仓库位于 references/，详细审计见：

• notes/reference_audit.md

主仓库 license：MIT。
对于非商用或 license 不清晰仓库，仅参考思路，不复用实现代码。