# videoDispose

**Repository Path**: mii/videoDispose

## Basic Information

- **Project Name**: videoDispose
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2025-11-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 音视频处理服务

这是一个基于Python和MoviePy的音视频处理服务，提供了RESTful API接口来处理音视频文件。

## 功能特性

1. 基于 Python 和 MoviePy 的音视频处理服务
2. 支持多种视频格式处理（MP4、AVI、MOV 等）
3. 支持网络视频 URL 直接处理，自动下载和清理
4. 提供 RESTful API 接口，便于集成到其他系统
5. 支持视频拼接、截取、缩放、旋转等常见操作
6. 支持音频提取、合并、格式转换等功能
7. 内置任务队列和状态查询机制
8. 支持回调通知，处理完成后自动通知客户端
9. 支持 Docker 部署，便于快速部署和扩展
10. 支持处理不同分辨率和帧率的视频，可选择保持宽高比

## 文档

- [视频处理功能详细说明](docs/video_processing.md)
- [API 接口文档](docs/api.md)

## 测试

项目包含完整的测试套件，用于验证各种功能：

```bash
# 运行所有测试
python tests/test_enhanced_concat_processor.py
```

测试内容包括：
- 基础功能测试
- 宽高比处理测试
- 不保持宽高比测试
- 自动设置功能测试
- 异常处理测试

## 安装依赖

```bash
pip install -r requirements.txt
```

这将安装所有必需的依赖，包括用于生产环境的 `waitress` WSGI 服务器。

## 数据库配置

项目现在支持多数据库配置，默认使用 `freefishchn` 数据库。数据库配置文件位于 `config/db.json`，格式如下：

```json
{
  "freefish": {
    "host": "y05hephoz7pajlrcd1sr-rw4rm.rwlb.zhangbei.rds.aliyuncs.com",
    "port": 3306,
    "database": "freefish",
    "username": "freefish",
    "password": "freefish",
    "charset": "utf8mb4"
  },
  "freefishchn": {
    "host": "62.234.126.29",
    "port": 3306,
    "database": "freefishchn",
    "username": "freefishchn",
    "password": "freefishchn",
    "charset": "utf8mb4"
  }
}
```

### 配置说明

数据库配置采用新的格式，支持多个数据库配置。与旧版本不同的是：
- 新的配置格式不再按环境（development、production、test）区分，而是在不同环境下使用不同的 `db.json` 文件来实现配置区分。
- **默认数据库**：代码中默认使用 `freefishchn` 数据库配置。
- **字段说明**：
  - `host`：数据库服务器地址
  - `port`：数据库端口
  - `database`：数据库名称
  - `username`：用户名
  - `password`：密码
  - `charset`：字符集

### 不同环境的配置

为了在不同环境（开发、测试、生产）中使用不同的数据库配置，请在对应环境的服务器上放置不同的 `db.json` 文件，而不是在单个文件中配置多个环境。

### 指定数据库

默认情况下，应用程序使用 `freefishchn` 数据库。如果您想使用不同的数据库，可以通过设置环境变量 `DB_NAME` 来指定：

```bash
# 使用freefish数据库
export DB_NAME=freefish
python app.py

# 使用freefishchn数据库（默认）
export DB_NAME=freefishchn
python app.py
```

在Windows系统中，使用以下命令：

```cmd
# 使用freefish数据库
set DB_NAME=freefish
python app.py

# 使用freefishchn数据库（默认）
set DB_NAME=freefishchn
python app.py
```

## 启动服务

有三种方式启动服务：

### 方法1：直接运行Flask应用

```bash
python app.py
```

### 方法2：使用启动脚本（推荐）

```bash
python run.py
```

启动脚本会自动使用Waitress作为生产级服务器（如果已安装），如果未安装Waitress，将回退到Flask内置服务器。
同时会自动创建必要的目录。

### 方法3：使用Docker（推荐用于生产环境）

```bash
docker-compose up -d
```

服务将运行在 `http://localhost:5000`

### Docker部署说明

项目包含Dockerfile和docker-compose.yml文件，可以方便地进行容器化部署。

构建并启动服务：
```bash
docker-compose up -d
```

查看服务日志：
```bash
docker-compose logs -f
```

停止服务：
```bash
docker-compose down
```

