uvi-script

https://lua.uvi.net
Admin
uvi-script is a Lua-based musical event scripting framework for creating dynamic voice manipulation,...
Tokens:164,059
Snippets:1,765
Trust Score:9.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Harmonize a note using playNote

Source: https://lua.uvi.net/group___events.html

This example demonstrates how to harmonize an incoming note by playing it an octave higher using playNote. It also shows basic event posting.

```lua
function onNote(e)
postEvent(e)
local id = playNote(e.note+12, e.velocity) -- harmonize note
end
```

--------------------------------

### getTime

Source: https://lua.uvi.net/group___context.html

Gets the number of milliseconds elapsed since the script engine started.

```APIDOC
## getTime()

### Description
Get the number of milliseconds elapsed since the script engine start.

### Returns
- The elapsed time in milliseconds (number).
```

--------------------------------

### Basic UI Setup (Lua)

Source: https://lua.uvi.net/_examples_page.html

Sets the background color, creates a panel with specific bounds and color, and initializes three knobs with labels, each configured with different mappers, units, and colors.

```lua
setBackgroundColour("1a1a1a")
local panel = Panel{"controls"}
panel.bounds = {10, 10, 340, 90}
panel.backgroundColour = "2a2a2a"
local margin = 10
local knobSize = 60
local labelH = 16
local volKnob, volLabel, volName = makeKnobWithLabel(panel, "VOL", 0.8, 0, 1, margin,
{mapper = Mapper.Cubic, unit = Unit.LinearGain, colour = "FF8800"})
local cutKnob, cutLabel, cutName = makeKnobWithLabel(panel, "CUTOFF", 20000, 20, 20000, margin + 70 + margin,
{mapper = Mapper.Exponential, unit = Unit.Hertz, colour = "FFCC00"})
local resKnob, resLabel, resName = makeKnobWithLabel(panel, "RES", 0, 0, 1, margin + 2 * (70 + margin),
{unit = Unit.PercentNormalized, colour = "FFCC00"})
```

--------------------------------

### Example Usage

Source: https://lua.uvi.net/class_dn_d_area.html

Demonstrates how to create a DnDArea widget and set up its properties, including the fileDropped callback.

```APIDOC
dnd = DnDArea("DnD")
dnd.acceptedFileFormat = FileFormat.Audio
dnd.fileDropped = function(self)
  print("fileDropped", self.filepath)
end
```

--------------------------------

### Get Time

Source: https://lua.uvi.net/group___context.html

Returns the number of milliseconds that have elapsed since the script engine started.

```lua
function getTime()
```

--------------------------------

### Get Time Signature

Source: https://lua.uvi.net/group___context.html

Retrieves the current time signature as numerator and denominator. Example usage is provided.

```lua
function getTimeSignature()
local num,den = getTimeSignature()
getTimeSignature
```

```lua
function getTimeSignature()
```

--------------------------------

### Create and Configure WaveView Widget

Source: https://lua.uvi.net/class_wave_view.html

Instantiates a WaveView widget and sets its initial properties like position, dimensions, and the sample file to be displayed. Ensure the sample file exists in a location accessible by the application.

```lua
local waveview = WaveView("waveview")
waveview.x = 5
waveview.y = 5
waveview.width = 100
waveview.height = 100
waveview.sample = "Drum Loop.wav"
```

--------------------------------

### Create Panel and Sub-Widgets

Source: https://lua.uvi.net/_u_i_page.html

Demonstrates creating a Panel container and then adding sub-widgets like Knob, Slider, and OnOffButton to it using method syntax. The panel's bounds and background color are also configured.

```lua
local panel = Panel{"Controls"}
panel.bounds = {0, 0, 720, 100}
panel.backgroundColour = "3f000000"
-- sub-widgets belong to the panel
local k = panel:Knob("Gain", 0.5, 0, 1)
local s = panel:Slider("Pan", 0, -1, 1)
local b = panel:OnOffButton("Mute", false)
```

--------------------------------

### Playing a Note with Lua

Source: https://lua.uvi.net/_a_p_i_page.html

Handles incoming note-on events by forwarding them and getting a voice ID. This is a basic event handler setup.

```lua
function onNote(e)
local id = postEvent(e) -- Forward the event and get voice ID
end
```

--------------------------------

### Get Elapsed Time Since Script Engine Start

Source: https://lua.uvi.net/_tutorial.html

The getTime() function retrieves the number of milliseconds that have passed since the script engine was initialized.

