HISE Docs

Sampler

Type ID: StreamingSampler
Interface classes: Sampler TableProcessor RoutingMatrix

The sampler module of HISE


One of the key highlights of HISE is to build sample based VSTis. The main module for that task is the Sampler .

The Sampler is a disk streaming sampler which leverages the full power of the HISE Engine. It is optimized to play a lot of voices in parallel and allows to map samples in SampleMaps up to an individual SampleMap-size of 4GB.

The samples can be arranged in a three-dimensional map to account for Note number(x), Velocity(y) and Round Robin Groups(z) and a lot of tools are provided to map and edit your samples quick and efficiently.

General Workflow :

Sampler Tabs

The Sampler features four special edit tabs:

Additional to the default chains, it features two extra Modulation Chains to modulate the Sample Start of samples and the Group Fade between different RRGroups.

Sample Maps

You can load and save SampleMaps independently from the Sampler as human-readable .xml files, which makes it an own sampler file format. It saves all the individual sample-settings that you give your samples in the Map- and Sample-Editor.

Timestretching

Starting with HISE 3.5.1 the sampler module has an inbuilt timestretching mode that allows you to independently control pitch and time of your samplemaps.

It's using the (slightly modified) timestretching algorithm from signalsmith which is a pretty new library with a reasonably good performance / sound quality ratio. It's licensed permissively which means that the library can be embedded into the HISE codebase and used in proprietary projects.

In order to use the timestretching mode, just switch the mode in the Sampler Settings and adjust the stretch ratio using either the slider on the Sampler Settings (if applicable) or the scripting API call Sampler.setTimestretchRatio() . There are four modes which define how this stretch ratio is applied to the samples:

Mode Description
Disabled The default state with timestretching disabled. There's almost no CPU overhead if this is disabled to ensure that the CPU performance of most projects will stay the same.
VoiceStart This mode will use the current stretch ratio and apply it statically to new voices. This allows you to define different stretch ratios for different voices.
TimeVariant This mode will apply the current stretch ratio to all voices. This allows you to define a dynamic stretch ratio, but all voices will have the same ratio.
TempoSynced This mode will ignore the manual stretch ratio and automatically sync the stretch ratio to the BPM of the master clock. By default it tries to detect the musical length of a sample using the current tempo, but that automatic detection can be overriden by supplying a NumQuarters property to the timestretching options.

Be aware that if the timestretch mode is anything else than Disabled , it will process the sample using the timestretching library, even if the time and pitch ratio are 1.

If the timestretching is enabled, any pitch modulation (using the modulation or root note detune) will not change the pitch using resampling but with the pitch transposition of the timestretch algorithm which retains the duration of the sample.

Timestretching Options

In addition to the timestretching mode, there are several other options which allow you to customize the timestretching:

Property Type Default Description
Mode String "Disabled" the timestretching mode (as described above). Changing this mode will kill all voices and refresh the voice states on the background thread.
SkipLatency bool false If true, starting a new voice will skip the inherent latency of the timestretching algorithm. This vastly improves the timing of the voice, however it comes with a pretty steep CPU overhead because it has to (silently) calculate the timestretched signal for the duration of the latency (about 50ms).
NumQuarters double 0.0 if this is not 0.0, it will skip the automatic detection of the sample length when in tempo-synced mode and use this value to determine the BPM of the source sample (so you will need to set this to the value of your loop lengths).
Tonality double 0.0 This value allows you to retain the timbre when using pitch transposition.

Be aware that there is no UI interface for these properties in HISE (except for the mode). Instead, you will have to use the scripting API calls that query and set these properties from a JSON object.

// fetch the current state
const var obj = Sampler.getTimestretchOptions();

// print out all properties
Console.print(trace(obj));

// Apply your changed
obj.SkipLatency = true;

// Update the options
Sampler.setTimestretchOptions(obj);

Compress and Export

Export to HLAC (Monolith)

A freshly mapped SampleMap plays the samples directly from the Samples folder. This is not the most efficient way to play samples, though, especially if you have a lot of mapped samples.

