video-cut-agent

作者：WenTao

项目概述

基于 Gradio + LangChain 的智能视频制作与媒体理解实验项目。用户输入一个制作需求（prompt）并可上传素材（图片 / 视频 / 音频），系统通过 Agent 调用多种分析 / 合成工具，最终输出带音频的视频。交互支持多轮对话，实时流式展示 Agent 思考步骤与工具调用。

功能特性

已实现核心功能

• 📝 Prompt 解析：结合上下文与历史对话理解需求
• 💬 多轮对话：保持历史记录，连续迭代需求
• 🖼️ 多媒体上传：支持多文件（图片 / 视频 / 音频）路径传入
• 🔍 媒体分析工具：
  • 图像基础信息（Pillow + EXIF）
  • 视频技术参数（ffprobe）
  • 视频首尾帧语义理解（OpenCV + 多模态模型）
  • 音频基础信息（ffprobe）
  • 音频节拍 / 拍点检测（librosa beat_track + onset）
• 🤖 子 Agent 机制：批量媒体分析可通过子 Agent 汇总
• 🎬 视频合成：video_synthesis_tool 基于结构化数据生成渲染 JSON 并调用MoviePy渲染视频
• 🔊 音频混合：Track / Shot 级多段音频 + 淡入淡出包络 + 最终 ffmpeg 合并
• 🎨 媒体生成：Doubao Seedream 图生图 / 多图融合 / 纯文本生成，Doubao Seedance 图片驱动动画视频生成（lite / pro）

TODO / 正在迭代 / 预留能力 / 已知问题

• 视频剪辑tool(video_synthesis_tool)入参的数据结构复杂度较高，模型调用一次成功率低。
  • TODO：拆解视频剪辑tool从单步改为多步渐进式生成。
  • TODO：视频剪辑单独拆一个子Agent后，最终合成前增加一步对视频剪辑JSON结构的校验和修复。
• MoviePy结束渲染后偶发异常
• 文字位置不居中，且在文字字号较大时，渲染可能出现不正常的裁切，在设置了文字大小自适应时仍会出现。

用户界面特性

• 多轮对话：历史与当前执行步骤同时展示

项目目录（精简）

video-cut-agent/
├── agent.py                # 主 Agent，注册工具
├── gradio_app.py           # 前端（多轮 + 流式步骤）
├── tools/
│   ├── video_synthesis.py  # 视频 + 音频合成工具
│   ├── media_analysis/
│   │   ├── image_analysis.py
│   │   ├── video_analysis.py
│   │   ├── audio_analysis.py
│   ├── media_generate/
│   │   ├── ark_base.py      # Doubao Seedream / Seedance 封装（绝对路径输出）
│   └── runtime/
│       └── video_render.py # 调用视频合成渲染服务
├── sub_agents/
│   ├── media_analysis_agent.py   # 子 Agent 封装批量分析逻辑
├── requirements.txt
└── README.md

技术栈与关键依赖

类别	使用	说明
Web	Gradio	流式多轮界面
Agent	LangChain	工具调度 + stream updates
LLM	OpenAI / 兼容模型	文本与多模态（首尾帧描述）
媒体分析	ffprobe	基础技术参数提取
图像处理	Pillow	EXIF + 基础属性
视频帧	OpenCV	抽取首 / 尾帧
音频特征	librosa + soundfile	节拍 & onset 检测
合成	外部渲染器 + ffmpeg	视频渲染 + 音频混合
数据结构	dataclasses + Literal	轻量约束，避免枚举误填
媒体生成	Doubao Seedream / Seedance	图生图 / 多图融合 / 图片驱动视频

开发计划

Phase 1: 基础架构 🏗️ (已完成)

• 基础目录与核心文件
• Gradio 初版界面 + 流式输出
• Agent 简化集成
• 环境变量加载（dotenv）

Phase 2: 核心功能 🔧 (进行中)

• 文件上传（多文件）
• LangChain 工具注册 / 子 Agent
• 视频合成（结构化 JSON -> 渲染器）
• 音频混合 (淡入淡出 + 多段拼接)
• 媒体分析工具集
• 思考过程流式展示
• 输出结构严格验证

安装和运行

环境要求

• Python 3.8+
• FFmpeg
• 足够的存储空间用于媒体文件

安装步骤

# 安装依赖
pip install -r requirements.txt

# 安装 FFmpeg (若未安装) 并确保 ffmpeg / ffprobe 在 PATH 中

# 设置必要环境变量

# 启动 Gradio 前端
python gradio_app.py

## API 文档

### 主要工具与接口

#### 媒体分析工具（部分）
- `image_analysis_tool(image_path)`: 图像尺寸 / 模式 / EXIF
- `video_basic_analysis_tool(video_path)`: 编码 / 分辨率 / 时长 / 比特率
- `video_understand_tool(video_path)`: 抽取首尾帧，多模态描述差异
- `audio_basic_analysis_tool(audio_path)`: 编码 / 采样率 / 声道
- `audio_beat_analysis_tool(audio_path, max_beats?)`: BPM / beat_times / onset / 间隔统计

#### 子 Agent 工具
`media_analysis_sub_agent_tool(files, prompt)`：批量多类型媒体分析汇总。

#### 媒体生成工具
- `seedream_i2i_tool(prompt, image_paths?, model_version='4.0')`：4.0 支持多图融合 / 文生图 / 图生图；3.0 单图或纯文本。
- `seedance_video_tool(prompt, first_image, last_image?, variant='lite')`：首帧 / 末帧指导的视频生成（lite / pro）。

### 支持的文件格式（当前测试）
- 图片：JPG / PNG
- 视频：MP4（其他格式经 ffprobe 支持后可扩展）
- 音频：MP3（librosa 支持 WAV/OGG/AAC 等，若安装相应解码）


**注意**: 这是一个正在开发中的项目，功能和 API 可能会发生变化。