```lua
function getTime()
get the number of milliseconds elapsed since the script engine start.
**Definition** api.lua:740
```

--------------------------------

### Create and Configure a Panel Widget

Source: https://lua.uvi.net/class_panel.html

Demonstrates how to create a Panel widget, set its position, dimensions, and background color, and add various sub-widgets to it. Use this to build complex UI layouts.

```lua
local panel = Panel("panel")
panel.x = 5
panel.y = 5
panel.width = 710
panel.height = 120
panel:Button("foo")
panel:OnOffButton("onoff", false)
panel:Knob("knob", 0, 0, 1)
panel:Slider("slider", 0, 0, 1)
panel:Label("label")
panel:NumBox("NumBox", 0, 0, 1)
panel:Menu("Menu", {"one", "two", "three"})
panel:Table("table", 24, 0, 0, 1)
panel.backgroundColour = "3f000000"
```

--------------------------------

### Store Voice IDs for Later Manipulation

Source: https://lua.uvi.net/_time_intro.html

Stores the ID returned by `postEvent` to allow modification of a specific voice after it has started playing. This example demonstrates changing the tune after a 1-second delay.

```lua
function onNote(e)
local id = postEvent(e) -- Store the voice ID
spawn(function()
wait(1000)
changeTune(id, 0.5) -- Can modify this specific voice
end)
end
```

--------------------------------

### Create and Configure AudioMeter Widget

Source: https://lua.uvi.net/_u_i_page.html

Instantiate an AudioMeter to display real-time audio levels. Set its bounds for positioning.

```lua
local meter = AudioMeter("out", Program, true, 0, true)
meter.bounds = {680, 0, 40, 100}
```

--------------------------------

### fade2

Source: https://lua.uvi.net/group___voice.html

Starts a volume fade with specified start and target values.

```APIDOC
## fade2

### Description
Starts a volume fade.

### Parameters
- **voiceId** (any) - Description
- **startValue** (any) - Description
- **targetValue** (any) - Description
- **duration** (any) - Description
- **layer** (any) - Description
```

--------------------------------

### Create and Configure a Menu Widget

Source: https://lua.uvi.net/class_menu.html

Instantiate a Menu widget with a name and initial items. You can also add items later and define a callback for selection changes.

```lua
m = Menu("menu", {"one", "two", "three"})
m:addItem("four")
m.changed = function(self)
print("menu selection changed:", self.value, self.selectedText)
end
m:setValue(2)
```

--------------------------------

### Functions starting with 'o'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'o', along with the classes they belong to.

```APIDOC
## Functions starting with 'o'

### Description
Lists functions that start with the letter 'o', along with the classes they belong to.

### Functions
- **OnOffButton()**: OnOffButton
```

--------------------------------

### Sample Loading

Source: https://lua.uvi.net/_async_intro.html

Functions to load audio files into oscillators and configure their playback parameters.

```APIDOC
## loadSample

### Description
Loads an audio file into an oscillator.

### Definition
api.lua:56

### Parameters
- **oscillator** (object) - Required - The oscillator object to load the sample into.
- **path** (string) - Required - The path to the audio file.
- **callback** (function) - Optional - A callback function to be executed after the sample is loaded.

### Request Example
```lua
local osc = Program.layers[1].oscillators[1]
loadSample(osc, "/path/to/kick.wav", function(task)
  if task.success then
    print("Sample loaded")
  end
end)
```
```

```APIDOC
## setPlaybackOptions

### Description
Sets playback options for an oscillator, including start, end, loop points, and direction.

### Definition
api.lua:81

### Parameters
- **oscillator** (object) - Required - The oscillator object.
- **start** (number) - Required - The start point in samples.
- **end_** (number) - Required - The end point in samples.
- **loopType** (number) - Required - The loop type (0=None, 1=Forward, 2=Alternate, 3=OneShot).
- **loopStart** (number) - Required - The loop start point in samples.
- **loopEnd** (number) - Required - The loop end point in samples.
- **playForward** (boolean) - Required - Whether to play forward.
- **callback** (function) - Optional - A callback function to be executed after the options are set.

### Request Example
```lua
setPlaybackOptions(osc, 0, 44100, 1, 1000, 40000, true, function(t)
  if t.success then
    print("Playback configured")
  end
end)
```
```

