# ffmpeg_service

**Repository Path**: hackyin/ffmpeg_service

## Basic Information

- **Project Name**: ffmpeg_service
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-31
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FFmpeg Service

这是一个基于 Node.js 和 Docker 的全功能 FFmpeg HTTP 服务。它提供了一个现代化的 Web 界面来演示功能，同时提供 RESTful API 供程序调用。支持视频转换、压缩、序列帧合成、音频提取等多种功能。

## 功能概览

- 🐳 **Docker 支持**: 开箱即用，环境一致。
- 🖥️ **Web Dashboard**: 访问根路径 `/` 即可使用类似工具箱的图形界面。
- 📖 **Swagger API**: 访问 `/api-docs` 查看完整的接口定义和测试工具。
- 🔧 **万能接口**: `/api/ffmpeg` 支持直接执行任意 FFmpeg 命令。
- ⚡ **GPU 硬件加速**: 自动检测并使用 VideoToolbox/NVENC/AMF/QSV，转换速度提升 **3-10 倍**！
- 🎞️ **高级特性**:
  - **序列帧合成**: 将 ZIP 包中的图片序列合称为 MP4 或 透明 WebM 视频。
  - **图片/视频压缩**: 支持自定义质量 (Quality/CRF) 和尺寸。
  - **透明视频支持**: 专门的 Prores 4444 和 VP9 Alpha 支持。

## 快速开始

### 1. 使用 Docker

```bash
# 构建镜像
docker build -t ffmpeg-service .

# 启动容器 (映射端口 3001)
docker run -d -p 3001:3001 --name ffmpeg-service ffmpeg-service
```

访问: `http://localhost:3001`

### 2. 本地开发

需要本地安装 Node.js 18+ 和 FFmpeg。

```bash
# 安装依赖
npm install

# 启动服务
npm start
```

## API 指南

详细 API 请参考 Swagger (`/api-docs`)。部分核心接口如下：

### 序列帧合成 (`POST /convert/images-to-video`)

将一组图片（ZIP 压缩包）合成为视频。

- **Params**:
  - `file`: (File) 包含图片序列 (如 img_001.png) 的 ZIP 文件。
  - `fps`: (Int) 帧率，默认 30。
  - `format`: `mp4` 或 `webm-alpha` (支持透明)。
  - `quality`: `high` / `medium` / `low`.

### 视频压缩 (`POST /tool/compress`)

- **Params**:
  - `media`: (File) 原始视频。
  - `crf`: (Int) 压缩系数，18-51。28 为推荐值。

### 图片工具 (`POST /tool/compress-image`)

支持格式转换 (WebP/JPEG) 和缩放。

---

## 环境变量

- `PORT`: 监听端口 (默认 3001)

## ⚡ GPU 加速优化

本服务已全面支持硬件编码器加速，可大幅提升视频转换效率。详细说明请查看：

👉 **[GPU 加速优化文档](./GPU_OPTIMIZATION.md)**

### 快速了解

- ✅ 自动检测可用的硬件编码器（VideoToolbox/NVENC/AMF/QSV）
- ✅ 图像序列转视频速度提升 **3-10 倍**
- ✅ 支持 macOS、Windows、Linux 多平台
- ✅ 无需额外配置，开箱即用

**性能示例**（120 张 1080p 图片转 MP4）：

- MacBook Pro M1 (VideoToolbox): ~5 秒 ⚡
- 软件编码 (libx264): ~50 秒 🐌