smplr 0.6.1 → 0.8.0

package/README.md

@@ -34,6 +34,10 @@ piano.start({ note: "C4" });
 
 See demo: https://danigb.github.io/smplr/
 
+`smplr` is still under development and features are considered unstable until v 1.0
+
+Read [CHANGELOG](https://github.com/danigb/smplr/blob/main/CHANGELOG.md) for changes.
+
 #### Library goals
 
 - No setup: specifically, all samples are online, so no need for a server.
@@ -48,13 +52,11 @@ Install with npm or your favourite package manager:
 npm i smplr
 ```
 
-Samples are published at: https://github.com/danigb/samples
-
-`smplr` is still under development and features are considered unstable. See [CHANGELOG](https://github.com/danigb/smplr/blob/main/CHANGELOG.md) for changes.
+Samples are stored at https://github.com/danigb/samples and there is no need to install them. Kudos to all samplers 🙌
 
 ## Documentation
 
-### Create an instrument
+### Create and load an instrument
 
 All instruments follows the same pattern: `new Instrument(context, options?)`. For example:
 
@@ -68,10 +70,10 @@ 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 the `loaded()` function that returns a promise:
+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 the `load` property that returns a promise:
 
 ```js
-piano.loaded().then(() => {
+piano.load.then(() => {
   // now the piano is fully loaded
 });
 ```
@@ -79,28 +81,9 @@ piano.loaded().then(() => {
 Since the promise returns the instrument instance, you can create and wait in a single line:
 
 ```js
-const piano = await new SplendidGrandPiano(context).loaded();
-```
-
-#### Cache requests
-
-[Experimental]
-
-If you use default samples, they are stored at github pages. Github rate limits the number of requests per second. That could be a problem, specially if you're using a development environment with hot reload (like most React frameworks).
-
-If you want to cache samples on the browser you can use a `CacheStorage` object:
-
-```ts
-import { SplendidGrandPiano, CacheStorage } from "smplr";
-
-const context = new AudioContext();
-const storage = new CacheStorage();
-// First time the instrument loads, will fetch the samples from http. Subsequent times from cache.
-const piano = new SplendidGrandPiano(context, { storage });
+const piano = await new SplendidGrandPiano(context).load;
 ```
 
-⚠️ `CacheStorage` is based on [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) and only works in secure environments that runs with `https`. Read your framework documentation for setup instructions. For example, in nextjs you can use https://www.npmjs.com/package/next-dev-https. For vite there's https://github.com/liuweiGL/vite-plugin-mkcert. Find the appropriate solution for your environment.
-
 ### Play
 
 #### Start and stop notes
@@ -149,23 +132,23 @@ const now = context.currentTime;
 });
 ```
 
-#### onEnded event
+#### Looping
 
-You can add a `onEnded` callback that will be invoked when the note ends:
+You can loop a note by using `loop`, `loopStart` and `loopEnd`:
 
 ```js
-piano.start({
-  note: "C4",
-  duration: 1,
-  onEnded: () => {
-    // will be called after 1 second
-  },
+const sampler = new Sampler(audioContext, { string: "mi-long-sample.mp3" });
+sampler.start({
+  note: "string",
+  loop: "true",
+  loopStart: 1.0,
+  loopEnd: 9.0,
 });
 ```
 
-The callback will receive as parameter the same object you pass to the `start` function;
+If `loopStart` or `loopEnd` is not specified it will be use by default 0 and total duration respectively.
 
-### Change volume
+#### Change volume
 
 Instrument `output` attribute represents the main output of the instrument. `output.setVolume` method accepts a number where 0 means no volume, and 127 is max volume without amplification:
 
@@ -194,6 +177,41 @@ 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
+
+If you use default samples, they are stored at github pages. Github rate limits the number of requests per second. That could be a problem, specially if you're using a development environment with hot reload (like most React frameworks).
+
+If you want to cache samples on the browser you can use a `CacheStorage` object:
+
+```ts
+import { SplendidGrandPiano, CacheStorage } from "smplr";
+
+const context = new AudioContext();
+const storage = new CacheStorage();
+// First time the instrument loads, will fetch the samples from http. Subsequent times from cache.
+const piano = new SplendidGrandPiano(context, { storage });
+```
+
+⚠️ `CacheStorage` is based on [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) and only works in secure environments that runs with `https`. Read your framework documentation for setup instructions. For example, in nextjs you can use https://www.npmjs.com/package/next-dev-https. For vite there's https://github.com/liuweiGL/vite-plugin-mkcert. Find the appropriate solution for your environment.
+
 ## Instruments
 
 ### Sampler
@@ -242,11 +260,24 @@ Alternatively, you can pass your custom url as the instrument. In that case, the
 
 ```js
 const marimba = new Soundfont(context, {
-  instrument:
+  instrumentUrl:
     "https://gleitz.github.io/midi-js-soundfonts/MusyngKite/marimba-mp3.js",
 });
 ```
 
+#### Looping (experimental)
+
+You can enable note looping to make note names indefinitely long by loading loop data:
+
+```js
+const marimba = new Soundfont(context, {
+  instrument: "cello",
+  loadLoopData: true,
+});
+```
+
+Bear in mind that currently that feature produces click on lot of instruments.
+
 ### Piano
 
 A sampled acoustic piano. It uses Steinway samples with 4 velocity layers from
@@ -299,6 +330,20 @@ const mallet = new Mallet(new AudioContext(), {
 });
 ```
 
+### Mellotron
+
+Samples from [archive.org](https://archive.org/details/mellotron-archive-cd-rom-nki-wav.-7z)
+
+```js
+import { Mellotron, getMellotronNames } from "smplr";
+
+const instruments = getMellotronNames();
+
+const mallet = new Mellotron(new AudioContext(), {
+  instrument: instruments[0],
+});
+```
+
 ### Drum Machines
 
 Sampled drum machines. Samples from different sources:

package/dist/index.d.ts

@@ -1,19 +1,3 @@
-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 AudioInsert = {
     input: AudioNode;
     output: AudioNode;
@@ -24,15 +8,17 @@ type ChannelOptions = {
     volume: number;
     volumeToGain: (volume: number) => number;
 };
+type OutputChannel = Omit<Channel, "input">;
 /**
+ * An output channel with audio effects
  * @private
  */
 declare class Channel {
     #private;
-    readonly context: AudioContext;
+    readonly context: BaseAudioContext;
     readonly setVolume: (vol: number) => void;
     readonly input: AudioNode;
-    constructor(context: AudioContext, options: Partial<ChannelOptions>);
+    constructor(context: BaseAudioContext, options: Partial<ChannelOptions>);
     addInsert(effect: AudioNode | AudioInsert): void;
     addEffect(name: string, effect: AudioNode | {
         input: AudioNode;
@@ -41,72 +27,90 @@ declare class Channel {
     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>;
 
-type StopSample = {
-    stopId?: string | number;
-    time?: number;
-};
+/**
+ * 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;
 
 /**
- * A function that downloads audio
+ * @private
  */
-type SamplerAudioLoader = (context: AudioContext, buffers: AudioBuffers) => Promise<void>;
-type SamplerConfig = {
-    storage?: Storage;
-    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 InternalPlayer = {
+    readonly buffers: AudioBuffers;
+    readonly context: BaseAudioContext;
+    start(sample: SampleStart): (time?: number) => void;
+    stop(sample?: SampleStop): void;
+    disconnect(): void;
 };
-type SamplerNote = {
+type SampleStop = {
+    stopId?: string | number;
+    time?: number;
+};
+type SampleOptions = {
     decayTime?: number;
     detune?: number;
-    duration?: number;
+    duration?: number | null;
+    velocity?: number;
     lpfCutoffHz?: number;
+    loop?: boolean;
+    loopStart?: number;
+    loopEnd?: number;
+};
+type SampleStart = {
+    name?: string;
     note: string | number;
-    onEnded?: (note: SamplerNote | string | number) => void;
+    onEnded?: (sample: SampleStart) => void;
+    stop?: Subscribe<number>;
     stopId?: string | number;
     time?: number;
-    velocity?: 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 | undefined) => void;
-    stop(note?: StopSample | string | number): void;
-}
+} & SampleOptions;
 
 declare function getDrumMachineNames(): string[];
-type DrumMachineConfig = {
+type DrumMachineConfig = ChannelOptions & SampleOptions & {
     instrument: string;
-    destination: AudioNode;
     storage?: Storage;
-    detune: number;
-    volume: number;
-    velocity: number;
-    decayTime?: number;
-    lpfCutoffHz?: number;
 };
-declare class DrumMachine extends Sampler {
+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 = {
@@ -194,12 +198,14 @@ type SfzSamplerConfig = {
 declare class SfzSampler {
     #private;
     readonly context: AudioContext;
-    readonly output: Omit<Channel, "input">;
-    readonly buffers: AudioBuffers;
+    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(note: SamplerNote | string | number): (time?: number) => void;
-    stop(note?: StopSample | string | number): void;
+    start(sample: SampleStart | string | number): void;
+    stop(sample?: SampleStop | string | number): void;
     disconnect(): void;
 }
 
@@ -221,6 +227,26 @@ declare class Mallet extends SfzSampler {
 }
 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 layer;
+    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;
@@ -233,25 +259,61 @@ declare class Reverb {
     connect(output: AudioNode): void;
 }
 
-type SoundfontConfig = {
-    kit: "FluidR3_GM" | "MusyngKite" | string;
-    instrument: string;
+type SamplerConfig = {
     storage?: Storage;
-    destination: AudioNode;
     detune: number;
     volume: number;
     velocity: number;
     decayTime?: number;
     lpfCutoffHz?: number;
-    extraGain?: number;
+    destination: AudioNode;
+    buffers: Record<string | number, string | AudioBuffers> | AudioBuffersLoader;
+    volumeToGain: (volume: number) => number;
 };
-declare class Soundfont extends Sampler {
-    constructor(context: AudioContext, options: Partial<SoundfontConfig> & {
-        instrument: string;
-    });
+/**
+ * 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 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<unknown>;
+    constructor(context: AudioContext, options: SoundfontOptions);
+    get output(): OutputChannel;
+    loaded(): Promise<unknown>;
+    get hasLoops(): boolean;
+    disconnect(): void;
+    start(sample: SampleStart): (time?: number | undefined) => void;
+    stop(sample?: SampleStop | string | number): void;
+}
 
 /**
  * Splendid Grand Piano options
@@ -259,15 +321,25 @@ declare function getSoundfontNames(): string[];
 type SplendidGrandPianoConfig = {
     baseUrl: string;
     destination: AudioNode;
-    storage?: Storage;
+    storage: Storage;
     detune: number;
     volume: number;
     velocity: number;
     decayTime?: number;
     lpfCutoffHz?: number;
 };
-declare class SplendidGrandPiano extends Sampler {
+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;
@@ -281,4 +353,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { CacheStorage, DrumMachine, DrumMachineConfig, ElectricPiano, HttpStorage, LAYERS, Mallet, NAME_TO_PATH, Reverb, Sampler, SamplerAudioLoader, SamplerConfig, SamplerNote, Soundfont, SoundfontConfig, SplendidGrandPiano, SplendidGrandPianoConfig, Storage, StorageResponse, getDrumMachineNames, getElectricPianoNames, getMalletNames, getSoundfontKits, getSoundfontNames };
+export { CacheStorage, DrumMachine, DrumMachineConfig, ElectricPiano, HttpStorage, LAYERS, Mallet, Mellotron, MellotronConfig, MellotronOptions, NAME_TO_PATH, Reverb, Sampler, SamplerConfig, Soundfont, SoundfontOptions, SplendidGrandPiano, SplendidGrandPianoConfig, Storage, StorageResponse, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSoundfontKits, getSoundfontNames };