spessasynth_core 4.4.3 → 4.4.5

package/dist/index.d.ts

@@ -289,6 +289,27 @@ export declare const GeneratorTypes: Readonly<{
   readonly vibLfoToVolume: 65;
   readonly modLfoRate: 66;
   readonly modLfoAmplitudeDepth: 67;
+  readonly ignoreNoteOff: 68;
+  readonly delayVoice: 69;
+  readonly fadeVibLFO: 70;
+  readonly fadeModLFO: 71;
+  readonly vibLfoWaveform: 72;
+  readonly modLfoWaveform: 73;
+  readonly vibLfoStartPhase: 74;
+  readonly modLfoStartPhase: 75;
+  readonly maxFilterFc: 76;
+  readonly decay2VolEnv: 77;
+  readonly sustain2VolEnv: 78;
+  readonly delayModEnv2: 79;
+  readonly attackModEnv2: 80;
+  readonly holdModEnv2: 81;
+  readonly decayModEnv2: 82;
+  readonly sustainModEnv2: 83;
+  readonly releaseModEnv2: 84;
+  readonly keyNumToModEnv2Hold: 85;
+  readonly keyNumToModEnv2Decay: 86;
+  readonly modEnv2ToPitch: 87;
+  readonly modEnv2ToFilterFc: 88;
 }>;
 /**
  * @inheritDoc GeneratorTypes
@@ -331,6 +352,17 @@ export interface GeneratorLimit {
    * SoundFont2 NRPN scale factor for this generator type.
    */
   nrpn: number;
+  /**
+   * Minimum value of this generator in a preset zone.
+   * Preset generators are offsets added to the instrument, so they can go below the instrument range.
+   * If not set, it is the same as `min`.
+   */
+  presetMin?: number;
+  /**
+   * Maximum value of this generator in a preset zone.
+   * If not set, it is the same as `max`.
+   */
+  presetMax?: number;
 }
 /**
  * Limits and defaults for all the {@link BasicSoundBank} generator types.
@@ -653,53 +685,27 @@ export declare class BasicZone {
    */
   copyFrom(zone: BasicZone): void;
 }
-/**
- * Represents a single instrument zone with an associated {@link BasicSample}.
- *
- * @group Sound Banks.Zones
- */
-export declare class BasicInstrumentZone extends BasicZone {
-  /**
-   * The instrument this zone belongs to.
-   */
-  readonly parentInstrument: BasicInstrument;
-  /**
-   * Zone's sample.
-   */
-  private _sample;
-  /**
-   * The sample associated with this zone.
-   */
-  get sample(): BasicSample;
-  /**
-   * Sets a sample for this zone, unliking the previous one from it.
-   * @param sample The sample to set.
-   */
-  set sample(sample: BasicSample);
-}
 /**
  * Represents a single preset zone with an associated {@link BasicInstrument}.
  *
  * @group Sound Banks.Zones
  */