## 性能测试

项目包含一个性能测试脚本 `benchmark.py`，可以用来测试服务的并发处理能力。

运行性能测试：

```bash
python benchmark.py
```

测试结果将保存在 `benchmark_results.json` 文件中。

## API接口
### 1. 处理视频

根据指定的处理函数处理视频文件

**URL**: `/process/video`
**方法**: `POST`
**参数**:
- `video_url` (string, required): 视频文件的URL
- `process_func` (string, optional): 处理函数名称，默认为'default'
- `callback_url` (string, optional): 处理完成后的回调URL

**响应**:
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}
```

### 2. 处理音频

处理音频文件

**URL**: `/process/audio`
**方法**: `POST`
**参数**:
- `audio_url` (string, required): 音频文件的URL
- `callback_url` (string, optional): 处理完成后的回调URL

**响应**:
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}
```

### 3. 查询任务状态

**URL**: `/task/<task_id>`
**方法**: `GET`

**响应**:
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed"
}
```

### 4. 可用的处理函数

服务支持多种处理函数，可以通过 `process_func` 参数指定：

1. `default` - 默认处理函数，返回原视频和视频信息
2. `info` - 获取并返回视频信息
3. `concat` - 视频拼接处理器，支持处理不同分辨率和帧率的视频
  3.1 请求示例
  {"video_paths":["https://bbdev.oss-cn-zhangjiakou.aliyuncs.com/freefishpc/assets_library/6351/124/b2ff5f26-3699-4de3-adc7-730e6f7e5090.mp4","https://bbdev.oss-cn-zhangjiakou.aliyuncs.com/freefishpc/assets_library/6351/124/162fb124-18df-4c25-a56b-b7670d09b9e2.mp4"],"target_duration":120,"process_func":"concat","callback_url":"https://fishapi.chabaoxian.net/callback/appTest"}
4. `reverse_splice` - 正倒放拼接处理器，将视频正放和倒放拼接在一起
  4.1 请求示例
  {"video_path":"https://pubsto.fullpeace.cn/figure/double_human.mp4","target_duration":120,"process_func":"reverse_splice","callback_url":"https://fishapi.chabaoxian.net/callback/appTest"}
5. `cut` - 视频剪切处理器，根据提供的时间数组剪切视频并上传到OSS
  5.1 请求示例
  {"video_url":"https://example.com/sample_video.mp4","process_func":"cut","cut_time":[{"start_time":0,"end_time":10},{"start_time":15,"end_time":25}],"callback_url":"https://fishapi.chabaoxian.net/callback/appTest"}



## 视频处理函数系统

### 系统架构

服务采用模块化设计，每个视频处理函数都位于单独的文件中，存放在 `video_processors/` 目录下。这种设计使得添加新的处理函数变得简单，无需修改核心代码。

### 目录结构

```
videoDispose/
├── app.py                 # 主应用文件
├── video_processors/      # 视频处理函数目录
│   ├── __init__.py        # 处理器管理器
│   ├── default_processor.py # 默认处理函数
│   └── info_processor.py  # 视频信息获取处理函数
└── utils/                 # 工具函数目录
    └── __init__.py        # 通用工具函数
```

### 可用的处理函数

服务启动时会自动扫描 `video_processors/` 目录，并加载所有以 `_processor.py` 结尾的文件中的处理函数，以及特殊的 `default_video_processing` 函数。

当前可用的处理函数包括：
- `default`: 默认处理函数，返回原视频和视频信息
- `info`: 获取并返回视频信息
- `concat`: 视频拼接处理器，支持处理不同分辨率和帧率的视频
- `reverse_splice`: 正倒放拼接处理器，将视频正放和倒放拼接在一起

### 添加新的处理函数

要添加新的视频处理函数，只需在 `video_processors/` 目录下创建一个新的Python文件，并按照以下规则实现处理函数：

1. 文件名格式为 `[processor_name]_processor.py`
2. 函数名格式为 `[processor_name]_processor`
3. 函数至少接受一个参数 `video_path`，可以接受额外的命名参数 `**kwargs`
4. 函数返回值可以是：
   - 处理后的视频文件路径和视频信息的元组: `(output_path, video_info)`
   - 仅返回视频信息: `video_info`

示例：创建一个名为 `resize_processor.py` 的文件，实现视频尺寸调整功能：

```python
from moviepy.editor import VideoFileClip
from ..utils import get_video_info


