uvi-script
Musical event scripting with Lua
SampleMappingOscillator Class Reference

A multi-zone sample dispatcher. More...

Inheritance diagram for SampleMappingOscillator:
Oscillator Element

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.
 

Detailed Description

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:

osc:setParameter("DynamicsMode", 2) -- Velocity XFade, for the notes to come
osc:setParameter("VelMorph", 0.25) -- reaches the voices already playing
void setParameter(string parameter, Value value)
Sets an Element parameter.
local osc = Program.layers[1].keygroups[1].oscillators[1]
osc:loadMapping("Mappings/violin.dmap")
spawn(function() -- wait() only suspends inside a callback or a spawned thread
while osc:getLoadingStatus() < 1.0 do wait(50) end
print(osc:getNumZones(), "zones")
end)
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
table layers
Layer list for this Program (1-indexed, use #Program.layers to get the count)
Definition Engine.cpp:359
bool loadMapping(string path)
load a mapping file, replacing the oscillator's whole zone set.
number getLoadingStatus()
loading progress, 0 to 1.
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39
function spawn(fun,...)
Launch a function in a separate parallel execution thread (deferred execution)
Definition api.lua:1338
Note
A script drives an oscillator the program already contains; it cannot create one. Inserting a "MultiSample" oscillator is a user action, from the element browser.
It derives from Oscillator, not from SampleBasedOscillator, so the generic sample calls do not apply — and they fail in different ways. loadSample and setPlaybackOptions raise. purge / unpurge do nothing while still reporting success, and purged always reads false. Load through loadMapping and free memory with purgeZones / unpurgeZones.
Every method below exists only on this class, so calling one on a different oscillator raises rather than doing nothing — check type first.

Member Enumeration Documentation

◆ Parameters

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 maxSampleStart when the sample is streamed

Member Function Documentation

◆ getLoadingStatus()

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.

spawn(function()
while osc:getLoadingStatus() < 1.0 do wait(30) end
print("ready")
end)
string path
full path of the element in the synthesis tree
Definition Engine.cpp:205
Returns
the fraction of zones that have finished loading or failed. 1 when no mapping is loaded and none is on its way.

◆ getNumZones()

int SampleMappingOscillator::getNumZones ( )
Returns
the number of zones in the live mapping, 0 when none is loaded

◆ loadMapping() [1/2]

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.

Warning
The return value is not a success indicator — the load is queued and this returns true whatever happens next, the only false being an empty path. Pass a completion function to learn whether the mapping loaded.
Note
This is for switching mappings at run time. The program's own mapping belongs in its 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.
Parameters
pathmapping 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
Returns
true unless path is empty

◆ loadMapping() [2/2]

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.

Parameters
pathmapping file; resolved as above
completiona function called with the AsyncTask, or true to get the task back without a callback and poll it yourself
Returns
an AsyncTask

◆ purgeZones()

void SampleMappingOscillator::purgeZones ( int dim1,
int dim2 )

free the samples of the matching zones.

Parameters
dim1the logical layer
dim2the round-robin variant, or a negative value for the whole dim1 layer

◆ unpurgeZones() [1/2]

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.

Parameters
dim1the logical layer
dim2the round-robin variant, or a negative value for the whole dim1 layer

◆ unpurgeZones() [2/2]

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.

Parameters
dim1the logical layer
dim2the round-robin variant, or a negative value for the whole dim1 layer
completiona function called with the AsyncTask, or true to get the task back without a callback and poll it yourself
Returns
an AsyncTask

◆ waitForLoading()

void SampleMappingOscillator::waitForLoading ( )

block until pending loads complete.

Warning
Do not call this from a script: it blocks the audio thread, and it races the same way getLoadingStatus does, so it can return before the load it was meant to wait for has even started.