spessasynth_core 4.4.7 → 4.4.8

package/dist/index.d.ts

@@ -31,6 +31,35 @@ export interface WaveWriteOptions {
    */
   metadata: Partial<WaveMetadata>;
 }
+/**
+ * The result of reading a WAVE file with {@link wavToAudio}.
+ *
+ * @group Utilities
+ */
+export interface WaveReadResult {
+  /**
+   * The PCM audio data, one array per channel.
+   */
+  audioData: Float32Array[];
+  /**
+   * The sample rate, in Hertz.
+   */
+  sampleRate: number;
+  /**
+   * The loop of the file, undefined if it has none.
+   * The points are in sample frames, not seconds.
+   */
+  loop?: {
+    /**
+     * The loop start, in sample frames.
+     */
+    start: number;
+    /**
+     * The loop end, in sample frames.
+     */
+    end: number;
+  };
+}
 /**
  * Metadata to write into a WAVE file.
  *
@@ -148,6 +177,25 @@ declare function readVariableLengthQuantity(midiByteArray: IndexedByteArray): nu
  * @group Utilities
  */
 export declare function audioToWav(audioData: Float32Array[], sampleRate: number, options?: Partial<WaveWriteOptions>): ArrayBuffer;
+/**
+ * Reads a WAVE file into PCM audio data, the counterpart of {@link audioToWav}.
+ *
+ * It reads 8, 16, 24 and 32-bit integer PCM and 32 and 64-bit float files (including `WAVE_FORMAT_EXTENSIBLE`).
+ * The loop is read from the first loop of the `smpl` chunk. Without one, the first two points of the `cue ` chunk
+ * are taken as the loop start and end, which is how {@link audioToWav} writes it.
+ * Other files may use cue points as plain markers, so such a loop is only reliable for files written by core.
+ *
+ * > **Note**
+ * >
+ * > The returned loop end is exclusive, like the SoundFont loop end.
+ *
+ * @param buffer The binary WAVE file.
+ * @returns The audio data (one array per channel), the sample rate and the loop, if the file has one.
+ * @throws Error if the file is not a valid or supported WAVE file.
+ *
+ * @group Utilities
+ */
+export declare function wavToAudio(buffer: ArrayBuffer): WaveReadResult;
 /**
  * SpessaSynth can print out additional info to the console or print nothing at all.
  *
@@ -353,17 +401,6 @@ 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.
@@ -524,6 +561,15 @@ export declare class ModulatorSource {
    * This field specifies how the minimum value approaches the maximum value.
    */
   curveType: ModulatorCurveType;
+  /**
+   * Creates a new modulator source.
+   * @param index The controller or MIDI CC number, see `isCC`.
+   * @param curveType How the minimum value approaches the maximum value.
+   * @param isCC If the index is a MIDI CC instead of a general controller.
+   * @param isBipolar If the source is bipolar (-1 to 1) instead of unipolar (0 to 1).
+   * @param isNegative If the direction of the source is flipped.
+   */
+  constructor(index?: ModulatorSourceIndex, curveType?: ModulatorCurveType, isCC?: boolean, isBipolar?: boolean, isNegative?: boolean);
   private get sourceName();
   private get curveTypeName();
   toString(): string;
