spessasynth_core 4.4.6 → 4.4.7

package/dist/index.d.ts

@@ -2877,6 +2877,14 @@ export interface GSInsertionParameter {
    * Higher values result in more sound being sent.
    */
   sendLevelToDelay: number;
+  /**
+   * EFX send EQ switch: routes the insertion output through the equalizer (see {@link GSEqualizerProcessor})
+   * when on, or straight to the output when off.
+   * Default is `true` (on).
+   *
+   * In the SysEx message, `0` is off and any other value is on.
+   */
+  sendEQSwitch: boolean;
   /**
    * `0-127`
    *
@@ -2937,7 +2945,8 @@ export interface GSInsertionBlockSnapshot extends GSInsertionParameter {
 }
 /**
  * The Insertion effect (EFX) processes the parts (channels) that have EFX assigned
- * (see {@link ChannelMIDIParameter.efxAssign}) and is routed straight to the output.
+ * (see {@link ChannelMIDIParameter.efxAssign}) and is routed to the output,
+ * through the equalizer unless {@link GSInsertionParameter.sendEQSwitch} is off.
  * It can additionally send its output to the reverb, chorus and delay.
  *
  * This is a Roland GS-compatible insertion interface.
@@ -2962,7 +2971,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.
+   * Type change resets the parameters, the send levels and the send EQ switch to their defaults.
    * The EFX control sources and depths are kept.
    * Behavior for unsupported types is up to the implementation.
    *
@@ -3015,6 +3024,93 @@ export interface GSInsertionBlock extends GSInsertionParameter {
    */
   applySnapshot(snapshot: GSInsertionBlockSnapshot): void;
 }
+/**
+ * GS-compatible equalizer parameters.
+ *
+ * Also see {@link GSEqualizerProcessor} to see how to implement a custom GS-compatible equalizer processor.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export interface GSEqualizerParameter {
+  /**
+   * 0-1
+   * 200 Hz, 400 Hz
+   * This parameter sets the frequency of the low range shelf.
+   */
+  lowFrequency: number;
+  /**
+   * 52-76 (`0x34`-`0x4C`)
+   * -12 dB - 0 dB - +12 dB
+   * This parameter sets the amount of boost or cut for the low frequency range.
+   * 64 is 0 dB, each step is 1 dB.
+   */
+  lowGain: number;
+  /**
+   * 0-1
+   * 3 kHz, 6 kHz
+   * This parameter sets the frequency of the high range shelf.
+   */
+  highFrequency: number;
+  /**
+   * 52-76 (`0x34`-`0x4C`)
+   * -12 dB - 0 dB - +12 dB
+   * This parameter sets the amount of boost or cut for the high frequency range.
+   * 64 is 0 dB, each step is 1 dB.
+   */
+  highGain: number;
+}
+/**
+ * The equalizer is a two-band (low and high) shelving equalizer which boosts or cuts specified frequency
+ * ranges of the sound. An equalizer lets you
+ * boost or cut specified frequency ranges of a sound to adjust the tone. For each range,
+ * high and low, you can specify the frequency and the amount of boost or cut (gain).
+ *
+ * Only the parts with EQ enabled (see {@link ChannelMIDIParameter.eqEnabled}) pass through it,
+ * and the insertion effect passes through it when {@link GSInsertionParameter.sendEQSwitch} is on.
+ * The reverb, chorus and delay outputs do not.
+ *
+ * This is a Roland GS-compatible equalizer interface.
+ *
+ * It is used when {@link GlobalMIDIParameter.system} is `gm` `gm2` or `gs`.
+ *
+ * > **Note**
+ * >
+ * > The equalizer is disabled in XG mode.
+ *
+ * {@link SpessaSynthProcessor} allows you to supply a custom equalizer processor.
+ * A custom equalizer processor 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.78, 86, 236) for more information.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export interface GSEqualizerProcessor extends GSEqualizerParameter {
+  /**
+   * Process the effect and **adds** it to the output.
+   * @param inputLeft The left input buffer to process. It always starts at index 0.
+   * @param inputRight The right input buffer to process. It always starts at index 0.
+   * @param outputLeft The left output buffer.
+   * @param outputRight The right output buffer.
+   * @param startIndex The index to start mixing at into the output buffers.
+   * @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, startIndex: number, sampleCount: number): void;
+  /**
+   * Gets a snapshot of this effect processor instance.
+   */
+  getSnapshot(): GSEqualizerParameter;
+  /**
+   * Restores this effect processor instance from a snapshot.
+   * @param snapshot The snapshot to restore.
+   */
+  applySnapshot(snapshot: GSEqualizerParameter): void;
+}
 /**
  * A snapshot of a {@link XGEffectBlock}.
  *
@@ -3482,6 +3578,17 @@ interface GlobalSystemParameter {
    * the delay parameters then locking it to prevent changes by MIDI files.
    */
   gsDelayLock: boolean;
+  /**
+   * If the synthesizer should prevent editing of the GS equalizer parameters.
+   * This effect is modified using MIDI system exclusive messages, so
+   * the recommended use case would be setting
+   * the equalizer parameters then locking it to prevent changes by MIDI files.
+   *
+   * > **Warning**
+   * >
+   * > To lock the channel equalizer switch, lock the {@link ChannelMIDIParameter.eqEnabled `eqEnabled`} parameter instead.
+   */
+  gsEqualizerLock: boolean;
   /**
    * The XG variation gain when in system mode. {@link XGVariationConnection}
    * From 0 to any number. 1 is 100% variation.
@@ -3934,6 +4041,10 @@ interface SynthesizerSnapshot {
    * A snapshot of the delay processor.
    */
   gsDelayProcessor: GSDelayParameter;
+  /**
+   * A snapshot of the equalizer processor.
+   */
+  gsEqualizerProcessor: GSEqualizerParameter;
   /**
    * A snapshot of the GS insertion block.
    */
@@ -4509,6 +4620,25 @@ export type GSDelayParameterMessage = { [P in keyof GSDelayParameter]: {
    */
   value: number;
 };
+/**
+ * Represents an analyzed GS Equalizer Processor change.
+ *
+ * @group MIDI.Protocol
+ */
+export type GSEqualizerParameterMessage = { [P in keyof GSEqualizerParameter]: {
+  /**
+   * The message type identifier.
+   */
+  type: "GS Equalizer Param";
+  /**
+   * The GS equalizer parameter being modified.
+   */
+  parameter: P;
+  /**
+   * The new value of the GS equalizer parameter.
+   */
+  value: GSEqualizerParameter[P];
+}; }[keyof GSEqualizerParameter];
 /**
  * Represents an analyzed GS Insertion Processor change.
  *
@@ -4535,11 +4665,24 @@ export type GSInsertionParameterMessage = {
   /**
    * The parameter name that was modified in the processor: a send level or an EFX control setting.
    */
-  parameter: keyof GSInsertionParameter;
+  parameter: Exclude<keyof GSInsertionParameter, "sendEQSwitch">;
   /**
    * The new value of the parameter.
    */
   value: number;
+} | {
+  /**
+   * An insertion effect processor parameter message (Roland GS).
+   */
+  type: "GS Insertion Param";
+  /**
+   * The send EQ switch, see {@link GSInsertionParameter.sendEQSwitch}.
+   */
+  parameter: "sendEQSwitch";
+  /**
+   * If the insertion output goes through the equalizer.
+   */
+  value: boolean;
 } | {
   /**
    * An insertion effect processor parameter message (Roland GS).
@@ -4884,7 +5027,7 @@ export type AnalyzedParameter = {
  *
  * @group MIDI.Protocol
  */
-export type AnalyzedMIDIMessage = AnalyzedParameter | GSReverbParameterMessage | GSChorusParameterMessage | GSDelayParameterMessage | GSInsertionParameterMessage | XGReverbParameterMessage | XGChorusParameterMessage | XGVariationParameterMessage | XGInsertionParameterMessage | {
+export type AnalyzedMIDIMessage = AnalyzedParameter | GSReverbParameterMessage | GSChorusParameterMessage | GSDelayParameterMessage | GSEqualizerParameterMessage | GSInsertionParameterMessage | XGReverbParameterMessage | XGChorusParameterMessage | XGVariationParameterMessage | XGInsertionParameterMessage | {
   /**
    * A MIDI program change message configured via System Exclusive.
    */
@@ -5111,6 +5254,7 @@ export type FXType<K> = Exclude<keyof K, "process" | "getSnapshot" | "applySnaps
  * - {@link GSReverbProcessor} (`effect: "gsReverb"`)
  * - {@link GSChorusProcessor} (`effect: "gsChorus"`)
  * - {@link GSDelayProcessor} (`effect: "gsDelay"`)
+ * - {@link GSEqualizerProcessor} (`effect: "gsEqualizer"`)
  * - {@link GSInsertionBlock} (`effect: "gsInsertion"`)
  * - {@link XGReverbBlock} (`effect: "xgReverb"`)
  * - {@link XGChorusBlock} (`effect: "xgChorus"`)
@@ -5159,6 +5303,19 @@ export type EffectChangeEvent = {
    * The new 7-bit value.
    */
   value: number;
+} | {
+  /**
+   * The effect that was changed: Roland GS equalizer.
+   */
+  effect: "gsEqualizer";
+  /**
+   * The parameter, see {@link GSEqualizerParameter}.
+   */
+  parameter: keyof GSEqualizerParameter;
+  /**
+   * The new 7-bit value.
+   */
+  value: number;
 } | {
   /**
    * The effect that was changed: Roland GS insertion.
@@ -5171,11 +5328,24 @@ export type EffectChangeEvent = {
    * - `"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;
+  parameter: "type" | Exclude<keyof GSInsertionParameter, "sendEQSwitch"> | number;
   /**
    * The new value for the parameter.
    */
   value: number;
+} | {
+  /**
+   * The effect that was changed: Roland GS insertion.
+   */
+  effect: "gsInsertion";
+  /**
+   * The send EQ switch, see {@link GSInsertionParameter.sendEQSwitch}.
+   */
+  parameter: "sendEQSwitch";
+  /**
+   * If the insertion output goes through the equalizer.
+   */
+  value: boolean;
 } | {
   /**
    * The effect that was changed: Yamaha XG reverb block.
@@ -5820,6 +5990,10 @@ export interface SynthProcessorOptions {
    * Optional custom GS delay processor for the synthesizer. Leave undefined to use {@link DefaultGSDelay}.
    */
   gsDelayProcessor?: GSDelayProcessor;
+  /**
+   * Optional custom GS equalizer processor for the synthesizer. Leave undefined to use {@link DefaultGSEqualizer}.
+   */
+  gsEqualizerProcessor?: GSEqualizerProcessor;
   /**
    * Optional custom GS insertion block for the synthesizer. Leave undefined to use {@link DefaultGSInsertion}.
    */
@@ -6082,6 +6256,16 @@ interface ChannelMIDIParameter {
    * Indicates whether this channel uses the GS insertion EFX processor.
    */
   efxAssign: boolean;
+  /**
+   * Indicates whether this channel passes through the GS equalizer (see {@link GSEqualizerProcessor}).
+   * Default is `true`, like on the Sound Canvas.
+   *
+   * > **Note**
+   * >
+   * > Channels with {@link efxAssign} enabled ignore this.
+   * > Their equalizer routing is set by {@link GSInsertionParameter.sendEQSwitch} instead.
+   */
+  eqEnabled: boolean;
   /**
    * CC1 for GS controller matrix.
    * An arbitrary MIDI controller, which can be bound to any synthesis parameter.
@@ -6350,6 +6534,12 @@ interface ModifyMIDIOptions {
    * - {@link GSDelayParameter} - clear + the new parameters are set via System Exclusive messages.
    */
   gsDelayParams?: ClearableParameter<GSDelayParameter>;
+  /**
+   * The GS equalizer parameters.
+   * - `"clear"` - all existing parameter change MIDI messages are cleared.
+   * - {@link GSEqualizerParameter} - clear + the new parameters are set via System Exclusive messages.
+   */
+  gsEqualizerParams?: ClearableParameter<GSEqualizerParameter>;
   /**
    * The GS Insertion Effect parameters.
    * - `"clear"` - all existing parameter change MIDI messages are cleared.
@@ -7515,15 +7705,23 @@ export declare class MIDIUtils {
   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 Equalizer Parameter.
+   * @param ticks The MIDI tick time for the output event.
+   * @param parameter The parameter to set.
+   * @param value The value to set it to.
+   * @returns The {@link MIDIMessage} needed to set this GS Equalizer Parameter.
+   */
+  static setGSEqualizerParameter(ticks: number, parameter: GSEqualizerParameterMessage["parameter"], value: number): MIDIMessage;
   /**
    * 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 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.
+   * @param value The value to set it to. A boolean for `"sendEQSwitch"`.
    * @returns The {@link MIDIMessage} needed to set this GS Insertion Parameter.
    */
-  static setGSInsertionParameter(ticks: number, parameter: GSInsertionParameterMessage["parameter"], value: number): MIDIMessage;
+  static setGSInsertionParameter(ticks: number, parameter: GSInsertionParameterMessage["parameter"], value: number | boolean): MIDIMessage;
   /**
    * Returns a MIDI event needed to set the given XG Reverb Parameter.
    * @param ticks The MIDI tick time for the output event.
@@ -8325,6 +8523,47 @@ export declare class DefaultGSDelay implements GSDelayProcessor {
   private updateDelayTimes;
   private updateGain;
 }
+/**
+ * The default GS Equalizer implementation for {@link SpessaSynthProcessor}.
+ *
+ * @group Synthesizer.GS Effects
+ */
+export declare class DefaultGSEqualizer implements GSEqualizerProcessor {
+  private readonly sampleRate;
+  private lowB0;
+  private lowB1;
+  private lowA1;
+  private highB0;
+  private highB1;
+  private highA1;
+  private lowZL;
+  private lowZR;
+  private highZL;
+  private highZR;
+  /**
+   * Constructs a new default GS equalizer processor.
+   * @param sampleRate The sample rate, in Hertz.
+   */
+  constructor(sampleRate: number);
+  private _lowFrequency;
+  get lowFrequency(): number;
+  set lowFrequency(value: number);
+  private _lowGain;
+  get lowGain(): number;
+  set lowGain(value: number);
+  private _highFrequency;
+  get highFrequency(): number;
+  set highFrequency(value: number);
+  private _highGain;
+  get highGain(): number;
+  set highGain(value: number);
+  process(inputLeft: Float32Array, inputRight: Float32Array, outputLeft: Float32Array, outputRight: Float32Array, startIndex: number, sampleCount: number): void;
+  getSnapshot(): GSEqualizerParameter;
+  applySnapshot(snapshot: GSEqualizerParameter): void;
+  private getBand;
+  private updateLow;
+  private updateHigh;
+}
 /**
  * The default implementation for {@link GSInsertionBlock}.
  *
@@ -8335,6 +8574,7 @@ export declare class DefaultGSInsertion implements GSInsertionBlock {
   sendLevelToReverb: number;
   sendLevelToChorus: number;
   sendLevelToDelay: number;
+  sendEQSwitch: boolean;
   controlSource1: number;
   controlDepth1: number;
   controlSource2: number;