Runtime Sample Loading

This guide covers loading and replacing samples at runtime from your plugin’s JavaScript or TypeScript application layer. It does not describe a Gorilla Editor download feature. Use Gorilla Editor beforehand to define the instrument structure, mappings, zones, and default sample configuration.

Instrument Structure Overview

An instrument’s playback is controlled by Mappings, which are containers that define which audio samples should be loaded and how they are positioned across the keyboard. Within each mapping, Zones are the fundamental building blocks. A Zone holds the file path for a specific sample and its associated playback parameters (e.g., loop points, start/end times). For a complete list of supported Zone parameters, please refer to the Module Reference.

1. Instrument Preparation and Mapping

To load samples, you must first prepare the instrument by defining its Mappings.
The most straightforward approach is to create a single mapping for each unique sample you intend to use. However, the final choice of instrument design (e.g., a multi-sample drum kit or a singular looping player) will determine the best overall mapping strategy.

2. Creating and Configuring Zones

Once a mapping exists, you must create a Zone inside it and configure it. This can be done in the Gorilla Editor beforehand or while loading samples programmatically at runtime.

• Setting the Sample Path: The zone’s sample path must be set to the location of the file on disk. Crucially, the path must be prefixed with the < character to indicate that it is a user-defined sample path.
• Parameter Configuration: Configure all necessary Zone parameters (such as loop settings, start/end offsets, etc.) to define the desired playback behavior. Use the “Read from sample meta data” option during sample import in Gorilla Editor to do this automatically.

3. Loading Samples at Runtime

There are two distinct methods for updating content within your instrument:

• Adding or Replacing an entire Zone (Module): To replace an entire zone, including all its parameters and the associated sample, use the functions isModuleAtPath, removeModuleAtPath & setModuleAtPath (or in future versions of the Gorilla SDK: replaceModuleAtPath) that are callable on the instrument.
• Replacing Only the Sample File: If the existing zone setup and parameters are already correct, and you only need to change the audio file itself, use the setStringAtPath function to update the sample path string.

4. Supported Audio Formats

The audio engine natively supports AIFF and WAVE files.

• MP3 Conversion: If you are working with MP3 files, a built-in function allows you to convert them to the supported WAVE format:
  await GorillaEngine.convertMp3ToWav(src, dest)

• Any other audio formats must be converted to an accepted file type within your application layer before loading.

5. Downloading Samples in Application Code

Downloading files is an application-layer responsibility, not a Gorilla Editor feature. Your plugin application can use the Node.js fetch API to download a sample to disk before assigning the local file path to a Zone. For example:

import { createWriteStream } from 'node:fs';
import { unlink } from 'node:fs/promises';
import { pipeline } from 'node:stream/promises';

/**
 * Download a remote file to a local path.
 * Throws on failure.
 */
export async function downloadFile(fileUrl, destinationPath) {
  console.log(`Downloading: ${fileUrl} -> ${destinationPath}`);
  const response = await fetch(fileUrl);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status} ${response.statusText}`);
  }
  const body = response.body;
  if (!body) throw new Error('No response body');
  const out = createWriteStream(destinationPath);
  try {
    await pipeline(body, out);
    console.log('Download complete');
  } catch (err) {
    // Attempt cleanup of partial file
    try { await unlink(destinationPath); } catch {}
    throw err;
  }
}