-export declare class BasicPresetZone extends BasicZone {
+export declare class BasicPresetZone extends BasicLinkedZone<BasicPreset, BasicInstrument> {
+  protected readonly childGenerator: 41;
   /**
    * The preset this zone belongs to.
    */
-  readonly parentPreset: BasicPreset;
-  /**
-   * The instrument associated with this zone.
-   */
-  private _instrument;
+  get parentPreset(): BasicPreset;
   /**
    * The instrument associated with this zone.
    */
   get instrument(): BasicInstrument;
   /**
-   * Sets an instrument for this zone, unliking the previous one from it.
+   * Sets an instrument for this zone, unlinking the previous one from it.
    * @param instrument The instrument to set.
    */
   set instrument(instrument: BasicInstrument);
+  protected getChildList(bank: BasicSoundBank): BasicInstrument[];
 }
 /**
  * SpessaSynth 4.0 brings the full bank LSB support in the API.
@@ -825,6 +831,135 @@ export declare class MIDIPatchTools {
   static selectPatch<T extends MIDIPatchFull>(patches: T[], patch: MIDIPatch, system: MIDISystem): T;
   private static getAnyDrums;
 }
+/**
+ * Represents a single preset.
+ * This is what is used for MIDI playback.
+ *
+ * @group Sound Banks
+ */
+export declare class BasicPreset implements MIDIPatchFull {
+  /**
+   * The parent soundbank instance
+   * Currently used for determining default modulators and XG status
+   */
+  readonly parentSoundBank: BasicSoundBank;
+  /**
+   * The preset's name.
+   */
+  name: string;
+  program: number;
+  bankMSB: number;
+  bankLSB: number;
+  isGMGSDrum: boolean;
+  /**
+   * The preset's zones.
+   * These are limited to specific key/velocity ranges and contain associated instruments.
+   */
+  zones: BasicPresetZone[];
+  /**
+   * Preset's global zone.
+   * Its parameters are overridden by the local zone parameters.
+   */
+  readonly globalZone: BasicZone;
+  /**
+   * Unused preset metadata, preserved.
+   */
+  library: number;
+  /**
+   * Unused preset metadata, preserved.
+   */
+  genre: number;
+  /**
+   * Unused preset metadata, preserved.
+   */
+  morphology: number;
+  /**
+   * Creates a new preset.
+   * @param parentSoundBank The sound bank this preset belongs to.
+   * @param globalZone The optional global zone to associate within the preset.
+   */
+  constructor(parentSoundBank: BasicSoundBank, globalZone?: BasicZone);
+  /**
+   * A boolean indicating if this preset is a drum preset.
+   */
+  get isDrum(): boolean;
+  private static isInRange;
+  private static addUniqueModulators;
+  private static subtractRanges;
+  /**
+   * Unlinks everything from this preset.
+   * This is what {@link BasicSoundBank.deletePreset} calls, the preset itself stays intact.
+   * Use {@link restore} to undo it.
+   */
+  delete(): void;
+  /**
+   * Links the instruments back to this preset, the inverse of {@link delete}.
+   * Use it to restore a deleted preset, for example when undoing the deletion.
+   * Add the preset back to the sound bank as well.
+   */
+  restore(): void;
+  /**
+   * Deletes a preset zone from this preset.
+   * @param index The zone's index to delete.
+   */
+  deleteZone(index: number): void;
+  /**
+   * Creates a new preset zone and returns it.
+   * @param instrument The instrument to associate with the zone.
+   * @param link If the instrument should be linked to this preset.
+   * Pass false for helper presets that are not part of a sound bank.
+   * Such a zone never changes the instrument's use count or its `linkedTo` list.
+   *
+   * > **Warning**
+   * >
+   * > A preset with unlinked zones must not be added to a sound bank.
+   */
+  createZone(instrument: BasicInstrument, link?: boolean): BasicPresetZone;
+  /**
+   * Preloads (loads and caches synthesis data) for a given key range.
+   * @param keyMin The lowest allowed MIDI note number.
+   * @param keyMax The highest allowed MIDI note number.
+   */
+  preload(keyMin: number, keyMax: number): void;
+  /**
+   * Checks if the bank and program numbers are the same for the given preset as this one.
+   * Shortened version of {@link MIDIPatchTools.matches}
+   * @param preset The preset to check.
+   */
+  matches(preset: MIDIPatch): boolean;
+  /**
+   * Returns the voice synthesis data for this preset.
+   *
+   * > **Note**
+   * >
+   * > The `E-mu` attenuation correction
+   * > (`initialAttenuation` generator value being multiplied by `0.4`) is already performed.
+   *
+   * @param midiNote The MIDI note number.
+   * @param velocity The MIDI velocity.
+   * @returns The returned sound data.
+   */
+  getVoiceParameters(midiNote: number, velocity: number): VoiceParameters[];
+  /**
+   * Alias for {@link MIDIPatchTools.toMIDIString}
+   */
+  toMIDIString(): string;
+  /**
+   * Alias for {@link MIDIPatchTools.toFullMIDIString}
+   */
+  toString(): string;
+  /**
+   * Combines preset into an instrument, flattening the preset zones into instrument zones.
+   * This is a really complex function that attempts to work around the DLS limitations of only having the instrument layer.
+   *
+   * > **Tip**
+   * >
+   * > Consider reading about [the DLS conversion problem](../../../docs/extra/dls-conversion-problem.md).
+   *
+   * @returns The instrument containing the flattened zones. If flattening was successful, it should exactly the same as this preset.
+   */
+  toFlattenedInstrument(): BasicInstrument;
+}
 /**
  * This module handles parsing and writing SoundFont2 (`.sf2`, `.sf3` and `.sfogg`) files.
  * It represents a single sound bank.
@@ -941,8 +1076,10 @@ export declare class BasicSoundBank {
    * > This method is memory and CPU intensive with large sound banks.
    *
    * @param options Options associated with setting the sample format.
+   * @returns The samples whose sample rate or loop points changed.
+   * Compressing resamples samples outside 8000 to 96000 Hz.
    */
-  setSampleFormat(options: SetSampleFormatOptions): Promise<void>;
+  setSampleFormat(options: SetSampleFormatOptions): Promise<BasicSample[]>;
   /**
    * Writes out a DLS Level 2 sound bank. This may not be 100% accurate.
    * Samples data is always written in the S16LE PCM encoding.
@@ -995,41 +1132,47 @@ export declare class BasicSoundBank {
    */
   addSamples(...samples: BasicSample[]): void;
   /**
-   * Clones a sample into this bank.
+   * Clones a sample into this bank, together with its stereo partner.
    *
    * > **Important**
    * >
-   * > If a sample with the same name already exists in the sound bank,
+   * > By default, if a sample with the same name already exists in the sound bank,
    * > it is returned instead and the new sample is not copied.
+   * > Use the options or a {@link SoundBankCloner} to change that.
    *
    * @param sample The sample to copy.
+   * @param options Options for cloning.
    * @returns The copied sample.
    */
-  cloneSample(sample: BasicSample): BasicSample;
+  cloneSample(sample: BasicSample, options?: Partial<SoundBankCloneOptions>): BasicSample;
   /**
    * Recursively clones an instrument into this sound bank, as well as its samples.
    *
    * > **Important**
    * >
-   * > If an instrument with the same name already exists in the sound bank,
+   * > By default, if an instrument with the same name already exists in the sound bank,
    * > it is returned instead and the new instrument is not copied.
+   * > Use the options or a {@link SoundBankCloner} to change that.
    *
    * @param instrument The instrument to copy.
+   * @param options Options for cloning.
    * @returns The copied instrument.
    */
-  cloneInstrument(instrument: BasicInstrument): BasicInstrument;
+  cloneInstrument(instrument: BasicInstrument, options?: Partial<SoundBankCloneOptions>): BasicInstrument;
   /**
    * Recursively clones a preset into this sound bank, as well as its instruments and samples.
    *
    * > **Important**
    * >
-   * > If a preset with the same name already exists in the sound bank,
+   * > By default, if a preset with the same name already exists in the sound bank,
    * > it is returned instead and the new preset is not copied.
+   * > Use the options or a {@link SoundBankCloner} to change that.
    *
    * @param preset The preset to copy.
+   * @param options Options for cloning.
    * @returns The copied preset.
    */
-  clonePreset(preset: BasicPreset): BasicPreset;
+  clonePreset(preset: BasicPreset, options?: Partial<SoundBankCloneOptions>): BasicPreset;
   /**
    * Updates internal values. Call after updating the preset list.
    */
@@ -1091,114 +1234,90 @@ export declare class BasicSoundBank {
   protected printInfo(): void;
 }
 /**
- * Represents a single preset.
- * This is what is used for MIDI playback.
+ * An element that zones can link to, a {@link BasicInstrument} or a {@link BasicSample}.
  *
- * @group Sound Banks
+ * @group Sound Banks.Zones
  */
-export declare class BasicPreset implements MIDIPatchFull {
+interface LinkableZoneChild<P> {
   /**
-   * The parent soundbank instance
-   * Currently used for determining default modulators and XG status
-   */
-  readonly parentSoundBank: BasicSoundBank;
-  /**
-   * The preset's name.
+   * The element's name.
    */
   name: string;
-  program: number;
-  bankMSB: number;
-  bankLSB: number;
-  isGMGSDrum: boolean;
   /**
-   * The preset's zones.
-   * These are limited to specific key/velocity ranges and contain associated instruments.
-   */
-  zones: BasicPresetZone[];
-  /**
-   * Preset's global zone.
-   * Its parameters are overridden by the local zone parameters.
-   */
-  readonly globalZone: BasicZone;
-  /**
-   * Unused preset metadata, preserved.
-   */
-  library: number;
-  /**
-   * Unused preset metadata, preserved.
+   * Links the element to a parent.
+   * @param parent The parent that uses the element.
    */
-  genre: number;
+  linkTo(parent: P): void;
   /**
-   * Unused preset metadata, preserved.
+   * Unlinks the element from a parent.
+   * @param parent The parent that no longer uses the element.
    */
-  morphology: number;
+  unlinkFrom(parent: P): void;
+}
+/**
+ * A zone that belongs to a parent and uses a child: a preset zone with its instrument,
+ * or an instrument zone with its sample.
+ * It keeps the child linked to the parent while the zone uses it.
+ *
+ * @group Sound Banks.Zones
+ */
+export declare abstract class BasicLinkedZone<P, C extends LinkableZoneChild<P>> extends BasicZone {
   /**
-   * Creates a new preset.
-   * @param parentSoundBank The sound bank this preset belongs to.
-   * @param globalZone The optional global zone to associate within the preset.
+   * The element this zone belongs to.
    */
-  constructor(parentSoundBank: BasicSoundBank, globalZone?: BasicZone);
+  protected readonly parent: P;
   /**
-   * A boolean indicating if this preset is a drum preset.
+   * The element this zone uses.
    */
-  get isDrum(): boolean;
-  private static isInRange;
-  private static addUniqueModulators;
-  private static subtractRanges;
+  protected child: C;
   /**
-   * Deletes a preset zone from this preset.
-   * @param index The zone's index to delete.
+   * The generator that stores the child's index when writing.
    */
-  deleteZone(index: number): void;
+  protected abstract readonly childGenerator: GeneratorType;
   /**
-   * Creates a new preset zone and returns it.
-   * @param instrument The instrument to associate with the zone.
+   * If this zone counts as a use of its child.
+   * Zones created without linking never change the child's links.
    */
-  createZone(instrument: BasicInstrument): BasicPresetZone;
+  private readonly linked;
   /**
-   * Preloads (loads and caches synthesis data) for a given key range.
-   * @param keyMin The lowest allowed MIDI note number.
-   * @param keyMax The highest allowed MIDI note number.
+   * Creates a new zone and links the child to the parent.
+   * @param parent The element this zone belongs to.
+   * @param child The element this zone uses.
+   * @param link If the child should be linked to the parent.
    */
-  preload(keyMin: number, keyMax: number): void;
+  protected constructor(parent: P, child: C, link: boolean);
   /**
-   * Checks if the bank and program numbers are the same for the given preset as this one.
-   * Shortened version of {@link MIDIPatchTools.matches}
-   * @param preset The preset to check.
+   * Replaces the child, moving the link from the previous one to the new one.
+   * @param child The new child.
    */
-  matches(preset: MIDIPatch): boolean;
+  protected setChild(child: C): void;
   /**
-   * Returns the voice synthesis data for this preset.
-   *
-   * > **Note**
-   * >
-   * > The `E-mu` attenuation correction
-   * > (`initialAttenuation` generator value being multiplied by `0.4`) is already performed.
-   *
-   * @param midiNote The MIDI note number.
-   * @param velocity The MIDI velocity.
-   * @returns The returned sound data.
+   * The bank's list that the child's index is written from.
+   * @param bank The bank being written.
    */
-  getVoiceParameters(midiNote: number, velocity: number): VoiceParameters[];
+  protected abstract getChildList(bank: BasicSoundBank): C[];
+}
+/**
+ * Represents a single instrument zone with an associated {@link BasicSample}.
+ *
+ * @group Sound Banks.Zones
+ */
+export declare class BasicInstrumentZone extends BasicLinkedZone<BasicInstrument, BasicSample> {
+  protected readonly childGenerator: 53;
   /**
-   * Alias for {@link MIDIPatchTools.toMIDIString}
+   * The instrument this zone belongs to.
    */
-  toMIDIString(): string;
+  get parentInstrument(): BasicInstrument;
   /**
-   * Alias for {@link MIDIPatchTools.toFullMIDIString}
+   * The sample associated with this zone.
    */
-  toString(): string;
+  get sample(): BasicSample;
   /**
-   * Combines preset into an instrument, flattening the preset zones into instrument zones.
-   * This is a really complex function that attempts to work around the DLS limitations of only having the instrument layer.
-   *
-   * > **Tip**
-   * >
-   * > Consider reading about [the DLS conversion problem](../../../docs/extra/dls-conversion-problem.md).
-   *
-   * @returns The instrument containing the flattened zones. If flattening was successful, it should exactly the same as this preset.
+   * Sets a sample for this zone, unlinking the previous one from it.
+   * @param sample The sample to set.
    */
-  toFlattenedInstrument(): BasicInstrument;
+  set sample(sample: BasicSample);
+  protected getChildList(bank: BasicSoundBank): BasicSample[];
 }
 /**
  * This class represents a single instrument, a layer below the BasicPreset.
@@ -1239,13 +1358,33 @@ export declare class BasicInstrument {
   /**
    * Creates a new instrument zone, adds it to this instrument and returns it.
    * @param sample The sample to associate with the zone.
+   * @param link If the sample should be linked to this instrument.
+   * Pass false for helper instruments that are not part of a sound bank.
+   * Such a zone never changes the sample's use count or its `linkedTo` list.
+   *
+   * > **Warning**
+   * >
+   * > An instrument with unlinked zones must not be added to a sound bank!
    */
-  createZone(sample: BasicSample): BasicInstrumentZone;
+  createZone(sample: BasicSample, link?: boolean): BasicInstrumentZone;
   /**
    * Unlinks the instrument from a given preset.
    * @param preset The preset to unlink from.
    */
   unlinkFrom(preset: BasicPreset): void;
+  /**
+   * Unlinks everything from this instrument.
+   * This is what {@link BasicSoundBank.deleteInstrument} calls, the instrument itself stays intact.
+   * Use {@link restore} to undo it.
+   * @throws Error if the instrument is still used by a preset.
+   */
+  delete(): void;
+  /**
+   * Links the samples back to this instrument, the inverse of {@link delete}.
+   * Use it to restore a deleted instrument, for example when undoing the deletion.
+   * Add the instrument back to the sound bank as well.
+   */
+  restore(): void;
   /**
    * Deletes a given instrument zone if it has no uses.
    * @param index The index of the zone to delete.
@@ -1337,6 +1476,19 @@ export declare class BasicSample {
    * The sample's audio data.
    */
   protected audioData?: Float32Array;
+  /**
+   * The signed 16-bit little endian PCM data, as read from the file.
+   */
+  protected s16leData?: Uint8Array;
+  /**
+   * The length in sample points when it is not known from the data,
+   * either a sample without data or a vorbis stream's length that was read once.
+   */
+  protected cachedLength?: number;
+  /**
+   * The form the data had before it was released or when it was loaded without data.
+   */
+  protected releasedForm?: SampleStoredData["form"];
   /**
    * Creates a new `BasicSample`.
    *
@@ -1357,6 +1509,27 @@ export declare class BasicSample {
    * Indicates if the sample contains compressed audio.
    */
   get isCompressed(): boolean;
+  /**
+   * The form the sample stores its data in, see {@link BasicSample.getStoredData}.
+   * A sample without data reports the form it had, or undefined if it never had data.
+   */
+  get storedForm(): SampleStoredData["form"] | undefined;
+  /**
+   * Indicates if the sample holds any audio data.
+   * A sample loaded with `sampleData: false` or released with {@link BasicSample.releaseData} does not.
+   */
+  get hasData(): boolean;
+  /**
+   * The sample's length in sample points, known without decoding the data.
+   * Samples without data keep the length they had.
+   *
+   * > **Note**
+   * >
+   * > For compressed samples, it is read from the Ogg page headers, which is exact for well-formed streams.
+   * > A stream with gaps in its granule positions decodes shorter. Once it is decoded,
+   * > the length is the decoded one.
+   */
+  get sampleLength(): number;
   /**
    * If the sample is linked to another sample.
    */
@@ -1371,6 +1544,34 @@ export declare class BasicSample {
    * @return either s16le or vorbis data.
    */
   getRawData(allowVorbis: boolean): Uint8Array;
+  /**
+   * Gets the sample's data in the form it is stored, without decoding, encoding or copying it.
+   * Use {@link BasicSample.setStoredData} to give it to another sample, for example in another thread.
+   * @returns The stored form and its data.
+   */
+  getStoredData(): SampleStoredData;
+  /**
+   * Replaces the sample's data with data in a given stored form, without decoding or encoding it.
+   * The sample rate and loop points are not changed.
+   *
+   * > **Note**
+   * >
+   * > s16le and vorbis data is written back unchanged when saving, float32 data is encoded.
+   *
+   * @param stored The stored form and its data, as returned by {@link BasicSample.getStoredData}.
+   */
+  setStoredData(stored: SampleStoredData): void;
+  /**
+   * Drops all the sample's data. The parameters and {@link BasicSample.sampleLength} stay.
+   * Reading the audio data afterward throws an error until {@link BasicSample.setStoredData} gives it new data.
+   */
+  releaseData(): void;
+  /**
+   * Drops the decoded float data if the sample can decode it again from its stored s16le or vorbis data.
+   * Replaced data (set with {@link BasicSample.setAudioData}) is kept.
+   * @returns True if the decoded data was dropped.
+   */
+  releaseDecoded(): boolean;
   /**
    * Resamples the audio data _in-place_ to a given sample rate.
    * @param newSampleRate The new sample rate, in hertz.
@@ -1413,6 +1614,15 @@ export declare class BasicSample {
    * @param data The new compressed data.
    */
   setCompressedData(data: Uint8Array): void;
+  /**
+   * The error for reading the data of a sample that has none.
+   */
+  protected noDataError(): Error;
+  /**
+   * Decodes signed 16-bit little endian PCM into float.
+   * @param data The s16le data. It may be a view at any offset.
+   */
+  protected decodeS16LE(data: Uint8Array): Float32Array<ArrayBuffer>;
   /**
    * Encodes s16le sample
    * @return the encoded data
@@ -1993,6 +2203,75 @@ export type PresetsWithKeyCombinations<T extends MIDIPatchFull> = Map<T, Map<num
  * @group MIDI.Protocol
  */
 export type MIDISystem = "gm" | "gm2" | "gs" | "xg";
+/**
+ * A sample's data in the form the sample stores it, without decoding or encoding.
+ * - `s16le` - signed 16-bit little endian PCM
+ * - `vorbis` - an Ogg Vorbis stream (SF3)
+ * - `float32` - decoded or replaced float PCM
+ *
+ * @group Sound Banks.Samples
+ */
+export type SampleStoredData = {
+  form: "s16le";
+  data: Uint8Array;
+} | {
+  form: "vorbis";
+  data: Uint8Array;
+} | {
+  form: "float32";
+  data: Float32Array;
+};
+/**
+ * Options for loading a sound bank with {@link SoundBankLoader.fromArrayBuffer}.
+ *
+ * @group Sound Banks
+ */
+export interface SoundBankLoadOptions {
+  /**
+   * If the sample data should be loaded.
+   * When false, the samples keep all their parameters and their length, but hold no data.
+   * Presets, instruments and samples come out in the same order as with a full load.
+   * Use {@link BasicSample.setStoredData} to give a sample its data later.
+   *
+   * > **Note**
+   * >
+   * > DLS files and SF2Pack banks are still decoded fully during loading. The data is dropped afterward.
+   */
+  sampleData: boolean;
+  /**
+   * If the sample data should be copied out of the file buffer.
+   * When false, the samples are views into the given buffer, which saves memory and time during loading,
+   * but keeps the whole buffer alive as long as any of the samples are.
+   *
+   * > **Note**
+   * >
+   * > DLS files always copy their data.
+   */
+  copySampleData: boolean;
+}
+/**
+ * Options for cloning elements into a sound bank with {@link SoundBankCloner}.
+ *
+ * @group Sound Banks
+ */
+export interface SoundBankCloneOptions {
+  /**
+   * If the cloned element itself is reused when an element with the same name exists in the bank.
+   * When false, it is always copied, under a free name (`Name-1`, `Name-2` and so on).
+   */
+  reuseByName: boolean;
+  /**
+   * If the instruments and samples used by a cloned element are reused when one with the same name exists.
+   * When false, they are copied under a free name as well.
+   * A stereo partner of a copied sample is always copied with it.
+   */
+  reuseChildrenByName: boolean;
+  /**
+   * If the new elements are added to the bank.
+   * When false, they are only listed in {@link SoundBankCloner.created}.
+   */
+  addToBank: boolean;
+}
 /**
  * The available interpolation types of the synthesizer.
  * Interpolation defines how sample points between the sample data are calculated.
@@ -2022,6 +2301,32 @@ export declare const InterpolationTypes: {
  * @group Synthesizer.Options
  */
 export type InterpolationType = (typeof InterpolationTypes)[keyof typeof InterpolationTypes];
+/**
+ * The special EFX control sources of a {@link GSInsertionBlock} (EFX CONTROL SOURCE 1/2).
+ * Values `1-95` select the control change with that number, other values are off.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export declare const GSInsertionControlSources: {
+  /**
+   * No control.
+   */
+  readonly off: 0;
+  /**
+   * Channel aftertouch (channel pressure).
+   */
+  readonly channelPressure: 112;
+  /**
+   * Pitch bend.
+   */
+  readonly pitchBend: 113;
+};
+/**
+ * @inheritDoc GSInsertionControlSources
+ *
+ * @group Synthesizer.GS Effects
+ */
+export type GSInsertionControlSource = (typeof GSInsertionControlSources)[keyof typeof GSInsertionControlSources];
 /**
  * Channel System Parameters are API-only parameters
  * that affect a single MIDI channel.
@@ -2451,6 +2756,35 @@ export interface GSInsertionParameter {
    * Higher values result in more sound being sent.
    */
   sendLevelToDelay: number;
+  /**
+   * `0-127`
+   *
+   * EFX control source 1: the controller that modulates the first controlled parameter of the type
+   * (marked with `+` in the SC-8850 manual).
+   * `1-95` selects a control change number, see {@link GSInsertionControlSources} for the others.
+   * Only the parts with EFX assigned (see {@link ChannelMIDIParameter.efxAssign}) control it.
+   */
+  controlSource1: number;
+  /**
+   * `0-127`
+   *
+   * EFX control depth 1: how far control source 1 moves its parameter,
+   * from `0` (-100%) through `64` (0%) to `127` (+100%) of the full parameter range.
+   */
+  controlDepth1: number;
+  /**
+   * `0-127`
+   *
+   * EFX control source 2: the controller that modulates the second controlled parameter of the type
+   * (marked with `#` in the SC-8850 manual). See {@link controlSource1}.
+   */
+  controlSource2: number;
+  /**
+   * `0-127`
+   *
+   * EFX control depth 2, see {@link controlDepth1}.
+   */
+  controlDepth2: number;
 }
 /**
  * A snapshot of a {@link GSInsertionBlock}.
@@ -2475,6 +2809,10 @@ export interface GSInsertionBlockSnapshot extends GSInsertionParameter {
    * Value `255` means the parameter has not been changed since the type was set, so it uses the type default.
    */
   params: Uint8Array;
+  /**
+   * The last controller values of the two EFX control sources (signed, pitch bend is centered at 0).
+   */
+  controlValues: number[];
 }
 /**
  * The Insertion effect (EFX) processes the parts (channels) that have EFX assigned
@@ -2504,6 +2842,7 @@ export interface GSInsertionBlock extends GSInsertionParameter {
    * Sets the EFX type of the block.
    *
    * Type change resets the parameters and the send levels to their defaults.
+   * The EFX control sources and depths are kept.
    * Behavior for unsupported types is up to the implementation.
    *
    * @param type The 16-bit type value to use, `MSB << 8 | LSB`.
@@ -2515,7 +2854,7 @@ export interface GSInsertionBlock extends GSInsertionParameter {
    */
   getType(): number;
   /**
-   * Resets this block to default values, including the EFX type and the send levels.
+   * Resets this block to default values, including the EFX type, the send levels and the EFX control.
    */
   reset(): void;
   /**
@@ -2524,6 +2863,14 @@ export interface GSInsertionBlock extends GSInsertionParameter {
    * @param value The 7-bit value.
    */
   setParameter(param: number, value: number): void;
+  /**
+   * Passes a controller value of a part with EFX assigned (see {@link ChannelMIDIParameter.efxAssign})
+   * for the EFX control sources ({@link controlSource1}, {@link controlSource2}).
+   * @param source The controller, encoded like the control sources:
+   * `1-95` a control change number, or a value of {@link GSInsertionControlSources}.
+   * @param value The controller value: 7-bit, or 14-bit for {@link GSInsertionControlSources.pitchBend}.
+   */
+  setControllerValue(source: number, value: number): void;
   /**
    * Process the effect and **adds** it to the output.
    * @param inputLeft The left input buffer to process. It always starts at index 0.
@@ -3164,6 +3511,15 @@ export declare class SoundBankManager {
    * @param bankOffset The bank offset of the sound bank. Offsets the bank MSB value of all presets in this sound bank.
    */
   addSoundBank(bank: BasicSoundBank, id: string, bankOffset?: number): void;
+  /**
+   * Rebuilds the preset list from the current sound banks.
+   * Call it after editing a sound bank that is already added,
+   * for example after adding, removing or renumbering presets.
+   *
+   * The synthesizer then updates its channels to the new presets without resetting,
+   * see {@link SpessaSynthProcessor.refreshPresets}.
+   */
+  refresh(): void;
   private generatePresetList;
 }
 /**
@@ -3577,7 +3933,7 @@ export declare class SpessaSynthProcessor {
   setSystemParameter<P extends keyof GlobalSystemParameter>(parameter: P, value: GlobalSystemParameter[P]): void;
   /**
    * A handler for missing presets during program change.
-   * By default, it warns to console.
+   * By default, it warns to console, unless no sound bank has been added yet.
    * It may be useful for allowing the synthesizer to work without any sound banks.
    * @param patch The MIDI patch that was requested.
    * @param system The MIDI System for the request.
@@ -3743,6 +4099,25 @@ export declare class SpessaSynthProcessor {
    * These shouldn't be added to the `left` and `right` outputs. Recommended use-case is visualization.
    */
   process(left: Float32Array, right: Float32Array, startIndex?: number, sampleCount?: number, channelOutputs?: Float32Array[][]): void;