@@ -1090,6 +1136,7 @@ export declare class BasicSoundBank {
    * @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.
+   * @throws Error if `rejectOnFailure` is set and one of the samples has failed to compress.
    */
   setSampleFormat(options: SetSampleFormatOptions): Promise<BasicSample[]>;
   /**
@@ -1187,8 +1234,10 @@ export declare class BasicSoundBank {
   clonePreset(preset: BasicPreset, options?: Partial<SoundBankCloneOptions>): BasicPreset;
   /**
    * Updates internal values. Call after updating the preset list.
+   * @param sort If the presets should be sorted. Set it to `false` to keep a custom order,
+   * only the internal values (like {@link isXGBank}) are then recomputed.
    */
-  flush(): void;
+  flush(sort?: boolean): void;
   /**
    * Trims the sound bank _in-place_ to only contain samples in a given MIDI file.
    *
@@ -1236,6 +1285,7 @@ export declare class BasicSoundBank {
    * Deletes everything irreversibly.
    */
   destroySoundBank(): void;
+  protected addElements<T>(list: T[], elements: readonly T[]): void;
   protected parsingError(error: string): never;
   /**
    * Parses the bank after loading is done
@@ -1254,16 +1304,6 @@ interface LinkableZoneChild<P> {
    * The element's name.
    */
   name: string;
-  /**
-   * Links the element to a parent.
-   * @param parent The parent that uses the element.
-   */
-  linkTo(parent: P): void;
-  /**
-   * Unlinks the element from a parent.
-   * @param parent The parent that no longer uses the element.
-   */
-  unlinkFrom(parent: P): void;
 }
 /**
  * A zone that belongs to a parent and uses a child: a preset zone with its instrument,
@@ -1297,6 +1337,15 @@ export declare abstract class BasicLinkedZone<P, C extends LinkableZoneChild<P>>
    * @param link If the child should be linked to the parent.
    */
   protected constructor(parent: P, child: C, link: boolean);
+  /**
+   * Links the child to the parent, unless this zone was created without linking.
+   * Use it to put a zone back after {@link unlinkChild}, for example when undoing a zone deletion.
+   */
+  linkChild(): void;
+  /**
+   * Unlinks the child from the parent, unless this zone was created without linking.
+   */
+  unlinkChild(): void;
   /**
    * Replaces the child, moving the link from the previous one to the new one.
    * @param child The new child.
@@ -1378,11 +1427,6 @@ export declare class BasicInstrument {
    * > An instrument with unlinked zones must not be added to a sound bank!
    */
   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.
@@ -1549,6 +1593,12 @@ export declare class BasicSample {
    * How many instruments is this sample used by.
    */
   get useCount(): number;
+  /**
+   * If the decoded float data is currently held in memory.
+   * Check it before {@link getAudioData} to know if the call has to decode,
+   * then use {@link releaseDecoded} to drop the copy again.
+   */
+  get isDecoded(): boolean;
   /**
    * Get raw data for writing the file, either a compressed bit stream or signed 16-bit little endian PCM data.
    * @param allowVorbis if vorbis file data is allowed.
@@ -1603,11 +1653,6 @@ export declare class BasicSample {
    * @param type Either left, right or linked. The linked sample will be set appropriately as well.
    */
   setLinkedSample(sample: BasicSample, type: SampleType): void;
-  /**
-   * Unlinks the sample from a given instrument
-   * @param instrument the instrument to unlink from
-   */
-  unlinkFrom(instrument: BasicInstrument): void;
   /**
    * Get the PCM Float32 audio data of this sample.
    * This either decodes the compressed data or passes the ready sampleData.
@@ -2216,6 +2261,13 @@ export type SetSampleFormatOptions = {
    * It must be provided if `compressed` format is chosen.
    */
   compressionFunction: SampleEncodingFunction;
+  /**
+   * If the returned promise should reject when a sample fails to compress.
+   * By default, such a sample is left uncompressed (and a warning is logged),
+   * but the bank is still set to version 3.0.
+   * With this on, the method throws after trying every sample and the bank's version stays the same.
+   */
+  rejectOnFailure?: boolean;
 });
 /**
  * Options for writing a sound bank file.
@@ -2361,11 +2413,15 @@ export interface SoundBankCloneOptions {
    */
   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.
+   * How the instruments and samples used by a cloned element are reused instead of copied.
+   * - `name` - reuse the first element in the bank with the same name.
+   * - `identity` - reuse the element itself if it is already in the bank.
+   *   Use it to duplicate elements within one bank, as names often repeat in real banks.
+   * - `none` - always copy them, under a free name if needed.
+   *
    * A stereo partner of a copied sample is always copied with it.
    */
