scribbletune 5.2.0 → 5.5.0

package/dist/index.d.cts

@@ -0,0 +1,323 @@
+export { chord, chords, scale as mode, scales as modes, scale, scales } from 'harmonics';
+
+type SizzleStyle = 'sin' | 'cos' | 'rampUp' | 'rampDown';
+type ProgressionScale = 'major' | 'minor' | 'M' | 'm';
+type SeqFn = (time: string, el: string) => void;
+/**
+ * Callback function triggered when channel has a new event.
+ * @param event - one of ['loaded', 'error']
+ * @param params - object with event data
+ */
+type EventFn = (event: string, params: Record<string, unknown>) => void;
+/**
+ * Callback function triggered when a note is played.
+ * @param params - object with player data
+ */
+type PlayerObserverFn = (params: Record<string, unknown>) => void;
+/** Recursive pattern element produced by expandStr */
+type PatternElement = string | PatternElement[];
+interface NVP<T> {
+    [key: string]: T;
+}
+interface NoteObject {
+    note: string[] | null;
+    length: number;
+    level: number;
+}
+interface ArpParams {
+    count: number;
+    order?: string;
+    chords: string | string[][];
+}
+/**
+ * Definition of a synthesizer from `Tone.js`.
+ */
+interface SynthParams {
+    /**
+     *  The name of the synthesizer, listed in `Tone.js`.
+     *  - Example: `'PolySynth'`.
+     *  - See:  [GitHub ~ Tone.js/Tone/instrument](https://github.com/Tonejs/Tone.js/tree/dev/Tone/instrument)
+     */
+    synth: string;
+    /**
+     *  Descriptive name of the preset.
+     */
+    presetName?: string;
+    /**
+     *  Object with parameters for passing to `new Tone[synth](preset)`.
+     */
+    preset: Record<string, unknown>;
+}
+interface ClipParams {
+    /**
+     * A string or array of notes or chords names.
+     *  - Default:  `[ 'C4' ]`
+     *  - Example:  `'C4 D4 C4 D#4 C4 D4 C4 Bb3'`
+     */
+    notes?: string | (string | string[])[];
+    /**
+     * A musical rhythm, expressed using Scribbletune's pattern language,
+     * which can be adapted to output MIDI files or `Tone.js` sequences.
+     *  - Default:  `'x'`
+     *  - Contains: `x_-R[]`
+     *  - Example:  `'x_x_'`
+     */
+    pattern: string;
+    /**
+     * Randomize the order of the `notes` set in the clip.
+     *  - Default:  `false`
+     */
+    shuffle?: boolean;
+    /**
+     * Whether to apply arpeggiation.
+     *  - Default:  `false`
+     */
+    arpegiate?: boolean;
+    /**
+     * Sub-division — each `x` is a quarter note by default.
+     *  - Default: `'4n'`
+     *  - Example: `'1m'`
+     *  - See:  [Tone.js wiki ~ Time](https://github.com/Tonejs/Tone.js/wiki/Time#notation)
+     */
+    subdiv?: string;
+    /**
+     * Align start of clip playing to specific time grid.
+     *  - Default: `'1m'`
+     *  - Example: `'4m'` will align the clip to every 4 measures
+     */
+    align?: string;
+    /**
+     * Offset start of clip playing from the time grid defined by `align` parameter.
+     *  - Default: `'0'`
+     *  - Example: `'0.75m'` will offset the clip to start at 3rd beat of 4:4 measure
+     */
+    alignOffset?: string;
+    /**
+     * The default MIDI amplitube/ level/ volume of a note.
+     * Used as the upper bound for accents and sizzles (where the lower bound is `accentLow`).
+     *  - Default:  `100`
+     *  - Example:  `127`
+     */
+    amp?: number;
+    /**
+     * Add a "sizzle" (in a manner of speaking) applied to the levels/ volumes.
+     *  - Default: `false`
+     */
+    sizzle?: boolean | SizzleStyle;
+    /**
+     * Accentuate the specified notes in the clip, expressed using `x-` (on/off).
+     *  - Example:  `'x--x'`
+     */
+    accent?: string;
+    /**
+     * The minimum level used for accents.
+     *  - Default:  `70`
+     */
+    accentLow?: number;
+    /**
+     * The number of sizzle repetitions.
+     *  - Default:  `1`
+     */
+    sizzleReps?: number;
+    /**
+     * A string or array of random notes or chords.
+     *  - Default:  `null`
+     *  - Example:  `'C4 D4 C4 D#4 C4 D4 C4 Bb3'`
+     */
+    randomNotes?: null | string | (string | string[])[];
+    /**
+     * The duration of an individual sample that is used in a browser `clip`.
+     *  - Example: `'32n'`, `'1m'`, `2.3`
+     *  - See:  [Tone.js wiki ~ Time](https://github.com/Tonejs/Tone.js/wiki/Time#notation)
+     */
+    dur?: string;
+    /**
+     * Durations of notes in a browser `clip` as a number of quarter notes.
+     * Internal usage only, please use the pattern notation (`x`,`-`,`_`) instead.
+     *  - Example: `[1, 1, 0.5, 0.25]`
+     */
+    durations?: number[];
+    /**
+     * Boolean parameter to trigger offline rendering.
+     * If true, `scribbletune.clip` returns a `Tone.Player` with a buffer containing a pre-rendered sound of the sequence
+     * If false, it returns a `Tone.Sequence` which does live rendering.
+     */
+    offlineRendering?: boolean;
+    /**
+     * Callback function triggered when offline rendering is finished. Ignored when `offlineRendering: false`.
+     */
+    offlineRenderingCallback?: () => void;
+    /**
+     * URL of an audio sample for standalone clip usage (without Channel).
+     *  - Example: `'https://scribbletune.com/sounds/kick.wav'`
+     */
+    sample?: string;
+}
+interface ChannelParams {
+    idx?: number | string;
+    name?: string;
+    clips?: ClipParams[];
+    /**
+     * Audio context (e.g. Tone.getContext())
+     */
+    context?: ToneAudioContext;
+    /**
+     * The default MIDI amplitube/ level/ volume of a note.
+     * Used as the upper bound for accents and sizzles (where the lower bound is `accentLow`).
+     *  - Default:  `100`
+     *  - Example:  `127`
+     */
+    amp?: number;
+    /**
+     * This use is depreceated: The name of a synthesizer, listed in `Tone.js`.
+     *  - Example: `'PolySynth'`.
+     *
+     * New use going forward: SynthParams
+     */
+    synth?: string | SynthParams;
+    /**
+     * A `Tone.Instrument` instance or the name of a synthesizer, listed in `Tone.js`. Only in the browser.
+     *  - Example: `'Synth'`
+     *  - Example: `new Tone.Synth()`
+     */
+    instrument?: string | ToneInstrument;
+    /**
+     * The `URL` of an audio file containing an instrument sample. Supports `WAV` format.
+     *  - Example:  `'https://scribbletune.com/sounds/kick.wav'`
+     */
+    sample?: string;
+    /**
+     * A `Tone` buffer or any audio buffer.
+     *  - See:  https://tonejs.github.io/docs/13.8.25/Buffer
+     */
+    buffer?: string | ToneLoadable;
+    /**
+     * A dictionary of audio samples expressed as a `{ 'Note' : 'URI', ... }` object.
+     *  - Example: `{ 'C3': 'https://.../piano48.wav', 'C#3': '/Path/to/piano49.wav', ... }`
+     */
+    samples?: Record<string, string>;
+    /**
+     * A `Promise` that resolves to a `Tone.Sampler`.
+     *  - Example:  `{ sampler: getSampler('korgBass') }`
+     *  - See:      https://github.com/scribbletune/sampler#sampler
+     */
+    sampler?: ToneInstrument;
+    /**
+     * A `Tone.Player` instance.
+     *  - See:  https://tonejs.github.io/docs/13.8.25/Player
+     */
+    player?: ToneInstrument;
+    /**
+     * External sound producer object / module
+     */
+    external?: ExternalOutput;
+    /**
+     * Name of an effect listed in `Tone.js` or `Tone.Effect` instance. Single value or Array.
+     *  - Example:  `'Chorus'`
+     *  - Example:  `new Tone.AutoFilter()`
+     *  - Example:  `[ 'Chorus', 'AutoFilter' ]`
+     */
+    effects?: string | ToneNode | (string | ToneNode)[];
+    /**
+     * The volume in decibels, in the range `-60` to `+12`.
+     *  - Default:  `0`
+     *  - Example:  `-18`
+     */
+    volume?: number;
+    /**
+     * Callback function triggered when a note is played.
+     */
+    eventCb?: EventFn;
+    /**
+     * Callback function triggered when a note is played.
+     */
+    playerCb?: PlayerObserverFn;
+}
+type ChannelPattern = {
+    /**
+     * Channel index to apply the playing pattern.
+     *  - Example:  `0`
+     *  - Example:  `'beat'`
+     */
+    channelIdx: string;
+    /**
+     * The song structure for one channel, saying which clip to play at each step.
+     *  - Contains: `0123456789_-`
+     *  - Example:  `'0___1___----'`
+     */
+    pattern: string;
+};
+interface PlayParams {
+    /**
+     * An array of ChannelPattern
+     */
+    channelPatterns: ChannelPattern[];
+    /**
+     * The time duration to play each clip in the patterns. Default is 4 bars.
+     *  - Default: `'4:0:0'`
+     *  - Example: `'1:0:0'`
+     */
+    clipDuration?: string;
+}
+interface TPD {
+    /** Tonic */
+    T: string[];
+    /** Predominant (or subdominant) */
+    P: string[];
+    /** Dominant */
+    D: string[];
+}
+
+/**
+ *
+ * @param chordsOrParams a string that denotes space (comma?) separated chords to be used or an object with additional properties
+ * By default, if this is a string, the count of notes generated is 8 and the order is ascending.
+ * For instance arp('CM FM') will result in an array of notes [C4, E4, G4, F4, A4, C4, C5, E5]
+ * You can even provide Params as an object.
+ * For e.g. arp({count: 8, order: '10325476', chords: 'FM_4 Gm7b5_4 AbM_4 Bbm_4 Cm_5 DbM_5 EbM_5})
+ */
+declare const arp: (chordsOrParams: string | ArpParams) => string[];
+
+/**
+ * Generate an array of note objects from clip parameters (for MIDI export).
+ * Applies the pattern to notes, then optionally adds sizzle and accent dynamics.
+ */
+declare const clip: (params: ClipParams) => NoteObject[];
+
+/**
+ * Take an array of note objects to generate a MIDI file in the same location as this method is called
+ * @param  {NoteObject[]} notes    Notes are in the format: {note: ['c3'], level: 127, length: 64}
+ * @param  {String | null} fileName If a filename is not provided, then `music.mid` is used by default
+ * If `null` is passed for `fileName`, bytes are returned instead of creating a file
+ * If this method is called from a browser then it will return a HTML link that you can append in your page
+ * This link will enable the generated MIDI as a downloadable file.
+ * @param {Number | null} bpm If a value is provided, the generated midi file will be set to this bpm value.
+ */
+declare const midi: (notes: NoteObject[], fileName?: string | null, bpm?: number) => string | HTMLAnchorElement | undefined;
+
+/**
+ * Get the chords that go with a given scale/mode
+ * This is useful only in case you want to check what chords work with a scale/mode
+ * so that you can come up with chord progressions
+ * @param  {String} mode e.g. major
+ * @return {Array} e.g.['I', 'ii', 'iii', 'IV', 'V', 'vi', 'vii°']
+ */
+declare const getChordDegrees: (mode: string) => string[];
+/**
+ * Take the specified scale and degrees and return the chord names for them
+ * These can be used as the value for the `notes` param of the `clip` method
+ * @param {String} noteOctaveScale e.g. 'C4 major'
+ * @param  {String} chordDegress e.g. 'I IV V IV'
+ * @return {String} e.g. 'CM FM GM FM'
+ */
+declare const getChordsByProgression: (noteOctaveScale: string, chordDegress: string) => string;
+/**
+ * Generate a chord progression based on basic music theory
+ * where we follow tonic to optionally predominant and then dominant
+ * and then randomly to predominant and continue this till we reach `count`
+ * @param scaleType e.g. M (for major chord progression), m (for minor chord progression)
+ * @param count e.g. 4
+ */
+declare const progression: (scaleType: ProgressionScale, count?: number) => string[];
+
+export { type ArpParams, type ChannelParams, type ChannelPattern, type ClipParams, type EventFn, type NVP, type NoteObject, type PatternElement, type PlayParams, type PlayerObserverFn, type ProgressionScale, type SeqFn, type SizzleStyle, type SynthParams, type TPD, arp, clip, getChordDegrees, getChordsByProgression, midi, progression };