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.