smplr 0.7.0 → 0.8.1

package/README.md

@@ -56,7 +56,7 @@ Samples are stored at https://github.com/danigb/samples and there is no need to
 
 ## Documentation
 
-### Create an instrument
+### Create and load an instrument
 
 All instruments follows the same pattern: `new Instrument(context, options?)`. For example:
 
@@ -70,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
 });
 ```
@@ -81,7 +81,7 @@ 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();
+const piano = await new SplendidGrandPiano(context).load;
 ```
 
 ### Play
@@ -132,7 +132,7 @@ const now = context.currentTime;
 });
 ```
 
-### Looping
+#### Looping
 
 You can loop a note by using `loop`, `loopStart` and `loopEnd`:
 
@@ -148,7 +148,7 @@ sampler.start({
 
 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:
 
@@ -193,9 +193,9 @@ piano.start({
 
 The callback will receive as parameter the same object you pass to the `start` function;
 
-#### Cache requests
+### Experimental features
 
-[Experimental]
+#### 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).
 
@@ -330,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

@@ -27,6 +27,28 @@ 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>;
+
 /**
  * A function to unsubscribe from an event or control
  */
@@ -40,6 +62,16 @@ type Listener<T> = (value: T) => void;
  */
 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;
@@ -55,28 +87,26 @@ type SampleOptions = {
     loopEnd?: number;
 };
 type SampleStart = {
+    name?: string;
     note: string | number;
     onEnded?: (sample: SampleStart) => void;
     stop?: Subscribe<number>;
     stopId?: string | number;
     time?: number;
 } & SampleOptions;
-
-type StorageResponse = {
-    readonly status: number;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    json(): Promise<any>;
-    text(): Promise<string>;
+type SampleRegion = {
+    sampleName: string;
+    sampleCenter: number;
+    rangeMidi?: [number, number];
+    rangeVol?: [number, number];
+    offsetVol?: number;
+    offsetDetune?: number;
+    sample?: Partial<SampleOptions>;
 };
-type Storage = {
-    fetch: (url: string) => Promise<StorageResponse>;
+type SampleLayer = {
+    regions: SampleRegion[];
+    sample: Partial<SampleOptions>;
 };
-declare const HttpStorage: Storage;
-declare class CacheStorage implements Storage {
-    #private;
-    constructor(name?: string);
-    fetch(url: string): Promise<StorageResponse>;
-}
 
 declare function getDrumMachineNames(): string[];
 type DrumMachineConfig = ChannelOptions & SampleOptions & {
@@ -86,6 +116,7 @@ type DrumMachineConfig = ChannelOptions & SampleOptions & {
 declare class DrumMachine {
     #private;
     private readonly player;
+    readonly load: Promise<this>;
     readonly output: OutputChannel;
     constructor(context: AudioContext, options?: Partial<DrumMachineConfig>);
     loaded(): Promise<this>;
@@ -182,6 +213,7 @@ declare class SfzSampler {
     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>;
@@ -208,6 +240,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;
@@ -220,12 +272,6 @@ declare class Reverb {
     connect(output: AudioNode): void;
 }
 
-type AudioBuffers = Record<string | number, AudioBuffer | undefined>;
-/**
- * A function that downloads audio into a AudioBuffers
- */
-type AudioBuffersLoader = (context: BaseAudioContext, buffers: AudioBuffers) => Promise<void>;
-
 type SamplerConfig = {
     storage?: Storage;
     detune: number;
@@ -246,6 +292,7 @@ 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;
@@ -271,12 +318,14 @@ declare class Soundfont {
     readonly context: AudioContext;
     readonly config: Readonly<SoundfontConfig>;
     private readonly player;
+    readonly load: Promise<this>;
+    readonly layer: SampleLayer;
     constructor(context: AudioContext, options: SoundfontOptions);
     get output(): OutputChannel;
-    loaded(): Promise<this>;
     get hasLoops(): boolean;
+    loaded(): Promise<this>;
     disconnect(): void;
-    start(sample: SampleStart): (time?: number | undefined) => void;
+    start(sample: SampleStart | string | number): (time?: number | undefined) => void;
     stop(sample?: SampleStop | string | number): void;
 }
 
@@ -298,6 +347,7 @@ declare class SplendidGrandPiano {
     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;
@@ -317,4 +367,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { CacheStorage, DrumMachine, DrumMachineConfig, ElectricPiano, HttpStorage, LAYERS, Mallet, NAME_TO_PATH, Reverb, Sampler, SamplerConfig, Soundfont, SoundfontOptions, 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 };