piano-roll

bunnpmpnpmyarn
Copy
pnpm add @audio-ui/core

Copy
import { createPianoRollController, DRAG_THRESHOLD, cellStart, changeLevel, changeVelocity, /* … */ } from "@audio-ui/core/piano-roll";

Usage

A note is a pitch, a start and a length in the timeline's units, with a velocity, a chance, a deviation and a mute. The controller holds the notes, the selection and the pitches sounding, and every gesture and key that edits them; it follows the contract every controller shares:

Copy
import { createPianoRollController } from "@audio-ui/core/piano-roll";

const roll = createPianoRollController({
  timeline: { duration: 16, step: 0.25, grid: { offset: 0, step: 0.25 }, zoom: null, position: () => clock.position },
  defaultValue: [{ id: "n1", pitch: 60, start: 0, length: 1 }],
  minPitch: 36,
  maxPitch: 84,
  onValueCommitted: (notes) => save(notes),
  onNoteOn: (pitch) => synth.noteOn(pitch),
  onNoteOff: (pitch) => synth.noteOff(pitch),
});

The input

• pressGrid(event, grid) starts a selection rectangle, or draws a note in "draw" mode; addAtPlayback adds a note at the playback position from the keyboard.
• pressNote(id, handle, event, element, grid) moves a note by its body, or resizes it by an edge; the selected notes move with it, a chord keeping its spacing. pressStretch(edge, …) stretches the selection in time from its other edge.
• pressVelocity and paintLevels draw the velocity, the deviation or the chance in a lane under the roll.
• keyNote, keyGrid and shortcut take the keyboard: on a note, the arrows move the selection (Shift changes its length), Enter or Space selects it and Delete removes it; Escape clears the selection, Cmd or Ctrl with A selects every note, with C, X, V and D copies, cuts, pastes at the playhead and duplicates, and Q alone quantizes the selection, or every note with none selected. Each returns true when it handled the key.
• keyOn and keyOff sound the keyboard beside the roll.

Edits

Every edit is also a plain function on a list of notes, for a menu, a command or an engine that keeps the notes itself. Each takes the notes, the ids to change and the bounds to keep them in, and returns new notes:

Copy
import { findNotes, fitNotesToScale, moveNotes, quantizeNotes } from "@audio-ui/core/piano-roll";

const bounds = { duration: 16, minLength: 0.25, minPitch: 0, maxPitch: 127 };
const all = new Set(notes.map((note) => note.id));

moveNotes(notes, all, 1, 12, bounds); // a beat later, an octave up
quantizeNotes(notes, all, (time) => Math.round(time), bounds); // starts on the beat
fitNotesToScale(notes, all, { pitchClasses: [0, 2, 4, 5, 7, 9, 11], root: 9 }, bounds); // into A minor
findNotes(notes, { pitchClasses: [0] }); // the ids of every C

The others edit time and shape: splitNotes, joinNotes, chopNotes, stretchNotes, legatoNotes, reverseNotes, invertNotes, duplicateNotes, duplicateAfter, pasteNotes, insertTime, deleteTime, duplicateTime and toggleMuted; and the dynamics: changeVelocity, rampVelocity, humanizeNotes, setChance and setDeviation. findNotes selects by pitch class, scale, velocity, length, chance or mute, every nth of them, or the inverse.

Rows

rollRows(notes, min, max, fold, scale) gives the rows a roll draws, highest pitch first, with rowOf and pitchAt to go between a pitch and its row: every pitch, only those the notes use, or only those in a scale.

A scale is a RollScale: the pitch classes it keeps and its root, each from 0 (C) to 11 (B). The roll knows no scale by name; rollScale gives a named one in that shape.

The Piano roll draws this controller in React.