shimi/dist/types/Clip.d.ts

A JS framework for building complex MIDI applications

import Range from './Range';
import Note from './Note';
import { ITween } from './Tweens';
/**
 * ClipNote represents a note to be played within a clip, specifying the start and end time of the note within the clip, as well as all the information like pitch, velocity, channel, etc. needed to play the note.
 *
 * @category Clips
 */
export declare class ClipNote extends Range {
    /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */
    get typeName(): string;
    /** The MIDI pitch of the note, valid values range from 0 - 127. */
    get pitch(): number;
    set pitch(value: number);
    private _pitch;
    /**
     * The note's velocity, valid values range from 0 - 127, or an ITween object to allow for values that change over time.
     *
     * An example of using a tween for velocity to make a note swell in volume as it's played:
     * `clipNote.velocity = Tween.linear(1, 127)`
     */
    get velocity(): number | ITween;
    set velocity(value: number | ITween);
    private _velocity;
    /** Which channel to play the note on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide. */
    get channel(): number;
    set channel(value: number);
    private _channel;
    /** Provides way of identifying notes so they can be easily retrieved later. */
    ref: string;
    /**
     * @param start What beat within the clip that the note starts on.
     * @param duration How many beats the note lasts.
     * @param pitch The MIDI pitch of the note, valid values range from 0 - 127. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information.
     * @param velocity The note's velocity, valid values range from 0 - 127, or a function that maps beats to values.
     * @param channel Which channel to play the note on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide.
     * @param ref Provides way of identifying notes so they can be easily retrieved later.
     */
    constructor(start: number, duration: number, pitch: number | string, velocity: number | ITween, channel?: number, ref?: string);
    /**
     * The createNote method is primarily intended for use by the ClipPlayer to generate a new Note object from the ClipNote.
     * @param channel This is the preferred channel to use if the ClipNote doesn't specify one.
     * @param percent How far into the note we should start from
     * @returns
     */
    createNote(channel: number, percent: number): Note;
    /** Returns a copy of this ClipNote object */
    duplicate(): ClipNote;
    /** Used by the library for the custom serialization of Clips */
    toJSON(): any;
    /** Takes an object parsed from JSON ClipNote data to load into an actual clip note instance. */
    static load(clipNoteData: any): ClipNote;
}
/**
 * ClipCC represents a control change to be played within a clip, specifying the start and end of the control change within the clip, as well as the information to be sent by the control change.
 *
 * @category Clips
 */
export declare class ClipCC extends Range {
    /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */
    get typeName(): string;
    /** The MIDI controller to modify, valid values range from 0 - 127. */
    get controller(): number;
    set controller(value: number);
    private _controller;
    /**
     * The value to set, valid values range from 0 - 127, or an ITween object to allow for values that change over time.
     *
     * An example of using a tween to sweep the CC value from 0 to 127 over the course of 1 beat:
     * `new ClipCC(0, 1, 25, Tween.linear(0, 127));`
     */
    get value(): number | ITween;
    set value(value: number | ITween);
    private _value;
    /** Which channel to send the control change to, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide. */
    get channel(): number;
    set channel(value: number);
    private _channel;
    /**
     * @param start What beat within the clip that the control change starts.
     * @param duration How many beats the control change lasts.
     * @param controller The MIDI controller to modify, valid values range from 0 - 127.
     * @param value The value to set, valid values range from 0 - 127, or a Tween object which defines a strategy for how to change over the course of the control change's lifetime.
     * @param channel Which channel to play the control change on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide.
     */
    constructor(start: number, duration: number, controller: number, value: number | ITween, channel?: number);
    /** Returns a copy of this ClipCC object */
    duplicate(): ClipCC;
    /** Used by the library for the custom serialization of Clips */
    toJSON(): any;
    /** Takes an object parsed from JSON ClipCC data to load into an actual clip CC instance. */
    static load(clipCCData: any): ClipCC;
}
/**
 * ClipBend represents a bend to be played within a clip, specifying the start and end of the bend, as well as the bend amount and optionally shape.
 *
 * @category Clips
 */