```APIDOC
## unpurge

### Description
Reloads previously purged samples into oscillators.

### Definition
api.lua:384

### Parameters
- **target** (object or table) - Required - The oscillator(s) or element(s) to unpurge.
- **callback** (function) - Optional - A callback function to be executed after the unpurge operation completes.

### Request Example
```lua
unpurge(osc, function(task)
  if task.success then
    print("Samples reloaded")
  end
end)
```
```

--------------------------------

### Load Audio Sample and Configure Playback

Source: https://lua.uvi.net/_async_intro.html

Load audio files into oscillators using `loadSample` and configure playback parameters like start, end, and loop points with `setPlaybackOptions`. Callbacks confirm operation success.

```lua
local osc = Program.layers[1].oscillators[1]
-- Load a sample and configure loop points
loadSample(osc, "/path/to/kick.wav", function(task)
if task.success then
-- Set playback: start=0, end=44100, loop Forward from 1000 to 40000, forward
setPlaybackOptions(osc, 0, 44100, 1, 1000, 40000, true, function(t) 
if t.success then print("Playback configured") end 
end)
end
end)
```

--------------------------------

### Functions starting with 'i'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'i', along with the classes they belong to.

```APIDOC
## Functions starting with 'i'

### Description
Lists functions that start with the letter 'i', along with the classes they belong to.

### Functions
- **Image()**: Image
- **insertEvent()**: MidiSequence
```

--------------------------------

### Functions starting with 'a'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'a', along with the classes they belong to.

```APIDOC
## Functions starting with 'a'

### Description
Lists functions that start with the letter 'a', along with the classes they belong to.

### Functions
- **addItem()**: Menu, MultiStateButton
- **AudioMeter()**: AudioMeter
```

--------------------------------

### Implement Drag-and-Drop for Loading Samples

Source: https://lua.uvi.net/_examples_page.html

Use DnDArea to create a drop zone for audio files. The `loadSample` function asynchronously loads the dropped file into an oscillator, providing visual feedback via a Label.

```lua
local osc = Program.layers[1].keygroups[1].oscillators[1]
local status = Label{"status"}
status.text = "Drop a sample here"
status.align = "centred"
status.textColour = "white"
local dnd = DnDArea("drop")
dnd.acceptedFileFormat = FileFormat.Audio
dnd.bounds = {5, 30, 350, 60}
dnd.backgroundColour = "3fFFFFFF"
dnd.fileDropped = function(self)
status.text = "Loading..."
loadSample(osc, self.filepath, function(task)
if task.success then
status.text = osc.sampleInfo.name
else
status.text = "Load failed"
end
end)
end
setSize(360, 100)
makePerformanceView()
```

--------------------------------

### Functions starting with 'x'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'x', along with the classes they belong to.

```APIDOC
## Functions starting with 'x'

### Description
Lists functions that start with the letter 'x', along with the classes they belong to.

### Functions
- **XY()**: XY
```

--------------------------------

### Create Button, OnOffButton, and MultiStateButton UI Controls

Source: https://lua.uvi.net/_u_i_page.html

Shows how to instantiate Button, OnOffButton, and MultiStateButton controls. Button triggers a callback on click. OnOffButton has a boolean state, and MultiStateButton cycles through predefined text states.

```lua
local trigger = Button{"Play"}
trigger.changed = function(self) playNote(60, 100, 500) end
local bypass = OnOffButton{"Bypass", false}
bypass.changed = function(self) print("Bypass:", self.value) end
local mode = MultiStateButton{"Mode", {"Poly", "Mono", "Legato"}}
mode.changed = function(self) print("Mode:", self.selectedText) end
```

--------------------------------

### Functions starting with 'w'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'w', along with the classes they belong to.

```APIDOC
## Functions starting with 'w'

### Description
Lists functions that start with the letter 'w', along with the classes they belong to.

### Functions
- **WaveView()**: WaveView
```

--------------------------------

### Create and Configure DnDArea Widget

Source: https://lua.uvi.net/_u_i_page.html

Set up a DnDArea for file drops. Specify accepted file formats and define a callback for when a file is dropped.

```lua
local dnd = DnDArea{"Drop"}
dnd.acceptedFileFormat = FileFormat.Audio
dnd.fileDropped = function(self)
print("Dropped:", self.filepath)
end
```

--------------------------------

### Create and Configure XY Widget

Source: https://lua.uvi.net/class_x_y.html

Instantiates an XY widget and sets its bounds. It also shows how to create associated Knob widgets and handle their change events.

