v2css is a lightweight Python-based Command-Line Interface (CLI) tool that converts standard video files (.mp4, .mov, .gif) into pure CSS/SVG keyframe animations. The resulting .svg files have zero JavaScript dependencies, making them completely compatible with environments like GitHub READMEs and standard Markdown.
- Temporal Motion-Diffing: Only pixels that change between frames are plotted, reducing SVG payload size significantly.
- K-Means Color Quantization: Groups and strips redundant pixel colors, producing a stylized pixel-art aesthetic while keeping DOM size ultra-lean.
- Decoupled Resolution: Renders frames internally at a very low resolution (e.g.
120pxmax) while allowing<svg>wrappers to scale to any requested display dimension viaimage-rendering: pixelated;. - Run-Length Encoding (RLE): Groups contiguous pixels horizontally into singular, efficient SVG
<path>vectors. - FFmpeg Preprocessing Built-in: Seamlessly normalizes input videos under the hood, bypassing complex OpenCV decoder failures on strange chroma sub-sampling layers.
- Python 3.10+
- FFmpeg installed and available on your system
PATH. (Used internally for preprocessing).
- Clone the repository:
git clone git@github.com:PandaBean18/v2css.git
cd v2css- Create a virtual environment and install dependencies:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtpython cli.py -i input_video.mp4 -o output.svg [OPTIONS]-i, --input(Required): Path to source video file (.mp4,.mov,.gif).-o, --output(Required): Output file path (e.g.,output.svg).--fps: Target frame rate for extraction (default:10). Keep this low (10-15) for smaller file sizes.--width: Target display width (default: auto based on height or original video).--height: Target display height (default: auto based on width or original video).--max-resolution: Maximum internal render resolution for either dimension to keep file size low (default:120).--palette-size: Max color count for palette quantization (default:16).--diff-threshold: Sensitivity threshold for pixel motion detection (default:15.0).
Render an animation to display at 400px height, using the default internal pixel-art resolution:
python cli.py -i my_video.mp4 -o preview.svg --height 400 --fps 12Instead of the standard animation-delay tactic (which breaks or fails to sync in strict image viewers), v2css hard-codes absolute CSS keyframe percentage timelines (0%, 5%, 100%) directly into <style> blocks. This guarantees a perfectly smooth, infinitely looping animation across all rendering backends.