export declare class ClipBend extends Range {
    /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */
    get typeName(): string;
    /**
     * How much bend to apply, valid values range from -1 to +1, or an ITween object to allow for values that change over time.
     *
     * In the MIDI standard, bends are defined by 2 7-bit numbers put together, this makes sense within the specification, but is not particularly friendly to work with. Shimi prefers to work with percentages for ease of use.
     *
     * An example of using a tween to make a bend that smoothly eases up:
     * `clipBend.percent = Tween.sineInOut(0, 1);`
     */
    get percent(): number | ITween;
    set percent(value: number | ITween);
    private _percent;
    /** Which channel to send the bend to, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide */
    get channel(): number;
    set channel(value: number);
    private _channel;
    /**
     * @param start What beat within the clip that the bend starts
     * @param duration How many beats the bend lasts
     * @param percent How much bend to apply, valid values range from 0 - 127, or a Tween object which defines a strategy for how to change over the course of the bend's lifetime.
     * @param channel Which channel to play the bend on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide
     */
    constructor(start: number, duration: number, percent: number | ITween, channel?: number);
    /** Returns a copy of this ClipCC object */
    duplicate(): ClipBend;
    /** Used by the library for the custom serialization of Clips */
    toJSON(): any;
    /** Takes an object parsed from JSON ClipBend data to load into an actual clip bend instance. */
    static load(clipBendData: any): ClipBend;
}
/**
 * The Clip class represents a collection of notes, control changes, and bends, arranged over a certain number of beats, to allow them to be played in a musical expression.
 *
 * An example of using a clip to contain the first 2 bars of the melody Twinkle Twinkle Little Star:
 * ```
 *  const clip = new shimi.Clip(8)
 *      .addNote([0,1], 1, 'C4', 80)
 *      .addNote([2,3], 1, 'G4', 80)
 *      .addNote([4,5], 1, 'A4', 80)
 *      .addNote(6, 2, 'G4', 80);
 * ```
 *
 * @category Clips
 */