Here the HLAC (HISE Lossless Audio Codec) comes in to compress all the SampleMaps samples into one big "monolith" chunk. Export to HLAC will render your samples in a single compressed file, to have faster access to the audio material. This shrinks the overall filesize + speeds up general file access. The .ch1 monolith files will end up in the root directory of the Samples Folder .

Read this Forum entry of Christoph if you want to understand how it works behind the hood: HISE Lossless Audio Codec is ready

There are three modes in which the HLAC (.ch1) file can be processed:

No Normalization

No Normalization just takes the samples and compresses them into the monolith file.

Normalise every sample

This normalises every sample individually and compressed them together.

Full Dynamics

Full Dynamics is a mode that leverages the higher resolution of 24bit samples.

Behind the scenes Full Dynamics still uses 16bit, but normalises the samples internally in chunks of 1024 samples so that decaying samples still use the full available bit depth.

This way you get the advantages of a 16bit signal path (half memory usage for all the streaming buffers) but the quantisation noise at the end of a sample is not audible anymore (which can happen if you heavily compress or distort the sound).

During the extraction process of the samples the user can decide for herself if she favors disk usage or sound quality. But with Full Dynamics enabled, the .hr1 archive file uses 24bit FLAC encoding, otherwise the normalisation would be pointless.

If your material is 16bit from the start, you won‘t get any benefits from using Full Dynamics. Just disable it at exporting and the end user will not have this option.

Hise Resources Archive File

If you want to distribute the samples to the enduser you have the option to compress the monoliths (lossless) further for delivery. Export > Export Samples for installer .

The HLAC codec is optimized for maximal decoding performance so a standard lossless algorithm like FLAC can provide you with a 10%-20% better compression ratio.

The Hise Resource is a file archive that uses the FLAC codec and splits up the files into customizable chunks of 500MB - 1GB. So if you compress a 3.7GB library and choose 1GB file size, you will get these files:

Samples.hr1 // 1GB
Samples.hr2 // 1GB
Samples.hr3 // 1GB
Samples.hr4 // 700MB

When the user runs the plugin for the first time they will be asked to locate the HR files that were shipped with the instrument/plugin. The monoliths will be extracted to their chosen location, after which the user can opt-in to delete the HR files.

A thorough explanation of this process can be found on the excellent user manual of David Healey's Sofia Woodwinds :

Parameters

# ID Description
4 PreloadSize The preload size in samples for all samples that are loaded into the sampler. If the preload size is -1 , then the whole sample will be loaded into memory.
5 BufferSize The buffer size of the streaming buffers (2 per voice) in samples.
The sampler uses two buffers which are swapped (one is used for reading from disk and one is used to supply the sampler with the audio data)
6 VoiceAmount The amount of voices that the sampler can play.
7 RRGroupAmount The number of groups that are cycled in a round robin manier. This is effectively just another dimension for mapping samples and can be used for many different purposes (handling round robins is just the default).
8 SamplerRepeatMode Determines how the sampler treats repeated notes.
9 PitchTracking Enables pitch ratio modification for different notes than the root note. Disable this for drum samples.
10 OneShot Plays the whole sample (ignores the note off) if set to enabled.
11 CrossfadeGroups If enabled, the groups are played simultanously and can be crossfaded with the Group-Fade Modulation Chain.
12 Purged If Enabled , it will unload all preload buffers and deactivate the sample playback to save memory. The Lazy load option unloads all preload buffers and delays the preloading of a sample until it is triggered for the first time.
13 Reversed If this is true, the samples will be fully loaded into preload buffer and reversed
14 UseStaticMatrix If this is true, then the routing matrix will not be resized when you load a sample map with another mic position amount.
15 LowPassEnvelopeOrder -
16 Timestretching -

Chains

# ID Restriction Description
4 Sample Start Allows modification of the sample start if the sound allows this. The modulation range is depending on the SampleStartMod value of each sample.
5 Group Fade Fades between the RR groups. This can be used for crossfading dynamics samples.
4 Sample Start All types -
Join Discussion Next: Sine Wave Generator