```lua
paramX = Knob("X", 5, 0, 10)
function paramX:changed(v)
print("X changed ", paramX.value)
end
paramY = Knob("Y", 5, 0, 10)
function paramY:changed(v)
print("X changed ", paramY.value)
end
xy = XY("X", "Y")
xy.bounds = {250, 0, 200, 200}
```

--------------------------------

### Functions starting with 'v'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'v', along with the classes they belong to.

```APIDOC
## Functions starting with 'v'

### Description
Lists functions that start with the letter 'v', along with the classes they belong to.

### Functions
- **Viewport()**: Viewport
```

--------------------------------

### Functions starting with 't'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 't', along with the classes they belong to.

```APIDOC
## Functions starting with 't'

### Description
Lists functions that start with the letter 't', along with the classes they belong to.

### Functions
- **Table()**: Table
```

--------------------------------

### onInit

Source: https://lua.uvi.net/group___event_callbacks.html

Initial callback that is called just after the script initialisation if the script was successfully analyzed.

```APIDOC
## onInit

### Description
Initial callback that is called just after the script initialisation if the script was successfully analyzed.

### Signature
`void onInit()`
```

--------------------------------

### Create and Configure Table Widget

Source: https://lua.uvi.net/_u_i_page.html

Instantiate a Table widget for multi-value data like sequencer steps. Configure its properties and set a callback for value changes.

```lua
local steps = Table{"Steps", 16, 0, -12, 12, true} -- 16 steps, int, range -12..12
steps.changed = function(self, index)
print("Step", index, "=", self:getValue(index))
end
```

--------------------------------

### Functions starting with 's'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 's', along with the classes they belong to.

```APIDOC
## Functions starting with 's'

### Description
Lists functions that start with the letter 's', along with the classes they belong to.

### Functions
- **setItem()**: Menu, MultiStateButton
- **setParameter()**: Element
- **setRange()**: Knob, NumBox, Slider, Table
- **setStripImage()**: AudioMeter, Knob, Slider
- **setValue()**: Knob, Menu, MultiStateButton, NumBox, OnOffButton, Slider, Table
- **setViewPosition()**: Viewport
- **Slider()**: Slider
- **SVG()**: SVG
```

--------------------------------

### Load Sample

Source: https://lua.uvi.net/group___async.html

Loads a sample file into an oscillator asynchronously. The callback function is invoked upon completion, indicating the success of the operation.

```lua
loadSample(Program.layers[1].keygroups[1].oscillators[1], "samples/sample.wav", function(task) print("done") print(task.success) end)
```

```lua
function loadSample(oscillator, path, callback)
load a sample inside the oscillator
```

--------------------------------

### Functions starting with 'p'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'p', along with the classes they belong to.

```APIDOC
## Functions starting with 'p'

### Description
Lists functions that start with the letter 'p', along with the classes they belong to.

### Functions
- **Panel()**: Panel
- **prev()**: FileSelector
- **push()**: Button
```

--------------------------------

### Functions starting with 'n'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'n', along with the classes they belong to.

```APIDOC
## Functions starting with 'n'

### Description
Lists functions that start with the letter 'n', along with the classes they belong to.

### Functions
- **next()**: FileSelector
- **NumBox()**: NumBox
```

--------------------------------

### Functions starting with 'm'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'm', along with the classes they belong to.

```APIDOC
## Functions starting with 'm'

### Description
Lists functions that start with the letter 'm', along with the classes they belong to.

### Functions
- **Menu()**: Menu
- **MidiEvent()**: MidiEvent
- **MultiStateButton()**: MultiStateButton
```

--------------------------------

### Create and Configure MultiStateButton

Source: https://lua.uvi.net/class_multi_state_button.html

Demonstrates how to create a MultiStateButton, add items, set a callback for changes, and set an initial value. The callback function is invoked when the button's value changes.

```lua
m = MultiStateButton("Multi", {"one", "two", "three"})
m:addItem("four")
m.changed = function(self)
print("multi state changed:", self.value, self.selectedText)
end
m:setValue(2)
```

--------------------------------

### Create and Save Empty MIDI File

Source: https://lua.uvi.net/_async_intro.html

Creates an empty Type-1 MIDI file with specified tracks and PPQ, then saves it asynchronously. Verify the save path.

```lua
createMidiFile(2, 1, 480, function(task)
if task.success then
local seq = task.result
saveMidi(seq, "/path/to/output.mid", function(t)
if t.success then print("MIDI file saved") end
end)
end
end)
```

--------------------------------

### Functions starting with 'l'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'l', along with the classes they belong to.