export declare class Clip extends Range {
    /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */
    get typeName(): string;
    /**
     * The collection of notes that the clip contains.
     */
    notes: ClipNote[];
    /**
     * The collection of control changes that the clip contains.
     */
    controlChanges: ClipCC[];
    /**
     * The collection of pitch bends that the clip contains.
     */
    bends: ClipBend[];
    /**
     * @param duration How many beats the clip lasts for.
     */
    constructor(duration: number);
    /**
     * Adds a note to the clip. The start & pitch parameters can each take arrays of values, allowing for multiple notes to be added at once for the same pitches and start beats.
     * @param start What beat within the clip that the note starts on. Can take array of multiple note starts
     * @param duration How many beats the note lasts.
     * @param pitch The MIDI pitch of the note, valid values range from 0 - 127. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. Can take array of multiple pitch values
     * @param velocity The note's velocity, valid values range from 0 - 127, or a function that maps beats to values.
     * @param channel Which channel to play the note on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide.
     * @param ref Provides way of identifying notes so they can be easily retrieved later.
     * @returns Returns the Clip object which the note(s) is being added to.
     */
    addNote(start: number | Array<number>, duration: number, pitch: number | string | Array<number | string>, velocity: number | ITween, channel?: number, ref?: string): Clip;
    /**
     * Adds a control change to the clip. The start parameter can take an array of values, allowing for multiple similar control changes to be added at once.
     * @param start What beat within the clip that the control change starts. Can take array of multiple start values.
     * @param duration How many beats the control change lasts.
     * @param controller The MIDI controller to modify, valid values range from 0 - 127.
     * @param value The value to set, valid values range from 0 - 127, or a Tween object which defines a strategy for how to change over the course of the control change's lifetime.
     * @param channel Which channel to play the control change on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide.
     * @returns Returns the Clip object which the control change(s) is being added to.
     */
    addCC(start: number | Array<number>, duration: number, controller: number, value: number | ITween, channel?: number): Clip;
    /**
     * Adds a bend to the clip. The start parameter can take an array of values, allowing for multiple similar bends to be added at once.
     * @param start What beat within the clip that the bend starts
     * @param duration How many beats the bend lasts
     * @param percent How much bend to apply, valid values range from 0 - 127, or a Tween object which defines a strategy for how to change over the course of the bend's lifetime.
     * @param channel Which channel to play the bend on, valid values range from 0 - 15, or null to allow whatever is playing the clip to decide
     * @returns Returns the Clip object which the bend(s) is being added to.
     */
    addBend(start: number | Array<number>, duration: number, percent: number | ITween, channel?: number): Clip;
    /**
     * Creates and returns a new deep-copy of the clip.
     * @returns
     */
    duplicate(): Clip;
    /**
     * Modify the start times of notes in the clip to be closer to some desired rhythmic pattern. Modifies the clip in place.
     * @param rhythm An array of numbers that specify a rhythm to quantize to.
     * For example [0.5] means that the clip should be quantized to eighth notes.
     * Alternatively, [0.5, 0.25, 0.25] means that the clip should be quantized to a heavy metal style gallop rhythm.
     * @param strength A number from 0 to 1, 1 means full quantization to the target rhythm
     * 0.5 will move notes half way towards the target rhythm, while 0 will do nothing
     * @returns Returns the clip instance to allow for chaining.
     */
    quantize(rhythm: number[], strength?: number): Clip;
    /**
     * Transposes the notes in the clip up/down. Modifies the clip in place.
     * @param semitones How many semitones to transpose each note in the clip up by.
     * @returns Returns the clip instance to allow for chaining.
     */
    transpose(semitones: number): Clip;
    /**
     * Reflects the clip vertically around a center pitch.
     * Modifies the clip in place.
     * @param reflectionPitch The pitch which notes in the clip are reflected around.
     * @returns Returns the clip instance to allow for chaining.
     */
    invert(reflectionPitch: number): Clip;
    /**
     * Reflects the clip horizontally, with events from the start reflected to the end.
     * Modifies the clip in place.
     * @returns Returns the clip instance to allow for chaining.
     */
    reverse(): Clip;
    /**
     * Intended primarily for use by the ClipPlayer to fetch all notes who's start times are between the provided start & end parameters.
     * @param start The beat at which to start searching for note beginnings.
     * @param end The beat at which to end searching for note beginnings.
     * @returns
     */
    getNotesStartingInRange(start: number, end: number): ClipNote[];
    /**
     * Intended primarily for use by the ClipPlayer to fetch all notes who's end times are between the provided start & end parameters.
     * @param start The beat at which to start searching for note endings.
     * @param end The beat at which to end searching for note endings.
     * @returns
     */
    getNotesEndingInRange(start: number, end: number): ClipNote[];
    /**
     * Intended primarily for use by the ClipPlayer to fetch all control changes who's durations overlap with the provided start & end parameters.
     * @param start The beat at which to start searching for overlapping control changes.
     * @param end The beat at which to end searching for overlapping control changes.
     * @returns
     */
    getControlChangesIntersectingRange(start: number, end: number): ClipCC[];
    /**
     * Intended primarily for use by the ClipPlayer to fetch all pitch bends who's durations overlap with the provided start & end parameters.
     * @param start The beat at which to start searching for overlapping pitch bends.
     * @param end The beat at which to end searching for overlapping pitch bends.
     * @returns
     */
    getBendsIntersectingRange(start: number, end: number): ClipBend[];
    /**
     * Get items from the passed in array whos start is within the start & end points
     * Note: If end arg is less than start arg then it assumes that the range to be searched is wrapping around
     * So in this case, it will actually search for anything whos end is greater than the start arg, OR less than the end arg
     */
    private _getChildrenStartingInRange;
    /**
     * Get items from the passed in array whos end is within the start & end points
     * Note: If end arg is less than start arg then it assumes that the range to be searched is wrapping around
     * So in this case, it will actually search for anything whos start is greater than the start arg, OR less than the end arg
     */
    private _getChildrenEndingInRange;
    /**
     * Get items from the passed in array which in any way intersect with the start & end points
     */
    private _getChildrenIntersectingRange;
    /** Used by the library for the custom serialization of Clips */
    toJSON(): {
        start: number;
        duration: number;
        notes: ClipNote[];
        controlChanges: ClipCC[];
        bends: ClipBend[];
    };
    /** Takes an object parsed from JSON Clip data to load into an actual clip instance. */
    static load(clipData: any): Clip;
}