mirror of
https://github.com/Tonejs/Tone.js
synced 2024-12-26 19:43:12 +00:00
393 lines
12 KiB
TypeScript
393 lines
12 KiB
TypeScript
import { MidiClass } from "../core/type/Midi";
|
|
import { Frequency, MidiNote, NormalRange, Seconds, Time } from "../core/type/Units";
|
|
import { deepMerge, omitFromObject, optionsFromArguments } from "../core/util/Defaults";
|
|
import { RecursivePartial } from "../core/util/Interface";
|
|
import { isArray, isNumber } from "../core/util/TypeCheck";
|
|
import { Instrument, InstrumentOptions } from "./Instrument";
|
|
import { MembraneSynth, MembraneSynthOptions } from "./MembraneSynth";
|
|
import { FMSynth, FMSynthOptions } from "./FMSynth";
|
|
import { AMSynth, AMSynthOptions } from "./AMSynth";
|
|
import { MetalSynth, MetalSynthOptions } from "./MetalSynth";
|
|
import { Monophonic } from "./Monophonic";
|
|
import { Synth, SynthOptions } from "./Synth";
|
|
import { assert, warn } from "../core/util/Debug";
|
|
|
|
type VoiceConstructor<V> = {
|
|
getDefaults: () => VoiceOptions<V>;
|
|
} & (new (...args: any[]) => V);
|
|
|
|
type OmitMonophonicOptions<T> = Omit<T, "context" | "onsilence">;
|
|
|
|
type VoiceOptions<T> =
|
|
T extends MembraneSynth ? MembraneSynthOptions :
|
|
T extends MetalSynth ? MetalSynthOptions :
|
|
T extends FMSynth ? FMSynthOptions :
|
|
T extends AMSynth ? AMSynthOptions :
|
|
T extends Synth ? SynthOptions :
|
|
never;
|
|
|
|
/**
|
|
* The settable synth options. excludes monophonic options.
|
|
*/
|
|
type PartialVoiceOptions<T> = RecursivePartial<OmitMonophonicOptions<VoiceOptions<T>>>;
|
|
|
|
export interface PolySynthOptions<Voice> extends InstrumentOptions {
|
|
maxPolyphony: number;
|
|
voice: VoiceConstructor<Voice>;
|
|
options: PartialVoiceOptions<Voice>;
|
|
}
|
|
|
|
/**
|
|
* PolySynth handles voice creation and allocation for any
|
|
* instruments passed in as the second paramter. PolySynth is
|
|
* not a synthesizer by itself, it merely manages voices of
|
|
* one of the other types of synths, allowing any of the
|
|
* monophonic synthesizers to be polyphonic.
|
|
*
|
|
* @example
|
|
* import { PolySynth } from "tone";
|
|
* const synth = new PolySynth().toDestination();
|
|
* // set the attributes across all the voices using 'set'
|
|
* synth.set({ detune: -1200 });
|
|
* // play a chord
|
|
* synth.triggerAttackRelease(["C4", "E4", "A4"], 1);
|
|
* @category Instrument
|
|
*/
|
|
export class PolySynth<Voice extends Monophonic<any> = Synth> extends Instrument<VoiceOptions<Voice>> {
|
|
|
|
readonly name: string = "PolySynth";
|
|
|
|
/**
|
|
* The voices which are not currently in use
|
|
*/
|
|
private _availableVoices: Voice[] = [];
|
|
|
|
/**
|
|
* The currently active voices
|
|
*/
|
|
private _activeVoices: Array<{midi: MidiNote; voice: Voice; released: boolean}> = [];
|
|
|
|
/**
|
|
* All of the allocated voices for this synth.
|
|
*/
|
|
private _voices: Voice[] = [];
|
|
|
|
/**
|
|
* The options that are set on the synth.
|
|
*/
|
|
private options: VoiceOptions<Voice>;
|
|
|
|
/**
|
|
* The polyphony limit.
|
|
*/
|
|
maxPolyphony: number;
|
|
|
|
/**
|
|
* The voice constructor
|
|
*/
|
|
private readonly voice: VoiceConstructor<Voice>;
|
|
|
|
/**
|
|
* A voice used for holding the get/set values
|
|
*/
|
|
private _dummyVoice: Voice;
|
|
|
|
/**
|
|
* The GC timeout. Held so that it could be cancelled when the node is disposed.
|
|
*/
|
|
private _gcTimeout = -1;
|
|
|
|
/**
|
|
* A moving average of the number of active voices
|
|
*/
|
|
private _averageActiveVoices = 0;
|
|
|
|
/**
|
|
* @param voice The constructor of the voices
|
|
* @param options The options object to set the synth voice
|
|
*/
|
|
constructor(
|
|
voice?: VoiceConstructor<Voice>,
|
|
options?: PartialVoiceOptions<Voice>,
|
|
);
|
|
constructor(options?: Partial<PolySynthOptions<Voice>>);
|
|
constructor() {
|
|
|
|
super(optionsFromArguments(PolySynth.getDefaults(), arguments, ["voice", "options"]));
|
|
const options = optionsFromArguments(PolySynth.getDefaults(), arguments, ["voice", "options"]);
|
|
|
|
// check against the old API (pre 14.3.0)
|
|
assert(!isNumber(options.voice), "DEPRECATED: The polyphony count is no longer the first argument.");
|
|
|
|
const defaults = options.voice.getDefaults();
|
|
this.options = Object.assign(defaults, options.options) as VoiceOptions<Voice>;
|
|
this.voice = options.voice as unknown as VoiceConstructor<Voice>;
|
|
this.maxPolyphony = options.maxPolyphony;
|
|
|
|
// create the first voice
|
|
this._dummyVoice = this._getNextAvailableVoice() as Voice;
|
|
// remove it from the voices list
|
|
const index = this._voices.indexOf(this._dummyVoice);
|
|
this._voices.splice(index, 1);
|
|
// kick off the GC interval
|
|
this._gcTimeout = this.context.setInterval(this._collectGarbage.bind(this), 1);
|
|
}
|
|
|
|
static getDefaults(): PolySynthOptions<Synth> {
|
|
return Object.assign(Instrument.getDefaults(), {
|
|
maxPolyphony: 32,
|
|
options: {},
|
|
voice: Synth,
|
|
});
|
|
}
|
|
|
|
/**
|
|
* The number of active voices.
|
|
*/
|
|
get activeVoices(): number {
|
|
return this._activeVoices.length;
|
|
}
|
|
|
|
/**
|
|
* Invoked when the source is done making sound, so that it can be
|
|
* readded to the pool of available voices
|
|
*/
|
|
private _makeVoiceAvailable(voice: Voice): void {
|
|
this._availableVoices.push(voice);
|
|
// remove the midi note from 'active voices'
|
|
const activeVoiceIndex = this._activeVoices.findIndex((e) => e.voice === voice);
|
|
this._activeVoices.splice(activeVoiceIndex, 1);
|
|
}
|
|
|
|
/**
|
|
* Get an available voice from the pool of available voices.
|
|
* If one is not available and the maxPolyphony limit is reached,
|
|
* steal a voice, otherwise return null.
|
|
*/
|
|
private _getNextAvailableVoice(): Voice | undefined {
|
|
// if there are available voices, return the first one
|
|
if (this._availableVoices.length) {
|
|
return this._availableVoices.shift();
|
|
} else if (this._voices.length < this.maxPolyphony) {
|
|
// otherwise if there is still more maxPolyphony, make a new voice
|
|
const voice = new this.voice(Object.assign(this.options, {
|
|
context: this.context,
|
|
onsilence: this._makeVoiceAvailable.bind(this),
|
|
}));
|
|
voice.connect(this.output);
|
|
this._voices.push(voice);
|
|
return voice;
|
|
} else {
|
|
warn("Max polyphony exceeded. Note dropped.");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Occasionally check if there are any allocated voices which can be cleaned up.
|
|
*/
|
|
private _collectGarbage(): void {
|
|
this._averageActiveVoices = Math.max(this._averageActiveVoices * 0.95, this.activeVoices);
|
|
if (this._availableVoices.length && this._voices.length > Math.ceil(this._averageActiveVoices + 1)) {
|
|
// take off an available note
|
|
const firstAvail = this._availableVoices.shift() as Voice;
|
|
const index = this._voices.indexOf(firstAvail);
|
|
this._voices.splice(index, 1);
|
|
if (!this.context.isOffline) {
|
|
firstAvail.dispose();
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Internal method which triggers the attack
|
|
*/
|
|
private _triggerAttack(notes: Frequency[], time: Seconds, velocity?: NormalRange): void {
|
|
notes.forEach(note => {
|
|
const midiNote = new MidiClass(this.context, note).toMidi();
|
|
const voice = this._getNextAvailableVoice();
|
|
if (voice) {
|
|
voice.triggerAttack(note, time, velocity);
|
|
this._activeVoices.push({
|
|
midi: midiNote, voice, released: false,
|
|
});
|
|
this.log("triggerAttack", note, time);
|
|
}
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Internal method which triggers the release
|
|
*/
|
|
private _triggerRelease(notes: Frequency[], time: Seconds): void {
|
|
notes.forEach(note => {
|
|
const midiNote = new MidiClass(this.context, note).toMidi();
|
|
const event = this._activeVoices.find(({ midi, released }) => midi === midiNote && !released);
|
|
if (event) {
|
|
// trigger release on that note
|
|
event.voice.triggerRelease(time);
|
|
// mark it as released
|
|
event.released = true;
|
|
this.log("triggerRelease", note, time);
|
|
}
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Schedule the attack/release events. If the time is in the future, then it should set a timeout
|
|
* to wait for just-in-time scheduling
|
|
*/
|
|
private _scheduleEvent(type: "attack" | "release", notes: Frequency[], time: Seconds, velocity?: NormalRange): void {
|
|
assert(!this.disposed, "Synth was already disposed");
|
|
// if the notes are greater than this amount of time in the future, they should be scheduled with setTimeout
|
|
if (time <= this.now()) {
|
|
// do it immediately
|
|
if (type === "attack") {
|
|
this._triggerAttack(notes, time, velocity);
|
|
} else {
|
|
this._triggerRelease(notes, time);
|
|
}
|
|
} else {
|
|
// schedule it to start in the future
|
|
this.context.setTimeout(() => {
|
|
this._scheduleEvent(type, notes, time, velocity);
|
|
}, time - this.now());
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Trigger the attack portion of the note
|
|
* @param notes The notes to play. Accepts a single Frequency or an array of frequencies.
|
|
* @param time The start time of the note.
|
|
* @param velocity The velocity of the note.
|
|
* @example
|
|
* import { FMSynth, now, PolySynth } from "tone";
|
|
* const synth = new PolySynth(FMSynth).toDestination();
|
|
* // trigger a chord immediately with a velocity of 0.2
|
|
* synth.triggerAttack(["Ab3", "C4", "F5"], now(), 0.2);
|
|
*/
|
|
triggerAttack(notes: Frequency | Frequency[], time?: Time, velocity?: NormalRange): this {
|
|
|
|
if (!Array.isArray(notes)) {
|
|
notes = [notes];
|
|
}
|
|
const computedTime = this.toSeconds(time);
|
|
this._scheduleEvent("attack", notes, computedTime, velocity);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Trigger the release of the note. Unlike monophonic instruments,
|
|
* a note (or array of notes) needs to be passed in as the first argument.
|
|
* @param notes The notes to play. Accepts a single Frequency or an array of frequencies.
|
|
* @param time When the release will be triggered.
|
|
* @example
|
|
* @example
|
|
* import { AMSynth, PolySynth } from "tone";
|
|
* const poly = new PolySynth(AMSynth).toDestination();
|
|
* poly.triggerAttack(["Ab3", "C4", "F5"]);
|
|
* // trigger the release of the given notes.
|
|
* poly.triggerRelease(["Ab3", "C4"], "+1");
|
|
* poly.triggerRelease("F5", "+3");
|
|
*/
|
|
triggerRelease(notes: Frequency | Frequency[], time?: Time): this {
|
|
if (!Array.isArray(notes)) {
|
|
notes = [notes];
|
|
}
|
|
const computedTime = this.toSeconds(time);
|
|
this._scheduleEvent("release", notes, computedTime);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Trigger the attack and release after the specified duration
|
|
* @param notes The notes to play. Accepts a single Frequency or an array of frequencies.
|
|
* @param duration the duration of the note
|
|
* @param time if no time is given, defaults to now
|
|
* @param velocity the velocity of the attack (0-1)
|
|
* @example
|
|
* import { AMSynth, PolySynth } from "tone";
|
|
* const poly = new PolySynth(AMSynth).toDestination();
|
|
* // can pass in an array of durations as well
|
|
* poly.triggerAttackRelease(["Eb3", "G4", "Bb4", "D5"], [4, 3, 2, 1]);
|
|
*/
|
|
triggerAttackRelease(
|
|
notes: Frequency | Frequency[],
|
|
duration: Time | Time[],
|
|
time?: Time,
|
|
velocity?: NormalRange,
|
|
): this {
|
|
const computedTime = this.toSeconds(time);
|
|
this.triggerAttack(notes, computedTime, velocity);
|
|
if (isArray(duration)) {
|
|
assert(isArray(notes), "If the duration is an array, the notes must also be an array");
|
|
notes = notes as Frequency[];
|
|
for (let i = 0; i < notes.length; i++) {
|
|
const d = duration[Math.min(i, duration.length - 1)];
|
|
const durationSeconds = this.toSeconds(d);
|
|
assert(durationSeconds > 0, "The duration must be greater than 0");
|
|
this.triggerRelease(notes[i], computedTime + durationSeconds);
|
|
}
|
|
} else {
|
|
const durationSeconds = this.toSeconds(duration);
|
|
assert(durationSeconds > 0, "The duration must be greater than 0");
|
|
this.triggerRelease(notes, computedTime + durationSeconds);
|
|
}
|
|
return this;
|
|
}
|
|
|
|
sync(): this {
|
|
this._syncMethod("triggerAttack", 1);
|
|
this._syncMethod("triggerRelease", 1);
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Set a member/attribute of the voices
|
|
* @example
|
|
* import { PolySynth } from "tone";
|
|
* const poly = new PolySynth().toDestination();
|
|
* // set all of the voices using an options object for the synth type
|
|
* poly.set({
|
|
* envelope: {
|
|
* attack: 0.25
|
|
* }
|
|
* });
|
|
* poly.triggerAttackRelease("Bb3", 0.2);
|
|
*/
|
|
set(options: RecursivePartial<VoiceOptions<Voice>>): this {
|
|
// remove options which are controlled by the PolySynth
|
|
const sanitizedOptions = omitFromObject(options, ["onsilence", "context"]);
|
|
// store all of the options
|
|
this.options = deepMerge(this.options, sanitizedOptions);
|
|
this._voices.forEach(voice => voice.set(sanitizedOptions));
|
|
this._dummyVoice.set(sanitizedOptions);
|
|
return this;
|
|
}
|
|
|
|
get(): VoiceOptions<Voice> {
|
|
return this._dummyVoice.get();
|
|
}
|
|
|
|
/**
|
|
* Trigger the release portion of all the currently active voices immediately.
|
|
* Useful for silencing the synth.
|
|
*/
|
|
releaseAll(): this {
|
|
const now = this.now();
|
|
this._activeVoices.forEach(({ voice }) => {
|
|
voice.triggerRelease(now);
|
|
});
|
|
this._activeVoices = [];
|
|
return this;
|
|
}
|
|
|
|
dispose(): this {
|
|
super.dispose();
|
|
this._dummyVoice.dispose();
|
|
this._voices.forEach(v => v.dispose());
|
|
this._activeVoices = [];
|
|
this._availableVoices = [];
|
|
this.context.clearInterval(this._gcTimeout);
|
|
return this;
|
|
}
|
|
}
|