```APIDOC
## Functions starting with 'l'

### Description
Lists functions that start with the letter 'l', along with the classes they belong to.

### Functions
- **Label()**: Label
- **loadImpulse()**: SampledReverb
```

--------------------------------

### Functions starting with 'k'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'k', along with the classes they belong to.

```APIDOC
## Functions starting with 'k'

### Description
Lists functions that start with the letter 'k', along with the classes they belong to.

### Functions
- **Knob()**: Knob
```

--------------------------------

### this

Source: https://lua.uvi.net/group___globals.html

Reference to the current ScriptProcessor instance. Use as a starting point to navigate through the Engine hierarchy.

```APIDOC
## ◆ this
ScriptProcessor& this

### Description
Reference to the current ScriptProcessor instance.
Use as a starting point to navigate through the Engine hierarchy.
```

--------------------------------

### loadSample()

Source: https://lua.uvi.net/group___async.html

Loads a sample file into an oscillator asynchronously. It requires the oscillator object, the path to the sample file, and a callback function.

```APIDOC
## ◆ loadSample()
function loadSample(oscillator, path, callback)
load a sample inside the oscillator  

Parameters
     oscillator|
path| path to sample file   
callback| callback function that will be called upon completion of the asynchronous task  

Returns
    an AsyncTask  
**Example:**
loadSample(Program.layers[1].keygroups[1].oscillators[1], "samples/sample.wav", function(task) print("done") print(task.success) end)
```

--------------------------------

### Functions starting with 'h'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'h', along with the classes they belong to.

```APIDOC
## Functions starting with 'h'

### Description
Lists functions that start with the letter 'h', along with the classes they belong to.

### Functions
- **hasParameter()**: Element
```

--------------------------------

### Available Libraries

Source: https://lua.uvi.net/_lua_reference.html

Core Lua libraries and uvi-script extensions available for use.

```APIDOC
## Available Libraries

**base - Basic Functions**
  * Core functions: `assert`, `error`, `pcall`, `type`, `tonumber`, `tostring`
  * Table/iteration: `pairs`, `ipairs`, `next`
  * Utility: `print`, `select`, `unpack`


**package - Module System**
  * `require` - Load Lua modules
  * Note: Only Lua modules can be loaded, not C libraries


**table - Table Manipulation**
  * `table.insert`, `table.remove`
  * `table.concat`
  * `table.sort`
  * `table.copy(t)` - uvi-script extension: creates a shallow copy of a table
  * Note: Be mindful of performance on large tables in real-time code


**string - String Operations**
  * `string.sub`, `string.find`, `string.match`
  * `string.format`, `string.gsub`
  * Pattern matching (Lua patterns, not full regex)


**math - Mathematical Functions**
  * Trigonometry: `math.sin`, `math.cos`, `math.tan`, `math.asin`, etc.
  * Utilities: `math.abs`, `math.floor`, `math.ceil`, `math.min`, `math.max`
  * Random: `math.random`, `math.randomseed`
  * Constants: `math.pi`, `math.huge`


**class - Object-Oriented Programming**
  * ‘class 'Name’` - Create a new class (see Object-Oriented Programming below)
  * uvi-script extension: auto-loaded, always available
```

--------------------------------

### Functions starting with 'g'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'g', along with the classes they belong to.

```APIDOC
## Functions starting with 'g'

### Description
Lists functions that start with the letter 'g', along with the classes they belong to.

### Functions
- **getEvent()**: MidiSequence
- **getEventProcessor()**: Synth
- **getInsert()**: AuxEffect
- **getNumEventsForTrack()**: MidiSequence
- **getParameter()**: Element
- **getParameterConnections()**: Element
- **getSliceInfo()**: Oscillator
- **getText()**: Menu, MultiStateButton
- **getValue()**: Table
```

--------------------------------

### Create and Configure Viewport

Source: https://lua.uvi.net/class_viewport.html

Creates a Viewport widget and sets its initial position and dimensions. It also demonstrates adding a Panel widget as a child, which can then contain other UI elements.

```lua
local viewport = Viewport("viewport")
viewport.x = 5
viewport.y = 5
viewport.width = 100
viewport.height = 100
local panel = viewport:Panel("panel")
panel.size = {700, 700}
panel:Button("foo")
```

--------------------------------

### Functions starting with 'f'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'f', along with the classes they belong to.

```APIDOC
## Functions starting with 'f'

### Description
Lists functions that start with the letter 'f', along with the classes they belong to.

