uvi-script
Musical event scripting with Lua
Sample File Metadata

Overview

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.

How a file is read

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.

What each format provides

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

The smpl chunk (WAV, or embedded in FLAC) is where loops are expected:

  • the root key is dwMIDIUnityNote (0 … 127), and the fine tune comes from dwMIDIPitchFraction;
  • only the first loop is used; further loops are ignored;
  • loop type 0 plays forward, 1 ping-pong, and 2 (backward) plays forward; any other type leaves the sample unlooped;
  • dwStart and dwEnd are in sample frames and dwEnd is inclusive — the frame it names is the last one played;
  • the play count is ignored: a loop repeats for as long as the voice sustains.

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

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

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.

AIFF

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

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;
  • embedded 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.

Ignored in every format

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.

What reaches the sound

MultiSample zones

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.

SamplePlayer

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.

Reading it from a script

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.

Porting checklist

  1. Write the root note, fine tune, gain and key and velocity ranges of every zone into the .dmap. Whatever the source sampler stored in the files will not be used.
  2. Put the loops in the sample files: a smpl chunk in WAV, or FLAC encoded with flac --keep-foreign-metadata from such a WAV. One loop per file.
  3. Remember that dwEnd is inclusive when converting loop points from a format that stores an exclusive end or a length.
  4. Do not rely on cue points, regions, marker labels or FLAC tags to carry a loop; none of them is read.
  5. Check the result from a script: sampleInfo on a Sample loaded with the file shows the loop points the engine found.
See also
MultiSample (SampleMappingOscillator), Sample, sampleInfo, Porting from Kontakt (KSP)