Vector Score

A lightweight, SVG-based TypeScript library for rendering musical staves, notes, and rhythm patterns in the browser.

Features

• Multiple Staff Types: Supports Treble, Bass, Alto, and Grand staves (MusicStaff and ScrollingStaff).
• Music Staff:Standard music staff for notation.
• Rhythm Staff: Dedicated staff for rhythm exercises with customizable time signatures and bar handling.
• Scrolling Staff Staff made to allow for 'endless' style of notes.
• SVG Rendering: Scalable Vector graphics suitable for any screen size.
• Flexible Note Input: Simple string-based syntax for defining notes.

Installation

npm i vector-score

Development

To start the development server with a playground:

npm run dev

To build the library for production:

npm run build

Usage

1. Setup HTML

Create a container element in your HTML where the staff will be rendered.

<div id="staff-container"></div>

2. Import and Initialize

Standard Music Staff

import { MusicStaff } from 'vector-score';

const container = document.getElementById('staff-container');

const staff = new MusicStaff(container, {
  staffType: 'treble', // 'treble', 'bass', 'alto', or 'grand'
  width: 400,
  scale: 1.2,
  spaceBelow: 1
});

// Draw a C Minor scale (quarter notes)
// Format: NoteName + Accidental(optional) + Octave + Duration
staff.drawNote(['C4q', 'D4q', 'Eb4q', 'F4q', 'G4q', 'Ab4q', 'Bb4q', 'C5q']);

// Draw a C Chord
staff.drawChord(['C4w', 'E4w', 'G4w']);

// Evenly space all notes on the staff
staff.justifyNotes();

Resulting Staff

Grand Staff

import { MusicStaff } from 'vector-score';

const grandStaff = new MusicStaff(container, {
  staffType: 'grand',
  width: 400,
  spaceBelow: 2,
  spaceAbove: 2
});

// Notes are automatically positioned on the correct stave based on pitch
grandStaff.drawNote(['G4q', 'E4h', 'C4w', "A3h", "F3h"]);

grandStaff.drawChord(["G3w", "C4w", "E4w"]);

Resulting Staff

Rhythm Staff

import { RhythmStaff } from 'vector-score';

const rhythmContainer = document.getElementById('rhythm-container');

const rhythm = new RhythmStaff(rhythmContainer, {
  width: 400,
  topNumber: 4, // Time signature numerator (e.g., 4/4 time)
  barsCount: 2
});

// Draw notes and rests
rhythm.drawNote(['q', 'q']); // Duration only
rhythm.drawRest(['h']);

// Draw beamed note
rhythm.drawBeamedNotes("e", 4); // Draws a beamed note of 4 eighth notes

// Finish the bar
rhythm.drawNote(['q', 'q']);

// Increment the UI to show the first beat in the bar
rhythm.incrementCurrentBeatUI();

Resulting Staff

Scrolling Staff

import { ScrollingStaff } from 'vector-score';

const scrollingContainer = document.getElementById('scrolling-container');

const scrollingStaff = new ScrollingStaff(scrollingContainer, {
  width: 400,
  spaceBelow: 2,
  spaceAbove: 2,
  onNotesOut: handleNotesOut, // Connect a handler when notes run out (optional)
});

// Handler for when notes run out
function handleNotesOut() {
  isNotesOut = true;
}

// ****
// NOTE CSS SELECTOR FOR NOTES FOR ANIMATION IS
// .vs-scrolling-notes-layer > g.vs-note-wrapper { transition: transform 0.2s ease-in }
// ****

// Add notes to the queue
// 5 single notes, a C chord, 2 more notes, finally a D chord
scrollingStaff.queueNotes([
  "C4w",
  "F4w",
  "C4w",
  "B4w",
  "D4w",
  ["C4w", "E4w", "G4w"],
  "B4w",
  "D4w",
  ["D4w", "F#4w", "A4w"],
]);

// The button event listener calls 'advanceNotes()' to move the notes over, one step at a time.

Resulting Staff