+  /**
+   * Updates the synthesizer after the added sound banks were edited.
+   * It rebuilds the preset list, clears the voice cache,
+   * and points every channel at the current preset for its patch.
+   *
+   * Unlike adding a sound bank, this does not reset the synthesizer or send program changes,
+   * so playback continues. Voices that are already playing keep the old data until they end.
+   *
+   * > **Tip**
+   * >
+   * > Call it after adding, removing or renumbering presets in a sound bank that is already added.
+   * > For edits inside existing presets, {@link clearCache} is enough.
+   */
+  refreshPresets(): void;
+  /**
+   * The decoded sample data kept under {@link SynthProcessorOptions.decodedSampleBudget}, in bytes.
+   * It is only counted when a budget is set.
+   */
+  get decodedSampleBytes(): number;
   /**
    * Clears the synthesizer's voice cache.
    * This can be used to hear the changes after editing a {@link BasicSoundBank}
@@ -4002,9 +4377,9 @@ export type GSInsertionParameterMessage = {
    */
   type: "GS Insertion Param";
   /**
-   * The parameter name that was modified in the processor.
+   * The parameter name that was modified in the processor: a send level or an EFX control setting.
    */
-  parameter: "sendLevelToReverb" | "sendLevelToChorus" | "sendLevelToDelay";
+  parameter: keyof GSInsertionParameter;
   /**
    * The new value of the parameter.
    */
