choraljs

A TypeScript library for generating SATB (Soprano, Alto, Tenor, Bass) choral voicings using TonalJS.

Installation

npm install choraljs @tonaljs/tonal @tonaljs/progression deepmerge

Usage

import { Progression, SATB, ChordSpec } from 'choraljs';

// Create a progression in C major
const prog = new Progression({ key: 'C', scale: 'major' });

// Chain voicings
prog
  .voiceChord('I')      // I chord in C major
  .voiceChord('vi')     // vi chord
  .voiceChord('IV');    // IV chord

console.log(prog.results.voicings);

// Check legal next moves
console.log(prog.legalMoves().map(m => m.chord));

// Validate a chord without adding
console.log(prog.validateChord('V'));  // true or false

// Modulate to G major via pivot
prog.modulate('G').voiceChord('V').voiceChord('I');

// Directly insert a custom SATB voicing
const custom: SATB = { S: 'E4', A: 'C4', T: 'G3', B: 'E3' };
prog.addDirect(custom, 'custom');

// Batch build
const batch = Progression.fromArray(['I','IV','V','I'], { key: 'F', scale: 'major' });
console.log(batch.results.voicings);

API

Progression

• constructor(options?: Partial)

  • options.key: starting key (default 'C')
  • options.scale: scale type (default 'major')
  • options.voicing: 'close' | 'open' (default 'close')

• voiceChord(spec: ChordSpec): this Voice a chord (Roman numeral, chord name, or { notes: string[] }).

• legalMoves(): Array<{ chord: DiatonicNumeral; voicing: SATB }> Get all next-step diatonic Roman numerals that avoid parallels/spacing errors.

• validateChord(spec: ChordSpec): boolean Check if a chord can be voiced legally at the current progression point.

• modulate(newKey: string, newScale?: string): this Pivot-mid progression modulation by detecting a common chord.

• addDirect(satb: SATB, label?: string): this Directly append an existing SATB voicing (throws if voice-leading errors).

• results

  • voicings: array of { chord: string; key: string; voicing: SATB }
  • errors: array of { chord: string; key: string; message: string }

• static fromArray(arr: ChordSpec[], opts?: Partial<Context>): Progression Build a progression from an array of chord specs in one call.

Contributing

1. Clone the repo
2. npm install
3. npm run build and npm test
4. Submit PRs for new features or bug fixes.