### Functions
- **FileSelector()**: FileSelector
- **findAt()**: MidiSequence
- **findNextAt()**: MidiSequence
- **findPreviousAt()**: MidiSequence
```

--------------------------------

### Create and Configure XY Pad Widget

Source: https://lua.uvi.net/_u_i_page.html

Initialize an XY widget for two-dimensional input. Assign a callback function to handle coordinate changes.

```lua
local pad = XY{"Pad", 0.5, 0.5}
pad.changed = function(self)
print("X:", self.x, "Y:", self.y)
end
```

--------------------------------

### Functions starting with 'd'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'd', along with the classes they belong to.

```APIDOC
## Functions starting with 'd'

### Description
Lists functions that start with the letter 'd', along with the classes they belong to.

### Functions
- **DnDArea()**: DnDArea
```

--------------------------------

### Instantiate and Use a Class in Lua

Source: https://lua.uvi.net/_lua_reference.html

Create instances of a defined class and use its methods within event callbacks. This example shows managing notes and their associated IDs.

```lua
local tracker = NoteTracker()
function onNote(e)
local id = postEvent(e)
tracker:add(e.note, id)
end
function onRelease(e)
tracker:remove(e.note)
postEvent(e)
end
function onPitchBend(e)
tracker:forEach(function(note, id)
changeTune(id, e.bend * 2)
end)
end
```

--------------------------------

### Functions starting with 'c'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'c', along with the classes they belong to.

```APIDOC
## Functions starting with 'c'

### Description
Lists functions that start with the letter 'c', along with the classes they belong to.

### Functions
- **cancel()**: AsyncTask
- **clear()**: Menu, MultiStateButton
```

--------------------------------

### Create and Configure FileSelector Widget

Source: https://lua.uvi.net/class_file_selector.html

Instantiates a FileSelector widget and sets its initial properties such as filepath, dimensions, and file type filtering. The filepath is initialized using getLocation("Script").

```lua
fs = FileSelector("fs")
fs.filepath = getLocation("Script")
fs.columnWidth = 180
fs.rowHeight = 20
fs.x = 0
fs.y = 0
fs.width = 720
fs.height = 360
fs.filetype = "*.*"
```

--------------------------------

### Functions starting with 'b'

Source: https://lua.uvi.net/functions_func.html

Lists functions that start with the letter 'b', along with the classes they belong to.

```APIDOC
## Functions starting with 'b'

### Description
Lists functions that start with the letter 'b', along with the classes they belong to.

### Functions
- **bind()**: WaveView
- **Button()**: Button
```

--------------------------------

### Set Sample Start Offset with Lua

Source: https://lua.uvi.net/_voice_intro.html

Modify the playback start point of a sample in milliseconds for an already playing voice using `setSampleOffset`.

```lua
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
```

--------------------------------

### Create an Image Widget

Source: https://lua.uvi.net/class_image.html

Use this constructor to create an Image widget on the user interface. Specify the path to the image file.

```lua
img = Image("resources/image.png")
```

--------------------------------

### Change Sample Start Offset

Source: https://lua.uvi.net/group___voice.html

Modifies the starting point of a sample for a given voice in milliseconds. Note that in streaming mode, the offset is subject to preload clipping.

```lua
setSampleOffset(voiceId, value)
```

--------------------------------

### Create Label and Image UI Controls

Source: https://lua.uvi.net/_u_i_page.html

Shows the creation of a Label control for displaying text with specified alignment and an Image control for displaying a static image file. The Image control's position is also set.

```lua
local title = Label{"title", text = "My Instrument", align = "centred"}
local logo = Image("resources/logo.png")
logo.pos = {10, 10}
```

--------------------------------

### MIDI Learn for Note Assignment

Source: https://lua.uvi.net/_examples_page.html

Demonstrates the MIDI learn pattern. Press a button to enter learn mode, then play a note to assign it. The learned note is displayed and used to transpose incoming notes. Use this pattern to dynamically assign MIDI notes.

```lua
local learnedNote = 60
local learning = false
local learnBtn = Button{"Learn"}
learnBtn.changed = function(self)
learning = true
status.text = "Play a note..."
end
local status = Label{"status"}
status.text = "C4"
function onNote(e)
if learning then
-- assign the played note
resetKeyColour(learnedNote)
learnedNote = e.note
setKeyColour(learnedNote, "00FF00") -- green
status.text = string.format("Note: %d", learnedNote)
learning = false
else
-- transpose relative to learned note
local offset = e.note - 60
playNote(learnedNote + offset, e.velocity, -1)
end
end
function onRelease(e)
-- eat releases: playNote handles them via duration -1
end
setKeyColour(learnedNote, "00FF00")
```

--------------------------------

### fade2()

Source: https://lua.uvi.net/group___voice.html

Starts a volume fade for a voice, specifying both the start and target values, duration, and optionally the layer. This fade is applied on top of volume changes made by changeVolume().

```APIDOC
## fade2()

