# ffmpeg-python-api

**Repository Path**: darrenliu/ffmpeg-python-api

## Basic Information

- **Project Name**: ffmpeg-python-api
- **Description**: https://github.com/kkroening/ffmpeg-python.git
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FFmpeg HTTP API

基于 **FastAPI** + **ffmpeg-python** 的 HTTP 视频处理服务。前端通过 multipart 上传文件，同步等待处理完成后直接获取结果文件或 JSON 元数据。

## 功能

| 接口 | 说明 |
|------|------|
| `POST /api/v1/probe` | 获取视频/音频信息（时长、分辨率、编码等） |
| `POST /api/v1/video/trim` | 按起止时间剪辑视频 |
| `POST /api/v1/video/concat` | 拼接多段视频（2 段及以上） |
| `POST /api/v1/video/convert` | 格式转换（mp4 / gif / webm / avi） |
| `POST /api/v1/audio/extract` | 从视频提取音频（mp3 / aac / wav） |
| `POST /api/v1/audio/add` | 为视频添加或替换音频轨道 |
| `GET /health` | 健康检查（含 FFmpeg 是否可用） |

交互式文档：启动服务后访问 [http://localhost:8000/docs](http://localhost:8000/docs)

## 架构

```
前端 --multipart POST--> FastAPI --> ffmpeg_service --> 系统 ffmpeg/ffprobe
                              |                              |
                         uploads/                       outputs/
                              +-------- 响应后自动清理 --------+
```

- **同步模式**：请求阻塞至处理完成，适合短视频（建议单文件 < 100MB）
- **无 Redis**：入门简单，无需额外中间件

## 前置条件

| 依赖 | 说明 |
|------|------|
| Python 3.10+ | [python.org](https://www.python.org/downloads/) 安装时勾选 Add to PATH |
| FFmpeg | 必须单独安装，[下载地址](https://ffmpeg.org/download.html) 或 `winget install Gyan.FFmpeg` |
| pip 包 | 通过 `requirements.txt` 安装，**不要复制 FastAPI / ffmpeg-python 源码到项目中** |

验证 FFmpeg：

```powershell
ffmpeg -version
ffprobe -version
```

## 快速开始

### 1. 克隆并进入项目

```powershell
cd D:\python\ffmpeg-python-api
```

### 2. 创建虚拟环境

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

### 3. 安装依赖

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

> 若需使用本地 ffmpeg-python 源码调试：`pip install -e D:\python\ffmpeg-python-master`

### 4. 配置（可选）

```powershell
copy .env.example .env
```

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `8000` | 监听端口 |
| `MAX_UPLOAD_SIZE` | `104857600` | 单文件上限（字节，100MB） |
| `UPLOAD_DIR` | `uploads` | 上传临时目录 |
| `OUTPUT_DIR` | `outputs` | 输出临时目录 |
| `CORS_ORIGINS` | `*` | CORS 来源，逗号分隔 |

### 5. 启动服务

```powershell
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

浏览器打开 http://localhost:8000/docs 即可测试。

## API 调用示例

### 获取视频信息

```bash
curl -X POST http://localhost:8000/api/v1/probe \
  -F "file=@sample.mp4"
```

响应示例：

```json
{
  "filename": "abc123.mp4",
  "duration": 10.5,
  "width": 1920,
  "height": 1080,
  "video_codec": "h264",
  "audio_codec": "aac",
  "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
  "bitrate": 500000,
  "fps": 30.0
}
```

### 剪辑视频

```bash
curl -X POST http://localhost:8000/api/v1/video/trim \
  -F "file=@sample.mp4" \
  -F "start=1.0" \
  -F "end=5.0" \
  -o trimmed.mp4
```

### 拼接视频

```bash
curl -X POST http://localhost:8000/api/v1/video/concat \
  -F "files=@part1.mp4" \
  -F "files=@part2.mp4" \
  -o merged.mp4
```

### 格式转换

```bash
curl -X POST http://localhost:8000/api/v1/video/convert \
  -F "file=@sample.mp4" \
  -F "format=gif" \
  -o output.gif
```

### 提取音频

```bash
curl -X POST http://localhost:8000/api/v1/audio/extract \
  -F "file=@sample.mp4" \
  -F "format=mp3" \
  -o audio.mp3
```

### 添加/替换音频

```bash
curl -X POST http://localhost:8000/api/v1/audio/add \
  -F "video=@sample.mp4" \
  -F "audio=@bgm.mp3" \
  -F "replace=true" \
  -o output.mp4
```

### 前端 JavaScript 示例

```javascript
async function trimVideo(file, start, end) {
  const form = new FormData();
  form.append("file", file);
  form.append("start", String(start));
  form.append("end", String(end));

  const res = await fetch("http://localhost:8000/api/v1/video/trim", {
    method: "POST",
    body: form,
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.detail);
  }

  const blob = await res.blob();
  const url = URL.createObjectURL(blob);
  // 用于预览或下载
  return url;
}
```

## 项目结构

```
ffmpeg-python-api/
├── app/
│   ├── main.py              # FastAPI 入口
│   ├── config.py            # 配置
│   ├── routers/             # API 路由
│   ├── services/            # ffmpeg-python 封装
│   ├── schemas/             # 请求/响应模型
│   └── utils/               # 文件工具
├── tests/                   # pytest 测试
├── requirements.txt
├── pytest.ini
└── README.md
```

## 测试

```powershell
# 需确保 ffmpeg 在 PATH 中
pytest tests/ -v
```

无 FFmpeg 时，集成测试会自动跳过，单元测试与健康检查仍可运行。

## 常见问题

### `ffmpeg: command not found`

FFmpeg 未安装或未加入 PATH。Windows 可下载 [gyan.dev builds](https://www.gyan.dev/ffmpeg/builds/)，解压后将 `bin` 目录加入系统环境变量。

### 视频拼接失败

多段视频分辨率、帧率、编码不一致时可能失败。请先统一规格，或在拼接前对各段做转码。

### 剪辑结果不精确

使用 `-c copy` 流复制时只能在关键帧处切割。服务会在失败时自动回退为重新编码（libx264 + aac），精度更高但速度较慢。

### HTTP 超时

同步模式下长视频处理可能导致网关/客户端超时。建议控制单文件大小，或后续升级为异步任务队列（Celery + Redis）。

### 能否复制 FastAPI / ffmpeg-python 源码？

**不建议。** FastAPI 和 ffmpeg-python 应通过 `pip install` 作为依赖引入。你本地的 `D:\python\FastAPI` 是框架源码，`D:\python\ffmpeg-python-master` 是库源码，仅供阅读或 `pip install -e` 本地调试。

## 生产部署提示

- 使用 `uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 1`（FFmpeg  CPU 密集，多 worker 需评估）
- 在 Nginx 后反向代理时增大 `proxy_read_timeout`
- 收紧 `CORS_ORIGINS`，添加 API Key 鉴权
- 定期清理 `uploads/`、`outputs/` 目录（正常流程会在响应后自动删除）

## 技术栈

- [FastAPI](https://fastapi.tiangolo.com/) — Web 框架
- [ffmpeg-python](https://github.com/kkroening/ffmpeg-python) — FFmpeg Python 绑定
- [Uvicorn](https://www.uvicorn.org/) — ASGI 服务器
- [pytest](https://docs.pytest.org/) — 测试框架

## License

MIT