vgif

Zero-dependency Discord-focused GIF toolkit using a custom Rust + WASM core.

Install

npm install vgif

Features

• No canvas dependency
• No external GIF encoder dependency
• Built-in ship animation pipeline (legacy-compatible)
• Advanced ship layout engine (fine X/Y/size/rotation/scale control)
• Built-in multi-theme + icon system for rich presets
• Preset market layer (romantic, anime, cyberpunk, minimal, luxury)
• Safe JSON preset import (preset, presetFile, presetJson)
• Scene-oriented v2 CLI workflow (render / validate)
• Async and sync APIs

Ship API

import {
  ship,
  shipSync,
  getShipThemes,
  getShipIcons,
  getShipPresets,
  getShipPreset,
} from "vgif";

const gif = await ship(leftUrlOrPathOrBuffer, rightUrlOrPathOrBuffer, {
  size: 256,
  fps: 20,
  durationMs: 3000,
  effects: ["zoom", "pulse", "blur"],
  theme: "classic",
});

const gifSync = shipSync(leftPngBuffer, rightPngBuffer, {
  score: 92,
  text: "92%",
});

const custom = await ship(leftUrlOrPathOrBuffer, rightUrlOrPathOrBuffer, {
  preset: "cyberpunk",
  right: { x: "78%", rotation: 11 },
  text: "99%",
  iconRing: "36%",
  accentColor: "#8bf2ff",
});

console.log(getShipThemes());
console.log(getShipIcons());
console.log(getShipPresets());
console.log(getShipPreset("romantic"));

ship(left, right, options?)

• Inputs: string | Uint8Array
• URL/path/Buffer supported
• Returns: Promise<Uint8Array>

shipSync(left, right, options?)

• Inputs: Uint8Array only
• Returns: Uint8Array

v2 Scene API (Builder Layer)

Scene builder helpers are exposed from vgif/scene:

const { createScene, createCanvas, validateScene } = require("vgif/scene");

const scene = createScene({
  width: 256,
  height: 256,
  fps: 20,
  durationMs: 3000,
  loop: 0,
  seed: 1337,
});

scene.addNode("rect", {
  id: 1,
  x: 128,
  y: 128,
  width: 120,
  height: 120,
  color: [255, 80, 120, 255],
});

const result = validateScene(scene.toJSON());
if (!result.ok) console.error(result.errors);

CLI

ship

vgif ship --left <url|path> --right <url|path> --out ./ship.gif

Advanced ship example:

vgif ship \
  --left ./left.png \
  --right ./right.png \
  --out ./ship-pro.gif \
  --preset cyberpunk \
  --center-icon bolt \
  --icons spark,ring,infinity \
  --left-x 24% --right-x 76% \
  --avatar-size 40% \
  --left-rotation -8 --right-rotation 9 \
  --heart-y 52% --heart-size 21% \
  --text-y 91% --text-width 74% \
  --background-color #15253f --accent-color #5ef2d2

List available presets:

vgif ship --list-themes
vgif ship --list-icons
vgif ship --list-presets

JSON preset import:

vgif ship \
  --left ./left.png \
  --right ./right.png \
  --preset-file ./presets/my-custom-ship.json \
  --out ./ship-custom.gif

validate (scene schema)

vgif validate --scene ./scene.json

render (scene to GIF)

vgif render --scene ./scene.json --out ./render.gif

If your installed build does not include the new render API yet, CLI returns ERR_RENDER_API_MISSING. Legacy ship still works.

Common options

• --size (default: 256)
• --fps (default: 20)
• --seconds (default: 3)
• --score (0..100)
• --text custom text
• --theme (classic|neon|warm|aurora|midnight|ocean|forest|candy|mono|ember)
• --preset (romantic|anime|cyberpunk|minimal|luxury)
• --preset-file local JSON file
• --preset-json inline JSON string
• --preset-max-bytes safety limit for preset import
• --effects (zoom,pulse,blur,shake)
• --loop (0 for infinite)
• --scene scene definition for render / validate
• --sync sync mode for render / validate
• --normalized-out write normalized scene JSON
• --json print validation object as JSON
• --left-x/--left-y/--right-x/--right-y for pixel or percentage positioning
• --avatar-size / --left-scale / --right-scale
• --left-rotation / --right-rotation (degrees or rad suffix)
• --heart-x / --heart-y / --heart-size
• --center-icon and --icons
• --icon-size / --icon-ring
• --text-x / --text-y / --text-width / --text-height
• --background-color / --accent-color / --text-color / --icon-color / --heart-color

Debug flags (render, validate, optional ship)

• --debug
• --debug-seed <number>
• --debug-overlay <list>
• --debug-trace <path>
• --debug-scene-dump <path>
• --debug-perf <path>
• --debug-snapshot-dir <path>
• --debug-snapshot-every <n>
• --debug-snapshot-format <ppm|rgba|json>

Input support

• Phase 1: PNG input
• Discord CDN avatar URLs are auto-forced to PNG in async API
• JPEG/WEBP decode is planned for phase 2