### Description
Starts a volume fade for a specific voice with defined start and target values.

### Parameters
- **voiceId** (id) - The ID of the voice to fade.
- **startValue** (volume) - The initial volume for the fade.
- **targetValue** (volume) - The target volume to reach.
- **duration** (ms) - The duration of the fade in milliseconds.
- **layer** (integer) - Optional. The target layer to apply the fade to. Use 0 for all layers (broadcast). Defaults to 0.
```

--------------------------------

### Open File Dialog with Callback

Source: https://lua.uvi.net/_async_intro.html

Initiate an asynchronous file open dialog using `browseForFile`. The provided callback function will be executed once the user selects a file or cancels the operation.

```lua
-- Open file dialog
browseForFile("open", "Select Audio File", "", "*.wav;*.aif", function(task)
if task.success then
local filepath = task.result
print("User selected: " .. filepath)
end
end)
```

--------------------------------

### Create and Configure OnOffButton

Source: https://lua.uvi.net/class_on_off_button.html

Instantiate an OnOffButton with a name and default value. Customize its appearance and define a callback for state changes.

```lua
b = OnOffButton("button", false)
b.backgroundColourOff = "darkgrey"
b.backgroundColourOn = "darkred"
b.textColourOff = "white"
b.textColourOn = "white"
b.changed = function(self, mods)
print("button changed state:", self.value, mods.altDown)
end
```

--------------------------------

### Start Volume Fade with Start Value

Source: https://lua.uvi.net/group___voice.html

Begins a volume fade for a voice, specifying both the initial volume and the target volume over a given duration. Applied on top of volume changes made with changeVolume().

--------------------------------

### Start Generic Voice Fade

Source: https://lua.uvi.net/group___voice.html

Initiates a volume fade for a specific voice. This function allows for fades to a target value over a set duration. A variant 'fade2' also accepts a start value.

```lua
function fade (voiceId, targetValue, duration, layer)
| starts a volume fade. 

```

```lua
function fade2 (voiceId, startValue, targetValue, duration, layer)
| starts a volume fade. 

```

--------------------------------

### Create and Configure AudioMeter Widget

Source: https://lua.uvi.net/class_audio_meter.html

Instantiates an AudioMeter widget and sets its bounds and color properties. Note that properties like '0dBColour' must be accessed using bracket notation due to Lua identifier rules.

```lua
meter = AudioMeter("out", Program, true, 0, true)
meter.bounds = {250, 0, 40, 100}
-- meter.0dBColour is not a valid Lua identifier, use bracket notation:
meter["0dBColour"] = "red"
meter["10dBColour"] = "blue"
```

--------------------------------

### Send Script Modulation Event with Start Value (sendScriptModulation2)

Source: https://lua.uvi.net/group___voice.html

Controls a Script Modulation source by ramping from a start value to a target value over a specified ramp time. If voiceId is omitted, the modulation is applied to all voices.

```lua
local id = playNote(note, vel)
local sourceIndex = 0
local startValue = 0.1
local targetValue = 0.5
local rampTime = 100 -- ramp to modValue over 100 ms
sendScriptModulation2(sourceIndex, startValue, targetValue, rampTime, id)
```

--------------------------------

### Initialize Script with Algorithmic Event Generation

Source: https://lua.uvi.net/group___event_callbacks.html

Initial callback executed after script initialization. Suitable for starting background processes like algorithmic event generation. UI widget creation is disabled here.

```lua
-- chromatic scale
function onInit()
local velocity = 100
for i=0,11 do
local note = 60 + i
local id = playNote(note, velocity, 0) -- manual release
waitBeat(0.5) -- 8th notes
releaseVoice(id)
end
end
```

--------------------------------

### length

Source: https://lua.uvi.net/class_multi_state_button-members.html

Gets the number of items in the MultiStateButton.

```APIDOC
## length

### Description
Returns the total number of items (states) currently in the MultiStateButton.
```

--------------------------------

### Timing and Note Playback in Lua

Source: https://lua.uvi.net/_a_p_i_page.html

Demonstrates playing a note, waiting for a specified duration, and then playing another note. Use `playNote` for note generation and `wait` for pausing execution.

```lua
function onNote(e)
playNote(60, 100, 500) -- Play C4 immediately
wait(250) -- Wait 250ms
playNote(64, 100, 500) -- Play E4
end
```

--------------------------------

### fade

Source: https://lua.uvi.net/group___voice.html

Starts a volume fade with a custom curve.

```APIDOC
## fade

### Description
Starts a volume fade.

### Parameters
- **voiceId** (any) - Description
- **targetValue** (any) - Description
- **duration** (any) - Description
- **layer** (any) - Description
```

--------------------------------

### browseForFile

Source: https://lua.uvi.net/group___async.html

Launches a file chooser dialog to select a file for opening or saving. This is an asynchronous operation.

```APIDOC
## browseForFile

### Description
Launches a file chooser to select a file to open or save.

### Parameters
- **mode** (string) - Required - The mode for the file chooser (e.g., 'open', 'save').
- **title** (string) - Required - The title of the file chooser dialog.
- **initialFileOrDirectory** (string) - Optional - The initial file or directory to display.
- **filePatterns** (array) - Optional - An array of file pattern strings (e.g., '*.wav').
- **callback** (function) - Required - A function to be called when the user selects a file or cancels the dialog. The callback receives the selected file path or null if canceled.

### Example
```lua
browseForFile('open', 'Select a sample file', nil, {'*.wav', '*.aif'}, function(filePath)
  if filePath then
    print('Selected file: ' .. filePath)
  else
    print('File selection canceled.')
  end
end)
```
```

--------------------------------

### fadein

Source: https://lua.uvi.net/group___voice.html

Starts a volume fade-in for a specific voice.

```APIDOC
## fadein

### Description
Starts a volume fade-in for a specific voice.

### Parameters
- **voiceId** (any) - Description
- **duration** (any) - Description
- **reset** (any) - Description
- **layer** (any) - Description
```

--------------------------------

### Usage Example for RectanglePlacement

Source: https://lua.uvi.net/class_rectangle_placement.html

Demonstrates how to set the rectangle placement for an Image widget. Ensure the Image widget and RectanglePlacement enum are accessible.

```lua
local img = Image("resources/logo.png")
img.rectanglePlacement = RectanglePlacement.Centred
img.bounds = {0, 0, 200, 100}
```

--------------------------------

### fadeout

Source: https://lua.uvi.net/group___voice.html

Starts a volume fade-out for a specific voice.

```APIDOC
## fadeout

### Description
Starts a volume fade-out.

### Parameters
- **voiceId** (any) - Description
- **duration** (any) - Description
- **killVoice** (any) - Description
- **reset** (any) - Description
- **layer** (any) - Description
```

--------------------------------

### Asynchronous File Loading in Lua

Source: https://lua.uvi.net/_a_p_i_page.html

Opens a file browser to select a sample file and then loads it into an oscillator. The callback function handles the result of the file selection.

```lua
browseForFile("open", "Select Sample", "", "*.wav;*.aif", function(task)
if task.success then
loadSample(Program.layers[1].keygroups[1].oscillators[1], task.result)
end
end)
```

--------------------------------

### Create and Configure a Button

Source: https://lua.uvi.net/class_button.html

Creates a push button widget and configures its appearance and behavior. The `changed` callback is set to print a message when the button is clicked.

```lua
b = Button("button")
b.backgroundColourOff = "darkgrey"
b.backgroundColourOn = "darkred"
b.textColourOff = "white"
b.textColourOn = "white"
b.changed = function(self, mods)
print("button clicked:", mods.altDown)
end
```

--------------------------------

### getBeatTime

Source: https://lua.uvi.net/group___context.html

Gets the current song position in beats.

```APIDOC
## getBeatTime()

### Description
Gets the song position in beats.

### Returns
- current song beat position (number)

### See Also
- getRunningBeatTime
- getTime
```

--------------------------------

### Browse for File

Source: https://lua.uvi.net/group___async.html

Launches a file chooser dialog for opening or saving files. Specify the mode, title, initial file/directory, and file patterns. A callback function is invoked upon completion.

```lua
browseForFile("open", "choose file to open", "", "", function(task) print(task.result) end)
```

```lua
function browseForFile(mode, title, initialFileOrDirectory, filePatterns, callback)
launch a file chooser to select a file to open or save
```
Tokens:
Raw