npm - smplr - Versions diffs - 0.8.1 → 0.10.1 - Mend

smplr 0.8.1 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -44,21 +44,49 @@ Read [CHANGELOG](https://github.com/danigb/smplr/blob/main/CHANGELOG.md) for cha
 - Easy to use: everything should be intuitive for non-experienced developers
 - Decent sounding: uses high quality open source samples. For better or worse, it is sample based 🤷
-## Install
+## Setup
-Install with npm or your favourite package manager:
+You can install the library with a package manager or use it directly by importing from the browser.
+Samples are stored at https://github.com/smpldsnds and there is no need to download them. Kudos to all _samplerist_ 🙌
+#### Using a package manger
+Use npm or your favourite package manager to install the library to use it in your project:
 ```
 npm i smplr
 ```
-Samples are stored at https://github.com/danigb/samples and there is no need to install them. Kudos to all samplers 🙌
+#### Usage from the browser
+You can import directly from the browser. For example:
+```html
+<html>
+  <body>
+    <button id="btn">play</button>
+  </body>
+  <script type="module">
+    import { SplendidGrandPiano } from "https://unpkg.com/smplr@0.10.0/dist/index.mjs"; // needs to be a url
+    const context = new AudioContext(); // create the audio context
+    const marimba = new SplendidGrandPiano(context); // create and load the instrument
+    document.getElementById("btn").onclick = () => {
+      context.resume(); // enable audio context after a user interaction
+      marimba.start({ note: 60, velocity: 80 }); // play the note
+    };
+  </script>
+</html>
+```
+The package needs to be serve as a url from a service like [unpkg](unpkg.com) or similar.
 ## Documentation
 ### Create and load an instrument
-All instruments follows the same pattern: `new Instrument(context, options?)`. For example:
+All instruments follows the same pattern: `new Instrument(context, options)`. For example:
 ```js
 import { SplendidGrandPiano, Soundfont } from "smplr";
@@ -84,6 +112,8 @@ Since the promise returns the instrument instance, you can create and wait in a
 const piano = await new SplendidGrandPiano(context).load;
 ```
+⚠️ In versions lower than 0.8.0 a `loaded()` function was exposed instead.
 ### Play
 #### Start and stop notes
@@ -121,7 +151,7 @@ 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.
+You can schedule notes using `time` and `duration` properties. Both are measured in seconds. Time is the number of seconds since the AudioContext was created, like in `audioContext.currentTime`
 For example, next example plays a C major arpeggio, one note per second:
@@ -137,16 +167,16 @@ const now = context.currentTime;
 You can loop a note by using `loop`, `loopStart` and `loopEnd`:
 ```js
-const sampler = new Sampler(audioContext, { string: "mi-long-sample.mp3" });
+const sampler = new Sampler(audioContext, { duh: "duh-duh-ah.mp3" });
 sampler.start({
-  note: "string",
-  loop: "true",
+  note: "duh"
+  loop: true
   loopStart: 1.0,
   loopEnd: 9.0,
 });
 ```
-If `loopStart` or `loopEnd` is not specified it will be use by default 0 and total duration respectively.
+If `loop` is true but `loopStart` or `loopEnd` are not specified, 0 and total duration will be used by default, respectively.
 #### Change volume
@@ -156,10 +186,28 @@ Instrument `output` attribute represents the main output of the instrument. `out
 piano.output.setVolume(80);
 ```
-Bear in mind that `volume` is global to the instrument, but `velocity` is specific for each note.
+⚠️ `volume` is global to the instrument, but `velocity` is specific for each note.
+#### Events
+You can add a `onEnded` callback that will be invoked when the note ends:
+```js
+piano.start({
+  note: "C4",
+  duration: 1,
+  onEnded: () => {
+    // will be called after 1 second
+  },
+});
+```
+The callback will receive as parameter the same object you pass to the `start` function;
 ### Effects
+#### Reverb
 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:
@@ -177,22 +225,6 @@ To change the mix level, use `output.sendEffect(name, mix)`:
 piano.output.sendEffect("reverb", 0.5);
 ```
-#### Events
-You can add a `onEnded` callback that will be invoked when the note ends:
-```js
-piano.start({
-  note: "C4",
-  duration: 1,
-  onEnded: () => {
-    // will be called after 1 second
-  },
-});
-```
-The callback will receive as parameter the same object you pass to the `start` function;
 ### Experimental features
 #### Cache requests
@@ -265,7 +297,7 @@ const marimba = new Soundfont(context, {
 });
 ```
-#### Looping (experimental)
+#### Soundfont sustained notes
 You can enable note looping to make note names indefinitely long by loading loop data:
@@ -276,11 +308,11 @@ const marimba = new Soundfont(context, {
 });
 ```
-Bear in mind that currently that feature produces click on lot of instruments.
+⚠️ This feature is still experimental and can produces clicks on lot of instruments.
-### Piano
+### SplendidGrandPiano
-A sampled acoustic piano. It uses Steinway samples with 4 velocity layers from
+A sampled acoustic piano. It uses Steinway samples with 4 velocity groups from
 [SplendidGrandPiano](https://github.com/sfzinstruments/SplendidGrandPiano)
 ```js
@@ -364,6 +396,34 @@ drums.getVariations("kick").forEach((variation, index) => {
 });
 ```
+### Smolken double bass
+```js
+import { Smolken, getSmolkenNames } from "smplr";
+const instruments = getSmolkenNames(); // => Arco, Pizzicato & Switched
+// Create an instrument
+const context = new AudioContext();
+const doubleBass = await new Smolken(context, { instrument: "Arco" }).load;
+```
+### Versilian
+Versilian is a sample capable of using the [Versilian Community Sample Library](https://github.com/sgossner/VCSL).
+⚠️ Not all features are implemented. Some instruments may sound incorrect ⚠️
+```js
+import { Versilian, getVersilianInstruments } from "smplr";
+// getVersilianInstruments returns a Promise
+const instrumentNames = await getVersilianInstruments();
+const context = new AudioContext();
+const sampler = new Versilian(context, { instrument: instrumentNAmes[0] });
+```
 ## License
 MIT License

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,492 @@
+type AudioInsert = {
+    input: AudioNode;
+    output: AudioNode;
+};
+type ChannelOptions = {
+    destination: AudioNode;
+    volume: number;
+    volumeToGain: (volume: number) => number;
+};
+type OutputChannel = Omit<Channel, "input">;
+/**
+ * An output channel with audio effects
+ * @private
+ */
+declare class Channel {
+    #private;
+    readonly context: BaseAudioContext;
+    readonly setVolume: (vol: number) => void;
+    readonly input: AudioNode;
+    constructor(context: BaseAudioContext, 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 StorageResponse = {
+    readonly status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    json(): Promise<any>;
+    text(): Promise<string>;
+};
+type Storage = {
+    fetch: (url: string) => Promise<StorageResponse>;
+};
+declare const HttpStorage: Storage;
+declare class CacheStorage implements Storage {
+    #private;
+    constructor(name?: string);
+    fetch(url: string): Promise<StorageResponse>;
+}
+type AudioBuffers = Record<string | number, AudioBuffer | undefined>;
+/**
+ * A function that downloads audio into a AudioBuffers
+ */
+type AudioBuffersLoader = (context: BaseAudioContext, buffers: AudioBuffers) => Promise<void>;
+/**
+ * A function to unsubscribe from an event or control
+ */
+type Unsubscribe = () => void;
+/**
+ * A function that listener to event or control changes
+ */
+type Listener<T> = (value: T) => void;
+/**
+ * A function to subscribe an trigger or control events
+ */
+type Subscribe<T> = (listener: Listener<T>) => Unsubscribe;
+/**
+ * @private
+ */
+type InternalPlayer = {
+    readonly buffers: AudioBuffers;
+    readonly context: BaseAudioContext;
+    start(sample: SampleStart): (time?: number) => void;
+    stop(sample?: SampleStop): void;
+    disconnect(): void;
+};
+type SampleStop = {
+    stopId?: string | number;
+    time?: number;
+};
+type SampleOptions = {
+    decayTime?: number;
+    detune?: number;
+    duration?: number | null;
+    velocity?: number;
+    lpfCutoffHz?: number;
+    loop?: boolean;
+    loopStart?: number;
+    loopEnd?: number;
+    gainOffset?: number;
+};
+type SampleStart = {
+    name?: string;
+    note: string | number;
+    onEnded?: (sample: SampleStart) => void;
+    stop?: Subscribe<number>;
+    stopId?: string | number;
+    time?: number;
+} & SampleOptions;
+/**
+ * Heavily inspired by SFZ format
+ */
+type SampleRegion = {
+    sampleName: string;
+    /**
+     * This specifies the MIDI key number that corresponds to the sample's original pitch
+     */
+    midiPitch: number;
+    /**
+     * This defines the lowest MIDI key number that will trigger this sample.
+     */
+    midiLow?: number;
+    /**
+     * This specifies the highest MIDI key number that will trigger this sample.
+     */
+    midiHigh?: number;
+    velLow?: number;
+    /**
+     * This determines the highest MIDI velocity at which this sample will be triggered.
+     */
+    velHigh?: number;
+    /**
+     * These define the pitch bend range for the samples in this group. The values are given in cents
+     */
+    bendUp?: number;
+    bendDown?: number;
+    /**
+     * Velocity-based amplitude scaling. [Vel, Gain] tells the sampler to play the sample
+     * at volume Gain when the note's velocity is Vel
+     */
+    ampVelCurve?: [number, number];
+    /**
+     * Amplitude envelope release time in seconds.
+     * Stored here for convenience (flatness) but needs to be
+     * copied inside sample options before playback
+     */
+    ampRelease?: number;
+    /**
+     * Attack time in seconds. Currently not implemented
+     *
+     * @see http://sfzformat.com/opcodes/amp_attack.html
+     */
+    ampAttack?: number;
+    /**
+     * seqLength defines how many samples are in the sequence.
+     * When using the seqPosition and seqLength , you can set up round-robin
+     * or sequential sample playback.
+     */
+    seqLength?: number;
+    /**
+     * Determine the position of this particular sample within the sequence
+     * 1 means first element of the sequence (not zero based!)
+     */
+    seqPosition?: number;
+    /**
+     * This assigns the group to a specific number.
+     * Group numbers can be used in combination with groupOffBy to implement
+     * exclusive groups, where playing one sample can stop another sample from playing.
+     */
+    group?: number;
+    /**
+     * Triggering a sample in this region will stop (or "turn off") any samples
+     * currently playing in the specified group number
+     */
+    groupOffBy?: number;
+    /**
+     * Start offset (in samples). Not implemented (yet)
+     */
+    offset?: number;
+    /**
+     * Adjust the playback pitch of a sample (in semitones)
+     */
+    tune?: number;
+    /**
+     * The volume opcode in SFZ defines the default playback volume for a given region.
+     * It specifies an adjustment to the sample's original amplitude.
+     * The unit for the volume opcode is decibels (dB).
+     */
+    volume?: number;
+    /**
+     * sample options for this particular region
+     */
+    sample?: Partial<SampleOptions>;
+};
+type RegionGroup = {
+    regions: SampleRegion[];
+    sample: Partial<SampleOptions>;
+};
+declare function getDrumMachineNames(): string[];
+type DrumMachineConfig = ChannelOptions & SampleOptions & {
+    instrument: string;
+    storage?: Storage;
+};
+declare class DrumMachine {
+    #private;
+    private readonly player;
+    readonly load: Promise<this>;
+    readonly output: OutputChannel;
+    constructor(context: AudioContext, options?: Partial<DrumMachineConfig>);
+    loaded(): Promise<this>;
+    get sampleNames(): string[];
+    getVariations(name: string): string[];
+    start(sample: SampleStart): (time?: number | undefined) => void;
+    stop(sample: SampleStop): void;
+}
+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;
+    storage?: Storage;
+    destination: AudioNode;
+    volume: number;
+    velocity: number;
+    detune: number;
+    decayTime: number;
+    lpfCutoffHz?: number;
+};
+declare class SfzSampler {
+    #private;
+    readonly context: AudioContext;
+    readonly options: Readonly<Partial<SfzSamplerConfig>>;
+    private readonly player;
+    readonly load: Promise<this>;
+    constructor(context: AudioContext, options: Partial<SfzSamplerConfig> & Pick<SfzSamplerConfig, "instrument">);
+    get output(): OutputChannel;
+    loaded(): Promise<this>;
+    start(sample: SampleStart | string | number): void;
+    stop(sample?: SampleStop | 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 getVersilianInstruments(): Promise<string[]>;
+declare function VcslInstrumentLoader(instrument: string, buffers: AudioBuffers, group: RegionGroup): (context: BaseAudioContext, storage: Storage) => Promise<void[]>;
+type VersilianConfig = {
+    instrument: string;
+    storage: Storage;
+};
+type VersilianOptions = Partial<VersilianConfig & SampleOptions & ChannelOptions>;
+/**
+ * Versilian
+ *
+ * The Versilian Community Sample Library is an open CC0 general-purpose sample library created by Versilian Studios LLC
+ * for the purpose of introducing a set of quality, publicly available samples suitable for use in software and media of all kinds.
+ */
+declare class Versilian implements InternalPlayer {
+    private readonly player;
+    readonly load: Promise<this>;
+    private config;
+    constructor(context: BaseAudioContext, options?: VersilianOptions);
+    get output(): OutputChannel;
+    get buffers(): AudioBuffers;
+    get context(): BaseAudioContext;
+    start(sample: SampleStart | string | number): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | string | number): void;
+    disconnect(): void;
+}
+declare function getMalletNames(): string[];
+declare class Mallet extends Versilian {
+    constructor(context: AudioContext, options: VersilianOptions);
+}
+declare const NAME_TO_PATH: Record<string, string | undefined>;
+declare function getMellotronNames(): string[];
+type MellotronConfig = {
+    instrument: string;
+    storage: Storage;
+};
+type MellotronOptions = Partial<SampleOptions & ChannelOptions & MellotronConfig>;
+declare class Mellotron implements InternalPlayer {
+    readonly context: BaseAudioContext;
+    private readonly config;
+    private readonly player;
+    private readonly group;
+    readonly load: Promise<this>;
+    constructor(context: BaseAudioContext, options: MellotronOptions);
+    get buffers(): AudioBuffers;
+    get output(): OutputChannel;
+    start(sample: SampleStart | string | number): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | string | number): void;
+    disconnect(): void;
+}
+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 SamplerConfig = {
+    storage?: Storage;
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+    destination: AudioNode;
+    buffers: Record<string | number, string | AudioBuffers> | AudioBuffersLoader;
+    volumeToGain: (volume: number) => number;
+};
+/**
+ * A Sampler instrument
+ *
+ * @private
+ */
+declare class Sampler {
+    #private;
+    readonly context: AudioContext;
+    private readonly player;
+    readonly load: Promise<this>;
+    constructor(context: AudioContext, options?: Partial<SamplerConfig>);
+    loaded(): Promise<this>;
+    get output(): OutputChannel;
+    start(sample: SampleStart | string | number): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | string | number): void;
+    disconnect(): void;
+}
+declare function getSmolkenNames(): string[];
+type SmolkenConfig = {
+    instrument: string;
+    storage: Storage;
+};
+type SmolkenOptions = Partial<SmolkenConfig & SampleOptions & ChannelOptions>;
+declare class Smolken implements InternalPlayer {
+    private readonly player;
+    private readonly group;
+    readonly load: Promise<this>;
+    private config;
+    private seqNum;
+    constructor(context: BaseAudioContext, options?: SmolkenOptions);
+    get output(): OutputChannel;
+    get buffers(): AudioBuffers;
+    get context(): BaseAudioContext;
+    start(sample: SampleStart | string | number): (time?: number) => void;
+    stop(sample?: SampleStop | string | number): void;
+    disconnect(): void;
+}
+declare function getSoundfontKits(): string[];
+declare function getSoundfontNames(): string[];
+type SoundfontConfig = {
+    kit: "FluidR3_GM" | "MusyngKite" | string;
+    instrument?: string;
+    instrumentUrl: string;
+    storage: Storage;
+    extraGain: number;
+    loadLoopData: boolean;
+    loopDataUrl?: string;
+};
+type SoundfontOptions = Partial<SoundfontConfig & SampleOptions & ChannelOptions>;
+declare class Soundfont {
+    #private;
+    readonly context: AudioContext;
+    readonly config: Readonly<SoundfontConfig>;
+    private readonly player;
+    readonly load: Promise<this>;
+    readonly group: RegionGroup;
+    constructor(context: AudioContext, options: SoundfontOptions);
+    get output(): OutputChannel;
+    get hasLoops(): boolean;
+    loaded(): Promise<this>;
+    disconnect(): void;
+    start(sample: SampleStart | string | number): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | string | number): void;
+}
+/**
+ * Splendid Grand Piano options
+ */
+type SplendidGrandPianoConfig = {
+    baseUrl: string;
+    destination: AudioNode;
+    storage: Storage;
+    detune: number;
+    volume: number;
+    velocity: number;
+    decayTime?: number;
+    lpfCutoffHz?: number;
+};
+declare class SplendidGrandPiano {
+    #private;
+    readonly context: AudioContext;
+    options: Readonly<SplendidGrandPianoConfig>;
+    private readonly player;
+    readonly load: Promise<this>;
+    constructor(context: AudioContext, options?: Partial<SplendidGrandPianoConfig>);
+    get output(): OutputChannel;
+    get buffers(): AudioBuffers;
+    loaded(): Promise<this>;
+    start(sampleOrNote: SampleStart | number | string): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | number | string): void;
+}
+declare const LAYERS: ({
+    name: string;
+    vel_range: number[];
+    cutoff: number;
+    samples: (string | number)[][];
+} | {
+    name: string;
+    vel_range: number[];
+    samples: (string | number)[][];
+    cutoff?: undefined;
+})[];
+export { CacheStorage, DrumMachine, DrumMachineConfig, ElectricPiano, HttpStorage, LAYERS, Mallet, Mellotron, MellotronConfig, MellotronOptions, NAME_TO_PATH, Reverb, Sampler, SamplerConfig, Smolken, SmolkenConfig, SmolkenOptions, Soundfont, SoundfontOptions, SplendidGrandPiano, SplendidGrandPianoConfig, Storage, StorageResponse, VcslInstrumentLoader, Versilian, VersilianConfig, VersilianOptions, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments };