Gitframes: Code-first video, native gerenderd op WebGPU

Gitframes is ontwikkeld voor coding agents. Het bundelt functionaliteiten die normaalmente over drie verschillende desktopapplicaties zijn verdeeld (compositing en VFX op Photoshop-niveau, motion, typografie en keyframing in de stijl van After Effects, en 3D-scènes, camera's en modellen zoals in Blender) in één lichtgewicht npm-pakket. Een agent schrijft een TypeScript-compositie, controleert de frames en rendert een MP4, zonder dat er een gigantische creative suite geïnstalleerd of gelicentieerd hoeft te worden.

Het is code-first video als pure software engineering: geen headless browser, geen DOM-reflow en geen screenshot-pipeline. De rendering vindt direct plaats op de GPU-hardware via Dawn / WebGPU / Metal / Vulkan in Node.js en moderne WebGPU-browsers.

Waarom Gitframes?

Moderne geautomatiseerde videogeneratie wordt meestal beperkt door de architectuur van algemene webbrowsers: proces-overhead, niet-deterministische DOM-layout reflows en trage screenshot-captures. Gitframes benadert videocompositie als software engineering:

PijlerBetekenis
Geen Headless-Browser OverheadGeen Puppeteer, geen Chromium IPC, geen page.screenshot(). Gitframes communiceert direct met native GPU-apparaten via Dawn/WebGPU en codeert hardwarematig met @napi-rs/webcodecs.
Deterministische, Frame-nauwkeurige KlokAbsolute frame-klokken, discrete sample-punten en frame-nauwkeurige audio BeatGrids. Geen zwevende timers, geen drift en geen gedropte frames.
Analytische, Resolutie-onafhankelijke TypografieHet Slug-algoritme evalueert glyph-contouren per pixel in WGSL — geen texture atlases, geen schalingsartefacten; vlijmscherp van 10 px tot 10.000 px.
Tonaal & Spatiaal VFX op Photoshop-niveauMeer dan 50 modulaire GPU-shaders: Curves, Levels, Selective Color, 3D LUTs, Halftone, Film Grain, Unsharp Mask, Mesh Warp en Screen-Space Relighting.
Unified 3D & 2D Depth CompositingNest 2D flex/box-trees binnen 3D-homografievlakken, multiplane rigs en meshes (OBJ, FBX, glTF/GLB, STL, PLY, VOX, 3DS, OFF), met PBR-glas en SSAO.
Ingebouwde Procedurele Audio DSPMulti-track soundtracks, deterministische procedurele transitie-SFX (whoosh, impact, riser) en reactieve signalen die visuals aansturen vanuit audio.
On-Device Neural VisionObject-tracking, instance segmentation, multi-person pose en person mattes via Apache-2.0 ONNX-modellen, die reactieve signalen leveren zonder dat er data naar de schijf moet.
Cloud-Native & CI/CD ReadyVerbruikt circa 200–400 MB RAM per worker (tegenover 2–4 GB voor Chromium), ideaal voor serverless GPU-render clusters (AWS G4/G5, Modal, RunPod, Kubernetes).

Architecturale Vergelijking: Gitframes vs. Remotion vs. Hyperframes

Ontwikkelaars die programmatisch video genereren, maken vaak een keuze tussen Remotion (React/Chromium) of Hyperframes (Canvas2D/SVG web-animatie). Onderstaande matrix vergelijkt de fundamentele engineering-dimensies.

Mogelijkheid / DimensieGitframesRemotionHyperframes
Underlying EngineNative WebGPU (WGSL compute & render pipelines via Dawn / Metal / Vulkan)Chromium / Puppeteer (React DOM, HTML/CSS layout)Canvas2D / WebGL / SVG (browser of Node Skia)
Rendering ArchitectuurDirecte hardware framebuffer rendering & hardware video encoding (@napi-rs/webcodecs)Start headless Chrome; capturet frames via CDP / page.screenshot()Software of hardware 2D canvas context
Throughput60–120+ FPS (real-time tot sneller-dan-real-time GPU executie)5–20 FPS (DOM reflow, IPC, rasterization)20–40 FPS (CPU draw commands / JS)
Memory Footprint~200–400 MB per render (geen browser)1.5–4.0 GB+ per worker (Chromium + V8 DOM heap)~500 MB–1 GB (Skia/Canvas bindings)
Typografie EngineSlug GPU — analytische Bézier-evaluatie in WGSL, oneindige zoom, After Effects selectorsBrowser DOM text (CSS fonts, gerasterd, wazig bij 3D transforms)Canvas2D / path text (CPU-gerasterde glyphs)
2D VFX & Post-Processing50+ WebGPU shaders (Curves, Levels, Selective Color, 3D LUT, Film Grain, Halftone, Liquify, PBR Glass, Relight)CSS Filters of custom WebGL canvas wrappersBasis Canvas2D composites en 2D filters
3D Graphics & DepthNative 3D scene graph — LookAt/Turntable camera, multiplane, skinning (OBJ/FBX/glTF), SSAO, PCSS, DoFGeen ingebouwd (embed Three.js/Fiber binnen React DOM)Minimale 2.5D layers; geen unified mesh pipeline
Motion Blur & PhysicsFysieke 180° shutter velocity buffers in MRT + closed-form spring kinematicsCSS transitions / JS interpolatie; synthetische blur hacksFrame interpolatie of handmatige multipass
Audio Engine & DSPNative audio DSP & procedurele SFX (multi-track mixing, beat grids, reactieve signalen)<Audio> playback; basis volume curvesBasis statische audio playback
Charts & Data VizLayer.chart — line, area, bar, scatter, candlestick, pie en donut charts via native vector nodes, met staggered reveal animatiesDOM chart libraries (Recharts, Chart.js)Custom canvas draw operaties
AI & Computer VisionOn-device ONNX vision — COCO-80 detectie + instance masks (RTMDet-Ins), COCO-17 pose (RTMO), person mattes (Selfie Segmenter); WebGPU tensor conditioning (Canny, depth-to-normals, optical flow, deflicker)Externe pre-rendered assets; geen native GPU tensor conditioningExterne pre-rendered assets
Headless VerificatieFrameGrid contact sheets, single-frame snapshots, Skia MSE pixel-invariant assertionsPlaywright/Puppeteer visual snapshotsHandmatige frame inspectie / canvas diffing
Docker / Cloud PortabilityCompact (~500 MB slim image met native GPU/Vulkan drivers)Zwaar (~2–3 GB met Chromium, fonts, X11/Mesa)Gematigde container grootte

Belangrijkste Functies en Mogelijkheden

1. Slug GPU Vector Typografie & AE Parity

Traditionele tekst vertrouwt op CPU-rasterisatie of lage-resolutie SDF-atlases die wazig worden bij 3D-camerabewegingen. Gitframes integreert het Slug-algoritme (SlugPipeline):

  • Analytische GPU-evaluatie: WGSL-fragment shaders lossen exacte kubieke/kwadratische Béziers per pixel op. Glyphs blijven scherp bij zowel 10 px als 10.000 px zonder CPU-re-rasterisatie.
  • After Effects-parity animators: Range selectors (square, rampup, rampdown, triangle, smooth), easeHigh/easeLow curves, en seeded PRNG character shuffling (TextAnimator).
  • Menselijk typtempo: Gewogen punctuatie-vertragingen (komma's 3×, zinsuiteinden 5.5×, nieuwe regels 7×) en trailing scramble resolution (TypewriterAnimator).
  • 3D volumetrische formaties: Tekst mappen op cilindrische drums, logaritmische vortex spiralen en double-helix ribbons met surface-normal banking (evaluateVolumetricFormation).
  • Dynamische leading & skew: Area-preserving unimodular shear en accordion line-leading verankerd aan baseline, center, of top.

2. Photoshop-Grade WebGPU 2D VFX (50+ Shaders)

Een uitgebreide suite van professionele image/video shader-nodes:

  • Tonale grading: Curves (RGB/R/G/B spline), Levels (black/white point, gamma, output), Shadows/Highlights, Selective Color (CMYK gamut isolatie), 3D Cube LUT (ApplyLUT).
  • Stylisering & grain: Film Grain (Gaussian emulsion met spatial seed variatie), Halftone (mono/RGB/CMYK, instelbare dot shape & angle), Gradient Map, High Pass.
  • Optiek & lens: Bilateral Gaussian Blur, Unsharp Mask, Vignette, Refraction Caustics, PBR Glassmorphism met chromatische dispersie (PBRGlass).
  • Distortie & warping: Displacement Maps, Liquify, Mesh Warp, Corner Pin homografie.

3. Unified 3D Scene Graph, Camera & Mesh Shading

  • Gecalibreerde camera rig: LookAt en Turntable camera's (Camera3D) waarbij $z = 0$ exact overeenkomt met 2D canvas pixel-coördinaten (1:1).
  • 3D layout primitives: Layer3D.cube, carousel, prism, plane, grid met unified depth-buffer testing.
  • Zero-dependency model parsers: Ondersteuning voor OBJ, FBX, glTF/GLB, STL, PLY, VOX, 3DS, OFF.
  • Skeletal animation & shading: 128-bone Linear Blend Skinning, Blinn-Phong & PBR multi-light shading, PCSS/Poisson contact shadows, SSAO, en optische DoF.
  • Fysieke motion blur: 180° shutter motion blur met per-vertex velocity vectors verpakt in rg16float MRT buffers.

4. Audio-lagen, Procedurele SFX & Reactieve Signalen

  • Soundtrack lagen: .audio media-nodes met frame-exacte lifecycle control.
  • Procedurele SFX: Deterministische CPU-gesynthetiseerde whooshes, impacts, risers, downshifters en glitches geplaatst op het bar/beat grid (renderSfx, mixSfxInto, softLimit).
  • Multi-track mixing: Headless master tracks via mixAudioTracks en encodeStereoWav.
  • Reactieve signalen: Stuur transforms, scale, borders of shader uniforms aan via tempo-signalen (Signal.builder) of audio-analyse.

5. Geanimeerde Grafieken

Layer.chart bouwt line, area, bar (grouped of stacked), scatter, candlestick, pie en donut charts. D3 berekent de schalen, ticks en geometrie; elk element is een reguliere box, path of text node:

  • Labels gebruiken de geregistreerde fonts van de compositie en dezelfde GPU text renderer als de rest van de film.
  • Een ingebouwde 'reveal' tekent lijnen, laat bars groeien vanuit de baseline en staggers points en slices (animate: { start, duration, stagger, ease }).
  • De grafiek is één box, waardoor deze gepositioneerd, geanimeerd, gegraded en gekanteld kan worden in 3D.

Voorbeeld:

Layer.chart(
  {
    type: "bar",
    width: 900,
    height: 480,
    categories: ["Q1", "Q2", "Q3", "Q4"],
    series: [
      { name: "Revenue", data: [12, 19, 24, 31] },
      { name: "Costs", data: [8, 11, 13, 15] },
    ],
    yAxis: { format: "$,.0f" },
    animate: { start: 10, duration: 30 },
  },
  { position: "absolute", x: 120, y: 200 },
);

6. On-Device Vision & Tracking

@gitframes/vision draait ONNX-modellen via onnxruntime-node (CPU) of onnxruntime-web (WebGPU).

Belangrijk: De engine is lazy by construction. Modellen worden pas gedownload bij het eerste gebruik. Gebruik await runner.preload(["detect", "pose"]) om modellen vooraf te laden.

Taken en modellen (Apache-2.0)

TaakOptieModelOutput
DetectenableDetectionRTMDet-Ins t/s/mCOCO-80 boxes + scores, getrackt over tijd
SegmentenableSegmentationRTMDet-InsSoft per-instance masks, frame-aligned
PoseenablePoseRTMO t/s/m17 COCO keypoints + visibility per person
MatteenableMatteMediaPipe Selfie SegmenterSnelle person-vs-background alpha

Technische details:

  • Snelheid: Op CPU duurt een 2K frame ongeveer 200–340 ms voor detectie + segmentatie, ~120 ms voor pose en ~20 ms voor de matte (variant "s").
  • Efficiëntie: Detectie en segmentatie delen één enkele RTMDet-Ins inference per frame.
  • Consistentie: De TemporalObjectTracker wijst stabiele trackIds toe via IoU-associatie met configureerbare smoothing.
  • Vertraging: Vision leest het vorige gerenderde frame, waardoor resultaten één frame achterlopen op het beeld.

Reactieve Vision Signalen

Elke getrackte entiteit is beschikbaar als ProgrammaticSignals:

  • Objects: bounds (x/y/w/h), anchors (9 punten), kinematics (snelheid, acceleratie, heading).
  • Pose: Alle 17 COCO keypoints, wristSpeed, handRaised, bodyTiltAngle.
  • Masks: Area, coverage, solidity, bboxFill.

Ruimtelijke Pinning & Hulpfuncties

  • Pinning: Bind nodes aan tracks of landmarks via pinToObject of pinToLandmark.
  • Subject Sandwich: Snij het voorgrondsubject uit en plaats typografie/graphics erachter.
  • Smart Reframing: Automatische crop van 16:9 naar 9:16 terwijl het target gevolgd wordt.
  • Subject Outline: Teken een audio-reactieve contour-glow rond het gesegmenteerde subject.

7. Headless Conformance & FrameGrid Testing

  • Pixel-sampling invariant assertions: Test composities in Vitest met skia-canvas om shader-berekeningen en Mean Squared Error (MSE) temporal deltas te verifiëren.
  • FrameGrid contact sheets: Genereer contact-sheets van sequentiële frames voor snelle review van easing en transities.

8. Live Preview in de Browser

Start een localhost WebGPU-player die de compositie live rendert in de browser (startPreview). Er wordt niets gestreamd; de server verstuurt enkel de bundle, assets en de soundtrack.

  • Bevat een tijdlijn, waveform en frame-stepping.
  • Gebruikt één stabiele URL per project (afgeleid van de werkmap).
  • Kan direct in het paneel van een agent (zoals Claude Code of Codex) worden getoond.

Monorepo Architectuur

Beheerd met pnpm workspaces en turbo:

  • packages/:
  • gitframes/: Unified SDK (Composition, Layer, Signal, etc.).
  • core/: Core AST, Effect base class, vision types.
  • compositions/: Layout engine, timeline evaluator.
  • webgpu-renderers/: WGSL shaders, Slug text engine, 3D renderer.
  • tensor-webgpu/: WebGPU compute pipelines (Canny, flow, etc.).
  • vision/: ONNX vision engine.
  • renderer/: Headless Node.js WebGPU renderer.
  • media/: Media decoding/encoding adapters.
  • nodes/: 58+ gespecialiseerde domein-nodes.
  • apps/renderer-service/: Productie HTTP/gRPC rendering microservice.
  • examples/: Referentie-composities.
  • plugins/gitframes/: Agent-plugin met skills.

Snelstartgids

Installatie

pnpm add gitframes

Vereiste: Node.js ≥ 22. Gebruikt native GPU-acceleratie via Dawn / WebGPU of Vulkan.

1. Basis Compositie & Kinetic Auto-Layout

import { Composition, Layer, LayerAnimation } from "gitframes";

const comp = new Composition({
  width: 1920,
  height: 1080,
  fps: 60,
  durationFrames: 180,
  backgroundColor: "#090a0f",
  fonts: ["assets/fonts/Inter.ttf", "assets/fonts/SpaceGrotesk.ttf"],
});

const cardEntrance = LayerAnimation.create()
  .fadeIn(0, 20, "power2.out")
  .fromTo("y", 60, 0, { start: 0, end: 35, ease: "back.out(1.5)" })
  .fromTo("scale", 0.92, 1.0, { start: 0, end: 35, ease: "back.out(1.2)" });

const heroCard = Layer.box({
  width: 720,
  height: 380,
  background: "#141721",
  borderRadius: 24,
  borderColor: "#262b3d",
  borderWidth: 1.5,
  padding: 32,
  children: [
    Layer.flex({
      dir: "column",
      gap: 16,
      children: [
        Layer.text("GITFRAMES ENGINE", { fontSize: 16, fontWeight: 700, fill: "#6366f1", letterSpacing: 2.0 }),
        Layer.text("Next-Gen WebGPU Motion", { fontSize: 48, fontWeight: 700, fill: "#f8fafc", fontFamily: "SpaceGrotesk" }),
        Layer.text("Direct hardware video composition without headless browser overhead.", { fontSize: 20, fill: "#94a3b8", lineHeight: 28 }),
      ],
    }),
  ],
}).animate(cardEntrance);

comp.add(heroCard);

2. Unified 3D Scene met Camera & 3D Model

import { Composition, Layer, Layer3D, CameraAnimation, Light } from "gitframes";

const comp = new Composition({ width: 1920, height: 1080, fps: 60, durationFrames: 300 });

const cameraAnim = CameraAnimation.camera().orbit({
  azimuth: { from: -30, to: 30 },
  elevation: { from: 15, to: 15 },
  radius: { to: 1200 },
  start: 0,
  end: 300,
});

comp.add(Layer.camera({ x: 960, y: 540, z: -1000, targetX: 960, targetY: 540, targetZ: 0 }).animate(cameraAnim));
comp.add(Light.ambient("#ffffff", 0.4));
comp.add(Light.directional({ color: "#e0e7ff", intensity: 1.2, x: 500, y: -800, z: -600 }));
comp.add(Layer.glb("assets/models/character.glb", { x: 960, y: 640, z: 0, scale: 2.5, material: "lit", loop: true }));
comp.add(Layer3D.carousel({
  radius: 400,
  items: [
    Layer.box({ width: 280, height: 180, background: "#1e293b", borderRadius: 16 }),
    Layer.box({ width: 280, height: 180, background: "#334155", borderRadius: 16 }),
    Layer.box({ width: 280, height: 180, background: "#0f172a", borderRadius: 16 }),
  ],
}));

3. Audio Soundtrack, Procedurele SFX & Reactieve Signalen

import { Composition, Layer, LayerAnimation, Signal, renderSfx, mixSfxInto, softLimit } from "gitframes";

const comp = new Composition({ width: 1920, height: 1080, fps: 60 });
const totalFrames = 240;

comp.addAudio(Layer.audio("assets/score.mp3", { volume: 0.9, durationFrames: totalFrames }));

const bed: [Float32Array, Float32Array] = [
  new Float32Array(Math.ceil((totalFrames / 60) * 48000)),
  new Float32Array(Math.ceil((totalFrames / 60) * 48000)),
];

mixSfxInto(bed, [
  renderSfx({ type: "whoosh", atBar: 0.79, volume: 0.5 }, { sampleRate: 48000, secondsPerBar: 2.0, seed: 1 }),
  renderSfx({ type: "impact", atBar: 1.0, volume: 0.8 }, { sampleRate: 48000, secondsPerBar: 2.0, seed: 2 }),
]);
softLimit(bed);

const beatPulse = Signal.builder({ type: "sawtooth", frequency: 2, amplitude: 0.08, offset: 1.0 });

const reactiveCard = Layer.box({ width: 400, height: 250, background: "#1c202e", borderRadius: 20 })
  .animate(
    LayerAnimation.create()
      .signal("scale", beatPulse, { multiplier: 1.0, offset: 0.0 })
      .fromTo("opacity", 0, 1, { start: 0, end: 15, ease: "power2.out" }),
  );
comp.add(reactiveCard);

4. Geketende WebGPU Post-Processing VFX

import { Composition, FilmGrain, Vignette, ColorBalance } from "gitframes";

const comp = new Composition({ width: 1920, height: 1080, fps: 60 });

comp.apply(new Vignette({ strength: 0.28, radius: 0.85 }));
comp.apply(new FilmGrain({ strength: 0.06, size: 1.5, animated: true }));
comp.apply(new ColorBalance({
  shadows: { cyanRed: 0, magentaGreen: 2, yellowBlue: 6 },
  highlights: { cyanRed: 4, magentaGreen: 1, yellowBlue: -2 },
}));

5. Vision: Pin, Matte & Reframe

import { Composition, Layer, Vignette } from "gitframes";

const comp = new Composition({ width: 1920, height: 1080, fps: 30 });

const vision = comp.withVision({
  enableDetection: true,
  enableSegmentation: true,
  enablePose: true,
  variant: "s",
  confidence: 0.35,
});

comp.add(
  Layer.text("SUBJECT 01", { fontSize: 40, fill: "#f8fafc" }).pinToObject(
    vision.objects.primary,
    { anchor: "topCenter", offsetY: -48, smoothFrames: 5, hideWhenLost: true },
  ),
);

comp.add(
  Layer.box({ width: 1920, height: 1080, background: "#000000" }).withEffect(
    new Vignette({ strength: vision.segmentation.subject.coverage, radius: 0.9 }),
  ),
);

6. Headless Video & FrameGrid Rendering

import { buildMyComposition } from "./my-composition.js";

const comp = await buildMyComposition();

// 1. Single frame naar PNG buffer
const frameBuffer = await comp.renderFrame({ frame: 45 });

// 2. Contact-sheet grid van 12 sequentiële frames
const gridBuffer = await comp.renderFrameGrid({
  startFrame: 0,
  endFrame: 120,
  stepFrames: 10,
  cellWidth: 320,
  showLabels: true,
});

// 3. Hardware-encoded MP4 met mixed audio
const { filePath } = await comp.renderVideo({
  outputPath: "output/final-product-film.mp4",
  quality: "high",
  concurrency: 4,
});

Engineering-principes en Best Practices

  • Design tokens & theme contracts: Definieer een gecentraliseerde THEME voor kleuren, typografie, radii en spacing. Hardcode geen hex-waarden of ad-hoc marges.
  • WebGPU premultiplied-alpha invariant: Fragment shaders die premultiplied alpha outputten (color opacity alpha) moeten srcFactor: "one" gebruiken in hun blend state. Gebruik nooit srcFactor: "src-alpha" voor premultiplied output, omdat dit fades donkerder maakt.
  • Carrier match cuts: Neem een visueel element (badge, card, cursor) mee over scène-grenzen met continue snelheid en positie om schokkerige cuts te voorkomen.
  • Fysieke easing vocabulaire: back.out(1.4–1.7) voor snap-overshoot entrances, spring / expo.out voor decelererende beweging, power2.in voor exits. Reserveer linear voor oneindige spinners en tijdstempels.
  • Headless invariant verificatie: Verifieer shader transforms en glyph coverage met skia-canvas pixel sampling in Vitest voordat er wordt gepubliceerd.

Agent Skills & Plugins

Gitframes levert skills die coding agents (zoals Claude en Codex) leren hoe ze composities moeten schrijven, renderen en controleren.

SkillGebruik voor
gitframesProject start: installatie, scaffolding van compositie en render script
gitframes-composeComposities, layer trees, layout, animatie, easing, beat grids
gitframes-effectsEffect classes, unified section architecture, vision conditioning
gitframes-renderHeadless rendering, FrameGrid inspectie, MP4 delivery checks

Installatie voor Agents

Claude Code:

/plugin install gitframes

Of via de shell: claude plugin install gitframes@claude-plugins-official.

Overige agents (Codex, Cursor, Hermes, Gemini CLI, Copilot, etc.):

npx skills add gatewai-dev/gitframes

Referentievoorbeelden

De examples/ directory bevat productiewaardige composities:

  • 19gitframesfilm: De 30-seconden master brand film (volledige pipeline).
  • 21fullcircle: Multi-scène narratieve compositie.
  • 22gitframeslaunch: Launch/product-motion compositie.

Ontwikkeling & Build

Gitframes gebruikt pnpm (10+) en turbo voor orchestratie.

# Installatie
pnpm install

# Alle packages builden
pnpm build

# Conformance tests draaien
pnpm test

# Vision modellen end-to-end checken
pnpm --filter @gitframes/vision test:models

Docker Container voor Productie

Er is een geoptimaliseerde Dockerfile.renderer beschikbaar voor deployment in cloud GPU-clusters:

docker build -t gitframes-renderer -f Dockerfile.renderer .

Community & Licentie

  • Discord: Vragen stellen en renders delen op discord.gg/cbqMGGme5.
  • YouTube: Films gemaakt met gitframes bekijken op @gatewai.studio.
  • Licentie: Gitframes is open-source software onder de Apache-2.0 licentie. De vision-modellen (RTMDet-Ins, RTMO, Selfie Segmenter) zijn eveneens Apache-2.0.