linked-rolls 0.16.0 → 0.18.0

package/lib/Feature.d.ts

@@ -173,7 +173,7 @@ export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedO
      * Nested features do not need to be positioned explicitly.
      * @see crm:P56 bears feature
      */
-    features?: PartialBy<AnyFeature, 'horizontal' | 'vertical'>[];
+    features?: NestedFeature[];
 }
 /**
  * The union of all physical feature types that can appear on a roll:
@@ -181,4 +181,14 @@ export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedO
  * and glued-on patches (paper, tape).
  */
 export type AnyFeature = Hole | Writing | Mark | GluedOn;
+/**
+ * A feature borne by another feature. It states no place of its own,
+ * the feature bearing it standing in one.
+ */
+export type NestedFeature = PartialBy<AnyFeature, 'horizontal' | 'vertical'>;
 export declare const isRollFeature: (obj: object) => obj is AnyFeature;
+export declare const isGluedOn: <T extends NestedFeature>(feature: T) => feature is T & GluedOn;
+/** The features a feature bears: a patch those stated as parts of it, any other feature none. */
+export declare const featuresBorneBy: (feature: NestedFeature) => NestedFeature[];
+/** The feature together with everything it bears, as deep as a patch on a patch goes. */
+export declare const withBorneFeatures: (feature: NestedFeature) => NestedFeature[];

package/lib/Feature.js

@@ -9,3 +9,8 @@ export const writingMethods = ['Print', 'Handwriting', 'Stamp'];
 export const isRollFeature = (obj) => {
     return 'type' in obj && featureTypes.includes(obj.type);
 };
+export const isGluedOn = (feature) => feature.type === 'GluedOn';
+/** The features a feature bears: a patch those stated as parts of it, any other feature none. */
+export const featuresBorneBy = (feature) => isGluedOn(feature) ? feature.features ?? [] : [];
+/** The feature together with everything it bears, as deep as a patch on a patch goes. */
+export const withBorneFeatures = (feature) => [feature, ...featuresBorneBy(feature).flatMap(withBorneFeatures)];

package/lib/editionOps.d.ts

@@ -50,7 +50,12 @@ export declare const addGeneralCondition: (copyId: string, condition: ObjectAssu
 export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
 /** The symbols of the versions that no other copy carries. */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
-/** Takes the features off the copy, and out of the versions with what only they carried. */
+/**
+ * Takes the features off the copy, and out of the versions with what
+ * only they carried. A feature may be named wherever the copy bears it:
+ * a patch goes with everything glued onto it, and a feature of a patch
+ * may be taken back on its own, the patch staying where it is.
+ */
 export declare const removeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
 /**
  * Takes the copy out of the edition together with the symbols only it
@@ -78,6 +83,11 @@ export declare const mergeObstacle: (features: readonly AnyFeature[]) => MergeOb
  * whatever else named them, a modification or a comprehension, names
  * the merged one in their stead.
  *
+ * Only the features the copy bears itself are merged. A feature of a
+ * patch states no place along the roll of its own, so there is nothing
+ * for a merge to span, and an id naming one is passed over as an id the
+ * copy does not bear is.
+ *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
  */

package/lib/editionOps.js

@@ -7,7 +7,7 @@ import { collationToleranceOf, insertedBy } from "./Version";
 import { asSymbols } from "./RollCopy";
 import { applyShift, applyScale, revertShift, revertScale } from "./alignment";
 import { assignReference, idOf } from "./Assumption";
-import { conditions as conditionsAllowed } from "./Feature";
+import { conditions as conditionsAllowed, featuresBorneBy, isGluedOn, withBorneFeatures } from "./Feature";
 import { distance, mm, subtract } from "./Quantity";
 const noChange = () => undefined;
 const onCopy = (copyId, op) => draft => {
@@ -147,7 +147,8 @@ export const stateFeatureCondition = (copyId, featureId, condition) => onFeature
     }
     feature.condition = condition;
 });
