# 数字人换背景 **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或联系开发团队。