What is uvi-script?

uvi-script is a powerful, real-time scripting environment for musical event processing, built on the Lua programming language. It enables you to create intelligent, algorithmic behaviors that respond to and generate musical events with sample-accurate timing.

Unlike traditional MIDI processing, uvi-script gives you complete control over the entire musical pipeline: you can intercept and transform incoming events, generate new musical material, manipulate individual voices, control synthesis parameters, and create custom user interfaces—all from within a single, unified scripting environment.

The language combines Lua's simplicity and expressiveness with a specialized API designed specifically for real-time audio and music production, making it possible to implement sophisticated musical behaviors that would be difficult or impossible with conventional MIDI tools.

What are UVI scripts?

A UVI script is a text file containing Lua code that defines how your instrument responds to and generates musical Events. Each script acts as a programmable event processor inserted into the audio engine's signal path.

Scripts operate through an event-driven model: you define callback functions (like onNote, onRelease, onController) that are automatically invoked when specific events occur. Inside these callbacks, you have complete freedom to decide what happens—forward events unchanged, transform them, generate additional events, manipulate playing voices, or control any synthesis parameter.

Think of scripts as programmable MIDI effects with deep engine integration. They combine the event-processing capabilities of MIDI effects with direct access to voice control, synthesis parameters, and the ability to create custom user interfaces. This integration enables musical behaviors that span the entire sound production chain, from note input to final synthesis.

What can be done with uvi-script?

Possibilities are endless and only limited to your imagination:

Performance Tools:

Legato, Portamento, Articulation switching
Velocity curves and dynamic response

Generative Music:

Sequencing, Arpeggiation
Algorithmic composition
Generative patterns

Harmonic Tools:

Chord recognition and voicing
Harmonization
String selection for guitar instruments

Expression & Effects:

Vibrato, Tremolo
Ensemble/unison simulation
Echo, delay effects

Tuning:

Micro-tuning systems
Scale constraints and transformations
Alternate temperaments

Engine Control:

Complete synthesis engine scripting
Parameter automation and remote control
Sample management

User Interface:

Advanced custom graphics
Interactive controls
Visual feedback

Getting Started

Step-by-Step Tutorial

New to scripting? Start with the comprehensive Building Your First Script to build your first vibrato script.

Guides

Once you understand the basics, explore the topic guides:

Voice Manipulation - Per-voice manipulation (tune, volume, pan, fade, modulation)
Threading and Timing - Threading, timing, and musical context queries
User Interface - Building custom user interfaces
MIDI Event Generation - MIDI event generation
Asynchronous Operations - Asynchronous operations (file I/O, sample loading, state)

See Guides for the complete list.

API Reference

The uvi-script API is organized into functional groups:

Event Callbacks - onNote, onRelease, onController, onTransport, etc.
Events - postEvent, playNote, releaseVoice
Voice Manipulation - changeTune, changeVolume, changePan, fadein/fadeout
Time and Threading - wait, waitBeat, spawn, run
Musical Context - getTempo, getBeatTime, getCC, isKeyDown
Math Conversions - beat2ms, ms2beat, ms2samples
User Interface Classes and Functions - Knob, Button, Label, Image, Panel, etc.
Engine - Program, Layer, Keygroup, Oscillator
Elements & Parameters - Synthesis parameter access
Async - browseForFile, loadSample, saveData, loadMidi
MIDI - MIDI classes, event types, MidiSequence

For quick-start code snippets, see API Quick Reference.

Lua Language

uvi-script is built on Lua 5.1, a lightweight and powerful scripting language. The Lua VM runs with real-time constraints to ensure sample-accurate timing and low-latency performance.

See the Lua Language Reference page for available libraries, memory management, and threading details.