smplr 0.1.0 → 0.4.0

package/README.md

@@ -1,25 +1,263 @@
-# smplr [![npm](https://img.shields.io/npm/v/smplr.svg)](https://www.npmjs.com/package/smplr)
+# smplr
 
+[![npm version](https://img.shields.io/npm/v/smplr)](https://www.npmjs.com/package/smplr)
 
-A web audio sampler:
+> `smplr` is a collection of sampled instruments for Web Audio API ready to be used with no setup required.
+
+Examples:
+
+```js
+import { Soundfont } from "smplr";
+
+const context = new AudioContext();
+const marimba = new Soundfont(context, { instrument: "marimba" });
+marimba.start({ note: 60, velocity: 80 });
+```
+
+```js
+import { DrumMachine } from "smplr";
+
+const context = new AudioContext();
+const dm = new DrumMachine(context);
+dm.start({ note: "kick" });
+```
+
+```js
+import { SplendidGrandPiano, Reverb } from "smplr";
+
+const context = new AudioContext();
+const piano = new SplendidGrandPiano(context);
+piano.output.addEffect("reverb", new Reverb(context), 0.2);
+
+piano.start({ note: "C4" });
+```
+
+See demo: https://danigb.github.io/smplr/
+
+#### Library goals
+
+- No setup: specifically, all samples are online, so no need for a server.
+- Easy to use: everything should be intuitive for non-experienced developers
+- Decent sounding: use high quality open source samples. For good or worst, is sample based 🤷
+
+#### Installation
+
+Install with npm or your favourite package manager:
+
+```
+npm i smplr
+```
+
+Samples are published at: https://github.com/danigb/samples
+
+## Documentation
+
+### Create an instrument
+
+All instruments follows the same pattern: `new Instrument(context, options)`. For example:
+
+```js
+import { SplendidGrandPiano, Soundfont } from "smplr";
+
+const context = new AudioContext();
+const piano = new SplendidGrandPiano(context, { decayTime: 0.5 });
+const marimba = new Soundfont(context, { instrument: "marimba" });
+```
+
+### Wait for audio loading
+
+You can start playing notes as soon as one audio is loaded. But if you want to wait for all of them, you can use `loaded()` function that returns a promise:
+
+```js
+piano.loaded().then(() => {
+  // now the piano is fully loaded
+});
+```
+
+Since the promise returns the instrument instance, you can create and wait in a single line:
+
+```js
+const piano = await new SplendidGrandPiano(context).loaded();
+```
+
+### Start and stop notes
+
+The `start` function accepts a bunch of options:
+
+```js
+piano.start({ note: "C4", velocity: 80, time: 5, duration: 1 });
+```
+
+The `velocity` is a number between 0 and 127 the represents at which velocity the key is pressed. The bigger the number, louder the sound. But `velocity` not only controls the loudness. In some instruments, it also affects the timbre.
+
+The `start` function returns a `stop` function for the given note:
+
+```js
+const stopNote = piano.start({ note: 60 });
+stopNote({ time: 10 });
+```
+
+Bear in mind that you may need to call [`context.resume()` before playing a note](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy)
+
+Instruments have a global `stop` function that can be used to stop all notes:
+
+```js
+// This will stop all notes
+piano.stop();
+```
+
+Or stop the specified one:
+
+```js
+// This will stop C4 note
+piano.stop(60);
+```
+
+### Schedule notes
+
+You can schedule notes using `time` and `duration` properties. Both are measured in seconds, and time is the number of seconds since the AudioContext was created.
+
+For example, next example plays a C major arpeggio, one note per second:
+
+```js
+const now = context.currentTime;
+["C4", "E4", "G4", "C5"].forEach((note, i) => {
+  piano.start({ note, time: now + i, duration: 0.5 });
+});
+```
+
+### Change volume
+
+`setVolume` uses a scale where 0 means no volume, and 127 is max volume without amplification:
+
+```js
+piano.setVolume(80);
+```
+
+Bear in mind that `volume` is global to the instrument, but `velocity` is specific for each note.
+
+### Effects
+
+An packed version of [DattorroReverbNode](https://github.com/khoin/DattorroReverbNode) algorithmic reverb is included.
+
+Use `output.addEffect(name, effect, mix)` to connect an effect using a send bus:
+
+```js
+import { Reverb, SplendidGrandPiano } from "smplr";
+const reverb = new Reverb(context);
+const piano = new SplendidGrandPiano(context, { volume });
+piano.output.addEffect("reverb", reverb, 0.2);
+```
+
+To change the mix level, use `output.sendEffect(name, mix)`:
+
+```js
+piano.output.sendEffect("reverb", 0.5);
+```
+
+## Instruments
+
+### Sampler
+
+An audio buffer sampler.
+
+```js
+import { Sampler } from "smplr";
+
+const samples = {
+  kick: "https://danigb.github.io/samples/drum-machines/808-mini/kick.m4a",
+  snare: "https://danigb.github.io/samples/drum-machines/808-mini/snare-1.m4a",
+};
+const sampler = new Sampler(new AudioContext(), { samples });
+sampler.start({ note: "kick" });
+```
+
+### Soundfont
+
+A Soundfont player. By default it loads audio from Benjamin Gleitzman's package of
+[pre-rendered sound fonts](https://github.com/gleitz/midi-js-soundfonts).
+
+```js
+import { Soundfont } from "smplr";
+
+const marimba = new Soundfont(new AudioContext(), { instrument: "marimba" });
+marimba.start({ note: "C4" });
+```
+
+It's intended to be a modern replacement of [soundfont-player](https://github.com/danigb/soundfont-player)
+
+### Piano
+
+A sampled acoustic piano. It uses Steinway samples with 4 velocity layers from
+[SplendidGrandPiano](https://github.com/sfzinstruments/SplendidGrandPiano)
+
+```js
+import { SplendidGrandPiano } from "smplr";
+
+const piano = new SplendidGrandPiano(new AudioContext());
+
+piano.start({ note: "C4" });
+```
+
+### Electric Piano
+
+A sampled electric pianos. Samples from https://github.com/sfzinstruments/GregSullivan.E-Pianos
+
+```js
+import { ElectricPiano, getElectricPianoNames } from "smplr";
+
+const instruments = getElectricPianoNames(); // => ["CP80", "PianetT", "WurlitzerEP200"]
+
+const epiano = new ElectricPiano(new AudioContext(), {
+  instrument: "PianetT",
+});
+
+epiano.start({ note: "C4" });
+
+// Includes a (basic) tremolo effect:
+epiano.tremolo.level(30);
+```
+
+Available instruments:
+
+- `CP80`: Yamaha CP80 Electric Grand Piano v1.3 (29-Sep-2004)
+- `PianetT`: Hohner Pianet T (type 2) v1.3 (24-Sep-2004)
+- `WurlitzerEP200`: Wurlitzer EP200 Electric Piano v1.1 (16-May-1999)
+
+### Mallets
+
+Samples from [The Versilian Community Sample Library](https://github.com/sgossner/VCSL)
 
 ```js
-var ac = new AudioContext()
-var sampler = require('smplr')(ac)
-sampler.load('@drum-machines/maestro').then(function (maestro) {
-  var now = ac.currentTime
-  maestro('kick').start(now)
-  maestro('snare').start(now + 0.2)
-})
+import { Mallet, getMalletNames } from "smplr";
+
+const instruments = getMalletNames();
+
+const mallet = new Mallet(new AudioContext(), {
+  instrument: instruments[0],
+});
 ```
 
-## Install
+### Drum Machines
 
-Via npm: `npm i --save smplr` or grab the [browser ready file](https://raw.githubusercontent.com/danigb/smplr/master/packages/smplr/dist/smplr.min.js) (4kb) which exports `loader` as window globals.
+Sampled drum machines. Samples from different sources:
 
-## User guide
+```js
+import { DrumMachine, getDrumMachineNames } from "smplr";
 
+const instruments = getDrumMachineNames();
+
+const context = new AudioContext();
+const drums = new DrumMachine(context, { instrument: "TR-808" });
+drums.start({ note: "kick" });
+
+// Drum samples could have variations:
+const now = context.currentTime;
+drums.getVariations("kick").forEach((variation, index) => {
+  drums.start({ note: variation, time: now + index });
+});
+```
 
-# License
+## License
 
 MIT License

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+type AudioInsert = {
+    input: AudioNode;
+    output: AudioNode;
+};
+
+type ChannelOptions = {
+    destination: AudioNode;
+    volume: number;
+    volumeToGain: (volume: number) => number;
+};
+/**
+ * @private
+ */
+declare class Channel {
+    #private;
+    readonly context: AudioContext;
+    readonly setVolume: (vol: number) => void;
+    readonly input: AudioNode;
+    constructor(context: AudioContext, options: Partial<ChannelOptions>);
+    addInsert(effect: AudioNode | AudioInsert): void;
+    addEffect(name: string, effect: AudioNode | {
+        input: AudioNode;
+    }, mixValue: number): void;
+    sendEffect(name: string, mix: number): void;
+    disconnect(): void;
+}
+
+type AudioBuffers = Record<string | number, AudioBuffer>;
+
+type StopSample = {
+    stopId?: string | number;
+    time?: number;
+};
+
+/**
+ * A function that downloads audio
+ */
+type SamplerAudioLoader = (context: AudioContext, buffers: AudioBuffers) => Promise<void>;
+type SamplerConfig = {
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+    destination: AudioNode;
+    buffers: Record<string | number, string | AudioBuffers> | SamplerAudioLoader;
+    volumeToGain: (volume: number) => number;
+    noteToSample: (note: SamplerNote, buffers: AudioBuffers, config: SamplerConfig) => [string | number, number];
+};
+type SamplerNote = {
+    note: string | number;
+    stopId?: string | number;
+    time?: number;
+    duration?: number;
+    decayTime?: number;
+    detune?: number;
+    velocity?: number;
+    lpfCutoffHz?: number;
+};
+/**
+ * A Sampler instrument
+ *
+ * @private
+ */
+declare class Sampler {
+    #private;
+    readonly context: AudioContext;
+    readonly output: Omit<Channel, "input">;
+    readonly buffers: AudioBuffers;
+    constructor(context: AudioContext, options: Partial<SamplerConfig>);
+    loaded(): Promise<this>;
+    start(note: SamplerNote | string | number): (time?: number) => void;
+    stop(note?: StopSample | string | number): void;
+}
+
+declare function getDrumMachineNames(): string[];
+type DrumMachineConfig = {
+    instrument: string;
+    destination: AudioNode;
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+};
+declare class DrumMachine extends Sampler {
+    #private;
+    constructor(context: AudioContext, options: Partial<DrumMachineConfig>);
+    get sampleNames(): string[];
+    getVariations(name: string): string[];
+}
+
+type SfzInstrument = {
+    name: string;
+    formats?: string[];
+    baseUrl?: string;
+    websfzUrl: string;
+    tags?: string[];
+};
+
+type Websfz = {
+    global: Record<string, string | number>;
+    groups: WebsfzGroup[];
+    meta: {
+        name?: string;
+        description?: string;
+        license?: string;
+        source?: string;
+        baseUrl?: string;
+        websfzUrl?: string;
+        formats?: string[];
+        tags?: string[];
+    };
+};
+type WebsfzGroup = {
+    group_label?: string;
+    group?: number;
+    hikey?: number;
+    hivel?: number;
+    lokey?: number;
+    lovel?: number;
+    off_by?: number;
+    off_mode?: "normal";
+    pitch_keycenter?: number;
+    regions: WebsfzRegion[];
+    seq_length?: number;
+    trigger?: "first" | "legato";
+    volume?: number;
+    amp_velcurve_83?: number;
+    locc64?: number;
+    hicc64?: number;
+    hicc107?: number;
+    locc107?: number;
+    pan_oncc122?: number;
+    tune_oncc123?: number;
+    eg06_time1_oncc109?: number;
+    ampeg_attack_oncc100?: number;
+};
+type WebsfzRegion = {
+    end?: number;
+    group?: number;
+    hivel?: number;
+    lovel?: number;
+    hikey?: number;
+    key?: number;
+    lokey?: number;
+    off_by?: number;
+    pitch_keycenter?: number;
+    region_label?: number;
+    sample: string;
+    seq_position?: number;
+    trigger?: "first" | "legato";
+    volume?: number;
+    locc64?: number;
+    hicc64?: number;
+    ampeg_attack_oncc100?: number;
+    eg06_time1_oncc109?: number;
+    pan_oncc122?: number;
+    tune_oncc123?: number;
+};
+
+/**
+ * Splendid Grand Piano options
+ */
+type SfzSamplerConfig = {
+    instrument: SfzInstrument | Websfz | string;
+    destination: AudioNode;
+    volume: number;
+    velocity: number;
+    detune: number;
+    decayTime: number;
+    lpfCutoffHz?: number;
+};
+declare class SfzSampler {
+    #private;
+    readonly context: AudioContext;
+    readonly output: Omit<Channel, "input">;
+    readonly buffers: AudioBuffers;
+    constructor(context: AudioContext, options: Partial<SfzSamplerConfig> & Pick<SfzSamplerConfig, "instrument">);
+    loaded(): Promise<this>;
+    start(note: SamplerNote | string | number): (time?: number) => void;
+    stop(note?: StopSample | string | number): void;
+    disconnect(): void;
+}
+
+declare function getElectricPianoNames(): string[];
+declare class ElectricPiano extends SfzSampler {
+    readonly tremolo: Readonly<{
+        level: (value: number) => void;
+    }>;
+    constructor(context: AudioContext, options: Partial<SfzSamplerConfig> & {
+        instrument: string;
+    });
+}
+
+declare function getMalletNames(): ("Balafon - Hard Mallet" | "Balafon - Keyswitch" | "Balafon - Soft Mallet" | "Balafon - Traditional Mallet" | "Tubular Bells 1" | "Tubular Bells 2" | "Vibraphone - Hard Mallets" | "Vibraphone - Keyswitch" | "Vibraphone - Soft Mallets" | "Xylophone - Hard Mallets" | "Xylophone - Keyswitch" | "Xylophone - Medium Mallets" | "Xylophone - Soft Mallets")[];
+declare class Mallet extends SfzSampler {
+    constructor(context: AudioContext, options: Partial<SfzSamplerConfig> & {
+        instrument: string;
+    });
+}
+declare const DATA: {
+    readonly "Balafon - Hard Mallet": "Struck Idiophones/balafon-hard-mallet";
+    readonly "Balafon - Keyswitch": "Struck Idiophones/balafon-keyswitch";
+    readonly "Balafon - Soft Mallet": "Struck Idiophones/balafon-soft-mallet";
+    readonly "Balafon - Traditional Mallet": "Struck Idiophones/balafon-traditional-mallet";
+    readonly "Tubular Bells 1": "Struck Idiophones/tubular-bells-1";
+    readonly "Tubular Bells 2": "Struck Idiophones/tubular-bells-2";
+    readonly "Vibraphone - Hard Mallets": "Struck Idiophones/vibraphone-hard-mallets";
+    readonly "Vibraphone - Keyswitch": "Struck Idiophones/vibraphone-keyswitch";
+    readonly "Vibraphone - Soft Mallets": "Struck Idiophones/vibraphone-soft-mallets";
+    readonly "Xylophone - Hard Mallets": "Struck Idiophones/xylophone-hard-mallets";
+    readonly "Xylophone - Keyswitch": "Struck Idiophones/xylophone-keyswitch";
+    readonly "Xylophone - Medium Mallets": "Struck Idiophones/xylophone-medium-mallets";
+    readonly "Xylophone - Soft Mallets": "Struck Idiophones/xylophone-soft-mallets";
+};
+
+declare const PARAMS: readonly ["preDelay", "bandwidth", "inputDiffusion1", "inputDiffusion2", "decay", "decayDiffusion1", "decayDiffusion2", "damping", "excursionRate", "excursionDepth", "wet", "dry"];
+declare class Reverb {
+    #private;
+    readonly input: AudioNode;
+    constructor(context: AudioContext);
+    get paramNames(): readonly ["preDelay", "bandwidth", "inputDiffusion1", "inputDiffusion2", "decay", "decayDiffusion1", "decayDiffusion2", "damping", "excursionRate", "excursionDepth", "wet", "dry"];
+    getParam(name: (typeof PARAMS)[number]): AudioParam | undefined;
+    get isReady(): boolean;
+    ready(): Promise<this>;
+    connect(output: AudioNode): void;
+}
+
+type SoundfontConfig = {
+    library: SoundfontLibrary | LibraryUrlBuilder;
+    instrument: string;
+    destination: AudioNode;
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+    extraGain?: number;
+};
+declare class Soundfont extends Sampler {
+    constructor(context: AudioContext, options: Partial<SoundfontConfig> & {
+        instrument: string;
+    });
+}
+declare function gleitzKitUrl(kit: "FluidR3_GM" | "MusyngKite", name: string, format: string): string;
+type LibraryUrlBuilder = (instrument: string, format?: string) => string;
+type SoundfontLibrary = {
+    name: string;
+    url: (name: string, format?: "ogg" | "mp3") => string;
+    instruments: string[];
+};
+declare const FluidR3: SoundfontLibrary;
+declare const MusyngKite: SoundfontLibrary;
+declare const SoundfontLibraries: Record<string, SoundfontLibrary>;
+
+/**
+ * Splendid Grand Piano options
+ */
+type SplendidGrandPianoConfig = {
+    baseUrl: string;
+    destination: AudioNode;
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+};
+declare class SplendidGrandPiano extends Sampler {
+    constructor(context: AudioContext, options: Partial<SplendidGrandPianoConfig>);
+}
+declare const LAYERS: ({
+    name: string;
+    vel_range: number[];
+    cutoff: number;
+    samples: (string | number)[][];
+} | {
+    name: string;
+    vel_range: number[];
+    samples: (string | number)[][];
+    cutoff?: undefined;
+})[];
+
+export { DATA, DrumMachine, DrumMachineConfig, ElectricPiano, FluidR3, LAYERS, LibraryUrlBuilder, Mallet, MusyngKite, Reverb, Sampler, SamplerAudioLoader, SamplerConfig, SamplerNote, Soundfont, SoundfontConfig, SoundfontLibraries, SoundfontLibrary, SplendidGrandPiano, SplendidGrandPianoConfig, getDrumMachineNames, getElectricPianoNames, getMalletNames, gleitzKitUrl };