uvi-script
Musical event scripting with Lua
Guides

These guides explain the core concepts of uvi-script with practical examples. They are ordered from fundamental concepts to more specialized topics.

Voice Manipulation

Creating, manipulating, and fading voices. Covers changeTune, changeVolume, changePan, fadein/fadeout, script modulation, and sample offset control.

Threading and Timing

Cooperative threading, wait/waitBeat, spawn/run, musical context queries (tempo, beat position, key state, MIDI CC), and common timing patterns.

User Interface

Building custom UIs with Knobs, Sliders, Buttons, Panels, and more. Covers layout, mappers, units, performance view, and Retina support.

Lottie Animations

Dressing knobs, sliders, buttons and meters with vector animations instead of bitmap strips: the two file forms, what drives the frame on each widget, packaged animations that answer the mouse, and sizing.

MIDI Event Generation

Generating outgoing MIDI events (CC, pitch bend, aftertouch, program change) and working with MIDI files.

Asynchronous Operations

Non-blocking file dialogs, sample loading, state persistence, custom data I/O, MIDI file operations, and impulse responses.

MultiSample (SampleMappingOscillator)

Multi-zone sample sets: the mapping file format (.dmap and the SFZ subset), loading a mapping from a script, dispatching notes to an articulation or a round-robin variant, purging layers to save memory, and the program-load sequence that decides where loading belongs.

Sample File Metadata

Which metadata the engine reads from WAV, AIFF and FLAC files — root keys, loops, ranges — and which of it a zone or a Sample Player actually uses. The page to read before porting a library from another sampler.

Porting from Kontakt (KSP)

Coming from Native Instruments Kontakt? A concept-by-concept mapping of KSP callbacks, events, engine access, UI and persistence onto uvi-script, with unit-conversion traps and a full side-by-side port.

Using AI Assistants

Drop-in AGENTS.md for AI coding assistants (Claude Code, Cursor, Codex, …) — orients the assistant to uvi-script's runtime, real-time constraints, and conventions.