Overview

uvi-script provides per-voice control over tuning, volume, panning, and fading. Each voice represents a single playing note and has a unique ID that can be used to manipulate it individually.

This allows for sophisticated voice-level effects like vibrato, tremolo, detuning, crossfading, and dynamic expression that operate independently on each note.

Voice Lifecycle

Understanding the voice lifecycle is essential for effective voice manipulation:

Voice Creation - A voice is created via playNote or postEvent, which returns a unique voice ID
Voice Manipulation - The voice can be modified using changeTune, changePan, changeVolume
Voice Fading - The voice can be faded using fadein, fadeout, or fade
Voice Release - The voice ends via releaseVoice or automatic release when the note ends

Creating Voices

function onNote(e)
    -- Method 1: Forward incoming event and get voice ID
    local id1 = postEvent(e)
 
    -- Method 2: Create new voice with explicit parameters
    local id2 = playNote(e.note, e.velocity, -1)  -- -1 = sustain until released
 
    -- Method 3: Create voice with specific layer and channel
    local id3 = playNote(60, 100, 1000, 1, 0)  -- C4, vel 100, 1s duration, layer 1
end

Tracking Voice IDs

Always store voice IDs if you plan to manipulate them later:

function onNote(e)
    local voiceId = postEvent(e)  -- Store the ID
 
    -- Later, manipulate this specific voice
    wait(500)
    changeTune(voiceId, 0.5)  -- Bend up 50 cents
end

Managing Multiple Active Voices

Most real-world scripts need to track several playing voices simultaneously. The standard pattern is a table keyed by note number:

local voices = {}  -- voices[note] = voiceId
 
function onNote(e)
    local id = postEvent(e)
    voices[e.note] = id
 
    -- now you can manipulate this specific voice later
    changePan(id, (e.note / 127) * 2 - 1)  -- spread by pitch
end
 
function onRelease(e)
    voices[e.note] = nil
    postEvent(e)
end

This pattern is essential for effects that need to act on all active voices, such as pitch bend applied from a controller:

local voices = {}
 
function onNote(e)
    voices[e.note] = postEvent(e)
end
 
function onRelease(e)
    voices[e.note] = nil
    postEvent(e)
end
 
function onPitchBend(e)
    for note, id in pairs(voices) do
        changeTune(id, e.bend * 2)  -- ±2 semitone range
    end
end

Voice Parameters

Tuning Control

Use changeTune to modify the pitch of a voice in semitones:

function onNote(e)
    local id = postEvent(e)
 
    -- Bend pitch up by 2 semitones (whole step)
    changeTune(id, 2.0)
 
    -- Bend pitch down by 1 semitone
    changeTune(id, -1.0)
 
    -- Detune by 10 cents
    changeTune(id, 0.1)
end

Volume Control

Use changeVolume to modify the volume of a voice:

function onNote(e)
    local id = postEvent(e)
 
    -- Set volume to 50%
    changeVolume(id, 0.5)
 
    -- Set volume to 100%
    changeVolume(id, 1.0)
 
    -- Mute the voice
    changeVolume(id, 0.0)
end

Volume range: 0.0 (silent) to 1.0 (full volume)

For decibel-based control, use changeVolumedB instead. This is often more intuitive for mixing tasks where you think in dB attenuation:

function onNote(e)
    local id = postEvent(e)
 
    -- Attenuate by 6 dB (roughly half perceived loudness)
    changeVolumedB(id, -6)
 
    -- Boost by 3 dB
    changeVolumedB(id, 3)
end

Panning Control

Use changePan to modify the stereo position of a voice:

function onNote(e)
    local id = postEvent(e)
 
    -- Pan hard left
    changePan(id, -1.0)
 
    -- Pan center
    changePan(id, 0.0)
 
    -- Pan hard right
    changePan(id, 1.0)
 
    -- Pan slightly right
    changePan(id, 0.3)
end

Pan range: -1.0 (hard left) to 1.0 (hard right), 0.0 is center

Fading Voices

Control voice envelope with fade functions:

function onNote(e)
    local id = postEvent(e)
 
    -- Fade in over 500ms
    fadein(id, 500)
 
    -- Later, fade out over 1000ms and stop voice
    wait(2000)
    fadeout(id, 1000, true)  -- true = release voice after fade
end

Common Use Cases

Detuning for Richness

Create a richer sound by layering slightly detuned copies:

function onNote(e)
    -- Play root note
    local id1 = playNote(e.note, e.velocity, -1)
 
    -- Add slightly detuned copies for chorus effect
    local id2 = playNote(e.note, e.velocity, -1)
    local id3 = playNote(e.note, e.velocity, -1)
 
    changeTune(id2, 0.05)   -- +5 cents
    changeTune(id3, -0.05)  -- -5 cents
 
    -- Optional: Pan them for width
    changePan(id1, 0.0)     -- Center
    changePan(id2, -0.3)    -- Slightly left
    changePan(id3, 0.3)     -- Slightly right
end

Dynamic Vibrato

Apply vibrato that intensifies over time:

local vibratoRate = Knob("Vibrato Rate", 5, 0, 10)
local vibratoDepth = Knob("Vibrato Depth", 0.1, 0, 0.5)
 
function onNote(e)
    local id = postEvent(e)
    local elapsed = 0
 
    while isNoteHeld() do
        -- Vibrato depth increases over time
        local depthEnvelope = math.min(elapsed / 1000, 1.0)
        local phase = 2 * math.pi * vibratoRate.value * elapsed / 1000
        local modulation = vibratoDepth.value * depthEnvelope * math.sin(phase)
 
        changeTune(id, modulation)
 
        wait(5)
        elapsed = elapsed + 5
    end
