onimite
Make videos with code: Lua scripts rendered to MP4, previewed and checked by a coding agent.
Dokumentation
onimite
Make videos with code. A video is a Lua script: scenes, shapes, text, images, SVG and Lottie, clips, shaders, music, sound effects and spoken lines. One small native binary renders it to MP4, plays it in a live preview that reloads on save, and checks it for you: frames, contact sheets, problems found automatically, loudness and beats. It is built so that a coding agent can make a video end to end and know it is right without watching it.
Install it (what the installer does is under Releases):
curl -fsSL https://defnotmid.com/install.sh | sh # macOS (Apple Silicon), Linux (x86_64)
irm https://defnotmid.com/install.ps1 | iex # Windows (PowerShell)
Then, in a clone of this repository:
onimite render examples/why_onimite/video.lua -o why_onimite.mp4
onimite preview examples/why_onimite/video.lua # plays with sound, reloads on save
onimite inspect examples/why_onimite/video.lua # what is wrong, by script line
- Small. One binary and the SDL3 library beside it (and Lua's DLL on
Windows); BENCHMARK.md gives each archive's size as
downloaded and unpacked. Nothing else to install, no build step per
video. (
say()'s voice models are an optional 835-866 MB download, made on first use.) - Fast. Frames are built on every core and drawn on the GPU (Vulkan, Metal), with hardware encoding when there is one. BENCHMARK.md races it against every fframes example ported 1:1 on each release: wall time, CPU time and memory, fframes' wins included.
- Checkable.
inspect,show,frame,strip,onion,motion,audio analyzeand--jsonon every command answer "is it right?" without a human watching; an MCP server and an agent skill come with it.
When to use something else
onimite is one opinionated program, not a library. If you want to write a video in Rust and compile it into your own program, with the whole language and its crates at hand, use fframes (onimite began by porting its examples and keeps parity with them). If you want React and the web platform (HTML, CSS, npm), use Remotion. For a TypeScript animation library with an editor, use Motion Canvas. What fframes and Remotion put on disk before the first frame, measured on Linux, is in BENCHMARK.md.
onimite is built from sibling Odin projects and Odin's vendor packages:
| piece | what |
|---|---|
ovg | 2D vector canvas (femtovg lineage): software backend + SDL_GPU (Vulkan / Metal / D3D12) |
oglyph | fonts and OpenType text shaping in native Odin (HarfBuzz's rules, checked against it), which ovg draws text through |
oicut | H.264 / H.265 / AAC codecs (native Odin, Vulkan Video when available), MP4, clip decoding; every image (PNG, JPEG, GIF, WebP, ...) and audio file (WAV, FLAC, MP3, Ogg, M4A) |
oksl | shader compiler for SkSL, Shadertoy and GLSL: SPIR-V, MSL and a CPU program (machine code through its AVX2 JIT on x86-64 Linux and macOS, an interpreter elsewhere); ovg and o3d write their own shaders in it too |
ottis | text to speech with word timings (Kyutai's Pocket TTS through ONNX Runtime, loaded at run time; models downloaded on first use) |
odawg | sound in Tone.js's vocabulary: songs composed from data (song{}, sound{}), the mix, master and preview stream, loudness, onsets and spectra; sample sets downloaded on first use |
o3d | 3D in three.js's vocabulary: an SDL_GPU renderer and a software one drawing the same pixels, glTF 2.0 (skins, morph targets, animations), 3MF and OBJ import |
vendor:lua/5.4 | the script runtime |
vendor:sdl3 | GPU device and the preview window |
Features
- Scripts:
video{}andscene{}with overlaps and transitions, a node tree (shapes, paths, text, images, groups), keyframes with easings and springs, and a standard library after Remotion (sequence,series,loop,freeze,stagger, transitions, a beat clock). Data comes in aspropsfrom--props,--setor one--batchrow per video;json_decodereads JSON files. - Drawing (ovg): gradients, patterns, dashes, clip paths, masks, the 16 blend modes and every SVG 1.1 filter primitive (feTurbulence on the GPU, fractional morphology radii), with filter regions. Text is shaped (ligatures, kerning, Arabic, Indic, bidi) and drawn as outlines, with per-glyph fallback and bundled colour emoji.
- Media: fonts, png / jpeg / bmp / gif / tga / webp images (decoded on
first use, kept within
--image-cache MB), SVG documents and Lottie animations with per-id / per-layer overrides, video clips (.mp4, .mov, .webm, ProRes 4444 and VP9 alpha), subtitles and word-level captions (Whisper JSON, VTT, SRT; TikTok-stylecaptions{}), audio spectra, glTF 3MF and OBJ models (.glb, .gltf, .3mf, .obj). - Shaders (oksl): SkSL as in fframes, Shadertoy code and GLSL ES
fragment shaders (a real preprocessor,
texture,switch,discard), and multipass programs mixing them (passes: feedback, any pass's last frame; Shadertoy's Common + Buffer A-D + Image is one spelling). Images, clips and groups of nodes bind as inputs. The software backend runs the same shaders as oksl CPU programs. - 3D (o3d):
view3d{}draws a scene described in three.js's terms (perspective cameras with a physical lens, f-stop and focus on a point, and orthographic ones; ambient, hemisphere, point, directional and spot lights with up to 4 PCF shadow maps fitted to the view; a frame drawn in linear light, tone mapping and fog; box, sphere, plane, cylinder, torus, rounded box, circle, ring and lathe meshes plus per-frame 3D lines, point clouds, wireframe andinstances; 2D drawn onto surfaces every frame (panels) or once (bake{}, a studio light too); a mirror plane for reflective floors; MeshStandardMaterial, MeshPhysicalMaterial (clear coat, sheen, glass), MeshBasicMaterial, MeshToonMaterial with cartoon outlines, LineBasicMaterial and PointsMaterial with texture maps, and GLSL ES ShaderMaterial; an equirectangular environment and background; glTF 2.0, 3MF and OBJ models, including skinned characters, morph targets and punctual lights, posed at a time of their animations with optionalmorphsandmaterialoverrides) into a box composited like any layer, on the GPU or, the same picture, on the CPU. - Motion blur:
motion_blur = { shutter = 180 }opens a camera's shutter on every frame, or in the seconds of itsduringor a scene's own: what moves streaks along its motion, 2D draws and 3D views alike (meshes, models, particles, the camera), on the GPU and the CPU, in renders and the preview;onimite motionshows the speeds. - Physics: rigid bodies simulated once at load and sampled per frame,
in 2D (
physics{}, Box2D) and 3D forview3d{}(physics3d{}, Box3D): shapes, joints, kicks, kinematic movers, and impacts as times for sounds. - Sound: tracks on the video or scenes with gain, pan, fades, voice
ducking and a master limiter, mixed and streamed by odawg (the preview
plays the render's samples); music composed from data with
song{}(sections with tempo, style, energy and chords; its sections are cues and its notes answer the picture:score.time("drop@1m"),score.pulse(f, { part = "drums", note = "kick" })) and one-shots withsound{}; audio synthesized by the script (audio_add); onsets and the beat of any clip (audio_onsets); AAC in the MP4. - Voice:
say(name, text)speaks a line (ottis: Pocket TTS by Kyutai, CC-BY-4.0) with the time of every word, and its captions;say_cueputs animation keys and sound effects on spoken words, andinspectchecks them against the voice. A voice can be cloned from a recording inmedia/(voice = "me.wav"). Lines are kept on disk by content, so only new or changed lines are synthesized, where the script loads. ottis runs it on Linux, macOS and Windows in its CI; onimite's Windows build has it, untested. - Cues:
cue(name, t)names a moment andcue = "name"on scenes, tracks and animate keys lands them on it;inspectreports what drifts off, and cues work as times. - Output: H.264 / H.265 MP4 through the system's codecs (VideoToolbox on
macOS, in hardware or Apple's software codecs; Vulkan Video on Linux and
Windows; Media Foundation on Windows: H.264, and H.265 with Microsoft's HEVC
Video Extensions; else the system's FFmpeg, libavcodec, loaded at run time
and never bundled), AV1 MP4 through oicut's own encoder in every build
(
--codec av1: royalty-free, needs no codec on the machine; at the same quality, from a little smaller than H.264 to larger on sharp motion graphics), or PNG frames. Releases carry no H.264 / H.265 codec of their own: oicut's native one is only in a build with-define:OICUT_PATENTED=true. With none of those on the machine,renderto an MP4 says so and names--codec av1and PNG frames. Frames build on all cores and draw on the GPU (or on the CPU with--software); the output does not depend on the thread count. - Checking without watching: PNG frames, contact sheets, onion skins,
frames as SVG, snapshot tests,
inspect(missing media and fonts, clipped or overlapping text, NaN, script errors, unused options, sync drift), undefined globals as errors, loudness analysis, onsets, and stable error codes in--jsonoutput. - Preview: a window with sound, scrubbing, a timeline with thumbnails and waveforms, hot reload of the script, its modules, shaders, data and media.
The full script API is skills/onimite-video/references/api.md; skills/onimite-video is a skill for coding agents that make videos with onimite.
Use it with an AI agent
The onimite-video skill (skills/onimite-video) teaches a coding agent to write, check
and render onimite videos. No terminal tools are needed; use whichever fits your agent:
- Claude Code (terminal, desktop app or IDE): type
/plugin marketplace add defnotmid/onimite, then/plugin install onimite@defnotmid. - Codex: ask it
$skill-installer install https://github.com/defnotmid/onimite/tree/main/skills/onimite-video. - Any other agent that can run commands: paste this into it: "Install the agent skill at https://github.com/defnotmid/onimite/tree/main/skills/onimite-video (the folder holds SKILL.md and a references/ folder) into your skills directory, then install the onimite binary as the skill describes."
The skill downloads the onimite release binary itself (see Releases).
onimite mcp also serves the commands as MCP tools (JSON-RPC over stdio): typed arguments,
frames returned as images, no shell quoting, and a guide tool that returns this skill, built
into the binary. The Claude Code plugin registers it; for other MCP clients the server is the
command onimite with the argument mcp (the binary on PATH; --dir PATH sets the folder
relative paths start in).
Claude Desktop: download
onimite-macos-arm64.mcpb
or onimite-windows-x86_64.mcpb
and open it: Desktop installs the extension with its own copy of onimite and asks for a work
folder (default Documents/onimite). Claude writes the video files there with a filesystem
extension (Desktop's Filesystem extension, given the same folder). When a newer release is
out, Claude says so; ask it to update (the update tool), then quit and reopen Desktop.
The extension's "Check for updates" setting turns the check off.
Releases
The install command at the top of this page fetches the latest release: it
checks the archive against SHA256SUMS and puts an onimite launcher in
~/.local/bin (on Windows its folder on the user PATH). Run it again to
update; ONIMITE_VERSION=vX.Y.Z pins a release.
onimite --version prints the release it is. onimite update replaces it with
the latest release: it reads that release's SHA256SUMS, downloads this
platform's archive, checks it, runs the new binary once, then swaps it in (an
installer's current link moves to the new version's directory; anywhere else,
a Desktop extension or an unpacked archive, the files are replaced in place).
onimite update --check only says whether a newer release is out. onimite mcp
does that check once as it starts (off with --update-check false or
ONIMITE_NO_UPDATE_CHECK=1).
Push a tag vX.Y.Z (git tag v0.1.0 && git push origin v0.1.0; a tag with
a -, like v0.2.0-rc1, makes a prerelease, which the installers skip).
.github/workflows/release.yml builds -o:speed stripped binaries against
ovg, ocurves, oglyph, oksl, oicut, ottis, o3d and odawg at their pinned tags,
with the tag as their --version, and publishes a GitHub release:
| asset | |
|---|---|
onimite-vX.Y.Z-linux-x86_64.tar.gz | built on Ubuntu 22.04 (needs glibc 2.34+: its newest symbol) for x86-64-v3 (a CPU with AVX2: Intel Haswell, AMD Excavator or later), libSDL3.so.0 beside the binary (rpath $ORIGIN); needs the system libcurl (libcurl.so.4) |
onimite-vX.Y.Z-macos-arm64.tar.gz | macOS 11+, libSDL3.0.dylib beside the binary (rpath @executable_path) |
onimite-vX.Y.Z-windows-x86_64.zip | best effort (unsigned, tested only in CI), left out if the Windows build fails; for x86-64-v3 (AVX2) like the Linux build; SDL3.dll and lua54.dll beside the binary |
onimite-video-skill-vX.Y.Z.tar.gz | the agent skill as of the tag (onimite-video/ with SKILL.md, references/ and LICENSE), matching the binaries |
SHA256SUMS | checksums of the archives |
Each archive holds LICENSE, LICENSES/ and THIRD_PARTY_NOTICES.md too.
On macOS the binary and the SDL3 dylib are signed with the Developer ID
Application certificate (hardened runtime, secure timestamp) and notarized
by Apple; a bare binary can't be stapled, so Gatekeeper checks the
notarization online on first launch. The Linux and Windows builds are not
signed. The Apple secrets live in the release GitHub environment.
Commands
The commands of fframes' project CLI, with its outputs (text, or one JSON
document with --json) and exit codes (1 on failure, 2 for inspect and
snapshot failures and usage errors). onimite --help lists every option.
onimite render video.lua [range] -o out.mp4 [--draft] # the video (+ AAC mix, a chapter per scene), or PNGs into a directory
onimite video.lua # the same: render is the default
onimite render video.lua --batch rows.json -o out/{name}.mp4 # one video per row (or rows.csv)
onimite frame video.lua Intro@1s,50%,end -o frames [--svg] # PNGs of single frames, with their problems (-o shot.png: one)
onimite strip video.lua [range] -n 12 --columns 4 --width 480 -o strip.png
onimite onion video.lua Intro@0..Intro@1s -n 6 -o onion.png # frames blended, later ones stronger
onimite motion video.lua Intro@0.4s,2s # how fast each thing moves, px a frame, and the line that drew it
onimite snapshot video.lua 1s,Intro@end [--update] [--dir _frame_snapshots]
onimite timeline video.lua [range] # scenes (cue, source line), audio tracks, cues, songs
onimite mcp # every command as MCP tools on stdio (preview opens the window)
onimite show video.lua [path] [--at t] [--page n] # one thing, its fields and children: scene/Race, cue/drop,
# bus/sfx, track/12, clip/x, media/logo.png, fonts,
# bodies, body/ball, node/scenes/race.lua:19[2]
onimite inspect video.lua [range] [--every 0.25s] [--all-frames] [--info] [--fail-on error|warning|never]
onimite probe file.mp4 [--json] # container, video and audio streams of a media file (no ffprobe needed)
onimite audio render video.lua [range] -o audio.wav [--float]
onimite audio analyze video.lua [range] [--waveform w.png] # LUFS, LRA, true peak, clipping, silence, per scene
onimite audio at video.lua 3.1s,6.2s # what plays: file position, level, ducking, a song's notes
onimite audio onsets video.lua [range] [--min 0.1] # where sounds start, and the beat
# (audio commands: --track FILE hears one track, --track score/bass a song's part)
onimite preview video.lua [at] [--paused] [--no-loop] [--mute] [--bare] [--fullscreen] [--present] [--live]
# --bare: the video alone, played once, then the window closes
# --present: a presentation, waiting at each scene's end for a click
# --live: a board on a screen, for good, on the system clock
onimite update [--check] # replace this release with the latest (--check: only say)
render:--draftis half resolution (unless--scale), QP 32 and a one second GOP;--codec h264|h265|av1,--qp N(default 23, the same scale for every codec); in a build with-define:OICUT_PATENTED=true(not the releases, which refuse them),--native(oicut's native encoder instead of the system's) and--slices N(its H.264 slices, default 4: more encode faster in a slightly larger file; the file depends on it, never on the machine).- Common options:
--json,--scale S,--media DIR(defaultmedia/beside the script),--props FILE,--set K=V,--now TIME(the wall clock at the first frame,f.now:2026-11-02T14:05:00Z; default 0),--software(draw on the CPU),--threads N(default one per core;1runs everything on one thread with the same output),--image-cache MB(decoded images kept in memory, default 1024; the least recently used are freed between frames and decode again when shown). - Times and ranges read like fframes:
120,3.2s,1:05,50%,start,end,Intro,#2,Intro[1](the second scene named Intro),Intro@1.5s,Intro@end(an offset must land inside its scene), cues and sync ids like scenes (drop,drop@0.5s,drop@-6),a..b(end exclusive,drop..beat[8]),a..,..b,all. --batch rows.json|rows.csvrenders one video per row, the row asprops(--setover the row over--props).-otakes{field}and{index};--rows 2..3/--only 2pick rows. A failing row is reported and the batch goes on (exit 1 if any failed). Seeexamples/batch/.frame --svgalso writes each frame's node tree as SVG next to its PNG (onimite/svg_export.odin).snapshot: missing snapshots are created; a frame whose pixels differ by more than--threshold(16) in more than--max-diff(0.1%) of pixels fails withname.actual.pngandname.diff.png;--update(orONIMITE_UPDATE_SNAPSHOTS=1,FFRAMES_UPDATE_SNAPSHOTS=1) accepts it. A snapshot of another size than the frame (checked at another--scale) is an error naming both sizes (snapshot_size).- With
--json, every diagnostic and finding has a stablecodeand thefieldsits message is made from, and a failed command prints{"error": ..., "code": ...}. The codes are listed in problems.md.
render builds several frames at once: each builder loads the script into
its own Lua state (render procs must be pure per frame, as in fframes) and
records its frames, and one thread draws them on the GPU in frame order,
converts them to I420 there and hands them to the encoder thread. The set
of builders grows only while drawing waits for frames. --software takes
the same path: the builders record, and one software backend draws each
frame in row bands on the pool, so drawing's working set (layer images,
scratch) exists once at any thread count (the whole otfx video at 24
threads peaks at 266 MB, 4.8 GB before). tools/threads_check.sh compares
decoded frames of the pool and --threads 1.
Scripts
video { width = 1920, height = 1080, fps = 30, background = "#ffffff" }
scene { "Intro", duration = 2, render = function(f)
local y = animate(f, { { start = 0, stop = 0.4, from = 60, to = 0, easing = ease_out } })
group({ transform = translate(0, y), opacity = animate(f, { { start = 0, stop = 0.3, from = 0, to = 1 } }) }, function()
rect { x = 160, y = 240, w = 600, h = 120, rx = 24, fill = "#0ea5e9" }
text { "Hello", x = 200, y = 320, font = "DM Sans", size = 48, weight = 700, fill = "#ffffff" }
end)
end }
scene { "Outro", duration = 3, overlap = { previous = 0.5 }, render = function(f) -- crossfades with Intro
text { "Bye", x = 960, y = 560, align = "center", font = "Bebas Neue", size = 160, fill = "#0ea5e9" }
end }
A video is a video.lua with a media/ folder beside it (fonts, images,
SVG, Lottie and caption files, audio, clips, .sksl / .glsl / .frag shaders).
DM Sans, Instrument Serif, Bebas Neue and JetBrains Mono are built in; any
other font is a file copied into media/.
require and dofile resolve beside the script and SCRIPT_DIR is its
directory. Everything outside render runs once when the script loads, so
layouts, measured text and data belong there; shared(name, fn) computes
large load-time data once per render instead of once per frame builder.
api.md documents the core script API (nodes, groups, paints, text and measuring, images, animation, the standard library, sync points, the script environment) and links the topic files: audio.md (tracks, mixing, onsets, spectra, generated audio), media.md (SVG, Lottie, clips, subtitles, captions), shaders.md, filters.md and problems.md.
Preview
onimite preview video.lua [at] opens a window with the video above a
timeline (ruler, scenes with thumbnails, cue marks, each bus's sound as one
lane that opens to a lane per track; hovering a row or the cue marks names
it with the path onimite show takes) and plays it with sound, looping, as fframes' player
does. Sound joins as the script's clips are built, without holding up the
picture.
Saving any file in the script's folder reloads it within a quarter second
(changes in media/ reload the media); an edit that fails to load is shown
while the last good version keeps playing. The status line shows the GPU,
the preview resolution, render time, latency and the problems found in the
frames shown; a click opens them in the Watch. The bar above it holds
play / pause, loop, the bookmark, the sound, its volume and Reload at the
left (hover an icon for its key), then the time, and at the right end a
spectrum analyzer of the sound as it is heard (a bar per third-octave band
of odawg's, 20 Hz at the left, each with a peak mark; muted, it still
shows). The timeline's zoom (and Follow, once zoomed) sits at the right end
of its ruler.
The video, the timeline and Watch views are tabs in panels, as in oasic:
drag a tab onto another panel's tab strip, centre or edge to move it there
or split the panel; drag a splitter to resize; a tab's X, a middle click on
it or Ctrl+W (the focused panel's) closes a tab; the wheel over the tabs
scrolls them sideways when they don't fit; + lists
what opens in the panel (the video, the timeline, a Watch tab on each of
the video's tables, an expression Watch, a split, closing it) and Ctrl+P
the scenes, cues, problems and marks to go to, both filtered as you type
(each space-separated word anywhere in a row's name, any case; rows keep
their order). A timeline in a panel beside another and taller than
wide runs its ruler, scenes and cues top to bottom, without its lanes: the
scenes take the panel's width beside a column of cue names as wide as the
longest. The cues stay with the ruler and the scenes while the lanes scroll. The timeline's lanes scroll as a list (the wheel over them, the scroll
bar). A lane dragged out by its name opens as a Watch tab the same way, on
that track, group or part; a press on a lane's name doesn't scrub, and a
click on a group's opens or closes it. The Watch is a debugger's watch window over the video's tables:
each row an expression with its value. Its tabs on the tables
(video:scenes, video:cues, video:problems, video:media,
video:marks) list the scenes (with the problems seen in each), cues (with
their sync findings: drift, a hit with no sound near it), problems, media
(thumbnails; failed files, sounds no track plays) and marks, each tab titled
with its row count (in its worst row's colour when that is a warning or an
error), each row coloured by its status; a click goes to its frame, and N
jumps to the next row with a warning or an error. D and I open the
problems' and the media's tab, the first Watch tab in a panel beside the
video and the others after it (one already open is shown); + opens any
table's in its panel. A row's arrow (or a press on it) unfolds it into its
members, as a debugger's watch does: a scene into its name, start,
end, cue, source, hold, status and its problems, which unfold
in turn; a problem into what it says and the scenes it was seen in. An
image unfolds into the picture itself, eight rows tall: a drag pans it, Ctrl+wheel
zooms it and a double click puts it back, as over the video, while the plain wheel
still scrolls the list; it stays where you left it until you close its row. A sound unfolds into a player, four
rows tall: its waveform, with a button that plays and pauses it, as Enter or
Space does on its row; a press on the waveform plays from there and a drag
follows the pointer. The file plays alone, as it is, with nothing of the mix
on it. The video pauses, and its sound comes back where the picture is when
the file ends, when you close the file's last view, or when you play or move
the video; the video stays paused unless it was you who played it. Any row
dragged out of itself onto a panel, on the same drop sites as a tab, opens
there as a tab of its own: an image as the picture, taking its pan with it,
where the plain wheel zooms too and the pixel under the pointer is
outlined with its colour in a tooltip, while its row stays open with a fresh
view; a sound as its player, where Enter or Space plays and pauses it with its
panel focused; anything else as a Watch on it, and dragged again, that same
tab moves.
An expression Watch (+, "Watch") holds the expressions you type, one
a row: type (or paste) on its last row to add one, Enter commits, Esc
drops the edit; on an expression's row Enter (or a click) edits it, Delete
removes it, Alt+Up / Alt+Down move it, Ctrl+C copies its expression. The
language is small: the roots scenes, cues, problems, media,
marks and tracks (the timeline's groups, tracks and parts);
.member (scenes.Race.start, cues.drop.frame); a row by its name in
the member form (scenes.Race), or in quotes when the name isn't a plain
word (scenes["Big Finish"], media["logo.png"]); a row by its place
(scenes[3], from 0); video: before a root names the video's tables
(video:scenes); a comma lists several (scenes, cues). Two rows with one
name are an error that names each one's place (2 scenes named Race: scenes[3], scenes[7]); .domain of a field with fixed choices lists them
(scenes.Race.hold.domain), and .status of a table is its worst row's.
A row's expression is what Ctrl+C copies, ready to paste into another
Watch or to quote to an agent.
The window never waits on Lua, a fence or a file: a render worker owns the script, the media and the canvas and publishes frames through a mailbox (the newest request wins, so scrubbing drops stale frames), SDL's audio callback is the playback clock, and the UI thread only draws.
The arrows, Home / End, Page Up / Down, Delete, Backspace, Enter and Space go to the focused panel (a click on a view focuses its panel): the video's and the timeline's are the keys below, a Watch's move its cursor row (Enter or Space goes to its frame, edits an expression, or plays and pauses a sound's player), a field's edit its text. The letter keys work anywhere. A key works with exactly the modifiers it lists, and held it repeats. A wheel notch scrolls a list three rows.
| key | |
|---|---|
| Space, Enter (video, timeline) | play / pause (also a click on the video) |
| Left / Right (video, timeline), J / K | previous / next frame (held: repeats) |
| Ctrl+Left / Ctrl+Right (video, timeline) | one second back / forward |
| Home, Ctrl+Home, Shift+Left (video, timeline), 0, Shift+J | the bookmark, then the first frame |
| End, Ctrl+End, Shift+Right (video, timeline), Shift+G | last frame |
| Page Down / Page Up (video, timeline), S, W / Shift+S, B | next / previous scene |
| Up / Down (video, timeline), L / H | volume up / down |
| Ctrl+Down (video, timeline), Ctrl+H | mute |
| M | set / clear the bookmark (reloads return to it) |
| [ / ] | mark a range's in / out point, for the agent (NAME.marks.json beside the script or clip; onimite show NAME marks) |
| P | mark a moment (again on it: unmark) |
| Delete, Backspace (video, timeline) | remove the mark under the playhead |
| = / - | zoom the timeline (also Ctrl+wheel over it; a zoomed timeline you scroll stops following the playhead until Follow); Ctrl+0 fits it |
| T | collapse / expand the timeline |
| Z | fit the focused picture, or else the video, in its panel (over either the wheel zooms around the cursor, dragging pans and a double click fits it) |
| F, Ctrl+Enter | fullscreen |
| D / I | the Watch's problems / media tab |
| N / Shift+N | next / previous scene, cue, problem or media row with a warning or an error |
| Shift+L | loop |
| R | reload |
| Ctrl+P | go to a scene, cue, problem or mark (Go to: type to filter its names, Up/Down, Enter) |
| Ctrl+F or / (in a Watch's panel: click it first) | opens or shuts its filter row (type to filter its rows; Enter shuts the row and keeps the filter, Esc clears the filter and shuts it) |
| Alt+= / Alt+-, Ctrl+wheel (not over a picture or the timeline) | the window's text a point larger / smaller |
| Up / Down, Page Up / Down, Enter, Space (a focused Watch) | move its cursor row; Enter or Space goes to the row's frame (on an expression: edits it; on a sound's player: plays and pauses it) |
| typing, Ctrl+V / Delete / Alt+Up, Alt+Down / Ctrl+C (an expression Watch) | add or edit an expression / remove it / move it / copy a row's expression |
| Ctrl+C / Ctrl+X / Ctrl+V, Ctrl+A (in a field) | copy / cut / paste, select all |
| Ctrl+O | open a script (or drop a .lua file) |
| Esc | closes the list or a Watch's filter, or drops a dragged tab where it was |
| Q | closes the window |
--exit-after N closes after N window frames and prints frame timings;
ONIMITE_PREVIEW_CAPTURE=out.png also writes the last frame.
A board on a screen
onimite preview board.lua --live shows a script full screen for good, as
signage: it plays once and then runs on past its end (its last frame held,
the scenes' clocks going on), f.now is the system clock, and the only key
is Ctrl+Q. Whatever feeds it replaces a file beside the script (write the
new file, then rename it over the old one); the board reloads on the same
clock with no label, and a file that fails to load keeps the last good board
(the reason goes to stderr). track_changes gives each row of the new data
when it last changed and what it was before, so only what changed animates
(examples/departures). A frame of the board at a moment:
onimite frame board.lua 2s --now 2026-11-02T14:05:00Z.
To keep it up, run it as a service that restarts it, e.g. a systemd user
unit (~/.config/systemd/user/board.service, then systemctl --user enable --now board):
[Unit]
Description=Departures board
After=graphical-session.target
[Service]
ExecStart=/usr/local/bin/onimite preview /srv/board/video.lua --live
Restart=always
[Install]
WantedBy=graphical-session.target
Examples
Each folder in examples/ is a video.lua with its media/.
| example | shows |
|---|---|
onimite_saga | a 2 min film laid out for agents: a manifest, a file per scene on its cue, a tempo map, a music clip per act |
why_onimite | a 50 s beat-synced pitch: BPM clock, quick cuts, a soundtrack synthesized in Lua, a shader title |
suite | onimite, ovg, oksl, oicut and o3d in every frame: an SkSL world warping a group with a 3D gyroscope in it, alpha clips, a WebP skyline |
data_story | a 30 s chart explainer drawn from props, one video per --batch row |
motion_poster | a generative poster made of noise: SVG filter primitives, noise(), an SkSL warp |
social_clip_kit | one promo in 9:16, 1:1 and 16:9 through --batch: adaptive layout, word captions, an alpha clip |
designer_handoff | design tokens through json_decode, an SVG drawn on from its own paths, a recoloured Lottie badge |
shadertoy_multipass | Common + two feedback buffers + Image, a group channel feeding a buffer |
shader_passes | passes in two dialects: an SkSL trail reading its own last frame, coloured by a GLSL pass |
captions_demo | word-level TikTok captions from Whisper-style JSON, two highlight styles |
lottie_demo | four Lottie files with text and shapes, one with a text-layer override |
svg_demo | an SVG bird animated by element id |
three_d | view3d{}: an orbiting camera, shadows, metal, standard, basic and custom ShaderMaterial meshes, a transparent label on the floor drawn from its curves, a 2D title over the 3D |
fox | a downloaded, skinned glTF model (the Khronos Fox) playing its clips, then a ShaderMaterial override on the model |
pip_demo | Pip, the mascot, in each mood: one pixel-art SVG with parts shown and hidden by id |
transitions | every standard-library transition between scenes |
physics3d_demo | 3D rigid bodies (physics3d{}): a wrecking ball on a rod knocks down a block tower, instanced with shadows; its contacts place recorded sounds (a wood crash where the ball first hits, a thud per block, the orbs' bounces pitched) |
physics_demo | rigid bodies (physics{}) simulated at load: tiles dropped into a word and a ball bounced along them, a recorded thud or bounce per impact |
otfx | otfx's terminal text effects full screen (preview --bare --fullscreen): each effect a timeline built at load on a shared cell grid (term.lua), any text with --set text=...; burn with an SkSL fire fed by a heat map of the burning cells, thunderstorm with flickering return strokes, glyphs lit by their distance to the bolt, cooling struck letters and bloom |
audio_demo | tracks on the video and scenes, say() lines ducking the music, effects on animation constants |
voiceover | spoken lines made with say(), their captions, keys and effects on spoken words (say_cue) |
media_demo | a synced clip, WebVTT subtitles, an audio spectrum, durations from media |
batch | a title card per row of rows.json / rows.csv |
scenes | scene overlaps (cross-fades) |
departures | a split-flap departures board for preview --live: replace flights.json or notices.json and only what changed flips or comes in (track_changes), on the system clock (f.now); --set screen=portrait for a portrait screen |
production_line | a production line dashboard for preview --live: a PLC bridge rewrites line.json, stations matched by id (track_changes) turn and count from their last values, OEE and the shift's pace on f.now |
talk | a talk: preview --present holds each slide (a scene) until the next click, still moving; builds, a looping slide, a card that plays on |
fframes/ | all 20 fframes example crates (22 videos) ported: each makes the same video, the benchmark material (media: examples/fframes/fetch.sh) |
No heavy media is committed. An example that needs some has a fetch.sh, run
once before rendering: cuts, footage, suite, why_onimite and
onimite_saga make their clips with tools/gen_media/gen.sh (its part of the
same name), and graph_paper, physics_demo, physics3d_demo, voiceover and
onimite_saga download CC0 recordings from Freesound, each checked by SHA-256.
The songs' samples are fetched as they play, pinned in each example's
media/pins/. The rest of the sounds, clips, photos and textures, and the
decoder test clips in testdata/, are generated by gen.sh (onimite renders
and synthesizes them; ffmpeg converts them), and spoken lines are made by
say() where the script loads. Fonts, recordings and other third-party files
are listed in THIRD_PARTY_NOTICES.md.
The exception is examples/fframes/: its media, fonts and shaders are fframes'
own, not committed here, and examples/fframes/fetch.sh copies them from a
pinned fframes checkout.
Benchmarks
BENCHMARK.md races onimite against fframes on every
fframes example, ported 1:1 in examples/fframes/, with the method and
the caveats. Its tables are measured on each release's published binary by
tools/bench.sh facts, which writes them and bench/facts.json, the
numbers the films and the site show; tools/bench.sh setup measures what
fframes and Remotion install. examples/fframes/fetch.sh fetches fframes
and the ports' media first.
PARITY.md maps every fframes feature to onimite.
Build
git clone https://github.com/defnotmid/onimite
git clone https://github.com/defnotmid/ovg
git clone https://github.com/defnotmid/oglyph
git clone https://github.com/defnotmid/ocurves
git clone https://github.com/defnotmid/oksl
git clone https://github.com/defnotmid/oicut
git clone https://github.com/defnotmid/ottis
git clone https://github.com/defnotmid/o3d
git clone https://github.com/defnotmid/odawg
cd onimite
mkdir -p build # a fresh clone has no build/ (gitignored); Odin will not create it
odin build . -collection:deps=.. -o:speed -out:build/onimite
deps is the parent directory holding ovg, oglyph, ocurves, oksl, oicut, ottis, o3d and odawg. It
needs Odin dev-2026-11a or later (CI's pin is in .github/actions/setup-toolchain). Use
-o:speed: unoptimized builds are many times slower. On Linux the binary
links the system SDL3 (pacman -S sdl3, apt install libsdl3-dev on Ubuntu
25.04+, otherwise build SDL 3 from source as .github/actions/setup-toolchain
does) and libcurl (ottis downloads its models and odawg its sample sets with it: pacman -S curl,
apt install libcurl4-openssl-dev); Odin
ships SDL3 for Windows. Odin's Linux release ships some vendor C libraries
as source; build them once:
bash "$(odin root)/vendor/box2d/build_box2d.sh" # needs a C compiler; fetches Box2D 3.2.0 (its WASM step may fail: harmless)
Tests (every package that has them, as CI runs them):
bash .github/ci.sh test
macOS
Apple Silicon, SDL_GPU on Metal (ovg, o3d and the encoder compile their shaders to MSL with oksl as they start). With the Xcode command line tools and Homebrew:
brew install sdl3 lua@5.4 # lua@5.4 is keg-only; `lua` is 5.5
# vendor:lua links `lua5.4`; point the linker at the keg:
odin build . -collection:deps=.. -o:speed -out:build/onimite \
-extra-linker-flags:"-L$(brew --prefix lua@5.4)/lib"
Tests take the same flag. SDL's Metal driver needs Cocoa, which starts only
on the main thread, so the GPU tests in encode and onimite (view3d's GPU
half) skip under the test runner on macOS. On macOS render encodes with
VideoToolbox, in hardware or Apple's software codecs.
Layout
| path | package | |
|---|---|---|
onimite/ | onimite | core: timeline and easing, scenes, node tree, drawing, text, media, captions, 3D layers, time specs, SVG export |
script/ | onimite_script | the Lua host: the script API bound to the core builders; std.lua, the standard library |
encode/ | onimite_encode | RGBA to BT.709 I420 (an oksl compute shader on the GPU, or the CPU), oicut H.264 / H.265, MP4; clip and audio decoding |
app/ | onimite_app | command rows and one dispatch (after paf / raddbg): the commands, their output, batches, the preview |
main.odin | main | the command line: parses arguments into command rows |
platform/, render/, ui/ | SDL3 window and input, the UI's frame drawn as one ovg canvas (as onib draws its own), the raddbg-style UI (ported from paf) | |
tools/ | gen_media/ (generated media), bench.sh, threads_check.sh |
Each package's errors are codes with operands (*/errors.odin); text is
made only at the edge.
Not yet
WebM and alpha video output (oicut writes VP9 and HEVC with alpha, but its WebM has no sound yet; such clips work as inputs).
License
MIT, see LICENSE. Third-party notices are in THIRD_PARTY_NOTICES.md.
