uvi-script
Musical event scripting with Lua
Change log

Falcon 27.0.4 & UVI Player 5.0.2

MultiSample

  • added Morph (0 … 1, per voice), the ladder position in Continuous mode; VelMorph is now Velocity XFade only – see Driving it from script
  • VelMorph is modulated in its own units: a bipolar source at ratio 1 sweeps -1 … 1
  • the morphing modes accept layers of different lengths, e.g. a hi-hat from closed to open – see What makes a ladder

Falcon 27.0.3 & UVI Player 5.0.1

  • ParamKnob and ParamSlider take a default property, the value restored by a reset, overriding the parameter's own default – e.g. 0 for a modulation depth, whose Ratio defaults to 1
  • added getUserLocation(product[, vendor]): a per-product folder in Documents for user presets and data, shared by every host product and created if missing
  • added listFiles(path, patterns, recursive, callback), which lists a folder (sound banks included) asynchronously and returns an AsyncListFilesTask
  • browseForFile in save mode creates the folder of the proposed path when it is missing
  • added the UserPresetBrowser example: a user preset manager built on listFiles, saveData, loadData and browseForFile
  • WaveView draws the RMS level inside the peak envelope; showPeak and showRms choose which of the two layers are drawn (both on by default) – e.g. showRms = false for a peaks-only wave

Falcon 27 & UVI Player 5.0.0

MultiSample

  • added the SampleMappingOscillator, listed as MultiSample in the element browser: multi-dimensional zone mapping with round robin, driven from script – see MultiSample (SampleMappingOscillator)
  • velocity dynamics: DynamicsMode plays one zone per note (Velocity) or reads the zones of the velocity ladder together and crossfades between them under the per-voice VelMorph control (Continuous, Velocity XFade); DynamicRange and Curve shape the travel, VelGainRange / VelGainCurve / VelGainKeyTrack hold the velocity-to-level law. All seven are set by name and have no uvi.SampleMappingOscillator constant – see Velocity dynamics
  • mapping files carry the calibration next to the zones: <velGain> and <velXFade> on layers, <velFilter> on a zone, either a velocity-scaled high-shelf (type="shelf") or a one-pole lowpass whose corner tracks velocity across the zone (type="lp") – see Per-zone timbre correction. A layer's name (SFZ: group_label) is kept for display
  • loadMapping loads a mapping file (.dmap or the SFZ subset) and returns whether the request was accepted, not whether it succeeded; the same call with a callback, or with true, returns an AsyncTask instead, whose task.success is the only report of an actual failure
  • added clearMapping, purgeZones and unpurgeZones to free and reload the samples of one zone or, with a negative second argument, of a whole layer; plus getNumZones and getLoadingStatus, which reports loading progress from 0 to 1
  • unpurgeZones with a completion reports when an unpurged layer's zones are actually in. getLoadingStatus does not answer that question – it reports on the mapping overall and still reads 1 until the unpurge reaches the worker, so notes routed at the layer on the strength of it play silence
  • SFZ mappings honour the loop opcodes loop_mode (no_loop, one_shot, loop_continuous, loop_sustain), loop_start, loop_end and loop_crossfade, falling back to the sample file's markers and then to the whole sample for whatever a region leaves out, so a sample without embedded loop markers can loop; a one_shot zone plays to its end whatever the note-off (Falcon 27.0.3) – see The SFZ subset
  • the oscillator's Parameters enum carries MappingPath, InterpolationMode, RoundRobinMode and SampleStartMillisecond, the last one shared with Sample

Insert effects

  • scripts can edit insert chains: insertEffect, removeEffect and moveEffect on any node that has inserts. They are asynchronous and return an AsyncTask; task.success is false for an unknown type or a slot that no longer exists. moveEffect keeps the effect itself, with its settings, modulations and audio tail – see the FX Rack example
  • moving an effect within its chain in the Falcon rack no longer recreates it, so a reverb or delay tail carries on through the move
  • replacing an effect by one of another type no longer crashes a parameter-bound widget (or any Falcon control) pointing at it: the replacement takes the freed name of the effect it replaces, and a control whose element lacks its parameter now reads as unbound until it is bound again

Notes and MIDI

  • playNote takes dim1 and dim2, as trailing arguments or as table fields, to dispatch a note to a mapping zone. They are ignored when a slice is given, and the automatic note-off does not carry them
  • postEvent carries dim1 and dim2 on a note-on as well, which promotes the event to a mapping dispatch. Incoming events expose event.dim1 and event.dim2 only when they came from such a dispatch – an ordinary MIDI note has neither

