VGV — Vector Graphics Video

Experimental format and prototype implementation. Do not treat the current wire format or decoder as stable or hardened for untrusted input.

A resolution-independent 2D video format, player, and toolchain. Content is stored as bezier geometry plus a timeline instead of pixels; the player samples the timeline in continuous time and rasterizes at the output's native resolution every frame. The same file is pixel-perfect at 320x180 and 3840x2160, and keyframed motion is smooth at any refresh rate — there is no inherent frame rate ("infinite resolution", spatially and temporally).

Design lineage: Flash/SWF's shape-dictionary + display-list deltas, Lottie's keyframed properties, and classic video codecs' I/P-frame structure — combined into one small binary format built for movies, with an embedded audio track.

The approach in one minute

• A .vgv movie is a shape dictionary (bezier paths, solid/gradient fills, strokes) plus a timeline of display-list operations.
• Authored content uses keyframe tracks (translate/scale/rotate/ opacity/morph-weight with easing) — a 16 s cartoon fits in ~38 KB and interpolates natively to any Hz.
• Converted raster content uses SNAP snapshots (I-frames) — one full vector state per source frame. Proven up to 120 snapshots/s (assets/tempo120.vgv).
• Rendering is retained-mode: one engine paint per display-list slot; only changed paints are touched, and ThorVG's partial rendering rasterizes only damaged screen regions.
• Audio is an embedded Ogg Vorbis track; the video clock is master and audio resyncs to it (seek/pause/loop need no special cases).

Repository map

docs/WHITEPAPER.md    white paper: rationale, standards lineage, benefits
docs/FORMAT.md        wire format specification (start here)
docs/PLAYER.md        C core + desktop player internals, caveats
docs/WEB.md           WASM build, embeddable JS player API
docs/CONVERTER.md     sample converter + researched roadmap for the real one

include/vgv/vgv.h     public API: movie model, decode/encode, timeline VM
src/vgv_{buf,read,write,scene}.c   libvgv core (C11, zero dependencies)
src/vgv_render*.{h,c} renderer interface + ThorVG backend
src/player_main.c     vgv-play (SDL3 desktop shell)
src/player_audio.c    desktop audio (stb_vorbis + SDL3)
src/wasm_main.c       browser engine module (UI-free C API)
web/vgv-player.js     embeddable JS wrapper (transport + Web Audio)
web/index.html        reference web page; web/serve.py dev server
tools/vgv_gen.c       vgv-gen: procedural sample movies (demo/orbit/tempo)
tools/vgv_dump.c      vgv-dump: headless frame extractor / benchmark
tools/vgv_convert.py  sample mp4→vgv converter (ffmpeg + vtracer)
tools/vgv_attach_audio.py  retrofit an audio track onto a .vgv

Building (desktop)

Requires: gcc/clang, make, meson+ninja (for vendored ThorVG), SDL3, pkg-config. ffmpeg is needed only for make demo audio and the converter.

# one-time: vendored ThorVG (static, C API, partial rendering)
git clone --depth 1 --branch v1.0.6 https://github.com/thorvg/thorvg.git third_party/thorvg
cd third_party/thorvg
meson setup builddir --default-library=static -Dengines=cpu,gl \
    -Dpartial=true -Dloaders= -Dsavers= -Dbindings=capi -Dextra= \
    -Dsimd=true --prefix="$PWD/../install"
ninja -C builddir install
cd ../..

make            # bin/vgv-play, bin/vgv-gen, bin/vgv-dump
make demo       # assets/{demo,orbit,tempo120}.vgv (demo has audio)
./bin/vgv-play assets/demo.vgv

WASM build: see docs/WEB.md (make wasm, make serve).

Sample content

The small generated samples below are included in both assets/ and web/ so the native and browser demos work from a fresh clone. Converted third-party trailers are intentionally not distributed.

file	what it demonstrates
assets/demo.vgv (38 KB, audio)	full authored feature set: scene cut, easing, squash & stretch, morphing, PLAC/REMV lifecycle
assets/orbit.vgv (57 KB)	dense keyframe tracks (planets, moon, comets) — high-refresh smoothness test
assets/tempo120.vgv (1.2 MB)	120 snapshots/second physics — the "high-fps converted video" playback path
converted anime (via tools/vgv_convert.py)	real-world footage; see docs/CONVERTER.md for presets and sizes

Status

Working today: format v0 with audio, desktop player (SDL3, audio, seeking, looping, fullscreen), embeddable web player (WASM + Web Audio), headless tools, sample converter, sample movies. Measured: keyframed 1080p at ~1100 fps CPU-only; 4K at ~290 fps; 120 snap/s content at ~470 fps.

Known caveats and their current answers are documented per component in docs/PLAYER.md, docs/WEB.md, and docs/CONVERTER.md. The headline ones: heavy converted movies (10k+ paths/frame) are borderline realtime on the CPU rasterizer (GPU backend is the roadmap answer); files are loaded fully into memory (streaming via INDX is the roadmap answer); the advanced AI-assisted converter is a separate future project with a researched plan (docs/CONVERTER.md, "Next steps").

Licensing

No license has yet been granted for the original VGV project code or format documents. The repository is publicly viewable, but reuse requires permission from the copyright holder until a project license is added. Third-party terms are collected in THIRD_PARTY_NOTICES.md.