![]() |
uvi-script
Musical event scripting with Lua
|
A multi-zone sample dispatcher. More...
Public Types | |
| enum | Parameters { MappingPath , InterpolationMode , RoundRobinMode , SampleStartMillisecond } |
| SampleMappingOscillator Parameters. More... | |
Public Types inherited from Oscillator | |
| enum | Parameters { Pitch , NoteTracking , BaseNote , Gain , CoarseTune , FineTune } |
| Oscillator Parameters. More... | |
Public Member Functions | |
| bool | loadMapping (string path) |
| load a mapping file, replacing the oscillator's whole zone set. | |
| AsyncTask | loadMapping (string path, function completion) |
| load a mapping file and report the outcome. | |
| void | clearMapping () |
drop every zone, cut every voice of the keygroup and clear MappingPath. | |
| void | purgeZones (int dim1, int dim2) |
| free the samples of the matching zones. | |
| void | unpurgeZones (int dim1, int dim2) |
| reload previously purged zones. | |
| AsyncTask | unpurgeZones (int dim1, int dim2, function completion) |
| reload previously purged zones and report when they are in. | |
| number | getLoadingStatus () |
| loading progress, 0 to 1. | |
| int | getNumZones () |
| void | waitForLoading () |
| block until pending loads complete. | |
Public Member Functions inherited from Oscillator | |
| table | getSliceInfo (int sliceId) |
| get slice information for the given sliceId. | |
Public Member Functions inherited from Element | |
| void | setParameter (string parameter, Value value) |
| Sets an Element parameter. | |
| Value | getParameter (string parameter) |
| Gets an Element parameter. | |
| bool | hasParameter (string parameter) |
| table | getParameterConnections (string parameter) |
| Get all SignalConnection for this parameter. | |
| AsyncTask | insertEffect (string type, int slot, function completion) |
| Insert a new effect in this element's insert chain. | |
| AsyncTask | removeEffect (int slot, function completion) |
Remove the effect at slot from this element's insert chain. | |
| AsyncTask | moveEffect (int from, int to, function completion) |
Move the effect at from so that it ends up at to in this element's insert chain. | |
Additional Inherited Members | |
Public Attributes inherited from Oscillator | |
| Keygroup | keygroup |
| parent keygroup for this oscillator | |
| bool | purged |
| purged status for this oscillator (when true sample is not loaded in memory) | |
| int | numSlices |
| number of slices (only valid for Slice oscillator) | |
| table | looplabInfo |
| looplab information. | |
| table | sampleInfo |
| sample information. | |
Public Attributes inherited from Element | |
| string | name |
| internal element name | |
| string | displayName |
| name to display on the User Interface, name is used if displayName is not specified. | |
| string | type |
| internal element type | |
| string | path |
| full path of the element in the synthesis tree | |
| Element & | parent |
| element parent | |
| table | children |
| element children using the element name as key | |
| table | synthChildren |
| children of the element in the synthesis hierarchy, as a 1-indexed array. | |
| table | mods |
all ControlSignalSource for this node as a 1-indexed array (same content as modulations, keyed by index instead of name) | |
| int | output |
| output bus index for the element. Reading returns the index parsed from the current output bus name (1 when the element uses the default bus). Writing is asynchronous: the engine applies the new routing shortly after the assignment, so reading the property back immediately may still return the old value. Assigning on an element that cannot change its output raises an error. | |
| int | numParams |
| number of parameters | |
| table | parameterDefinitions |
| table of parameter definitions. | |
A multi-zone sample dispatcher.
Holds a whole sample set as a list of zones and selects one per note along four axes — key, velocity, and the two script-controlled dimensions dim1 (logical layer: articulation, microphone, dynamic) and dim2 (round-robin variant). The zone list is read from a mapping file (.dmap, .xml or .sfz).
See MultiSample (SampleMappingOscillator) for the mapping file format, the dispatch model, and the loading pitfalls this reference only summarises.
Falcon 27 also lets it treat the recorded velocity layers as a ladder and crossfade between them under a per-voice control — see Velocity dynamics. Those parameters, DynamicsMode, Morph, VelMorph, DynamicRange, Curve, VelGainRange, VelGainCurve and VelGainKeyTrack, have no constant in the enum below and are addressed by name:
loadMapping and free memory with purgeZones / unpurgeZones.SampleMappingOscillator Parameters.
| Enumerator | |
|---|---|
| MappingPath | resolved path of the mapping the oscillator holds. Read-only in practice: writing it records the string without loading anything |
| InterpolationMode | resampling quality: 0 = Lo-fi, 1 = Standard (default), 2 = Best |
| RoundRobinMode | variant policy: 0 = First, 1 = Cycle (default), 2 = Random |
| SampleStartMillisecond | per-voice sample start in ms; use setSampleOffset. Capped by the zone's |
| number SampleMappingOscillator::getLoadingStatus | ( | ) |
loading progress, 0 to 1.
This is what a script waits on, and what drives a progress display: it drops to 0 as soon as loadMapping is called, before the mapping is even parsed, and climbs back to 1 when every zone has finished — including zones an unpurgeZones batch added while it was running, so a bar driven by it completes when everything really is in.
The drop-to-0 guarantee is specific to loadMapping. unpurgeZones does not move this value until its work reaches the worker, which is why it takes a completion of its own.
| int SampleMappingOscillator::getNumZones | ( | ) |
| bool SampleMappingOscillator::loadMapping | ( | string | path | ) |
load a mapping file, replacing the oscillator's whole zone set.
Returns immediately; the samples arrive on a background thread. Poll getLoadingStatus to wait for them.
MappingPath, which loads with the preset before any script code runs; a load started from onInit only exists after the first notes have been handled. See Program load and warm-up.| path | mapping file (.dmap, .xml or .sfz). Tried as written, then against the script's folder, the program's folder, the performance's folder, the program's original folder, and finally the samples folder declared by the program's volume – see Path resolution |
path is empty | AsyncTask SampleMappingOscillator::loadMapping | ( | string | path, |
| function | completion ) |
load a mapping file and report the outcome.
The completion runs once every zone has finished loading or failed, and the task's success says whether they all made it. Waiting is still getLoadingStatus's job — this answers whether the load worked, not when it ended.
| path | mapping file; resolved as above |
| completion | a function called with the AsyncTask, or true to get the task back without a callback and poll it yourself |
| void SampleMappingOscillator::purgeZones | ( | int | dim1, |
| int | dim2 ) |
free the samples of the matching zones.
| dim1 | the logical layer |
| dim2 | the round-robin variant, or a negative value for the whole dim1 layer |
| void SampleMappingOscillator::unpurgeZones | ( | int | dim1, |
| int | dim2 ) |
reload previously purged zones.
Asynchronous: the samples arrive on a background thread, so the zones become audible some time after this returns.
| dim1 | the logical layer |
| dim2 | the round-robin variant, or a negative value for the whole dim1 layer |
| AsyncTask SampleMappingOscillator::unpurgeZones | ( | int | dim1, |
| int | dim2, | ||
| function | completion ) |
reload previously purged zones and report when they are in.
The completion runs once every zone of this batch has finished loading or failed, and the task's success says whether they all made it. Take it rather than polling getLoadingStatus: that reports on the mapping's loading overall and still reads 1 in the window between this call and the worker picking it up, so a note fired on the strength of it lands on zones that have not arrived and plays silence.
| dim1 | the logical layer |
| dim2 | the round-robin variant, or a negative value for the whole dim1 layer |
| completion | a function called with the AsyncTask, or true to get the task back without a callback and poll it yourself |
| void SampleMappingOscillator::waitForLoading | ( | ) |
block until pending loads complete.
getLoadingStatus does, so it can return before the load it was meant to wait for has even started.