-const featureIdsOf = (copy) => new Set(copy.features.map(feature => feature.id));
+/** The ids of every feature the copy bears, those a patch bears among them. */
+const featureIdsOf = (copy) => new Set(copy.features.flatMap(withBorneFeatures).map(feature => feature.id));
 /**
  * A symbol every carrier of which lies among the features loses its
  * evidence with them. A symbol without carriers, such as a label,
@@ -282,11 +283,33 @@ const forgetFeatures = (draft, features) => {
         version.edits = edits[i];
     });
 };
-/** Takes the features off the copy, and out of the versions with what only they carried. */
+/**
+ * The ids of the features named and of everything they bear: a feature
+ * of a patch stands nowhere once the patch is gone.
+ */
+const goneWith = (features, named) => features.flatMap(feature => named.has(feature.id)
+    ? withBorneFeatures(feature).map(borne => borne.id)
+    : goneWith(featuresBorneBy(feature), named));
+/** The feature with the named ones gone from what it bears, or the very same one where it bears none of them. */
+const withoutBorne = (feature, named) => {
+    if (!isGluedOn(feature) || !feature.features)
+        return feature;
+    const borne = withoutFeatures(feature.features, named);
+    return borne === feature.features ? feature : { ...feature, features: borne };
+};
+/** The features without those named, wherever they lie, and without whatever those bore. */
+const withoutFeatures = (features, named) => mapped(without(features, feature => named.has(feature.id)), feature => withoutBorne(feature, named));
+/**
+ * Takes the features off the copy, and out of the versions with what
+ * only they carried. A feature may be named wherever the copy bears it:
+ * a patch goes with everything glued onto it, and a feature of a patch
+ * may be taken back on its own, the patch staying where it is.
+ */
 export const removeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
-    const features = new Set(featureIds);
-    copy.features = without(copy.features, feature => features.has(feature.id));
-    forgetFeatures(draft, features);
+    const named = new Set(featureIds);
+    const features = stateOf(copy.features);
+    copy.features = withoutFeatures(features, named);
+    forgetFeatures(draft, new Set(goneWith(features, named)));
 });
 /**
  * Takes the copy out of the edition together with the symbols only it
@@ -311,10 +334,17 @@ const sayTheSame = (a, b) => {
     keys.delete('id');
     return [...keys].every(key => sayTheSame(a[key], b[key]));
 };
-/** What a feature states beyond its identity, its place along the roll, its depiction and its condition. */
+/**
+ * What a feature states beyond its identity, its place along the roll,
+ * its depiction and its condition. What a patch bears counts by
+ * identity: two patches bear the same only where they bear the very
+ * same features, so that no merge takes a feature of a patch away.
+ */
 const nature = (feature) => {
     const { id, horizontal, depiction, condition, ...rest } = feature;
-    return rest;
+    return isGluedOn(feature) && feature.features
+        ? { ...rest, features: feature.features.map(borne => borne.id) }
+        : rest;
 };
 const conditionsOf = (features) => features.flatMap(feature => feature.condition ? [feature.condition] : []);
 /**
@@ -393,20 +423,25 @@ const carryOver = (draft, replaced, mergedId) => {
  * whatever else named them, a modification or a comprehension, names
  * the merged one in their stead.
  *
+ * Only the features the copy bears itself are merged. A feature of a
+ * patch states no place along the roll of its own, so there is nothing
+ * for a merge to span, and an id naming one is passed over as an id the
+ * copy does not bear is.
+ *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
  */
 export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
-    const replaced = new Set(featureIds);
-    const isReplaced = (feature) => replaced.has(feature.id);
+    const named = new Set(featureIds);
     const features = stateOf(copy.features);
-    const toMerge = features.filter(isReplaced);
+    const toMerge = features.filter(feature => named.has(feature.id));
     const obstacle = mergeObstacle(toMerge);
     if (obstacle) {
         throw new Error(`The features of copy ${copyId} cannot be merged: ${obstacle}`);
     }
+    const replaced = new Set(toMerge.map(feature => feature.id));
     const merged = mergedFrom(toMerge);
-    copy.features = standingFor(features, isReplaced, merged);
+    copy.features = standingFor(features, feature => replaced.has(feature.id), merged);
     carryOver(draft, replaced, merged.id);
     renameReferences(draft, ids => standingFor(ids, id => replaced.has(id), merged.id));
 });

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/lib/schema.json

@@ -626,7 +626,7 @@
                 "features": {
                     "description": "A glued-on feature itself may carry other features. Nested features do not need to be positioned explicitly. [ontology: crm:P56 bears feature]",
                     "items": {
-                        "$ref": "#/definitions/PartialBy%3CAnyFeature%2C(%22horizontal%22%7C%22vertical%22)%3E"
+                        "$ref": "#/definitions/NestedFeature"
                     },
                     "type": "array"
                 },
@@ -1049,6 +1049,10 @@
             ],
             "type": "object"
         },
+        "NestedFeature": {
+            "$ref": "#/definitions/PartialBy%3CAnyFeature%2C(%22horizontal%22%7C%22vertical%22)%3E",
+            "description": "A feature borne by another feature. It states no place of its own, the feature bearing it standing in one."
+        },
         "Note": {
             "description": "A note symbol, representing a single pitched musical event on the roll. The pitch is encoded via the tracker bar position (track number). [ontology: reo:Note]",
             "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.16.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": {