# 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.