linked-rolls 0.17.0 → 0.19.0

package/lib/TrackerBar.d.ts

@@ -83,6 +83,13 @@ export interface TrackerBarSpec {
     };
     /** Every position outside the note block, keyed by track. */
     expressions: ReadonlyMap<number, string>;
+    /**
+     * The position the rewind runs on, where the system gives it no
+     * valve of its own to be named after. The T-98 drives its rewind
+     * with a long perforation on the bass sforzando-piano position.
+     * Left out, it is the position typed `Rewind`.
+     */
+    rewindTrack?: number;
     /** The speed the system runs its rolls at, where the literature states one. */
     paperSpeed?: SpeedMeasure;
 }

package/lib/TrackerBar.js

@@ -28,8 +28,8 @@ export const describeTrackerBar = (spec) => {
             return undefined;
         return { type: 'expression', expressionType, scope: scopeOf(role) };
     };
-    const rewind = [...spec.expressions]
-        .find(([, type]) => type === 'Rewind')?.[0];
+    const rewind = spec.rewindTrack
+        ?? [...spec.expressions].find(([, type]) => type === 'Rewind')?.[0];
     if (rewind === undefined) {
         throw new Error(`${spec.name} declares no rewind track`);
     }

package/lib/alignment.d.ts

@@ -24,12 +24,18 @@ export interface AlignmentResult {
 }
 /**
  * Finds the shift and scale that carry the places of `rollA` onto those
- * of `rollB`, reading both through the bar. Runs of pitches that occur
- * once on each roll anchor a first line; then every note is paired with
- * its nearest counterpart of the same pitch and the line refitted, the
- * window closing each time. A copy cut for another paper speed, a scan
- * with a calibration pattern, and holes the other copy lacks are all
- * within reach of that. Nothing is found where the rolls share no run of
- * pitches, as between two different pieces.
+ * of `rollB`, reading each through its own bar. Runs of pitches that
+ * occur once on each roll anchor a first line; then every note is paired
+ * with its nearest counterpart of the same pitch and the line refitted,
+ * the window closing each time. A copy cut for another paper speed, a
+ * scan with a calibration pattern, and holes the other copy lacks are
+ * all within reach of that. Nothing is found where the rolls share no
+ * run of pitches, as between two different pieces.
+ *
+ * Two bars are what lets a copy cut for one system be aligned against a
+ * copy cut for another, a T-98 against a T-100: the bars put the note
+ * positions on different tracks, but they agree on the pitch each track
+ * sounds, and it is the pitches that are matched. Where a copy's holes
+ * have already been put onto the edition's bar, that bar reads it.
  */
-export declare function alignFeatures(rollA: readonly AnyFeature[], rollB: readonly AnyFeature[], bar?: TrackerBar): AlignmentResult | undefined;
+export declare function alignFeatures(rollA: readonly AnyFeature[], rollB: readonly AnyFeature[], barA?: TrackerBar, barB?: TrackerBar): AlignmentResult | undefined;

package/lib/alignment.js

@@ -159,17 +159,23 @@ const resultOf = ({ line, matches }) => {
 };
 /**
  * Finds the shift and scale that carry the places of `rollA` onto those
- * of `rollB`, reading both through the bar. Runs of pitches that occur
- * once on each roll anchor a first line; then every note is paired with
- * its nearest counterpart of the same pitch and the line refitted, the
- * window closing each time. A copy cut for another paper speed, a scan
- * with a calibration pattern, and holes the other copy lacks are all
- * within reach of that. Nothing is found where the rolls share no run of
- * pitches, as between two different pieces.
+ * of `rollB`, reading each through its own bar. Runs of pitches that
+ * occur once on each roll anchor a first line; then every note is paired
+ * with its nearest counterpart of the same pitch and the line refitted,
+ * the window closing each time. A copy cut for another paper speed, a
+ * scan with a calibration pattern, and holes the other copy lacks are
+ * all within reach of that. Nothing is found where the rolls share no
+ * run of pitches, as between two different pieces.
+ *
+ * Two bars are what lets a copy cut for one system be aligned against a
+ * copy cut for another, a T-98 against a T-100: the bars put the note
+ * positions on different tracks, but they agree on the pitch each track
+ * sounds, and it is the pitches that are matched. Where a copy's holes
+ * have already been put onto the edition's bar, that bar reads it.
  */
