linked-rolls 0.17.0 → 0.18.0

package/lib/index.d.ts

@@ -29,4 +29,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

@@ -29,4 +29,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/package.json

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