first
This commit is contained in:
valenti
@@ -0,0 +1,185 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user