end

Tremolo Effect

Create rhythmic volume modulation:

local tremoloRate = Knob("Tremolo Rate", 5, 0, 20)
local tremoloDepth = Knob("Tremolo Depth", 0.5, 0, 1)
 
function onNote(e)
    local id = postEvent(e)
 
    while isNoteHeld() do
        local phase = 2 * math.pi * tremoloRate.value * getTime() / 1000
        local modulation = 1 - (tremoloDepth.value * (1 - math.cos(phase)) / 2)
        changeVolume(id, modulation)
        wait(5)
    end
end

Auto-Panning

Create movement in the stereo field:

local panRate = Knob("Pan Rate", 0.5, 0, 5)
 
function onNote(e)
    local id = postEvent(e)
 
    while isNoteHeld() do
        local phase = 2 * math.pi * panRate.value * getTime() / 1000
        local pan = math.sin(phase)
        changePan(id, pan)
        wait(10)
    end
end

Voice Crossfading

Smoothly transition between voices:

function onNote(e)
    -- Play two different layers
    local voice1 = playNote(e.note, e.velocity, -1, 1)  -- Layer 1
    local voice2 = playNote(e.note, e.velocity, -1, 2)  -- Layer 2
 
    -- Start with layer 1 only
    changeVolume(voice2, 0.0)
 
    -- Crossfade from layer 1 to layer 2 over 2 seconds
    for i = 0, 100 do
        local mix = i / 100
        changeVolume(voice1, 1.0 - mix)
        changeVolume(voice2, mix)
        wait(20)
    end
end

Pitch Bend Effect

Create smooth pitch glides:

function onNote(e)
    local id = postEvent(e)
 
    -- Bend from -2 semitones to 0 over 500ms
    for i = 0, 100 do
        local bend = -2.0 + (2.0 * i / 100)
        changeTune(id, bend, false, false)  -- Smooth interpolation
        wait(5)
    end
end

Unison/Ensemble Effect

Create a thick unison sound with multiple detuned voices:

local unisonVoices = 5
local unisonDetune = Knob("Detune", 0.1, 0, 0.5)
local unisonSpread = Knob("Stereo Spread", 0.5, 0, 1)
 
function onNote(e)
    for i = 1, unisonVoices do
        local id = playNote(e.note, e.velocity, -1)
 
        -- Detune each voice differently
        local detune = (i - (unisonVoices + 1) / 2) * unisonDetune.value / unisonVoices
        changeTune(id, detune)
 
        -- Spread across stereo field
        local pan = ((i - 1) / (unisonVoices - 1) - 0.5) * 2 * unisonSpread.value
        changePan(id, pan)
    end
end

Best Practices

Always Store Voice IDs: If you plan to manipulate a voice later, store its ID:
-- GOOD: Store ID for later use

local id = postEvent(e)

wait(1000)

changeTune(id, 0.5)

-- BAD: Can't manipulate the voice later

postEvent(e)

-- How do we change this voice now?

this
ScriptProcessor & this
Reference to the current ScriptProcessor instance.
Definition Engine.cpp:404

Clean Up Voice Data: Remove stored voice data when voices end:
function onNote(e)

local id = postEvent(e)

voiceData[id] = {startTime = getTime()}

waitForRelease()

-- Clean up

voiceData[id] = nil

end

waitForRelease
function waitForRelease()
suspend the current thread callback execution until the note that created this callback is released e...
Definition wrapper.lua:47

Limit Voice Count: Be mindful of CPU usage when creating many voices:
-- GOOD: Reasonable voice count

function onNote(e)

for i = 1, 5 do

playNote(e.note, e.velocity, -1)

end

end

-- POTENTIALLY BAD: Too many voices

function onNote(e)

for i = 1, 50 do -- May cause CPU issues

playNote(e.note, e.velocity, -1)

end

end

Sample Start Offset

Use setSampleOffset to change where playback begins within a sample, specified in milliseconds. This is applied to an already-playing voice, letting you skip into the middle of a sample on the fly.

function onNote(e)
    local id = postEvent(e)
 
    -- Random start offset (0–80 ms) for natural variation on repeated notes
    local offset = math.random() * 80
    setSampleOffset(id, offset)
end

Script Modulation

Script modulation sources are modulation slots in the engine that can be driven entirely from script code. You assign a script modulation source to a destination in the engine UI, then send values from your script. This allows continuous, per-voice or broadcast parameter control — useful for expression, morphing, or any automation that goes beyond simple note-on changes.

Use sendScriptModulation to send a value to a modulation source:

id — modulation source index (configured in the engine UI)
targetValue — destination value, [0,1] unipolar or [-1,1] bipolar depending on the mapping
rampTime — interpolation time in ms (default 20 ms, avoids zipper noise)
voiceId — optional; pass a voice ID for per-voice modulation, or nil to broadcast to all voices

-- Broadcast example: map MIDI CC1 (mod wheel) to script modulation source 0
function onController(e)
    if e.controller == 1 then
        local value = e.value / 127  -- Normalize to 0..1
        sendScriptModulation(0, value, 20)  -- voiceId omitted = broadcast
    end
end

Use sendScriptModulation2 for piece-wise linear ramps where you need an explicit start value. Parameters are the same, with an additional startValue before targetValue:

-- Per-voice expression: ramp modulation source 1 from 0 to 1 over 500 ms
function onNote(e)
    local id = postEvent(e)
    sendScriptModulation2(1, 0.0, 1.0, 500, id)
end