Note String Syntax

Notes are defined using a specific string format parsed by the library:

[Name][Accidental?][Octave][Duration]

• Name: A - G (Case insensitive)
• Accidental: # (Sharp) or b (Flat). Optional.
• Octave: 0 - 9
• Duration:
  • w: Whole
  • h: Half
  • q: Quarter
  • e: Eighth

Examples:

• C4w: C, Octave 4, Whole note
• F#5q: F Sharp, Octave 5, Quarter note
• Bb3e: B Flat, Octave 3, Eighth note

API Reference

MusicStaff Class

| Method | Description | | :--- | :--- | | drawNote(notes: string \| string[]) | Draws one or multiple notes sequentially. | | drawChord(notes: string \| string[]) | Draws multiple notes stacked as a chord at the current cursor position. | | justifyNotes() | Evenly spaces all currently drawn notes across the staff width. | | clearAllNotes() | Removes all notes from the staff and resets the cursor. | | changeNoteByIndex(note: string, index: number) | Replaces a note at a specific index with a new note. | | changeChordByIndex(notes: string[], index: number) | Replaces a chord at a specific index with a new chord. | | destroy() | Destroys internal arrays and elements |

RhythmStaff Class

| Method | Description | | :--- | :--- | | drawNote(notes: string \| string[]) | Draws rhythm notes. | | drawRest(rests: string \| string[]) | Draws rests. | | drawBeamedNotes(type: 'e'\|'s', count: number) | Draws a group of beamed eighth or sixteenth notes. | | clearAllNotes() | Removes all items from the staff. | | incrementCurrentBeatUI() | Starts the UI for showing the current beat. Connect to a external interval for accurate showing of current beat. | | resetCurrentBeatUI() | Must be called if current beat goes over the total beats in the bar to reset its state | | destroy() | Destroys internal arrays and elements |

ScrollingStaff Class

| Method | Description | | :--- | :--- | | queueNotes(notes: (string \| string[])[]) | Queues notes on the staff. ["C4", ["C4", "E4", "G4"], "B4"] | | advanceNotes() | Advances notes to the next position | | clearAllNote() | Clears all notes on the staff | | destroy() | Destroys internal arrays and elements |

Configuration Options

MusicStaffOptions

• width: Total width of the SVG in pixels.
• scale: Zoom factor (default: 1).
• noteStartX: Position where notes start to draw.
• staffType: 'treble' | 'bass' | 'alto' | 'grand'.
• spaceAbove: Padding units above the staff (in staff line spaces).
• spaceBelow: Padding units below the staff (in staff line spaces).
• staffColor: CSS color string for lines and notes.
• staffBackgroundColor: CSS color string for background.

RhythmStaffOptions

• topNumber: The top number of the time signature (e.g., 4 for 4/4 time).
• barsCount: Number of measures to draw.
• currentBeatUIColor: CSS color string for current beat UI.
• Inherits sizing and color options from MusicStaffOptions.
• width: Total width of the SVG in pixels.
• scale: Zoom factor (default: 1).
• topNumber: The top number of the time signature (e.g., 4 for 4/4 time).
• barsCount: Number of measures to draw.
• spaceAbove: Padding units above the staff (in staff line spaces).
• spaceBelow: Padding units below the staff (in staff line spaces).
• staffColor: CSS color string for lines and notes.
• staffBackgroundColor: CSS color string for background.
• currentBeatUIColor: CSS color string for current beat UI indicator.

ScrollingStaffOptions

• width: Total width of the SVG in pixels.
• scale: Zoom factor (default: 1).
• noteStartX: Position where notes start to draw.
• staffType: 'treble' | 'bass' | 'alto' | 'grand'.
• spaceAbove: Padding units above the staff (in staff line spaces).
• spaceBelow: Padding units below the staff (in staff line spaces).
• staffColor: CSS color string for lines and notes.
• staffBackgroundColor: CSS color string for background.
• onNotesOut: Callback function for when there are no more notes on the staff to advance.