-export function alignFeatures(rollA, rollB, bar = welteT100) {
-    const a = noteOnsets(rollA, bar);
-    const b = noteOnsets(rollB, bar);
+export function alignFeatures(rollA, rollB, barA = welteT100, barB = barA) {
+    const a = noteOnsets(rollA, barA);
+    const b = noteOnsets(rollB, barB);
     const coarse = robustLine(anchors(a, b));
     if (!coarse)
         return undefined;

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export * from './TrackCalibration';
 export * from './TrackerBar';
 export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
+export * from './systems/welteT98/bar';
 export * from './systems';
 export * from './ReproducingSystem';
 export * from './FeatureSource';
@@ -29,4 +30,5 @@ export * from './asJsonLd';
 export * from './importJsonLd';
 export * from './migrate';
 export { readFromStanfordAton, type StanfordAtonOptions } from './readers/stanfordAton';
+export { readFromPhillipsEroll, CONTROL_OFFSET, phillipsSystems, type PhillipsErollOptions } from './readers/phillipsEroll';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH, type SpencerBarOptions } from './readers/spencerBar';

package/lib/index.js

@@ -12,6 +12,7 @@ export * from './TrackCalibration';
 export * from './TrackerBar';
 export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
+export * from './systems/welteT98/bar';
 export * from './systems';
 export * from './ReproducingSystem';
 export * from './FeatureSource';
@@ -29,4 +30,5 @@ export * from './asJsonLd';
 export * from './importJsonLd';
 export * from './migrate';
 export { readFromStanfordAton } from './readers/stanfordAton';
+export { readFromPhillipsEroll, CONTROL_OFFSET, phillipsSystems } from './readers/phillipsEroll';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH } from './readers/spencerBar';

package/lib/readers/phillipsEroll.d.ts

@@ -0,0 +1,62 @@
+import { RollCopy } from "../RollCopy";
+import { TrackerBar } from "../TrackerBar";
+import { Millimeters, Seconds } from "../Quantity";
+/**
+ * Peter Phillips's "e-roll" file, the unprocessed output of his
+ * pneumatic roll reader (thesis pp. 182–196): the roll runs over a
+ * tracker bar and a switch on every position writes a MIDI note as its
+ * perforation passes. Every position is there, expression included, all
+ * at one velocity. His other product, the standard MIDI file, has the
+ * expression decoded into velocities already and cannot be read as a
+ * roll.
+ *
+ * Two things follow from a reader rather than a scanner. The events are
+ * elapsed time, not paper, and the take-up spool accelerates the paper
+ * as it fills, so `placeAt` has to put the time back onto the paper.
+ * And a switch stays open longer than its perforation is long, so a
+ * hole read here runs past the punched one.
+ */
+/**
+ * He numbers his files by two rules at once, which his free samples
+ * show and which follow from what the file is for. A note carries the
+ * MIDI number it sounds, so that the file plays on a MIDI instrument
+ * without translation. An expression position, having no pitch to
+ * carry, is numbered by its place on the bar plus a fixed offset: on a
+ * red e-roll the sustain commands sit at 107 and 108 for positions 93
+ * and 94, and the soft pedal at 21 and 22 for positions 7 and 8, so the
+ * offset is fourteen.
+ *
+ * The two rules collide on one number, the lowest note of the T-100
+ * sharing 24 with the tenth position. Notes win there, the note block
+ * being the larger claim; none of his samples uses the number at all.
+ */
+export declare const CONTROL_OFFSET: Readonly<Record<string, number>>;
+export interface PhillipsErollOptions {
+    /**
+     * The bar the file numbers its positions by, which is the bar of
+     * the roll he read.
+     */
+    system?: TrackerBar;
+    /** The edition's bar, onto which the positions are put. */
+    bar?: TrackerBar;
+    /**
+     * How far above its position an expression number sits. Defaults to
+     * what his samples show for that bar.
+     */
+    controlOffset?: number;
+    /**
+     * Where on the paper the roll had run after so many seconds. The
+     * default is the constant speed the system states, which ignores
+     * the take-up spool; pass `paperAt` of welte-t100-emulator to
+     * account for it.
+     */
+    placeAt?: (elapsed: Seconds) => Millimeters;
+}
+/**
+ * Reads one of his e-roll files as a copy of the roll, in millimetres
+ * of paper. A position the edition's bar does not read is left out, as
+ * the bar would leave it.
+ */
+export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, bar, controlOffset, placeAt }?: PhillipsErollOptions): RollCopy;
+/** The bars his files are known to be numbered by. */
+export declare const phillipsSystems: readonly TrackerBar[];