def resize_processor(video_path, width=640, height=-1, **kwargs):
    """
    调整视频尺寸
    
    Args:
        video_path (str): 视频文件路径
        width (int): 目标宽度，默认为640
        height (int): 目标高度，默认为-1（自动计算）
        **kwargs: 其他参数
        
    Returns:
        tuple: (output_path, video_info)
    """
    # 加载视频
    clip = VideoFileClip(video_path)
    
    # 调整尺寸
    resized_clip = clip.resize(width=width, height=height)
    
    # 生成输出文件名
    output_path = f"resized_{width}x{height}_{video_path}"
    
    # 导出视频
    resized_clip.write_videofile(output_path, codec="libx264", audio_codec="aac")
    
    # 获取视频信息
    video_info = get_video_info(output_path)
    
    # 关闭clip
    clip.close()
    resized_clip.close()
    
    return output_path, video_info
```

## 视频剪切处理器 (cut_processor)

视频剪切处理器可以根据提供的时间数组对视频进行剪切，并将剪切后的视频片段上传到OSS存储服务。

### 功能特性

1. **时间剪切**：根据提供的时间数组对视频进行精确剪切
2. **批量处理**：支持一次处理多个时间片段
3. **网络视频支持**：可以直接使用网络视频URL，系统会自动下载
4. **自动下载重试**：对于网络视频，系统会自动尝试下载
5. **指定下载目录**：所有网络视频将统一下载到项目目录下的`download`文件夹中
6. **自动清理**：处理完成后，系统会自动删除本次任务下载的视频文件
7. **OSS上传**：剪切后的视频片段会自动上传到配置的OSS存储桶
8. **返回上传地址**：处理结果包含每个剪切片段的上传地址

### 使用示例

```python
from video_processors.cut_processor import cut_processor

# 定义剪切时间数组
cut_time = [
    {"start_time": 0, "end_time": 10},
    {"start_time": 15, "end_time": 25},
    {"start_time": 30, "end_time": 40}
]

# 使用网络视频URL
video_url = "https://example.com/sample_video.mp4"

# 基础使用 - 函数会自动下载、处理并清理
result = cut_processor(
    video_url=video_url,
    cut_time=cut_time
)

# 高级使用 - 指定任务ID和OSS目录
result = cut_processor(
    video_url=video_url,
    cut_time=cut_time,
    task_id="example_task_001",
    oss_bucket_dir="freefishpc/cloud_video/dispose"
)

# 处理结果示例
# [
#   {
#     "start_time": 0,
#     "end_time": 10,
#     "url": "https://bbdev.oss-cn-zhangjiakou.aliyuncs.com/freefishpc/cloud_video/dispose/example_task_001_cut_1.mp4"
#   },
#   {
#     "start_time": 15,
#     "end_time": 25,
#     "url": "https://bbdev.oss-cn-zhangjiakou.aliyuncs.com/freefishpc/cloud_video/dispose/example_task_001_cut_2.mp4"
#   }
# ]
```

## 视频拼接处理器 (concat_processor)

视频拼接处理器支持处理不同分辨率和帧率的视频，可选择保持宽高比或不保持宽高比，并可指定目标分辨率和帧率。

### 功能特性

1. **多视频拼接**：支持将多个视频文件按顺序拼接成一个视频
2. **网络视频支持**：可以直接使用网络视频URL，系统会自动下载
3. **自动下载重试**：对于网络视频，系统会自动尝试下载2次，如果都失败则忽略该记录，确保处理流程不会因为单个视频下载失败而中断
4. **指定下载目录**：所有网络视频将统一下载到项目目录下的`download`文件夹中，便于管理和清理
5. **自动清理**：处理完成后，系统会自动删除本次任务下载的视频文件，但会保留`download`文件夹，便于后续使用
6. **多分辨率和帧率适配**：现在支持处理不同分辨率和帧率的视频，可选择保持宽高比或不保持宽高比，并可指定目标分辨率和帧率

### 使用示例

```python
from video_processors.concat_processor import concat_processor

# 可以直接使用网络链接
video_urls = [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4"
]

