# 数字人换背景
**Repository Path**: pywu/AI-change-background
## Basic Information
- **Project Name**: 数字人换背景
- **Description**: 数字人换背景项目,支持视频、图片背景。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 12
- **Created**: 2025-06-20
- **Last Updated**: 2025-06-20
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 数字人视频背景替换系统
## 项目概述
这是一个数字人视频背景替换系统,采用模块化架构设计,提供了强大的视频背景替换功能,支持批量处理、实时预览、素材库管理等特性。
## 🎯 主要特性
- 🎬 **视频背景替换**: 支持图片和视频背景替换
- 📚 **素材库管理**: 完整的文件上传、预览、分类管理
- 🔄 **批量处理**: 支持多文件组合批量处理
- 👀 **实时预览**: 参数调整实时预览效果
- 📊 **处理历史**: 完整的任务历史记录和状态跟踪
- ⚙️ **参数预设**: 可保存和复用处理参数
- 🔍 **搜索筛选**: 支持文件搜索和多维度筛选
- 📄 **分页显示**: 优化大量数据的显示性能
- 🏥 **健康监控**: 系统状态和资源监控
- 🧹 **自动清理**: 自动清理临时文件和过期数据
## 图片预览
## 🏗️ 架构设计
### 项目结构
```
video-bg-replacer/
├── app.py # 主应用文件
├── config.py # 配置管理
├── database.py # 数据库模块
├── video_processor.py # 视频处理模块
├── file_manager.py # 文件管理模块
├── task_manager.py # 任务管理模块
├── api/ # API路由模块
│ ├── __init__.py # 路由初始化
│ ├── upload_routes.py # 上传路由
│ ├── library_routes.py # 库管理路由
│ ├── task_routes.py # 任务路由
│ ├── preview_routes.py # 预览路由
│ ├── history_routes.py # 历史路由
│ ├── preset_routes.py # 预设路由
│ └── system_routes.py # 系统路由
├── uploads/ # 上传文件目录
├── outputs/ # 输出文件目录
├── library/ # 素材库目录
│ ├── human/ # 数字人文件
│ └── background/ # 背景文件
├── previews/ # 预览文件目录
├── temp/ # 临时文件目录
├── static/ # 静态文件目录
├── requirements.txt # 依赖清单
└── README.md # 项目说明
```
### 架构层次
1. **表现层 (API Routes)**: 处理HTTP请求和响应
2. **业务逻辑层 (Managers)**: 处理核心业务逻辑
3. **数据访问层 (DAOs)**: 处理数据库操作
4. **数据层 (Database)**: SQLite数据库存储
## 🚀 快速开始
### 环境要求
- Python 3.8+
- FFmpeg (用于视频处理)
- FFprobe (用于视频信息获取)
### 安装步骤
1. **克隆项目**
```bash
git clone
cd video-bg-replacer
```
2. **安装Python依赖**
```bash
pip install -r requirements.txt
```
3. **安装FFmpeg**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install ffmpeg
# macOS (使用Homebrew)
brew install ffmpeg
# Windows
# 从 https://ffmpeg.org/download.html 下载并配置环境变量
```
4. **启动应用**
```bash
python app.py
```
### 配置环境变量
```bash
# 可选的环境变量
export FLASK_ENV=development # 开发环境
export HOST=0.0.0.0 # 监听地址
export PORT=5000 # 监听端口
```
## 📡 API接口
### 文件上传
- `POST /api/upload` - 上传文件
### 库管理
- `GET /api/library` - 获取文件列表
- `DELETE /api/library/{file_id}` - 删除文件
- `POST /api/library/batch-delete` - 批量删除
### 预览生成
- `POST /api/generate-preview` - 生成预览
- `GET /api/preview-image/{preview_id}` - 获取预览图
- `DELETE /api/clear-preview/{preview_id}` - 清除预览
### 视频处理
- `POST /api/process-video` - 单个视频处理
- `POST /api/batch-process` - 批量处理
- `GET /api/task-status/{task_id}` - 获取任务状态
### 历史记录
- `GET /api/history` - 获取处理历史
- `DELETE /api/history/{task_id}` - 删除历史记录
### 预设管理
- `GET /api/presets` - 获取预设列表
- `POST /api/presets` - 保存预设
- `DELETE /api/presets/{preset_id}` - 删除预设
### 系统管理
- `GET /api/health` - 健康检查
- `POST /api/cleanup` - 手动清理
- `GET /api/info` - 系统信息
- `GET /api/stats` - 系统统计
## 🛠️ 开发指南
### 添加新功能
1. **添加新的API路由**:
- 在 `api/` 目录下创建新的路由文件
- 在 `api/__init__.py` 中注册新路由
2. **添加新的业务逻辑**:
- 在相应的Manager类中添加方法
- 或创建新的Manager类
3. **添加新的数据操作**:
- 在相应的DAO类中添加方法
- 或创建新的DAO类
### 配置管理
配置文件 `config.py` 提供了不同环境的配置类:
- `DevelopmentConfig`: 开发环境
- `ProductionConfig`: 生产环境
- `TestingConfig`: 测试环境
### 数据库管理
系统使用SQLite数据库,包含以下表:
- `uploads`: 文件上传记录
- `tasks`: 处理任务记录
- `previews`: 预览记录
- `presets`: 参数预设
### 日志管理
系统使用Python标准logging模块,日志级别可通过配置调整。
## 🔧 部署指南
### 开发环境部署
```bash
export FLASK_ENV=development
python app.py
```
### 生产环境部署
1. **使用Gunicorn**:
```bash
pip install gunicorn
export FLASK_ENV=production
gunicorn -w 4 -b 0.0.0.0:5000 app:create_app()
```
2. **使用Docker** (需要创建Dockerfile):
```dockerfile
FROM python:3.9-slim
# 安装系统依赖
RUN apt-get update && apt-get install -y ffmpeg
# 复制代码
COPY . /app
WORKDIR /app
# 安装Python依赖
RUN pip install -r requirements.txt
# 启动应用
CMD ["python", "app.py"]
```
### 反向代理配置 (Nginx)
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# 增加超时时间(用于视频处理)
proxy_read_timeout 300s;
proxy_send_timeout 300s;
# 增加上传限制
client_max_body_size 500M;
}
}
```
## 🐛 常见问题
### FFmpeg相关问题
1. **"ffmpeg不可用"错误**:
- 确保系统已安装FFmpeg
- 检查FFmpeg是否在系统PATH中
2. **视频处理失败**:
- 检查视频格式是否支持
- 确认FFmpeg版本兼容性
### 性能优化
1. **大文件处理**:
- 调整文件上传限制
- 增加处理超时时间
2. **并发处理**:
- 限制同时处理的任务数量
- 使用任务队列(如Celery)
## 📝 更新日志
### v2.0.0 (当前版本)
- 完全重构架构,采用模块化设计
- 分离数据访问层和业务逻辑层
- 改进错误处理和日志记录
- 添加健康检查和系统监控
- 优化文件管理和清理机制
### v1.0.0
- 初始版本,单文件架构
## 🤝 贡献指南
1. Fork项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开Pull Request
## 📄 许可证
本项目采用MIT许可证 - 查看[LICENSE](LICENSE)文件了解详情。
## 📞 支持
如有问题或建议,请提交Issue或联系开发团队。