package/lib/readers/phillipsEroll.js

@@ -0,0 +1,164 @@
+import { read } from "midifile-ts";
+import { v4 } from "uuid";
+import { assignObject } from "../Assumption";
+import { systemOf, translationBetween } from "../TrackerBar";
+import { welteT100 } from "../systems/welteT100/bar";
+import { welteLicensee } from "../systems/welteLicensee/bar";
+import { inMetersPerMinute, mm, seconds, track } from "../Quantity";
+/**
+ * Peter Phillips's "e-roll" file, the unprocessed output of his
+ * pneumatic roll reader (thesis pp. 182–196): the roll runs over a
+ * tracker bar and a switch on every position writes a MIDI note as its
+ * perforation passes. Every position is there, expression included, all
+ * at one velocity. His other product, the standard MIDI file, has the
+ * expression decoded into velocities already and cannot be read as a
+ * roll.
+ *
+ * Two things follow from a reader rather than a scanner. The events are
+ * elapsed time, not paper, and the take-up spool accelerates the paper
+ * as it fills, so `placeAt` has to put the time back onto the paper.
+ * And a switch stays open longer than its perforation is long, so a
+ * hole read here runs past the punched one.
+ */
+/**
+ * He numbers his files by two rules at once, which his free samples
+ * show and which follow from what the file is for. A note carries the
+ * MIDI number it sounds, so that the file plays on a MIDI instrument
+ * without translation. An expression position, having no pitch to
+ * carry, is numbered by its place on the bar plus a fixed offset: on a
+ * red e-roll the sustain commands sit at 107 and 108 for positions 93
+ * and 94, and the soft pedal at 21 and 22 for positions 7 and 8, so the
+ * offset is fourteen.
+ *
+ * The two rules collide on one number, the lowest note of the T-100
+ * sharing 24 with the tenth position. Notes win there, the note block
+ * being the larger claim; none of his samples uses the number at all.
+ */
+export const CONTROL_OFFSET = {
+    'welte-t100': 14,
+    'welte-licensee': 15
+};
+const DEFAULT_TEMPO = 500000;
+const isNoteOn = (event) => event.type === 'channel' && event.subtype === 'noteOn' && event.velocity > 0;
+const isNoteOff = (event) => event.type === 'channel' && (event.subtype === 'noteOff' || (event.subtype === 'noteOn' && event.velocity === 0));
+/** The events of every track on one clock, since a note may end on another track than it began. */
+const onOneClock = (tracks) => tracks
+    .flatMap(events => {
+    let at = 0;
+    return events.map(event => ({ at: at += event.deltaTime, event }));
+})
+    .sort((a, b) => a.at - b.at);
+const temposIn = (timed) => {
+    const changes = timed.flatMap(({ at, event }) => event.type === 'meta' && event.subtype === 'setTempo'
+        ? [{ at, microsecondsPerBeat: event.microsecondsPerBeat }]
+        : []);
+    return changes.length > 0 && changes[0].at === 0
+        ? changes
+        : [{ at: 0, microsecondsPerBeat: DEFAULT_TEMPO }, ...changes];
+};
+/**
+ * Turns a tick into elapsed seconds, following the tempo changes. His
+ * files carry one tempo, but a file written by hand may carry several.
+ */
+const clockOf = (tempos, ticksPerBeat) => {
+    /** Microseconds elapsed at the start of each tempo, the first being zero. */
+    const elapsedBefore = tempos.map((_, index) => tempos
+        .slice(0, index)
+        .reduce((total, tempo, at) => total + (tempos[at + 1].at - tempo.at) * tempo.microsecondsPerBeat, 0));
+    return (tick) => {
+        const index = Math.max(tempos.findLastIndex(tempo => tempo.at <= tick), 0);
+        const microseconds = elapsedBefore[index] + (tick - tempos[index].at) * tempos[index].microsecondsPerBeat;
+        return seconds(microseconds / ticksPerBeat / 1000000);
+    };
+};
+/** Pairs note-on with the next note-off of the same pitch. */
+const notesIn = (timed) => {
+    const open = new Map();
+    const notes = [];
+    timed.forEach(({ at, event }) => {
+        if (event.type !== 'channel' || !('noteNumber' in event))
+            return;
+        const pitch = event.noteNumber;
+        if (isNoteOn(event)) {
+            open.set(pitch, [...(open.get(pitch) ?? []), at]);
+        }
+        else if (isNoteOff(event)) {
+            const [from, ...rest] = open.get(pitch) ?? [];
+            if (from === undefined)
+                return;
+            open.set(pitch, rest);
+            notes.push({ pitch, from, to: at });
+        }
+    });
+    return notes.sort((a, b) => a.from - b.from || a.pitch - b.pitch);
+};
+/** Paper run at the constant speed the system states, for a bar that states one. */
+const atStatedSpeed = (system) => {
+    const speed = system.paperSpeed;
+    if (!speed) {
+        throw new Error(`Phillips e-roll: the ${system.name} states no paper speed, so pass placeAt to say where the paper had run`);
+    }
+    const perSecond = inMetersPerMinute(speed) * 1000 / 60;
+    return (elapsed) => mm(elapsed * perSecond);
+};
+const controlOffsetOf = (system, given) => {
+    const measured = given ?? CONTROL_OFFSET[system.id];
+    if (measured === undefined) {
+        throw new Error(`Phillips e-roll: no control offset is known for the ${system.name}, so pass controlOffset to say how far above its position an expression number sits`);
+    }
+    return measured;
+};
+/** The position each note of the bar sounds from. */
+const positionsByPitch = (bar) => new Map(Array.from({ length: bar.trackCount }, (_, index) => track(index + 1))
+    .flatMap((position) => {
+    const meaning = bar.meaningOf(position);
+    return meaning?.type === 'note' ? [[meaning.pitch, position]] : [];
+}));
+/**
+ * Reads one of his e-roll files as a copy of the roll, in millimetres
+ * of paper. A position the edition's bar does not read is left out, as
+ * the bar would leave it.
+ */
+export function readFromPhillipsEroll(buffer, { system = welteT100, bar = welteT100, controlOffset, placeAt } = {}) {
+    const file = read(new Uint8Array(buffer));
+    const timed = onOneClock(file.tracks);
+    const elapsedAt = clockOf(temposIn(timed), file.header.ticksPerBeat);
+    const place = placeAt ?? atStatedSpeed(system);
+    const offset = controlOffsetOf(system, controlOffset);
+    const notePositions = positionsByPitch(system);
+    const onBar = translationBetween(system, bar);
+    const positionOf = (number) => notePositions.get(number) ?? track(number - offset);
+    const features = notesIn(timed).flatMap((note) => {
+        const position = onBar(positionOf(note.pitch));
+        if (position === undefined)
+            return [];
+        return [{
+                type: 'Hole',
+                id: v4(),
+                vertical: { from: position, unit: 'track' },
+                horizontal: {
+                    unit: 'mm',
+                    from: place(elapsedAt(note.from)),
+                    to: place(elapsedAt(note.to))
+                }
+            }];
+    });
+    return {
+        type: 'RollCopy',
+        id: v4(),
+        ops: [],
+        conditions: [],
+        keeper: { name: '', sameAs: [] },
+        measurements: {},
+        production: { system: systemOf(system) },
+        modifications: [],
+        features,
+        readFrom: {
+            kind: 'recording',
+            actor: assignObject({ name: 'Phillips, Peter', sameAs: [] }),
+            note: 'Read on Phillips’s pneumatic roll reader. The places are elapsed time put back onto the paper, and a hole runs as long as its switch stayed open, which is longer than the perforation.'
+        }
+    };
+}
+/** The bars his files are known to be numbered by. */
+export const phillipsSystems = [welteT100, welteLicensee];

