@resequence/patterns-utils

@resequence/patterns-utils

Shared utilities for MIDI rendering, validation, built-in tunings, and keyframe/slide evaluation. Used across pattern implementations and the rendering pipeline.

npm install @resequence/patterns-utils

Also available as @resequence/patterns/utils or resequence/patterns/utils when using the full library or bridge package.

MIDI Rendering

Render a pattern tree to Standard MIDI Files:

import { renderMidi, renderAllEvents } from "@resequence/patterns-utils";

const midiFiles = renderMidi(song, { ppq: 480 });
// Map<string, Uint8Array> — one MIDI file per port

const events = renderAllEvents(song);
// Event[] — all events unfiltered (used by the Router for the complete event stream)

The renderer handles pitch bend allocation across MIDI channels (avoiding conflicts with simultaneous bends), CC events, lyric meta events, tempo changes, time signatures, and markers.

Low-Level Encoding

import { encodeMidi } from "@resequence/patterns-utils";
import type { MidiNote, MidiPitchBend } from "@resequence/patterns-utils";

Tempo Map

Build tempo-aware time conversion from pattern events:

import { collectMetadata, buildTempoMap, beatsToSeconds, secondsToBeats } from "@resequence/patterns-utils";
import type { TempoMap, CollectedMetadata, MarkerPoint, RegionPoint, TempoPoint, TimeSignaturePoint } from "@resequence/patterns-utils";

const metadata = collectMetadata(events);
// metadata.tempoMap, metadata.markers, metadata.timeSignatures, metadata.regions

const seconds = beatsToSeconds(beat, tempoMap);
const beat = secondsToBeats(seconds, tempoMap);

Validation

import { validate } from "@resequence/patterns-utils";
import type { ValidationWarning } from "@resequence/patterns-utils";

const warnings = validate(song);
// Reports orphaned notes — notes without port routing in their ancestor chain

Built-in Tunings

All tuning presets except Chromatic (which is in @resequence/patterns-core as the default). Each is a pre-configured tuning created via core's createTuning() or createIndexTuning():

import { Just, Pythagorean, Meantone, Werckmeister, A432, Midi } from "@resequence/patterns-utils";
import { tuning } from "@resequence/patterns-core";

tuning(pattern, Just.config);

Tuning	Description
Midi	12-TET A=440, octave range [-1, 9]
A432	12-TET A=432
QuarterTone	24 steps per octave
Just	5-limit just intonation
Pythagorean	3-limit frequency ratios
Meantone	Quarter-comma meantone
Werckmeister	Historical well-temperament
Pelog	7-step gamelan tuning
Slendro	5-step gamelan tuning
BohlenPierce	13 steps per tritave (octave ratio 3)
Tet19 / Tet31 / Tet53	Equal temperaments with 19/31/53 steps
I	Integer-index-based tuning for programmatic access

Chord and Scale Utilities

import { CD, CS } from "@resequence/patterns-utils";
import type { ScaleAccessor } from "@resequence/patterns-utils";

CD("Cm7", 2);               // chord — returns a layer of notes
CD("Gmaj9", 4);

const scale = CS("C4 minor");
scale(0);                    // C4
scale(2);                    // Eb4

Keyframe Evaluation

import { applyCurve, evaluateAt } from "@resequence/patterns-utils";

applyCurve(0.5, "exponential");    // apply curve shaping to a normalized value
evaluateAt(keyframes, beat);       // evaluate a keyframe array at a beat position

Slide Utilities

import { evaluateSlide, evaluateSlideCents, mergeSlides } from "@resequence/patterns-utils";

Evaluate pitch slides at tick intervals for pitch bend automation. Used by the MIDI rendering pipeline and slide modifier.