spark-ffmppppeg-api/README.md

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

cd /home/azurian/ffmppppeg-api
/home/azurian/.venv/bin/pip install -r requirements.txt

Start

Using the launcher:

/home/azurian/start-convert.sh

Or directly with Uvicorn:

cd /home/azurian/ffmppppeg-api
/home/azurian/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8022

Start in CUDA-only mode:

cd /home/azurian/ffmppppeg-api
FORCE_CUDA=1 /home/azurian/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8022

Health Check

curl http://IP_DEL_SERVER:8022/health

API Contract

Endpoint

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:

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:

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:

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:

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.