![]() |
uvi-script
Musical event scripting with Lua
|
Sample files carry more than audio: a root key, a fine tune, loop points, key and velocity ranges, a tempo. Which of those the engine reads depends on the file format, and which of the values it reads actually reach the sound depends on the oscillator. This page answers both questions, which is what matters when sample content is brought over from another sampler — a Kontakt library, an SFZ set, anything exported with loops and roots baked into the files.
The short version: loops live in the sample file, everything else lives in the mapping. A MultiSample zone takes its root, tune, gain and ranges from the .dmap and its loop from the file; the file's own root key and ranges are ignored there.
A file that starts with the FLAC signature (fLaC) is read as FLAC, whatever its extension says. Every other file — WAV, AIFF, and the other formats the engine opens — goes through the general reader. The two read different metadata, so the content of a file decides what is honoured, not its name.
| information | WAV | AIFF | FLAC |
|---|---|---|---|
| root key, fine tune | smpl, inst | INST | embedded smpl / inst, or INST |
| key and velocity ranges | inst | INST | embedded inst or INST |
| loop | smpl (first loop) | INST sustain loop + MARK | embedded smpl, or INST sustain loop + MARK |
| loop crossfade, sample start | UVI data in smpl | — | UVI data in embedded smpl |
| tempo, beats, time signature | acid | basc (tempo, beats) | embedded acid |
| gain | ignored | ignored | ignored |
"Embedded" is the key word for FLAC, described below.
The smpl chunk (WAV, or embedded in FLAC) is where loops are expected:
dwMIDIUnityNote (0 … 127), and the fine tune comes from dwMIDIPitchFraction;dwStart and dwEnd are in sample frames and dwEnd is inclusive — the frame it names is the last one played;A UVI sampler block inside smpl — the chunk's vendor-specific data — adds what the standard chunk cannot express: a loop crossfade and a sample start. It is honoured in WAV and FLAC alike.
The inst chunk (WAV, or embedded in FLAC) supplies the root key, the fine tune in cents, and the key and velocity ranges. When a file has both chunks, the root key and fine tune of inst take precedence over those of smpl, whatever their order in the file. Its gain field is ignored.
The acid chunk provides the tempo, the number of beats and the time signature. Its root note is used only when the chunk's root-note flag is set. In a FLAC file, an acid chunk that does not mark the file as a one-shot also loops the whole file forward; a WAV file's acid loop mode is ignored.
An AIFF file's INST chunk supplies the root key, the detune and the key and velocity ranges; it must be the standard 20 bytes. The loop is its sustain loop, located by the MARK markers it points to: mode 1 plays forward, mode 2 ping-pong. The release loop and the gain are ignored. A basc chunk supplies the tempo and the number of beats.
FLAC has no native loop or root metadata, so the reader looks for the foreign chunks that flac --keep-foreign-metadata stores when it encodes a WAV or AIFF file: APPLICATION blocks with the id riff or aiff. Their smpl, inst, acid, INST and MARK content is read as described above; together with STREAMINFO, that is all the reader takes from a FLAC file.
Everything else is ignored, notably:
VORBIS_COMMENT tags, including the LOOPSTART / LOOPLENGTH convention some tools write;CUESHEET and PICTURE blocks;cue, LIST/adtl, bext and regn chunks.So a FLAC loop survives only when the file was encoded from a looped WAV or AIFF with the foreign metadata kept. A FLAC file converted by a tool that drops it plays unlooped.
Cue points (cue), region lists (regn) and marker labels (LIST/adtl labl and ltxt) are never read, so markers and regions do not become loops or slices. Comment text is read from LIST/INFO ICMT, the AIFF COMT chunk, the Ogg comment and the bext description; the rest of bext is ignored.
For a zone of a MultiSample mapping, the split is strict:
from the mapping (.dmap, .xml, .sfz) | from the sample file |
|---|---|
root note (baseNote, 60 when absent) | loop start and end |
fine tune (tune) | loop mode |
gain (gain) | loop crossfade |
| key and velocity ranges | sample start and end |
round-robin index, purge and streaming state |
The file's root key, fine tune and ranges are ignored, and the .dmap format has no loop attributes. The file side is read again every time the zone loads, so editing a sample's loop takes effect on the next load of the mapping, with nothing to change in the .dmap. See The .dmap format.
An SFZ mapping is the one exception to the right-hand column: its loop_mode, loop_start, loop_end and loop_crossfade opcodes override the file's loop, and whatever a region leaves out still comes from the file — see The SFZ subset.
A Sample takes its start, end, loop and crossfade from the file — until the program stores playback options of its own, which happens once they are edited in the wave editor or set with setPlaybackOptions. From then on the program's values win over the file's.
The root key is an oscillator parameter, not a property of the loaded sample. The file's root is copied into it only when an oscillator is created from a file in the user interface; the metadata mode of a drag-and-drop also copies the key and velocity ranges. loadSample from a script leaves the root key as it was. The file's gain is never applied.
sampleInfo reports what the file says, whether or not the oscillator uses it: basenote and finetune are the file's root and fine tune, and loopStart / loopEnd its loop points. On a MultiSample oscillator it reads nil, since there is no single sample to describe.
.dmap. Whatever the source sampler stored in the files will not be used.smpl chunk in WAV, or FLAC encoded with flac --keep-foreign-metadata from such a WAV. One loop per file.dwEnd is inclusive when converting loop points from a format that stores an exclusive end or a length.sampleInfo on a Sample loaded with the file shows the loop points the engine found.