User interface

  • widgets can be dragged onto each other: a Button carries a text in dragAndDropText, and a DnDArea of the same script accepts the texts starting with its acceptedText and calls textDropped. A DnDArea only catches the mouse while a drag it may accept is under way, so it can lie over other widgets
  • parameter-bound widgets (ParamKnob, ParamSlider, ParamOnOffButton, ParamMenu, ParamNumBox, ParameterValue) can be retargeted with bind(elementOrPath, paramName), and created with a name only to start unbound. A widget whose element is deleted reads as unbound instead of pointing at freed memory
  • widgets can wear a Lottie vector animation instead of a strip of bitmaps: Button, OnOffButton, Knob, Slider, ParamKnob, ParamSlider, ParamOnOffButton and AudioMeter take lottieAnimation / setLottieAnimation. A .lottie package that declares a state machine runs it on its own, which is what gives a control its hovered and pressed look – see Lottie Animations
  • buttons can be dressed from a single strip image holding one frame per state, stacked off, on, hovered off, hovered on, held off, held on: stripImage / setStripImage on Button, OnOffButton and ParamOnOffButton, as the knobs and sliders already had
  • the parameter-bound widgets expose the bound parameter through value, typed as the parameter is – number, boolean or string – and nil until the binding resolves
  • ParamKnob and ParamSlider can override what they inherit from the parameter, with setRange(min, max) and unit. The other bound widgets cannot
  • bound widgets are persisted in script presets by default; pass persistent = false to opt out. Paths are stored relative, and a binding written with a wildcard is not persisted (the console says so). ParameterValue is never persisted

Falcon 26.0.4 & UVIWorkstation 4.0.6

Falcon 26 & UVIWorkstation 4.0.4

  • added SVG widget
  • added Label.url property to open URLs on click

Falcon 3.0.2 & UVIWorkstation 3.1.14

  • added WaveView widget
  • added setPlaybackOptions function for sample based oscillators

Falcon 2.8.4 & UVIWorkstation 3.1.10

  • added popup menu colours customization for Menu

Falcon 2.8.3 & UVIWorkstation 3.1.9

Falcon 2.5.4 & UVIWorkstation 3.1.4

  • added Viewport widget
  • added AudioMeter image strip support
  • added more Mapper choices
  • added over image support in Button
  • added setBackgroundColour for main Panel
  • added displayExtension and invertColourOnSelection in FileSelector widget
  • added minimumHorizontalScale for Menu

Falcon 2.1.5 & UVIWorkstation 3.0.18

Falcon 2.1.4 & UVIWorkstation 3.0.17

Falcon 2.1.1 & UVIWorkstation 3.0.15

  • added Widget.unit to support unit display in parameters

Falcon 2.1.0 & UVIWorkstation 3.0.15

Falcon 2.0.7 & UVIWorkstation 3.0.12

  • added getRunningBeatTime. Similar to getBeatTime but with a monotonic clock when the transport is stopped
  • added loadTextData and saveTextData which allows to read plain text file from the script similar to json based loadData

Falcon 2.0.0 & UVIWorkstation 3.0.6

Falcon 1.5.3 & UVIWorkstation 3.0.0

  • added optional oscIndex parameter to playNote to target specific oscillators

Falcon 1.0.2 & UVIWorkstation 2.6.0

Falcon 1.0.0 & UVIWorkstation 2.5.16

UVIWorkstation 2.5.11

UVIWorkstation 2.5.4

MachFive 3.2.2 & UVIWorkstation 2.2.1

  • added browseForFile()
  • added warning about invalid parameter names (triggers a warning for previous scripts and an assert for newly created scripts)

MachFive 3.2.1 & UVIWorkstation 2.1.7

MachFive 3.2 & UVIWorkstation 2.1.6

MachFive 3.1.3 & UVIWorkstation 2.0.8

MachFive 3.1.2 & UVIWorkstation 2.0.7

  • added purging to all sample-based oscillators
  • added Menu.align

MachFive 3.1

MachFive 3.0.3

  • added onTransport callback to be notified of transport bar state changes
  • added triggeredOnMouseDown on Button widget which sets whether the button click should happen when the mouse is pressed or released

MachFive 3.0.2

  • systematic pairing of voiceId between noteOn and noteOff
  • added onLoad, and onSave
  • added Widget setValue and displayName
  • added new Panel Widget container