spessasynth_core 4.4.2 → 4.4.3

package/dist/index.d.ts

@@ -2212,6 +2212,11 @@ export interface GSReverbProcessor extends GSReverbParameter {
    * Gets a snapshot of this effect processor instance.
    */
   getSnapshot(): GSReverbParameter;
+  /**
+   * Restores this effect processor instance from a snapshot.
+   * @param snapshot The snapshot to restore.
+   */
+  applySnapshot(snapshot: GSReverbParameter): void;
 }
 /**
  * GS-compatible chorus parameters.
@@ -2300,6 +2305,11 @@ export interface GSChorusProcessor extends GSChorusParameter {
    * Gets a snapshot of this effect processor instance.
    */
   getSnapshot(): GSChorusParameter;
+  /**
+   * Restores this effect processor instance from a snapshot.
+   * @param snapshot The snapshot to restore.
+   */
+  applySnapshot(snapshot: GSChorusParameter): void;
 }
 /**
  * GS-compatible delay parameters.
@@ -2408,50 +2418,112 @@ export interface GSDelayProcessor extends GSDelayParameter {
    * Gets a snapshot of this effect processor instance.
    */
   getSnapshot(): GSDelayParameter;
+  /**
+   * Restores this effect processor instance from a snapshot.
+   * @param snapshot The snapshot to restore.
+   */
+  applySnapshot(snapshot: GSDelayParameter): void;
 }
 /**
- * Represents a GS-compatible Insertion EFX processor.
+ * GS-compatible insertion effect (EFX) parameters.
  *
  * @group Synthesizer.GS Effects
  */
-export interface GSInsertionProcessor {
-  /**
-   * The EFX type of this processor, stored as `MSB << 8 | LSB`.
-   * For example `0x30`, `0x10` is `0x3010`.
-   */
-  readonly type: number;
+export interface GSInsertionParameter {
   /**
-   * `0-1` (floating point)
+   * `0-127`
    *
    * This parameter sets the amount of insertion sound that will be sent to the reverb.
    * Higher values result in more sound being sent.
    */
   sendLevelToReverb: number;
   /**
-   * `0-1` (floating point)
+   * `0-127`
    *
    * This parameter sets the amount of insertion sound that will be sent to the chorus.
    * Higher values result in more sound being sent.
    */
   sendLevelToChorus: number;
   /**
-   * `0-1` (floating point)
+   * `0-127`
    *
    * This parameter sets the amount of insertion sound that will be sent to the delay.
    * Higher values result in more sound being sent.
    */
   sendLevelToDelay: number;
+}
+/**
+ * A snapshot of a {@link GSInsertionBlock}.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export interface GSInsertionBlockSnapshot extends GSInsertionParameter {
+  /**
+   * The EFX type of this block, stored as `MSB << 8 | LSB`.
+   * For example `0x30`, `0x10` is `0x3010`.
+   *
+   * This is the requested type, even if the block does not support it.
+   *
+   * > **Tip**
+   * >
+   * > Refer to [SC-8850 Owner's Manual](https://cdn.roland.com/assets/media/pdf/SC-8850_OM.pdf) (p.88, 237) for more information.
+   */
+  type: number;
+  /**
+   * The 20 EFX parameters (0-19). Their meaning depends on the effect type.
+   *
+   * Value `255` means the parameter has not been changed since the type was set, so it uses the type default.
+   */
+  params: Uint8Array;
+}
+/**
+ * The Insertion effect (EFX) processes the parts (channels) that have EFX assigned
+ * (see {@link ChannelMIDIParameter.efxAssign}) and is routed straight to the output.
+ * It can additionally send its output to the reverb, chorus and delay.
+ *
+ * This is a Roland GS-compatible insertion interface.
+ *
+ * It is used when {@link GlobalMIDIParameter.system} is `gm` `gm2` or `gs`,
+ * but it is only enabled when an insertion parameter is set via a system exclusive message.
+ *
+ * {@link SpessaSynthProcessor} allows you to supply a custom insertion block.
+ * A custom insertion block must implement this interface.
+ *
+ * ### Editing the parameters
+ *
+ * Editing the parameters can be done via GS system exclusive messages.
+ *
+ * > **Tip**
+ * >
+ * > Refer to [SC-8850 Owner's Manual](https://cdn.roland.com/assets/media/pdf/SC-8850_OM.pdf) (p.88, 237) for more information.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export interface GSInsertionBlock extends GSInsertionParameter {
+  /**
+   * Sets the EFX type of the block.
+   *
+   * Type change resets the parameters and the send levels to their defaults.
+   * Behavior for unsupported types is up to the implementation.
+   *
+   * @param type The 16-bit type value to use, `MSB << 8 | LSB`.
+   */
+  setType(type: number): void;
+  /**
+   * Gets the current 16-bit type of the block.
+   * @returns The 16-bit (`MSB << 8 | LSB`) type requested by the last {@link setType} call.
+   */
+  getType(): number;
   /**
-   * Resets the params to their default values.
-   * This does not need to reset send levels.
+   * Resets this block to default values, including the EFX type and the send levels.
    */
   reset(): void;
   /**
-   * Sets an EFX parameter.
-   * @param parameter The parameter number (0x03-0x16).
-   * @param value The new value (0-127).
+   * Sets the given EFX parameter to the given value.
+   * @param param The parameter number (0-based, 0-19).
+   * @param value The 7-bit value.
    */
-  setParameter(parameter: number, value: number): void;
+  setParameter(param: 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.
@@ -2465,31 +2537,15 @@ export interface GSInsertionProcessor {
    * @param sampleCount The amount of samples to mix. This will never be larger than {@link SynthProcessorOptions.maxBufferSize} of the parent {@link SpessaSynthProcessor} instance.
    */
   process(inputLeft: Float32Array, inputRight: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, outputReverb: Float32Array, outputChorus: Float32Array, outputDelay: Float32Array, startIndex: number, sampleCount: number): void;
-}
-/**
- * Represents stored GS-compatible insertion processor data.
- *
- * @group Synthesizer.GS Effects
- */
-export interface GSInsertionProcessorSnapshot {
   /**
-   * The EFX type of this processor, stored as `MSB << 8 | LSB`.
-   * For example `0x30`, `0x10` is `0x3010`.
-   *
-   * > **Tip**
-   * >
-   * > Refer to [SC-8850 Owner's Manual](https://cdn.roland.com/assets/media/pdf/SC-8850_OM.pdf) (p.88, 237) for more information.
+   * Gets a snapshot of this insertion block.
    */
-  type: number;
+  getSnapshot(): GSInsertionBlockSnapshot;
   /**
-   * 20 parameters for the effect. These depend on effect type.
-   * After that 3 effect sends follow (index 20, 21, 22),
-   * the length totaling to 23.
-   *
-   * Value `255` means "no change" for that parameter.
-   *
+   * Restores this insertion block from a snapshot.
+   * @param snapshot The snapshot to restore.
    */
-  params: Uint8Array;
+  applySnapshot(snapshot: GSInsertionBlockSnapshot): void;
 }
 /**
  * A snapshot of a {@link XGEffectBlock}.
@@ -3370,9 +3426,9 @@ interface SynthesizerSnapshot {
    */
   gsDelayProcessor: GSDelayParameter;
   /**
-   * A snapshot of the insertion effect processor.
+   * A snapshot of the GS insertion block.
    */
-  gsInsertionProcessor: GSInsertionProcessorSnapshot;
+  gsInsertionBlock: GSInsertionBlockSnapshot;
   /**
    * A snapshot of the XG reverb block.
    */
@@ -3411,6 +3467,7 @@ interface SynthesizerSnapshot {
  * - {@link GSReverbProcessor} - How to implement your own GS reverb processor.
  * - {@link GSChorusProcessor} - How to implement your own GS chorus processor.
  * - {@link GSDelayProcessor} - How to implement your own GS delay processor.
+ * - {@link GSInsertionBlock} - How to implement your own GS insertion processor.
  *
  * #### XG
  *
@@ -3700,7 +3757,6 @@ export declare class SpessaSynthProcessor {
    */
   private processXGInsertion;
   private createMIDIChannelInternal;
-  private registerInsertionProcessor;
   private processMessageInternal;
   /**
    * Assigns priorities to the voices.
@@ -4510,9 +4566,12 @@ export type GlobalMIDIParameterChangeEvent = { [P in keyof GlobalMIDIParameter]:
 /**
  * The parameter names of an effect processor, or `macro` for the effect's macro.
  *
+ * When a macro is applied, an event is first emitted for every parameter it sets,
+ * then the `macro` event.
+ *
  * @group Synthesizer.Events
  */
-export type FXType<K> = Exclude<keyof K, "process" | "getSnapshot"> | "macro";
+export type FXType<K> = Exclude<keyof K, "process" | "getSnapshot" | "applySnapshot"> | "macro";
 /**
  * This event is triggered when an effect processor has one of its parameters changed.
  *
@@ -4521,7 +4580,7 @@ export type FXType<K> = Exclude<keyof K, "process" | "getSnapshot"> | "macro";
  * - {@link GSReverbProcessor} (`effect: "gsReverb"`)
  * - {@link GSChorusProcessor} (`effect: "gsChorus"`)
  * - {@link GSDelayProcessor} (`effect: "gsDelay"`)
- * - GS insertion (`effect: "gsInsertion"`). It has special treatment.
+ * - {@link GSInsertionBlock} (`effect: "gsInsertion"`)
  * - {@link XGReverbBlock} (`effect: "xgReverb"`)
  * - {@link XGChorusBlock} (`effect: "xgChorus"`)
  * - {@link XGVariationBlock} (`effect: "xgVariation"`)
@@ -4536,7 +4595,7 @@ export type EffectChangeEvent = {
    */
   effect: "gsReverb";
   /**
-   * The parameter, see {@link GSReverbProcessor}, or `macro`.
+   * The parameter, see {@link GSReverbProcessor}, or `macro` (see {@link FXType}).
    */
   parameter: FXType<GSReverbProcessor>;
   /**
@@ -4549,7 +4608,7 @@ export type EffectChangeEvent = {
    */
   effect: "gsChorus";
   /**
-   * The parameter, see {@link GSChorusProcessor}, or `macro`.
+   * The parameter, see {@link GSChorusProcessor}, or `macro` (see {@link FXType}).
    */
   parameter: FXType<GSChorusProcessor>;
   /**
@@ -4562,7 +4621,7 @@ export type EffectChangeEvent = {
    */
   effect: "gsDelay";
   /**
-   * The parameter, see {@link GSDelayProcessor}, or `macro`.
+   * The parameter, see {@link GSDelayProcessor}, or `macro` (see {@link FXType}).
    */
   parameter: FXType<GSDelayProcessor>;
   /**
@@ -4575,15 +4634,12 @@ export type EffectChangeEvent = {
    */
   effect: "gsInsertion";
   /**
-   * The parameter that was changed. This maps to GS address map at addr2 = `0x03`.
-   * See SC-8850 Manual p.237,
-   * for example:
-   * - `0x0` - EFX type, the value is 16 bit in this special case. Note that this resets the parameters!
-   * - `0x3` - EFX param 1
-   * - `0x16` - EFX param 20 (usually level)
-   * - `0x17` - EFX send to reverb
+   * 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}.
+   * - `number` - 0-based type-specific EFX parameter index (0-19). EFX parameter 1 is 0. Value is 7-bit.
    */
-  parameter: number;
+  parameter: "type" | keyof GSInsertionParameter | number;
   /**
    * The new value for the parameter.
    */
@@ -4839,7 +4895,7 @@ export interface SynthesizerEvent {
    * - {@link GSReverbProcessor} (`effect: "gsReverb"`)
    * - {@link GSChorusProcessor} (`effect: "gsChorus"`)
    * - {@link GSDelayProcessor} (`effect: "gsDelay"`)
-   * - GS insertion (`effect: "gsInsertion"`). It has special treatment.
+   * - {@link GSInsertionBlock} (`effect: "gsInsertion"`)
    * - {@link XGReverbBlock} (`effect: "xgReverb"`)
    * - {@link XGChorusBlock} (`effect: "xgChorus"`)
    * - {@link XGVariationBlock} (`effect: "xgVariation"`)
@@ -5159,6 +5215,10 @@ export interface SynthProcessorOptions {
    * Optional custom GS delay processor for the synthesizer. Leave undefined to use {@link DefaultGSDelay}.
    */
   gsDelayProcessor?: GSDelayProcessor;
+  /**
+   * Optional custom GS insertion block for the synthesizer. Leave undefined to use {@link DefaultGSInsertion}.
+   */
+  gsInsertionBlock?: GSInsertionBlock;
   /**
    * Optional custom XG reverb block for the synthesizer. Leave undefined to use {@link DefaultXGReverb}.
    *
@@ -5693,9 +5753,9 @@ interface ModifyMIDIOptions {
   /**
    * The GS Insertion Effect parameters.
    * - `"clear"` - all existing parameter change MIDI messages are cleared.
-   * - {@link GSInsertionProcessorSnapshot} - clear + the new parameters are set via System Exclusive messages.
+   * - {@link GSInsertionBlockSnapshot} - clear + the new parameters are set via System Exclusive messages.
    */
-  gsInsertionParams?: ClearableParameter<GSInsertionProcessorSnapshot>;
+  gsInsertionParams?: ClearableParameter<GSInsertionBlockSnapshot>;
   /**
    * The desired XG reverb parameters.
    * - `"clear"` - all existing parameter change MIDI messages are removed.
@@ -6786,27 +6846,33 @@ export declare class MIDIUtils {
   /**
    * Returns a MIDI event needed to set the given GS Reverb Parameter.
    * @param ticks The MIDI tick time for the output event.
-   * @param parameter The parameter to set.
+   * @param parameter The parameter to set, or `"macro"` to select a reverb macro.
    * @param value The value to set it to.
    * @returns The {@link MIDIMessage} needed to set this GS Reverb Parameter.
    */
-  static setGSReverbParameter<P extends keyof GSReverbParameter>(ticks: number, parameter: P, value: GSReverbParameter[P]): MIDIMessage;
+  static setGSReverbParameter<P extends GSReverbParameterMessage["parameter"]>(ticks: number, parameter: P, value: Extract<GSReverbParameterMessage, {
+    parameter: P;
+  }>["value"]): MIDIMessage;
   /**
    * Returns a MIDI event needed to set the given GS Chorus Parameter.
    * @param ticks The MIDI tick time for the output event.
-   * @param parameter The parameter to set.
+   * @param parameter The parameter to set, or `"macro"` to select a chorus macro.
    * @param value The value to set it to.
    * @returns The {@link MIDIMessage} needed to set this GS Chorus Parameter.
    */
-  static setGSChorusParameter<P extends keyof GSChorusParameter>(ticks: number, parameter: P, value: GSChorusParameter[P]): MIDIMessage;
+  static setGSChorusParameter<P extends GSChorusParameterMessage["parameter"]>(ticks: number, parameter: P, value: Extract<GSChorusParameterMessage, {
+    parameter: P;
+  }>["value"]): MIDIMessage;
   /**
    * Returns a MIDI event needed to set the given GS Delay Parameter.
    * @param ticks The MIDI tick time for the output event.
-   * @param parameter The parameter to set.
+   * @param parameter The parameter to set, or `"macro"` to select a delay macro.
    * @param value The value to set it to.
    * @returns The {@link MIDIMessage} needed to set this GS Delay Parameter.
    */
-  static setGSDelayParameter<P extends keyof GSDelayParameter>(ticks: number, parameter: P, value: GSDelayParameter[P]): MIDIMessage;
+  static setGSDelayParameter<P extends GSDelayParameterMessage["parameter"]>(ticks: number, parameter: P, value: Extract<GSDelayParameterMessage, {
+    parameter: P;
+  }>["value"]): MIDIMessage;
   /**
    * Returns a MIDI event needed to set the given GS Insertion Parameter.
    * @param ticks The MIDI tick time for the output event.
@@ -6850,7 +6916,7 @@ export declare class MIDIUtils {
    * @param value The value to set it to.
    * @returns The {@link MIDIMessage} needed to set this XG Variation Parameter.
    */
-  static setXGVariationParameter(ticks: number, parameter: XGVariationParameterMessage["parameter"], value: number | XGVariationConnection): MIDIMessage;
+  static setXGVariationParameter<P extends XGVariationParameterMessage["parameter"]>(ticks: number, parameter: P, value: P extends "connection" ? XGVariationConnection : number): MIDIMessage;
   /**
    * Returns a MIDI event needed to set the given XG Insertion Parameter (EFFECT 2).
    * @param ticks The MIDI tick time for the output event.
@@ -6876,7 +6942,7 @@ export declare class MIDIUtils {
   /**
    * Returns a list of MIDI events needed to set the given parameter.
    * @param ticks The MIDI tick time for output events.
-   * @param channel The channel number.
+   * @param channel The channel number. Channels above 15 are wrapped to 0-15, so the port offset is ignored.
    * @param system If the message has multiple ways of setting it,
    * this selects the preferred way. Otherwise, it prefers Universal (GM).
    * @param parameter The parameter to set.
@@ -7003,6 +7069,15 @@ export declare class MIDIUtils {
    * @returns The system exclusive MIDI message.
    */
   static reset(ticks: number, system: MIDISystem): MIDIMessage;
+  /**
+   * Returns the GS or XG SysEx message that sets a part parameter of the given channel.
+   * @param ticks The MIDI tick time for the output event.
+   * @param channel The channel number (0-15).
+   * @param system The system to prepare the message for. Any value other than `xg` will result in a GS-style message.
+   * @param parameter The parameter to set.
+   * @param data The 7-bit data byte.
+   */
+  private static partParamMessage;
   private static analyzeGM;
   private static analyzeXG;
   private static analyzeGS;
@@ -7432,6 +7507,7 @@ export declare class DefaultGSReverb implements GSReverbProcessor {
    */
   process(input: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, startIndex: number, sampleCount: number): void;
   getSnapshot(): GSReverbParameter;
+  applySnapshot(snapshot: GSReverbParameter): void;
   private updateFeedback;
   private updateLowpass;
   private updateGain;
@@ -7503,6 +7579,7 @@ export declare class DefaultGSChorus implements GSChorusProcessor {
   set level(value: number);
   process(input: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, outputReverb: Float32Array, outputDelay: Float32Array, startIndex: number, sampleCount: number): void;
   getSnapshot(): GSChorusParameter;
+  applySnapshot(snapshot: GSChorusParameter): void;
 }
 /**
  * The default GS Delay implementation for {@link SpessaSynthProcessor}.
@@ -7597,9 +7674,65 @@ export declare class DefaultGSDelay implements GSDelayProcessor {
    */
   process(input: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, outputReverb: Float32Array, startIndex: number, sampleCount: number): void;
   getSnapshot(): GSDelayParameter;
+  applySnapshot(snapshot: GSDelayParameter): void;
   private updateDelayTimes;
   private updateGain;
 }
+/**
+ * The default implementation for {@link GSInsertionBlock}.
+ *
+ * @group Synthesizer.GS Effects
+ * @sealed
+ */
+export declare class DefaultGSInsertion implements GSInsertionBlock {
+  sendLevelToReverb: number;
+  sendLevelToChorus: number;
+  sendLevelToDelay: number;
+  /**
+   * The list of effects available in this block.
+   * Effect type: processor.
+   */
+  private readonly effectMap;
+  /**
+   * The processor used when the requested type is not available.
+   */
+  private readonly fallbackProcessor;
+  /**
+   * The currently used processor.
+   */
+  private processor;
+  /**
+   * The requested EFX type.
+   */
+  private type;
+  /**
+   * The parameters set since the last type change.
+   * 255 means the parameter uses the type default.
+   */
+  private readonly params;
+  /**
+   * The left output of the processor.
+   */
+  private readonly outputLeft;
+  /**
+   * The right output of the processor.
+   */
+  private readonly outputRight;
+  /**
+   * Constructs a new default GS insertion block.
+   * @param sampleRate The sample rate, in Hertz.
+   * @param maxBufferSize The maximum buffer size the synthesizer can render at once.
+   * Attempting to `.process()` more samples than this will result in an error.
+   */
+  constructor(sampleRate: number, maxBufferSize: number);
+  setType(type: number): void;
+  getType(): number;
+  reset(): 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;
+}
 /**
  * Synthesizer's default voice cap.
  *