package/lib/systems/index.js

@@ -1,8 +1,9 @@
 import { systemIdOf } from "../TrackerBar";
 import { welteT100 } from "./welteT100/bar";
 import { welteLicensee } from "./welteLicensee/bar";
+import { welteT98 } from "./welteT98/bar";
 /** The tracker bars the library knows, the T-100 first as the usual one. */
-export const trackerBars = [welteT100, welteLicensee];
+export const trackerBars = [welteT100, welteLicensee, welteT98];
 /** The bar of a system the type vocabulary knows, from its concept. */
 export const trackerBarOf = (system) => {
     const id = systemIdOf(system);

package/lib/systems/welteT98/bar.d.ts

@@ -0,0 +1,31 @@
+import { TrackerBar } from "../../TrackerBar";
+/**
+ * The commands of the Welte-Mignon T-98, as its tracker bar reads them.
+ *
+ * They are not the T-100's. Where the T-100 latches a function on with
+ * one perforation and cancels it with a second, the T-98 holds it for
+ * as long as one continuous perforation lasts (Hagmann, pp. 89 f. and
+ * 100–103; Phillips, p. 121), so none of these is an On or an Off. The
+ * two sforzando valves name the end of the range they pull towards.
+ */
+export declare const welteT98ExpressionTypes: readonly ['SforzandoPiano', 'SforzandoForte', 'Mezzoforte', 'Crescendo', 'SustainPedal', 'SoftPedal'];
+export type WelteT98ExpressionType = typeof welteT98ExpressionTypes[number];
+/**
+ * Welte-Mignon T-98 ("green Welte"), cf. Hagmann, Anhang 11 (p. 179)
+ * and Phillips, p. 121.
+ *
+ * 98 positions at nine to the inch on paper 286 mm wide, five expression
+ * valves on each side and 88 note positions between them, A0 to c⁵ (MIDI
+ * 21 to 108). A roll re-cut from a Mignon master uses only the middle 80
+ * of those, C1 to g⁴, which is the T-100's compass.
+ *
+ * The rewind is not a valve of its own: a long perforation on the bass
+ * sforzando-piano position drives it, which is why that position is
+ * named for the valve and the rewind stated separately.
+ *
+ * Measured against Julian Dyer's scan of the T-98 copy of roll 225
+ * (Grünfeld, Träumerei): 98 columns 2.818 mm apart on paper 285.6 mm
+ * wide, notes on the middle 80 columns, the sustain valve punched 53
+ * times where the T-100 copy latches its sustain on 53 times.
+ */
+export declare const welteT98: TrackerBar;

package/lib/systems/welteT98/bar.js

@@ -0,0 +1,57 @@
+import { describeTrackerBar } from "../../TrackerBar";
+import { mm } from "../../Quantity";
+/**
+ * The commands of the Welte-Mignon T-98, as its tracker bar reads them.
+ *
+ * They are not the T-100's. Where the T-100 latches a function on with
+ * one perforation and cancels it with a second, the T-98 holds it for
+ * as long as one continuous perforation lasts (Hagmann, pp. 89 f. and
+ * 100–103; Phillips, p. 121), so none of these is an On or an Off. The
+ * two sforzando valves name the end of the range they pull towards.
+ */
+export const welteT98ExpressionTypes = [
+    'SforzandoPiano',
+    'SforzandoForte',
+    'Mezzoforte',
+    'Crescendo',
+    'SustainPedal',
+    'SoftPedal'
+];
+/**
+ * Welte-Mignon T-98 ("green Welte"), cf. Hagmann, Anhang 11 (p. 179)
+ * and Phillips, p. 121.
+ *
+ * 98 positions at nine to the inch on paper 286 mm wide, five expression
+ * valves on each side and 88 note positions between them, A0 to c⁵ (MIDI
+ * 21 to 108). A roll re-cut from a Mignon master uses only the middle 80
+ * of those, C1 to g⁴, which is the T-100's compass.
+ *
+ * The rewind is not a valve of its own: a long perforation on the bass
+ * sforzando-piano position drives it, which is why that position is
+ * named for the valve and the rewind stated separately.
+ *
+ * Measured against Julian Dyer's scan of the T-98 copy of roll 225
+ * (Grünfeld, Träumerei): 98 columns 2.818 mm apart on paper 285.6 mm
+ * wide, notes on the middle 80 columns, the sustain valve punched 53
+ * times where the T-100 copy latches its sustain on 53 times.
+ */
+export const welteT98 = describeTrackerBar({
+    id: 'welte-green',
+    name: 'Welte-Mignon T98',
+    width: mm(286),
+    trackCount: 98,
+    notes: { from: 6, to: 93, lowestPitch: 21 },
+    rewindTrack: 1,
+    expressions: new Map([
+        [1, 'SforzandoPiano'],
+        [2, 'Mezzoforte'],
+        [3, 'SustainPedal'],
+        [4, 'Crescendo'],
+        [5, 'SforzandoForte'],
+        [94, 'SforzandoForte'],
+        [95, 'Crescendo'],
+        [96, 'SoftPedal'],
+        [97, 'Mezzoforte'],
+        [98, 'SforzandoPiano']
+    ])
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {