mirror of
https://github.com/Tonejs/Tone.js
synced 2024-12-25 19:13:08 +00:00
372 lines
10 KiB
TypeScript
372 lines
10 KiB
TypeScript
import { ToneAudioBuffer } from "../core/context/ToneAudioBuffer.js";
|
|
import { ToneAudioBuffers } from "../core/context/ToneAudioBuffers.js";
|
|
import { ftomf, intervalToFrequencyRatio } from "../core/type/Conversions.js";
|
|
import { FrequencyClass } from "../core/type/Frequency.js";
|
|
import {
|
|
Frequency,
|
|
Interval,
|
|
MidiNote,
|
|
NormalRange,
|
|
Note,
|
|
Time,
|
|
} from "../core/type/Units.js";
|
|
import { optionsFromArguments } from "../core/util/Defaults.js";
|
|
import { noOp } from "../core/util/Interface.js";
|
|
import { isArray, isNote, isNumber } from "../core/util/TypeCheck.js";
|
|
import { Instrument, InstrumentOptions } from "../instrument/Instrument.js";
|
|
import {
|
|
ToneBufferSource,
|
|
ToneBufferSourceCurve,
|
|
} from "../source/buffer/ToneBufferSource.js";
|
|
import { timeRange } from "../core/util/Decorator.js";
|
|
import { assert } from "../core/util/Debug.js";
|
|
|
|
interface SamplesMap {
|
|
[note: string]: ToneAudioBuffer | AudioBuffer | string;
|
|
[midi: number]: ToneAudioBuffer | AudioBuffer | string;
|
|
}
|
|
|
|
export interface SamplerOptions extends InstrumentOptions {
|
|
attack: Time;
|
|
release: Time;
|
|
onload: () => void;
|
|
onerror: (error: Error) => void;
|
|
baseUrl: string;
|
|
curve: ToneBufferSourceCurve;
|
|
urls: SamplesMap;
|
|
}
|
|
|
|
/**
|
|
* Pass in an object which maps the note's pitch or midi value to the url,
|
|
* then you can trigger the attack and release of that note like other instruments.
|
|
* By automatically repitching the samples, it is possible to play pitches which
|
|
* were not explicitly included which can save loading time.
|
|
*
|
|
* For sample or buffer playback where repitching is not necessary,
|
|
* use {@link Player}.
|
|
* @example
|
|
* const sampler = new Tone.Sampler({
|
|
* urls: {
|
|
* A1: "A1.mp3",
|
|
* A2: "A2.mp3",
|
|
* },
|
|
* baseUrl: "https://tonejs.github.io/audio/casio/",
|
|
* onload: () => {
|
|
* sampler.triggerAttackRelease(["C1", "E1", "G1", "B1"], 0.5);
|
|
* }
|
|
* }).toDestination();
|
|
* @category Instrument
|
|
*/
|
|
export class Sampler extends Instrument<SamplerOptions> {
|
|
readonly name: string = "Sampler";
|
|
|
|
/**
|
|
* The stored and loaded buffers
|
|
*/
|
|
private _buffers: ToneAudioBuffers;
|
|
|
|
/**
|
|
* The object of all currently playing BufferSources
|
|
*/
|
|
private _activeSources: Map<MidiNote, ToneBufferSource[]> = new Map();
|
|
|
|
/**
|
|
* The envelope applied to the beginning of the sample.
|
|
* @min 0
|
|
* @max 1
|
|
*/
|
|
@timeRange(0)
|
|
attack: Time;
|
|
|
|
/**
|
|
* The envelope applied to the end of the envelope.
|
|
* @min 0
|
|
* @max 1
|
|
*/
|
|
@timeRange(0)
|
|
release: Time;
|
|
|
|
/**
|
|
* The shape of the attack/release curve.
|
|
* Either "linear" or "exponential"
|
|
*/
|
|
curve: ToneBufferSourceCurve;
|
|
|
|
/**
|
|
* @param samples An object of samples mapping either Midi Note Numbers or
|
|
* Scientific Pitch Notation to the url of that sample.
|
|
* @param onload The callback to invoke when all of the samples are loaded.
|
|
* @param baseUrl The root URL of all of the samples, which is prepended to all the URLs.
|
|
*/
|
|
constructor(samples?: SamplesMap, onload?: () => void, baseUrl?: string);
|
|
/**
|
|
* @param samples An object of samples mapping either Midi Note Numbers or
|
|
* Scientific Pitch Notation to the url of that sample.
|
|
* @param options The remaining options associated with the sampler
|
|
*/
|
|
constructor(
|
|
samples?: SamplesMap,
|
|
options?: Partial<Omit<SamplerOptions, "urls">>
|
|
);
|
|
constructor(options?: Partial<SamplerOptions>);
|
|
constructor() {
|
|
const options = optionsFromArguments(
|
|
Sampler.getDefaults(),
|
|
arguments,
|
|
["urls", "onload", "baseUrl"],
|
|
"urls"
|
|
);
|
|
super(options);
|
|
|
|
const urlMap = {};
|
|
Object.keys(options.urls).forEach((note) => {
|
|
const noteNumber = parseInt(note, 10);
|
|
assert(
|
|
isNote(note) || (isNumber(noteNumber) && isFinite(noteNumber)),
|
|
`url key is neither a note or midi pitch: ${note}`
|
|
);
|
|
if (isNote(note)) {
|
|
// convert the note name to MIDI
|
|
const mid = new FrequencyClass(this.context, note).toMidi();
|
|
urlMap[mid] = options.urls[note];
|
|
} else if (isNumber(noteNumber) && isFinite(noteNumber)) {
|
|
// otherwise if it's numbers assume it's midi
|
|
urlMap[noteNumber] = options.urls[noteNumber];
|
|
}
|
|
});
|
|
|
|
this._buffers = new ToneAudioBuffers({
|
|
urls: urlMap,
|
|
onload: options.onload,
|
|
baseUrl: options.baseUrl,
|
|
onerror: options.onerror,
|
|
});
|
|
this.attack = options.attack;
|
|
this.release = options.release;
|
|
this.curve = options.curve;
|
|
|
|
// invoke the callback if it's already loaded
|
|
if (this._buffers.loaded) {
|
|
// invoke onload deferred
|
|
Promise.resolve().then(options.onload);
|
|
}
|
|
}
|
|
|
|
static getDefaults(): SamplerOptions {
|
|
return Object.assign(Instrument.getDefaults(), {
|
|
attack: 0,
|
|
baseUrl: "",
|
|
curve: "exponential" as const,
|
|
onload: noOp,
|
|
onerror: noOp,
|
|
release: 0.1,
|
|
urls: {},
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Returns the difference in steps between the given midi note at the closets sample.
|
|
*/
|
|
private _findClosest(midi: MidiNote): Interval {
|
|
// searches within 8 octaves of the given midi note
|
|
const MAX_INTERVAL = 96;
|
|
let interval = 0;
|
|
while (interval < MAX_INTERVAL) {
|
|
// check above and below
|
|
if (this._buffers.has(midi + interval)) {
|
|
return -interval;
|
|
} else if (this._buffers.has(midi - interval)) {
|
|
return interval;
|
|
}
|
|
interval++;
|
|
}
|
|
throw new Error(`No available buffers for note: ${midi}`);
|
|
}
|
|
|
|
/**
|
|
* @param notes The note to play, or an array of notes.
|
|
* @param time When to play the note
|
|
* @param velocity The velocity to play the sample back.
|
|
*/
|
|
triggerAttack(
|
|
notes: Frequency | Frequency[],
|
|
time?: Time,
|
|
velocity: NormalRange = 1
|
|
): this {
|
|
this.log("triggerAttack", notes, time, velocity);
|
|
if (!Array.isArray(notes)) {
|
|
notes = [notes];
|
|
}
|
|
notes.forEach((note) => {
|
|
const midiFloat = ftomf(
|
|
new FrequencyClass(this.context, note).toFrequency()
|
|
);
|
|
const midi = Math.round(midiFloat) as MidiNote;
|
|
const remainder = midiFloat - midi;
|
|
// find the closest note pitch
|
|
const difference = this._findClosest(midi);
|
|
const closestNote = midi - difference;
|
|
const buffer = this._buffers.get(closestNote);
|
|
const playbackRate = intervalToFrequencyRatio(
|
|
difference + remainder
|
|
);
|
|
// play that note
|
|
const source = new ToneBufferSource({
|
|
url: buffer,
|
|
context: this.context,
|
|
curve: this.curve,
|
|
fadeIn: this.attack,
|
|
fadeOut: this.release,
|
|
playbackRate,
|
|
}).connect(this.output);
|
|
source.start(time, 0, buffer.duration / playbackRate, velocity);
|
|
// add it to the active sources
|
|
if (!isArray(this._activeSources.get(midi))) {
|
|
this._activeSources.set(midi, []);
|
|
}
|
|
(this._activeSources.get(midi) as ToneBufferSource[]).push(source);
|
|
|
|
// remove it when it's done
|
|
source.onended = () => {
|
|
if (this._activeSources && this._activeSources.has(midi)) {
|
|
const sources = this._activeSources.get(
|
|
midi
|
|
) as ToneBufferSource[];
|
|
const index = sources.indexOf(source);
|
|
if (index !== -1) {
|
|
sources.splice(index, 1);
|
|
}
|
|
}
|
|
};
|
|
});
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* @param notes The note to release, or an array of notes.
|
|
* @param time When to release the note.
|
|
*/
|
|
triggerRelease(notes: Frequency | Frequency[], time?: Time): this {
|
|
this.log("triggerRelease", notes, time);
|
|
if (!Array.isArray(notes)) {
|
|
notes = [notes];
|
|
}
|
|
notes.forEach((note) => {
|
|
const midi = new FrequencyClass(this.context, note).toMidi();
|
|
// find the note
|
|
if (
|
|
this._activeSources.has(midi) &&
|
|
(this._activeSources.get(midi) as ToneBufferSource[]).length
|
|
) {
|
|
const sources = this._activeSources.get(
|
|
midi
|
|
) as ToneBufferSource[];
|
|
time = this.toSeconds(time);
|
|
sources.forEach((source) => {
|
|
source.stop(time);
|
|
});
|
|
this._activeSources.set(midi, []);
|
|
}
|
|
});
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Release all currently active notes.
|
|
* @param time When to release the notes.
|
|
*/
|
|
releaseAll(time?: Time): this {
|
|
const computedTime = this.toSeconds(time);
|
|
this._activeSources.forEach((sources) => {
|
|
while (sources.length) {
|
|
const source = sources.shift() as ToneBufferSource;
|
|
source.stop(computedTime);
|
|
}
|
|
});
|
|
return this;
|
|
}
|
|
|
|
sync(): this {
|
|
if (this._syncState()) {
|
|
this._syncMethod("triggerAttack", 1);
|
|
this._syncMethod("triggerRelease", 1);
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Invoke the attack phase, then after the duration, invoke the release.
|
|
* @param notes The note to play and release, or an array of notes.
|
|
* @param duration The time the note should be held
|
|
* @param time When to start the attack
|
|
* @param velocity The velocity of the attack
|
|
*/
|
|
triggerAttackRelease(
|
|
notes: Frequency[] | Frequency,
|
|
duration: Time | Time[],
|
|
time?: Time,
|
|
velocity: NormalRange = 1
|
|
): this {
|
|
const computedTime = this.toSeconds(time);
|
|
this.triggerAttack(notes, computedTime, velocity);
|
|
if (isArray(duration)) {
|
|
assert(
|
|
isArray(notes),
|
|
"notes must be an array when duration is array"
|
|
);
|
|
(notes as Frequency[]).forEach((note, index) => {
|
|
const d = duration[Math.min(index, duration.length - 1)];
|
|
this.triggerRelease(note, computedTime + this.toSeconds(d));
|
|
});
|
|
} else {
|
|
this.triggerRelease(notes, computedTime + this.toSeconds(duration));
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* Add a note to the sampler.
|
|
* @param note The buffer's pitch.
|
|
* @param url Either the url of the buffer, or a buffer which will be added with the given name.
|
|
* @param callback The callback to invoke when the url is loaded.
|
|
*/
|
|
add(
|
|
note: Note | MidiNote,
|
|
url: string | ToneAudioBuffer | AudioBuffer,
|
|
callback?: () => void
|
|
): this {
|
|
assert(
|
|
isNote(note) || isFinite(note),
|
|
`note must be a pitch or midi: ${note}`
|
|
);
|
|
if (isNote(note)) {
|
|
// convert the note name to MIDI
|
|
const mid = new FrequencyClass(this.context, note).toMidi();
|
|
this._buffers.add(mid, url, callback);
|
|
} else {
|
|
// otherwise if it's numbers assume it's midi
|
|
this._buffers.add(note, url, callback);
|
|
}
|
|
return this;
|
|
}
|
|
|
|
/**
|
|
* If the buffers are loaded or not
|
|
*/
|
|
get loaded(): boolean {
|
|
return this._buffers.loaded;
|
|
}
|
|
|
|
/**
|
|
* Clean up
|
|
*/
|
|
dispose(): this {
|
|
super.dispose();
|
|
this._buffers.dispose();
|
|
this._activeSources.forEach((sources) => {
|
|
sources.forEach((source) => source.dispose());
|
|
});
|
|
this._activeSources.clear();
|
|
return this;
|
|
}
|
|
}
|