Video Helper

🇫🇷 · 🇬🇧

Video Helper belongs to a collection of libraries called AI Helpers developed for building Artificial Intelligence.

🌍 AI Helpers

Video Helper is a Python library that provides utility functions for processing video files. It includes features like loading, converting, extracting frames as well as working with subtitle formats.

The Promise

Local-first by design. video-helper runs entirely on your machine. Everything is processed locally with open-source tooling (ffmpeg): your data is never uploaded to a third-party service, no telemetry, no account, no cloud lock-in. You own the whole pipeline. Part of the AI Helpers suite: sovereignty over your data through local-first Open Source.

Documentation

💻 Documentation

🗺️ Landscape

📋 Examples

Features

• Video validation: is_valid_video_file, extension check plus an ffmpeg.probe round-trip.
• Conversion: video_converter, re-encode, resample fps, resize (aspect-preserving), strip audio.
• Frame access: extract_frames (generator with time/index range, stabilization, sampling) and dump_frames (list → video).
• Temporal crop: extract_video_chunk, video_duration.
• Pipeline primitives: black_video, compress_video, image_loop_to_video, concat_videos, overlay_image, extract_audio_track, mux_audio_video, burn_subtitles.
• Subtitles: srt2vtt (with companion CSS), extract_unique_colors.

Installation

Prerequisites: Python 3.10–3.13 and git, ffmpeg, cross-platform:

• 🍎 macOS (Homebrew): brew install python git ffmpeg
• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git ffmpeg
• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git Gyan.FFmpeg

We recommend using Python environments. Check this link if you're unfamiliar with setting one up: 🥸 Tech tips.

From PyPI (recommended)

# Core video utilities (library + argparse CLI)
pip install video-helper

# Optional surfaces and backends
pip install "video-helper[pyav]"      # PyAV frame backend
pip install "video-helper[cli]"       # click-based CLI twin
pip install "video-helper[api]"       # FastAPI HTTP surface

From source (no PyPI)

git clone https://github.com/warith-harchaoui/video-helper.git
cd video-helper
pip install -e .

# Optional surfaces and backends
pip install -e ".[pyav]"
pip install -e ".[cli]"
pip install -e ".[api]"

Usage

For the full catalog of recipes, see 📋 EXAMPLES.md.

Here’s an example of how to use Video Helper to load, convert, and extract frames from a video file:

import video_helper as vh

# Check if the video file is valid
video_file = "example.mp4"
valid = vh.is_valid_video_file(video_file) # True or False

# Get video dimensions and details
details = vh.video_dimensions(video_file)
print(details)
# {'width': 1920, 'height': 1080, 'duration': 10.0, 'frame_rate': 30.0, 'has_sound': True}

# Convert the video file to a different format
output_video = "video_tests/example_converted.mp4"
vh.video_converter(video_file, output_video,
                   frame_rate=30, width=640, without_sound = True)

# The images will never be distorted:
# aspect ratios are kept even for arbitrary width and height thanks to black padding if necessary

# Extract frames from the video

start_instant=5 # seconds
# it corresponds to start_index = start_instant * frame_rate = 5 * 30 = 150th frame

end_instant=10 # seconds
# it corresponds to end_index = end_instant * frame_rate = 10 * 30 = 300th frame

frame_step=5 # take one frame every 5
# which corresponds to 1 frame every 5 / frame_rate = 5 / 30 = 0.17 second

# This means that in the video we take 1 frame every 5 from the 150th to the 300th

# List example
frames = list(
    vh.extract_frames(video_file, start_instant=start_instant, end_instant=end_instant, frame_step=frame_step)
)

# For loop example
for frame in vh.extract_frames(
    video_file,
    start_instant=start_instant,
    end_instant=end_instant,
    frame_step=frame_step):
    pass # Replace with your frame processing logic

# Each frame is a numpy array with shape (height, width, channels)
# with pixel values between 0 and 255.

Another example is about subtitles

Convert SRT subtitles to WebVTT with color preservation:

import video_helper as vh

srt_file = "subtitles.srt"
vtt_file = "subtitles.vtt"
css_file = "subtitles.css"

vh.srt2vtt(srt_file, vtt_file, css_file)

Multi-surface exposure

Every public function is reachable from five surfaces, all systematically wired (nothing is CLI-only or library-only):

The FastAPI app also serves a minimal browser GUI ("video bench") at GET /gui (and GET / redirects there): drop a clip, pick one operation, run it against the same HTTP endpoints, preview input vs output in an in-browser <video> / <img> player, and download the result. It is a single self-contained page (Tailwind via CDN + vanilla JS, no build step) defined in video_helper/gui.py.

pip install 'video-helper[api]'
uvicorn video_helper.api:app --port 8000
# open http://localhost:8000/gui  (or just http://localhost:8000/)

The Dockerfile at the repo root ships .[api,pyav] by default on python:3.11-slim with ffmpeg and libass: one docker build && docker run -p 8000:8000 gives you the HTTP + GUI surfaces immediately.

For the exhaustive catalogue of what triggers each operation (natural-language phrasings, commands, functions, file types), see TRIGGERS.md.

See GUI.md for the roadmap toward a richer GUI (Recipe Canvas, frame-first comparator, batch drop zone: the minimal /gui bench above is the first step).

API Reference

By default frames are BGR numpy.ndarray of shape (H, W, 3) with pixel values in [0, 255]. See EXAMPLES.md → Destination for the full shape × colorspace table including torch (CHW/NCHW/CTHW RGB) and PIL (RGB, size=(W, H)).

Author

• Warith HARCHAOUI

Acknowledgements

Special thanks to Mohamed Chelali and Bachir Zerroug for fruitful discussions.

License

This project is licensed under the BSD-3-Clause License: see the LICENSE file for details.