# 基础使用 - 函数会自动下载、处理并清理
output_path, video_info = concat_processor(video_paths=video_urls)

# 高级使用 - 处理不同分辨率和帧率的视频
# 保持宽高比，调整到指定尺寸和帧率
output_path, video_info = concat_processor(
    video_paths=video_paths,
    target_duration=10.0,           # 截取10秒
    maintain_aspect_ratio=True,     # 保持宽高比
    target_size=(1280, 720),        # 目标尺寸
    target_fps=30.0                 # 目标帧率
)

# 不保持宽高比，直接拉伸到指定尺寸
output_path, video_info = concat_processor(
    video_paths=video_urls,
    target_duration=8.0,            # 截取8秒
    maintain_aspect_ratio=False,    # 不保持宽高比
    target_size=(1920, 1080),       # 目标尺寸
    target_fps=24.0                 # 目标帧率
)
```

## 正倒放拼接处理器 (reverse_splice_processor)

正倒放拼接处理器将视频正放和倒放拼接在一起，常用于制作循环播放的视频效果。

### 功能特性

1. **正倒放拼接**：将视频正放和倒放拼接在一起
2. **时长控制**：支持指定目标时长，自动调整拼接方式
3. **网络视频支持**：可以直接使用网络视频URL，系统会自动下载
4. **自动下载重试**：对于网络视频，系统会自动尝试下载2次
5. **指定下载目录**：所有网络视频将统一下载到项目目录下的`download`文件夹中
6. **自动清理**：处理完成后，系统会自动删除本次任务下载的视频文件
7. **多分辨率和帧率适配**：支持处理不同分辨率和帧率的视频

### 使用示例

```python
from video_processors.reverse_splice_processor import reverse_splice_processor

# 使用网络视频URL
video_url = "https://example.com/sample_video.mp4"

# 基础使用 - 函数会自动下载、处理并清理
output_path, video_info = reverse_splice_processor(video_path=video_url)

# 指定目标时长
output_path, video_info = reverse_splice_processor(
    video_path=video_url,
    target_duration=30.0  # 截取30秒
)
```

## 错误处理

服务包含基本的错误处理机制，当处理过程中出现异常时：
1. 任务状态会被标记为`failed`
2. 错误信息会通过回调通知发送（如果配置了回调URL）
3. 错误信息会记录在日志中

### 常见错误类型

1. **网络下载错误**：视频URL无法访问或下载失败
2. **视频处理错误**：视频文件损坏或格式不支持
3. **资源不足错误**：内存不足或磁盘空间不足
4. **数据库连接错误**：无法连接到数据库

### 错误重试机制

1. **网络视频下载**：提供重试机制，最多尝试2次
2. **视频加载**：单个视频加载失败不会影响整个处理流程
3. **资源清理**：处理完成后自动清理下载的临时文件

## 性能优化建议

1. **内存管理**：处理大尺寸视频时确保有足够的内存
2. **网络视频处理**：网络视频会自动下载，处理时间取决于网络速度
3. **并行处理**：对于大量视频处理任务，考虑使用并行处理
4. **磁盘空间**：处理过程中会产生临时文件，确保有足够的磁盘空间

## 回调通知

服务支持回调通知功能，当视频处理完成后会向指定的URL发送POST请求。

### 回调数据格式

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "output_path": "/path/to/output.mp4",
    "video_info": {
      "duration": 120.5,
      "size": [1920, 1080],
      "fps": 30.0,
      "file_size": 1024000
    }
  }
}
```

### 回调服务示例

项目包含一个简单的回调服务示例，可以在 `test/test_client.py` 中找到：

```python
from flask import Flask, request, jsonify

callback_app = Flask(__name__)

@callback_app.route('/callback', methods=['POST'])
def handle_callback():
    data = request.json
    print(f"收到回调: {json.dumps(data, indent=2)}")
    return jsonify({"status": "ok"})

if __name__ == "__main__":
    callback_app.run(host='0.0.0.0', port=5001, debug=False)
```

启动回调服务：
```bash
python test/test_client.py callback
```

## 版本更新日志

详细的版本更新日志请查看 [CHANGELOG.md](CHANGELOG.md) 文件。

## 许可证

本项目采用 MIT 许可证，详情请查看 [LICENSE](LICENSE) 文件。