-  reuseChildrenByName: boolean;
+  reuseChildren: "name" | "identity" | "none";
   /**
    * If the new elements are added to the bank.
    * When false, they are only listed in {@link SoundBankCloner.created}.
@@ -3731,6 +3787,7 @@ export declare class SoundBankManager {
    */
   soundBankList: SoundBankManagerListEntry[];
   private readonly presetListChangeCallback;
+  private readonly bankRemovedCallback?;
   private selectablePresetList;
   private _presetList;
   /**
@@ -3760,17 +3817,21 @@ export declare class SoundBankManager {
   /**
    * This method removes a sound bank with a given ID from the sound bank list.
    * @param id The ID of the sound bank to delete.
+   * @param reset If the synthesizer should reset (put every channel's controllers back to defaults) after the change.
+   * Set it to `false` to keep a song playing, the channels then only update to the new presets.
    * @throws Error An error if there's no sound bank with the given ID.
    */
-  deleteSoundBank(id: string): void;
+  deleteSoundBank(id: string, reset?: boolean): void;
   /**
    * Adds a new sound bank with a given ID, or replaces an existing one.
    * @param bank The sound bank to add.
    * @param id The unique ID to assign to the sound bank.
    * If a sound bank with this ID already exists, it will be replaced.
    * @param bankOffset The bank offset of the sound bank. Offsets the bank MSB value of all presets in this sound bank.
+   * @param reset If the synthesizer should reset (put every channel's controllers back to defaults) after the change.
+   * Set it to `false` to keep a song playing, the channels then only update to the new presets.
    */
-  addSoundBank(bank: BasicSoundBank, id: string, bankOffset?: number): void;
+  addSoundBank(bank: BasicSoundBank, id: string, bankOffset?: number, reset?: boolean): void;
   /**
    * Rebuilds the preset list from the current sound banks.
    * Call it after editing a sound bank that is already added,
@@ -3780,6 +3841,7 @@ export declare class SoundBankManager {
    * see {@link SpessaSynthProcessor.refreshPresets}.
    */
   refresh(): void;
+  private bankRemoved;
   private generatePresetList;
 }
 /**
@@ -4115,10 +4177,6 @@ export declare class SpessaSynthProcessor {
    * All MIDI channels of the synthesizer.
    */
   readonly midiChannels: MIDIChannel[];
-  /**
-   * The sound bank manager, which manages all sound banks and presets.
-   */
-  readonly soundBankManager: SoundBankManager;
   /**
    * The sample rate, in Hertz.
    */
@@ -4147,6 +4205,10 @@ export declare class SpessaSynthProcessor {
    * @param event The event that occurred.
    */
   onEventCall?: (event: SynthesizerEventCallback) => unknown;
+  /**
+   * The sound bank manager, which manages all sound banks and presets.
+   */
+  readonly soundBankManager: SoundBankManager;
   /**
    * Left float32 buffer for processing XG insertion effects in-place.
    * (channel outputs are double precision)
@@ -8724,6 +8786,19 @@ export declare class SoundBankCloner {
    * @param options The options for this session.
    */
   constructor(bank: BasicSoundBank, options?: Partial<SoundBankCloneOptions>);
+  private get ownReuse();
+  /**
+   * Gets the clone this session made of an element.
+   * @param source The sample or instrument that was cloned.
+   * @returns The clone, or undefined if the session has not cloned the element.
+   */
+  getClone(source: BasicSample): BasicSample | undefined;
+  /**
+   * Gets the clone this session made of an element.
+   * @param source The sample or instrument that was cloned.
+   * @returns The clone, or undefined if the session has not cloned the element.
+   */
+  getClone(source: BasicInstrument): BasicInstrument | undefined;
   /**
    * Clones a sample and its stereo partner.
    * The data is shared with the original, not copied.
@@ -8745,6 +8820,10 @@ export declare class SoundBankCloner {
   clonePreset(preset: BasicPreset): BasicPreset;
   private copyInstrument;
   private copySample;
+  /**
+   * Finds the element to use instead of a copy, if the options allow one.
+   */
+  private findReused;
   private getFreeName;
 }
 /**