video_helper.api module

Video Helper — FastAPI HTTP surface.

Exposes every public function in video_helper.main as an HTTP endpoint so video-helper can be dropped behind any reverse proxy and consumed by other services. Kept intentionally minimal:

Multipart uploads for video inputs (UploadFile), streamed straight to a temporary file so large clips don’t blow up memory.
FileResponse for single-file outputs (/convert, /chunk …).
ZIP-encoded StreamingResponse for multi-file outputs (/extract-frames → PNG frames zipped) so the client gets one download per call.
BackgroundTasks cleans temp files after the response has been streamed — no leftover garbage on disk after a request.

Install the extra to get the runtime dependencies:

pip install 'video-helper[api]'

Then run the app with any ASGI server:

uvicorn video_helper.api:app --host 0.0.0.0 --port 8000

Usage Example

>>> # Start the server:
>>> #   uvicorn video_helper.api:app --reload
>>> # Get a file's dimensions (JSON):
>>> #   curl -F 'file=@clip.mp4' http://localhost:8000/dimensions
>>> # Cut a slice:
>>> #   curl -F 'file=@clip.mp4' -F 'start=10' -F 'end=20' \
>>> #        -o cut.mp4 http://localhost:8000/chunk
>>> # Extract PNG frames as a ZIP:
>>> #   curl -F 'file=@clip.mp4' -F 'frame_step=5' \
>>> #        -o frames.zip http://localhost:8000/extract-frames
>>> # Full OpenAPI docs at http://localhost:8000/docs

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

video_helper.api.black(background, duration_seconds=fastapi.Form, width=fastapi.Form, height=fastapi.Form, frame_rate=fastapi.Form, output_format=fastapi.Form)

Synthesize a silent solid-black clip.

Parameters:

background (fastapi.BackgroundTasks)
duration_seconds (float)
width (int)
height (int)
frame_rate (int)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.burn_subs(background, file=fastapi.File, subs=fastapi.File, force_style=fastapi.Form, output_format=fastapi.Form)

Burn subtitles into the frames of the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
subs (fastapi.UploadFile)
force_style (str | None)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.chunk(background, file=fastapi.File, start=fastapi.Form, end=fastapi.Form, output_format=fastapi.Form)

Extract a [start, end] slice from the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
start (float)
end (float)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.concat(background, files=fastapi.File, reencode=fastapi.Form, frame_rate=fastapi.Form, output_format=fastapi.Form)

Concatenate multiple uploaded videos head-to-tail.

Parameters:

background (fastapi.BackgroundTasks)
files (list[fastapi.UploadFile])
reencode (bool)
frame_rate (int | None)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.convert(background, file=fastapi.File, output_format=fastapi.Form, frame_rate=fastapi.Form, width=fastapi.Form, height=fastapi.Form, without_sound=fastapi.Form)

Re-encode / resize / drop-audio the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
output_format (str)
frame_rate (int | None)
width (int | None)
height (int | None)
without_sound (bool)

Return type:

fastapi.responses.FileResponse

video_helper.api.dimensions(file=fastapi.File)

Return width/height/duration/frame_rate/has_sound for the upload.

Parameters:: file (fastapi.UploadFile)
Return type:: fastapi.responses.JSONResponse

video_helper.api.duration(file=fastapi.File)

Return the duration in seconds of the uploaded video.

Parameters:: file (fastapi.UploadFile)
Return type:: fastapi.responses.JSONResponse

video_helper.api.extract_audio(background, file=fastapi.File, output_format=fastapi.Form, sample_rate=fastapi.Form, channels=fastapi.Form, encoding=fastapi.Form)

Dump the audio track of the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
output_format (str)
sample_rate (int)
channels (int)
encoding (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.extract_frames_route(background, file=fastapi.File, frame_step=fastapi.Form, frame_interval=fastapi.Form, start=fastapi.Form, end=fastapi.Form, backend=fastapi.Form)

Extract frames as PNGs; response is a ZIP archive.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
frame_step (int)
frame_interval (float | None)
start (float | None)
end (float | None)
backend (str)

Return type:

fastapi.responses.StreamingResponse

video_helper.api.gui()

Serve the self-contained single-page ‘video bench’ GUI.

The page (defined in video_helper.gui) is a build-step-free HTML + Tailwind-CDN + vanilla-JS client that calls the very same /convert / /chunk / /extract-frames / … endpoints defined below. It adds no server-side logic — it is purely a friendlier front door to the API: upload a clip, run one operation, preview the result in an in-browser <video> / <img> player, and download it.

Returns:: The complete HTML document (status 200, text/html).
Return type:: HTMLResponse

video_helper.api.health()

Simple liveness probe — no dependency check, just proves the app is up.

Return type:: dict

video_helper.api.image_loop(background, image=fastapi.File, duration_seconds=fastapi.Form, frame_rate=fastapi.Form, width=fastapi.Form, height=fastapi.Form, output_format=fastapi.Form)

Loop a still image for duration seconds into a silent video.

Parameters:

background (fastapi.BackgroundTasks)
image (fastapi.UploadFile)
duration_seconds (float)
frame_rate (int)
width (int | None)
height (int | None)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.mux_audio(background, file=fastapi.File, audio=fastapi.File, audio_codec=fastapi.Form, audio_bitrate=fastapi.Form, shortest=fastapi.Form, output_format=fastapi.Form)

Mux a separate audio track onto the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
audio (fastapi.UploadFile)
audio_codec (str)
audio_bitrate (str)
shortest (bool)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.overlay(background, file=fastapi.File, image=fastapi.File, x=fastapi.Form, y=fastapi.Form, scale_width=fastapi.Form, output_format=fastapi.Form)

Overlay a still image on the uploaded video.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)
image (fastapi.UploadFile)
x (str)
y (str)
scale_width (int | None)
output_format (str)

Return type:

fastapi.responses.FileResponse

video_helper.api.root()

Redirect the bare root to the GUI so opening the server just works.

Return type:: fastapi.responses.RedirectResponse

video_helper.api.srt2vtt_route(background, file=fastapi.File)

Convert an uploaded SRT to WebVTT + companion CSS; response is a ZIP.

Parameters:

background (fastapi.BackgroundTasks)
file (fastapi.UploadFile)

Return type:

fastapi.responses.StreamingResponse

video_helper.api.validate(file=fastapi.File)

Probe an uploaded video for validity (ffprobe + extension check).

Parameters:: file (fastapi.UploadFile)
Return type:: fastapi.responses.JSONResponse