Norwegian Parcel Mail

    @phbalance/d3-piano
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    A D3 library for drawing a piano

    Configurable SVG piano drawn with generated events for key press and release using D3. Implemented using TypeScript.

    Installation

    npm install --save @phbalance/d3-piano
    npm install --save d3-selection # peer dependency
    npm install --save d3-scale # peer dependency
    

    Use

    The drawing of the piano into an SVG element is achieved by calling drawPiano. Provide the svg element, a callback to be invoked when an action is performed on a key (i.e. event generated for "key" pressed or depressed), and configuration details. The configuration includes:

    export enum PianoKeyLabel {
    	NONE = 0,
    	SIMPLE = 1,
    	FULL = 2,
    }
    
    export interface IPianoDrawConfig {
    	steps: string[];
    	octaves: number[];
    	invalidNotes: string[];
    
    	stopKeyPressWithExit: boolean;
        
    	keyLabel: PianoKeyLabel;
    
    	width: number;
    }

    Configuration Parameters

    invalidNotes is a list of notes to exclude from the provided set of steps and octaves.

    keyLabel indicates what kind of label the key should have: none, a simple note name, or a full name of octave plus the simple note name.

    width is the width of the piano drawn in the svg in pixels.

    octaves is an array of which octaves to draw.

    steps is an array of the names of the keys starting from left most (lowest frequency) key.

    stopKeyPressWithExit indicates if mouseout or pointerout events should be bound to the keys. PointerEvents are a consolidation of mouse and touch events. If true, if the mouse/pointer cursor leaves the bounds of the piano key it will be the same as if the key were no longer pressed even if the mouse is still held down. If false there is no mouseout or pointerout event bound. Thus by pushing the mouse down, moving the cursor out of that key, and then releasing the mouse you will not generate a key released message. For touch devices you probably just need to drag your finger a bit. You can use this approach to crudely generate chords.

    Example

    An example of use:

    import { drawPiano, IKey, PianoKeyAction, PianoKeyLabel } from "@phbalance/d3-piano";
    
    ...
    
    const svgToDrawInto = do something to create the SVG you want the piano to be drawn into
    
    function keyAction(action: PianoKeyAction, keyInfo: IKey): void {
        if(action === PianoKeyAction.PRESS_START) {
            // Do stuff. Perhaps generate a tone?
        } else {
            // Do stuff. Perhaps turn off a tone?
        }
    }
    
    const config: IKey = {
        steps: ["C", "D", "E", "F", "G", "A", "B"],
        octaves: [3, 4, 5, 6, 7, 8], // Computer speakers probably can't reproduce octaves 0 & 1 & most of 2 so ignore them
        invalidNotes: [ // For an 88 key keyboard
            "0C", "0D", "0E", "0F", "0G",
            "8C", "8D", "8E", "8F", "8G", "8A", "8B",
        ],
        stopKeyPressWithExit: true,
        keyLabel: PianoKeyLabel.NONE,
        width: 800
    };
    
    // Note, if you're using a class method as the passed in callback you may need to do something like this.keyAction.bind(this)
    drawPiano(svgToDrawInto, keyAction, config);

    Touch Support

    Touch support via PointerEvents was added in version 0.1.1.

    Being Notified of a Key Press

    As mentioned above, the 2nd parameter of drawPiano is a function that is called as a result of keys being pressed by a user.

    Programmatically Generating a Key Press

    This was added in 0.1.1.

    Normally, a user will use an input device to manipulate the keyboard elements. However, it is possible to programmatically generate key presses in a way similar to a player piano moves keys without the user. For this use the press and release keys of the object returned by drawPiano.

    Both the press and release methods have the same signature:

    type CreatePianoKeyActionFunction = (containingSvgEle: SVGSVGElement, note: string, octave?: number) => void;

    Thus, provide the svg element that you passed into drawPiano as the containingSvgEle and then the note and, optionally, octave. If you do not provide a value for octave then any octave will be used and multiple key presses will be genereated at the "same time" (technically sequential mouse events).

    Reporting Issues

    You can report bugs here. Feel free to make suggestions as well.

    Install

    npm i @phbalance/d3-piano

    DownloadsWeekly Downloads

    17

    Version

    0.2.0

    License

    MIT

    Unpacked Size

    53.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • phbalance