video-to-svga

Convert mov / mp4 video files into ZIP-based .svga animations from the command line.

This project is aimed at the practical workflow we validated locally:

• inspect the source with ffprobe
• export PNG sequence frames with ffmpeg
• optionally quantize to PNG8
• dedupe identical frames
• package everything as an SVGA 1.x archive
• validate the generated file structure

Why this exists

Most people doing this kind of conversion want a CLI they can run directly in scripts, build pipelines, or local terminal workflows. This package keeps that path simple and explicit.

Features

• direct mov / mp4 to .svga conversion
• optional PNG8 quantization with ffmpeg palette generation
• optional resize before packaging
• identical-frame dedupe to shrink image count
• built-in .svga validator
• no native Node dependencies

Install

npm install -g video-to-svga

Or run it without installing:

npx video-to-svga --help

Requirements

The CLI expects these tools to exist on your machine:

• ffmpeg
• ffprobe
• zip
• unzip for validate

Usage

Convert a video:

video-to-svga convert input.mov -o output.svga

Inspect source metadata without converting:

video-to-svga probe input.mov

Resize and quantize to PNG8:

video-to-svga convert input.mov -o output.svga --size 360 --png8

Override FPS:

video-to-svga convert input.mp4 -o output.svga --fps 20

Keep temporary PNG sequence files:

video-to-svga convert input.mov -o output.svga --png8 --keep-temp

Validate an existing .svga:

video-to-svga validate output.svga

Commands

convert

video-to-svga convert <input> [options]

Options:

• -o, --output <file>: output .svga path
• --fps <number>: override output fps
• --size <number>: scale to a square size like 360
• --width <number>: output width
• --height <number>: output height
• --png8: quantize frames to indexed PNG using an ffmpeg palette
• --no-dedupe: keep every frame as its own image
• --keep-temp: keep the generated temporary frame directory

validate

video-to-svga validate <file.svga>

Checks:

• ZIP-based SVGA 1.x container
• movie.spec existence and JSON validity
• image references
• sprite frame counts

probe

video-to-svga probe <input>

Prints a compact summary of:

• size
• fps
• frame count
• pixel format
• alpha presence

Notes

• This tool currently emits SVGA 1.x archives, not protobuf-based SVGA 2.0.
• For opaque H.264 videos, the generated .svga is often larger than the source .mp4.
• For transparent animations or short motion assets, using --size and --png8 usually helps a lot.

License

MIT