186 lines
4.1 KiB
Markdown
186 lines
4.1 KiB
Markdown
# FFmpeg API
|
|
|
|
FastAPI service that exposes FFmpeg over HTTP for three explicit conversion workflows through a single endpoint:
|
|
|
|
- `video_to_mp4`
|
|
- `audio_to_mp3`
|
|
- `audio_image_to_mp4`
|
|
|
|
The API is designed to run with Uvicorn and prefer CUDA/NVIDIA acceleration by default through `h264_nvenc`.
|
|
|
|
Available H.264 video codecs:
|
|
|
|
- `libx264`
|
|
- `h264_nvenc`
|
|
|
|
## Requirements
|
|
|
|
- Python virtual environment available at `/home/azurian/.venv`
|
|
- FFmpeg installed on the host and available in `PATH`
|
|
- FFmpeg build with support for `libx264`
|
|
- Optional NVIDIA-enabled FFmpeg build with support for `h264_nvenc`
|
|
|
|
## Install
|
|
|
|
```bash
|
|
cd /home/azurian/ffmppppeg-api
|
|
/home/azurian/.venv/bin/pip install -r requirements.txt
|
|
```
|
|
|
|
## Start
|
|
|
|
Using the launcher:
|
|
|
|
```bash
|
|
/home/azurian/start-convert.sh
|
|
```
|
|
|
|
Or directly with Uvicorn:
|
|
|
|
```bash
|
|
cd /home/azurian/ffmppppeg-api
|
|
/home/azurian/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8022
|
|
```
|
|
|
|
Start in CUDA-only mode:
|
|
|
|
```bash
|
|
cd /home/azurian/ffmppppeg-api
|
|
FORCE_CUDA=1 /home/azurian/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8022
|
|
```
|
|
|
|
## Health Check
|
|
|
|
```bash
|
|
curl http://IP_DEL_SERVER:8022/health
|
|
```
|
|
|
|
## API Contract
|
|
|
|
### Endpoint
|
|
|
|
```text
|
|
POST /convert
|
|
```
|
|
|
|
### Query Parameters
|
|
|
|
- `mode`: `video_to_mp4`, `audio_to_mp3`, or `audio_image_to_mp4`
|
|
- `codec`: `libx264` or `h264_nvenc` for video modes, default `h264_nvenc`
|
|
- `preset`: optional video preset, default `medium` for `libx264` and `p4` for `h264_nvenc`
|
|
- `audio_bitrate`: audio bitrate for `audio_to_mp3`, default `192k`
|
|
- `width`: output width for `audio_image_to_mp4`, default `1920`
|
|
- `height`: output height for `audio_image_to_mp4`, default `1080`
|
|
- `fps`: output frame rate for `audio_image_to_mp4`, default `30`
|
|
- `logo_width`: logo width in pixels for `audio_image_to_mp4`, default `280`
|
|
- `margin`: top/right logo margin for `audio_image_to_mp4`, default `24`
|
|
|
|
Recommended output parameters:
|
|
|
|
- Video codec: H.264 via `h264_nvenc`
|
|
- Audio codec: `aac`
|
|
- Pixel format: `yuv420p`
|
|
- Container: `mp4`
|
|
- Flags: `+faststart`
|
|
|
|
Fallback:
|
|
|
|
- `libx264` remains available if you need a CPU-only fallback path.
|
|
|
|
CUDA enforcement:
|
|
|
|
- If you start the server with `FORCE_CUDA=1`, every video output must use `h264_nvenc`.
|
|
- With `FORCE_CUDA=1`, requests that specify `libx264` return HTTP 400.
|
|
- `audio_to_mp3` is unaffected because it does not produce video output.
|
|
|
|
## Modes
|
|
|
|
### 1. `video_to_mp4`
|
|
|
|
Multipart fields:
|
|
|
|
- `file`: input video file
|
|
|
|
Example:
|
|
|
|
```bash
|
|
curl -X POST "http://IP_DEL_SERVER:8022/convert?mode=video_to_mp4&codec=h264_nvenc&preset=p4" \
|
|
-F "file=@/path/input.mov" \
|
|
--output output.mp4
|
|
```
|
|
|
|
### 2. `audio_to_mp3`
|
|
|
|
Multipart fields:
|
|
|
|
- `audio`: input audio file
|
|
|
|
You can also send the audio file as `file`, but `audio` is the recommended field name.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
curl -X POST "http://IP_DEL_SERVER:8022/convert?mode=audio_to_mp3&audio_bitrate=192k" \
|
|
-F "audio=@/path/input.wav" \
|
|
--output output.mp3
|
|
```
|
|
|
|
### 3. `audio_image_to_mp4`
|
|
|
|
Multipart fields:
|
|
|
|
- `audio`: input audio file
|
|
- `background`: background image or background video
|
|
- `logo`: overlay logo image
|
|
|
|
Supported background image formats:
|
|
|
|
- `.jpg`
|
|
- `.jpeg`
|
|
- `.png`
|
|
- `.webp`
|
|
|
|
Supported background video formats:
|
|
|
|
- `.mp4`
|
|
- `.mov`
|
|
- `.mkv`
|
|
- `.avi`
|
|
- `.webm`
|
|
- `.m4v`
|
|
|
|
Supported audio formats:
|
|
|
|
- `.wav`
|
|
- `.mp3`
|
|
- `.m4a`
|
|
- `.aac`
|
|
- `.flac`
|
|
- `.ogg`
|
|
|
|
Example with image background:
|
|
|
|
```bash
|
|
curl -X POST "http://IP_DEL_SERVER:8022/convert?mode=audio_image_to_mp4&codec=h264_nvenc&preset=p4&width=1920&height=1080&fps=30&logo_width=280&margin=24" \
|
|
-F "audio=@/path/voice.wav" \
|
|
-F "background=@/path/background.jpg" \
|
|
-F "logo=@/path/logo.png" \
|
|
--output output.mp4
|
|
```
|
|
|
|
Example with video background:
|
|
|
|
```bash
|
|
curl -X POST "http://IP_DEL_SERVER:8022/convert?mode=audio_image_to_mp4&codec=h264_nvenc&preset=p4" \
|
|
-F "audio=@/path/voice.wav" \
|
|
-F "background=@/path/background.mp4" \
|
|
-F "logo=@/path/logo.png" \
|
|
--output output.mp4
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Temporary files are cleaned up automatically on success and error paths.
|
|
- FFmpeg failures are returned as HTTP 500 responses with the process error message.
|
|
- CORS is enabled for network access from other machines on the local network.
|