@@ -4637,6 +5012,7 @@ export type EffectChangeEvent = {
    * The parameter that was changed:
    * - `"type"` - 16-bit effect type (`MSB << 8 | LSB`). Note that this resets the parameters and the send levels!
    * - `"sendLevelToReverb" | "sendLevelToChorus" | "sendLevelToDelay"` - send levels (7-bit), see {@link GSInsertionParameter}.
+   * - `"controlSource1" | "controlDepth1" | "controlSource2" | "controlDepth2"` - EFX control (7-bit), see {@link GSInsertionParameter}.
    * - `number` - 0-based type-specific EFX parameter index (0-19). EFX parameter 1 is 0. Value is 7-bit.
    */
   parameter: "type" | keyof GSInsertionParameter | number;
@@ -5177,6 +5553,18 @@ export interface SynthMethodOptions {
  * @group Synthesizer.Options
  */
 export interface SynthProcessorOptions {
+  /**
+   * The most decoded sample data the synthesizer keeps, in bytes.
+   * When over it, the least recently played samples drop their decoded data and decode again when played.
+   * Only samples that can decode again (loaded s16le or vorbis data) are dropped.
+   * Defaults to Infinity, which keeps everything.
+   *
+   * > **Tip**
+   * >
+   * > Decoded data is 4 bytes per sample point, twice the size of 16-bit data.
+   * > This helps with very large sound banks.
+   */
+  decodedSampleBudget: number;
   /**
    * The maximum buffer size the synthesizer can render at once.
    * Attempting to `.process()` more samples than this will result in an error.
@@ -5754,8 +6142,9 @@ interface ModifyMIDIOptions {
    * The GS Insertion Effect parameters.
    * - `"clear"` - all existing parameter change MIDI messages are cleared.
    * - {@link GSInsertionBlockSnapshot} - clear + the new parameters are set via System Exclusive messages.
+   * The controller values of the EFX control sources are not part of it, they come from the controllers.
    */
-  gsInsertionParams?: ClearableParameter<GSInsertionBlockSnapshot>;
+  gsInsertionParams?: ClearableParameter<Omit<GSInsertionBlockSnapshot, "controlValues">>;
   /**
    * The desired XG reverb parameters.
    * - `"clear"` - all existing parameter change MIDI messages are removed.
@@ -6876,7 +7265,7 @@ export declare class MIDIUtils {
   /**
    * Returns a MIDI event needed to set the given GS Insertion Parameter.
    * @param ticks The MIDI tick time for the output event.
-   * @param parameter The parameter to set: `"type"`, a send level name,
+   * @param parameter The parameter to set: `"type"`, a send level or EFX control name (see {@link GSInsertionParameter}),
    * or a 0-based effect-specific parameter number (0-19).
    * @param value The value to set it to.
    * @returns The {@link MIDIMessage} needed to set this GS Insertion Parameter.
@@ -7688,6 +8077,14 @@ export declare class DefaultGSInsertion implements GSInsertionBlock {
   sendLevelToReverb: number;
   sendLevelToChorus: number;
   sendLevelToDelay: number;
+  controlSource1: number;
+  controlDepth1: number;
+  controlSource2: number;
+  controlDepth2: number;
+  /**
+   * The last controller values of both control sources (signed, pitch bend is centered).
+   */
+  private readonly controlValues;
   /**
    * The list of effects available in this block.
    * Effect type: processor.
@@ -7728,10 +8125,15 @@ export declare class DefaultGSInsertion implements GSInsertionBlock {
   setType(type: number): void;
   getType(): number;
   reset(): void;
+  setControllerValue(source: number, value: number): void;
   setParameter(param: number, value: number): void;
   process(inputLeft: Float32Array, inputRight: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, outputReverb: Float32Array, outputChorus: Float32Array, outputDelay: Float32Array, startIndex: number, sampleCount: number): void;
   getSnapshot(): GSInsertionBlockSnapshot;
   applySnapshot(snapshot: GSInsertionBlockSnapshot): void;
+  /**
+   * Sends the offsets of both control sources to the processor.
+   */
+  private updateControl;
 }
 /**
  * Synthesizer's default voice cap.
@@ -7777,6 +8179,82 @@ export declare const DEFAULT_MIDI_CONTROLLERS: Readonly<Int16Array>;
  * @group Synthesizer.Drum Sets
  */
 export declare const DEFAULT_DRUM_REVERB: Int8Array<ArrayBuffer>;
+/**
+ * The default clone options, matching {@link BasicSoundBank.clonePreset} and the other clone methods:
+ * every element with a name already in the bank is reused, and the copies are added to the bank.
+ *
+ * @group Sound Banks
+ */
+export declare const DEFAULT_SOUND_BANK_CLONE_OPTIONS: SoundBankCloneOptions;
+/**
+ * Clones presets, instruments and samples into a sound bank, as one session.
+ * Elements copied once in a session are reused when something else in the session uses them again,
+ * so an instrument used by two cloned presets is only copied once.
+ * Stereo pairs are always cloned together.
+ *
+ * > **Tip**
+ * >
+ * > With `addToBank: false`, nothing is added to the bank. The new elements are listed in {@link created},
+ * > in an order they can be added in (samples first, then instruments, then presets).
+ * > Their zones still link to the children they use, like {@link BasicInstrument.createZone} does,
+ * > so a reused child in the bank counts them as users.
+ *
+ * @group Sound Banks
+ */
+export declare class SoundBankCloner {
+  /**
+   * The new elements this session made, in the order they were made. Reused elements are not listed.
+   */
+  readonly created: {
+    samples: BasicSample[];
+    instruments: BasicInstrument[];
+    presets: BasicPreset[];
+  };
+  /**
+   * The bank the elements are cloned into.
+   */
+  readonly bank: BasicSoundBank;
+  /**
+   * The options of this session.
+   */
+  readonly options: SoundBankCloneOptions;
+  private readonly sampleClones;
+  private readonly instrumentClones;
+  /**
+   * Creates a new clone session.
+   * @param bank The bank to clone elements into.
+   * @param options The options for this session.
+   */
+  constructor(bank: BasicSoundBank, options?: Partial<SoundBankCloneOptions>);
+  /**
+   * Clones a sample and its stereo partner.
+   * The data is shared with the original, not copied.
+   * @param sample The sample to clone.
+   * @returns The clone, or the existing sample with the same name if it is reused.
+   */
+  cloneSample(sample: BasicSample): BasicSample;
+  /**
+   * Clones an instrument and the samples it uses.
+   * @param instrument The instrument to clone.
+   * @returns The clone, or the existing instrument with the same name if it is reused.
+   */
+  cloneInstrument(instrument: BasicInstrument): BasicInstrument;
+  /**
+   * Clones a preset and the instruments and samples it uses.
+   * @param preset The preset to clone.
+   * @returns The clone, or the existing preset with the same name if it is reused.
+   */
+  clonePreset(preset: BasicPreset): BasicPreset;
+  private copyInstrument;
+  private copySample;
+  private getFreeName;
+}
+/**
+ * The default options for loading a sound bank: full loading with copied sample data.
+ *
+ * @group Sound Banks
+ */
+export declare const DEFAULT_SOUND_BANK_LOAD_OPTIONS: SoundBankLoadOptions;
 /**
  * A helper class for loading sound bank files as {@link BasicSoundBank} instances.
  *
@@ -7786,9 +8264,10 @@ export declare class SoundBankLoader {
   /**
    * Loads a sound bank from a file buffer.
    * @param buffer The binary file buffer to load.
+   * @param options Options for loading the sample data.
    * @returns The loaded sound bank.
    */
-  static fromArrayBuffer(buffer: ArrayBuffer): BasicSoundBank;
+  static fromArrayBuffer(buffer: ArrayBuffer, options?: Partial<SoundBankLoadOptions>): BasicSoundBank;
 }
-export type { ChannelDrumModification, ChannelGenerators, ChannelMIDIParameter, ChannelModification, ChannelSnapshot, ChannelSystemParameter, ClearableParameter, FourCC, GenericRIFFFourCC, GlobalMIDIParameter, GlobalSystemParameter, MIDIController, MIDIMessageType, ModifyMIDIOptions, SynthesizerSnapshot, UserDrumModification, WAVFourCC };
+export type { ChannelDrumModification, ChannelGenerators, ChannelMIDIParameter, ChannelModification, ChannelSnapshot, ChannelSystemParameter, ClearableParameter, FourCC, GenericRIFFFourCC, GlobalMIDIParameter, GlobalSystemParameter, LinkableZoneChild, MIDIController, MIDIMessageType, ModifyMIDIOptions, SynthesizerSnapshot, UserDrumModification, WAVFourCC };
 //# sourceMappingURL=index.d.ts.map