linked-rolls 0.19.1 → 0.21.0

package/lib/migrate.js

@@ -1,6 +1,7 @@
 import { conditions } from "./Feature";
 import { rollConditions } from "./RollCopy";
-import { systemOf } from "./TrackerBar";
+import { systemIdIn, systemOf, translationBetween } from "./TrackerBar";
+import { trackerBars } from "./systems";
 import { welteT100 } from "./systems/welteT100/bar";
 import { versionTypes } from "./Version";
 const versionTypeValues = new Set(versionTypes);
@@ -88,20 +89,93 @@ const walk = (value) => {
         return withWalkedChildren(migrateNode(value));
     return value;
 };
+/** The production of a copy, under whichever of its two names it carries. */
+const productionKeyOf = (copy) => copy?.productionEvent && !copy?.production ? 'productionEvent' : 'production';
+/** The list under the key, or nothing where the document holds something else there. */
+const listAt = (edition, key) => Array.isArray(edition[key]) ? edition[key] : undefined;
+/** A file written while the system belonged to the roll rather than to each version. */
+const namesSystemOnTheRoll = (edition) => edition.roll?.system !== undefined
+    || (listAt(edition, 'versions') ?? []).some((version) => !version?.system);
+const barNamed = (system) => trackerBars.find(bar => bar.id === systemIdIn(system?.['@id']));
+const withSystem = (node, system) => node.system && typeof node.system === 'object' ? node : { ...node, system };
+/** A span on the other bar, or nothing where that bar does not read one of its ends. */
+const spanOnBar = (span, at) => {
+    const from = at(span.from);
+    if (from === undefined)
+        return undefined;
+    if (span.to === undefined)
+        return { ...span, from };
+    const to = at(span.to);
+    return to === undefined ? undefined : { ...span, from, to };
+};
+/** The features on the copy's own bar, those it does not read left out, patches and all. */
+const featuresOnBar = (features, at) => features.flatMap((feature) => {
+    const vertical = feature.vertical?.unit === 'track'
+        ? spanOnBar(feature.vertical, at)
+        : feature.vertical;
+    if (!vertical)
+        return [];
+    return [{
+            ...feature,
+            vertical,
+            ...(Array.isArray(feature.features) && { features: featuresOnBar(feature.features, at) })
+        }];
+});
+/**
+ * A copy cut for another system had its holes put onto the roll's bar
+ * as it was read, so they are numbered in the roll's system and not in
+ * its own. They go back onto the bar the copy names, which is the only
+ * numbering that means anything once each copy is read by its own bar.
+ * Between two Welte scales the difference is two tracks, which is a
+ * legal position a whole tone away rather than a visible error.
+ */
+const onOwnBar = (copy, rollSystem) => {
+    if (!copy || typeof copy !== 'object')
+        return copy;
+    const key = productionKeyOf(copy);
+    const own = copy[key]?.system;
+    const from = barNamed(rollSystem);
+    const to = own && typeof own === 'object' ? barNamed(own) : undefined;
+    if (!from || !to || from.id === to.id || !Array.isArray(copy.features))
+        return copy;
+    return { ...copy, features: featuresOnBar(copy.features, translationBetween(from, to)) };
+};
 /**
- * Every 0.1 edition was read with the T-100 tracker bar, so a roll
- * without a system is a T-100 roll. The text a copy's production
- * gave for the system is kept as the name.
+ * Systems belonged to the roll before they belonged to the versions
+ * and the copies. Every 0.1 edition was read with the T-100 bar, so a
+ * roll that named no system was a T-100 roll, and the text a copy's
+ * production gave for it is kept as the system's name.
  */
-const withRollSystem = (edition) => {
-    if (!edition.roll || edition.roll.system)
+const withSystems = (edition) => {
+    if (!edition.roll || !namesSystemOnTheRoll(edition))
         return edition;
-    const stated = (edition.copies ?? [])
-        .map((copy) => copy.production?.system ?? copy.productionEvent?.system)
+    const versions = listAt(edition, 'versions');
+    const copies = listAt(edition, 'copies');
+    const stated = (copies ?? [])
+        .map((copy) => copy?.[productionKeyOf(copy)]?.system)
         .find((system) => typeof system === 'string' && system !== '');
     const { id, ...concept } = systemOf(welteT100);
-    const system = { '@id': id, ...concept, ...(stated && { name: stated }) };
-    return { ...edition, roll: { ...edition.roll, system } };
+    const system = edition.roll.system ?? { '@id': id, ...concept, ...(stated && { name: stated }) };
+    const { system: _named, ...roll } = edition.roll;
+    const created = roll.recordingEvent?.created;
+    return {
+        ...edition,
+        roll: created
+            ? { ...roll, recordingEvent: { ...roll.recordingEvent, created: withSystem(created, system) } }
+            : roll,
+        ...(versions && {
+            versions: versions.map((version) => withSystem(version, system))
+        }),
+        ...(copies && {
+            copies: copies.map((copy) => {
+                if (!copy || typeof copy !== 'object')
+                    return copy;
+                const key = productionKeyOf(copy);
+                const onOwn = onOwnBar(copy, system);
+                return { ...onOwn, [key]: withSystem(onOwn[key] ?? {}, system) };
+            })
+        })
+    };
 };
 /** An edition written before the editors were carried names none. */
 const withEditors = (edition) => !edition.creation || edition.creation.editors
@@ -126,5 +200,5 @@ const withDerivationTolerance = (edition) => {
             : version)
     };
 };
-const editionSteps = [withRollSystem, withEditors, withDerivationTolerance];
+const editionSteps = [withSystems, withEditors, withDerivationTolerance];
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/readers/phillipsEroll.d.ts

@@ -37,8 +37,6 @@ export interface PhillipsErollOptions {
      * 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.
@@ -47,16 +45,16 @@ export interface PhillipsErollOptions {
     /**
      * 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
+     * the take-up spool; pass `paperAt` of welte-mignon-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.
+ * of paper, on the bar it was cut for and in that bar's numbering. A
+ * position the 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;
+export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, 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

@@ -1,7 +1,7 @@
 import { read } from "midifile-ts";
 import { v4 } from "uuid";
 import { assignObject } from "../Assumption";
-import { systemOf, translationBetween } from "../TrackerBar";
+import { systemOf } from "../TrackerBar";
 import { welteT100 } from "../systems/welteT100/bar";
 import { welteLicensee } from "../systems/welteLicensee/bar";
 import { inMetersPerMinute, mm, seconds, track } from "../Quantity";
@@ -116,21 +116,20 @@ const positionsByPitch = (bar) => new Map(Array.from({ length: bar.trackCount },
 }));
 /**
  * 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.
+ * of paper, on the bar it was cut for and in that bar's numbering. A
+ * position the bar does not read is left out, as the bar would leave it.
  */
-export function readFromPhillipsEroll(buffer, { system = welteT100, bar = welteT100, controlOffset, placeAt } = {}) {
+export function readFromPhillipsEroll(buffer, { system = 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)
+        const position = positionOf(note.pitch);
+        if (!system.meaningOf(position))
             return [];
         return [{
                 type: 'Hole',

package/lib/readers/spencerBar.d.ts

@@ -16,14 +16,13 @@ export interface SpencerBarOptions {
      * the roll it was scanned from. His Welte files are Licensee rolls.
      */
     system?: TrackerBar;
-    /** The edition's bar, onto which the positions are put. */
-    bar?: TrackerBar;
 }
 /**
- * Reads the copy onto the edition's bar. A hole on a position the
- * edition's bar does not read is left out, as the bar would leave it.
+ * Reads the copy on the bar it was cut for, whose numbering it keeps.
+ * A hole on a position that bar does not read is left out, as the bar
+ * would leave it.
  */
-export declare function readFromSpencerBar(buffer: ArrayBuffer, { rowsPerInch, system, bar }?: SpencerBarOptions): RollCopy;
+export declare function readFromSpencerBar(buffer: ArrayBuffer, { rowsPerInch, system }?: SpencerBarOptions): RollCopy;
 /**
  * The `.ann` file beside a `.bar` holds the player's settings for the
  * roll as lines of "/key:   value": title, composer, pianist, roll

package/lib/readers/spencerBar.js

@@ -1,6 +1,5 @@
 import { v4 } from "uuid";
-import { systemOf, translationBetween } from "../TrackerBar";
-import { welteT100 } from "../systems/welteT100/bar";
+import { systemOf } from "../TrackerBar";
 import { welteLicensee } from "../systems/welteLicensee/bar";
 import { feetPerMinute, inMillimeters, px, track } from "../Quantity";
 /**
@@ -80,20 +79,20 @@ const holesOf = (events) => {
     return holes.sort((a, b) => a.from - b.from);
 };
 /**
- * Reads the copy onto the edition's bar. A hole on a position the
- * edition's bar does not read is left out, as the bar would leave it.
+ * Reads the copy on the bar it was cut for, whose numbering it keeps.
+ * A hole on a position that bar does not read is left out, as the bar
+ * would leave it.
  */
-export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH, system = welteLicensee, bar = welteT100 } = {}) {
+export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH, system = welteLicensee } = {}) {
     const bytes = new Uint8Array(buffer);
     if (byteAt(bytes, TEXT_AT) !== TEXT_TAG) {
         throw new Error('Not a Spencer .bar file: no text after the header');
     }
     const placeOf = (row) => inMillimeters(px(row), rowsPerInch);
-    const onBar = translationBetween(system, bar);
     const features = holesOf(eventsIn(bytes, endOfText(bytes, TEXT_AT + 1)))
         .flatMap((hole) => {
-        const position = onBar(track(hole.position));
-        if (position === undefined)
+        const position = track(hole.position);
+        if (!system.meaningOf(position))
             return [];
         return [{
                 type: 'Hole',

package/lib/readers/stanfordAton.d.ts

@@ -8,13 +8,10 @@ export interface StanfordAtonOptions {
      * perforation on the bar's rewind track.
      */
     trackShift?: Track;
-    /** The edition's bar, onto which the holes are put. */
-    bar?: TrackerBar;
     /**
-     * The bar the scanned roll was cut for, where it is not the
-     * edition's. The scan is calibrated on it, and the holes are then
-     * put onto the edition's bar; one on a position that bar does not
-     * read is left out.
+     * The bar the scanned roll was cut for. The scan is calibrated on
+     * it and the holes keep its numbering, since a copy is read by the
+     * bar it was cut for and by no other.
      */
     system?: TrackerBar;
     /**
@@ -24,4 +21,4 @@ export interface StanfordAtonOptions {
      */
     scan?: string;
 }
-export declare function readFromStanfordAton(atonString: string, { trackShift, bar, system, scan }?: StanfordAtonOptions): RollCopy;
+export declare function readFromStanfordAton(atonString: string, { trackShift, system, scan }?: StanfordAtonOptions): RollCopy;

package/lib/readers/stanfordAton.js

@@ -1,6 +1,6 @@
 import { v4 } from "uuid";
 import { AtonParser } from "./AtonParser";
-import { systemOf, translationBetween } from "../TrackerBar";
+import { systemOf } from "../TrackerBar";
 import { welteT100 } from "../systems/welteT100/bar";
 import { inMillimeters, mean, mm, pixelsPerInch, px, subtract, track } from "../Quantity";
 /** Values in these files carry their unit as a suffix, e.g. "37.7646px". */
@@ -110,7 +110,7 @@ const measuredByOf = (rollinfo) => {
         date
     };
 };
-export function readFromStanfordAton(atonString, { trackShift, bar = welteT100, system = bar, scan } = {}) {
+export function readFromStanfordAton(atonString, { trackShift, system = welteT100, scan } = {}) {
     const parser = new AtonParser();
     const json = parser.parse(atonString);
     const holes = json.ROLLINFO.HOLES.HOLE;
@@ -128,11 +128,10 @@ export function readFromStanfordAton(atonString, { trackShift, bar = welteT100,
     };
     const punchDiameter = punchDiameterOf(holes, dpi);
     const chains = chainsAmong([...holes, ...chainedBadHoles(listOf(json.ROLLINFO.BADHOLES?.HOLE), calibration)]);
-    const onBar = translationBetween(system, bar);
     const features = chains
         .flatMap(({ hole, attack, release }) => {
-        const position = onBar(track(+hole.TRACKER_HOLE + shift));
-        if (position === undefined)
+        const position = track(+hole.TRACKER_HOLE + shift);
+        if (!system.meaningOf(position))
             return [];
         const column = readPx(hole.ORIGIN_COL);
         const columnWidth = readPx(hole.WIDTH_COL);

package/lib/reservations.d.ts

@@ -1,5 +1,5 @@
 import { RollCopy } from "./RollCopy";
-export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated'];
+export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown'];
 export type ReservationType = typeof reservationTypes[number];
 /**
  * Something an edition cannot vouch for in one of its copies.

package/lib/reservations.js

@@ -1,12 +1,14 @@
 import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "./FeatureSource";
 import { calibrationOf } from "./RollCopy";
+import { trackerBarOf } from "./systems";
 export const reservationTypes = [
     'source-not-stated',
     'source-undocumented',
     'features-interpreted',
     'no-physical-evidence',
     'measurement-undocumented',
-    'not-calibrated'
+    'not-calibrated',
+    'system-unknown'
 ];
 const sourceStated = copy => copy.readFrom ? undefined : {
     type: 'source-not-stated',
@@ -37,13 +39,33 @@ const calibrated = copy => calibrationOf(copy) ? undefined : {
     type: 'not-calibrated',
     note: 'The copy is not calibrated against the tracker bar, so its track positions rest on the numbering its source used.'
 };
+/**
+ * The bar decides what every track on the copy means, so a copy the
+ * edition cannot place in a system is read by the T-100 for want of
+ * anything better. Between two Welte scales that is a semitone rather
+ * than a visible error, which is why it is said out loud.
+ */
+const systemKnown = copy => {
+    const system = copy.production?.system;
+    if (system === undefined) {
+        return {
+            type: 'system-unknown',
+            note: 'The copy names no reproducing system, so it is read by the T-100 tracker bar.'
+        };
+    }
+    return trackerBarOf(system) ? undefined : {
+        type: 'system-unknown',
+        note: `The copy names ${system.name || 'a reproducing system'}, which the edition has no tracker bar for, so it is read by the T-100's.`
+    };
+};
 const checks = [
     sourceStated,
     sourceDocumented,
     featuresMeasured,
     physicalEvidence,
     measurementDocumented,
-    calibrated
+    calibrated,
+    systemKnown
 ];
 /**
  * What the edition cannot vouch for in a copy, in the order the

package/lib/schema.json

@@ -1802,15 +1802,10 @@
                 "recordingEvent": {
                     "$ref": "#/definitions/RecordingEvent",
                     "description": "[ontology: lrmoo:R19i was realised through]"
-                },
-                "system": {
-                    "$ref": "#/definitions/Concept",
-                    "description": "The reproducing system the roll was cut for. A system the type vocabulary knows carries the IRI of its concept as `id`, from which the export takes the system's own context, so that the expression types are read as that system's. [ontology: crm:P2 has type]"
                 }
             },
             "required": [
                 "catalogueNumber",
-                "system",
                 "recordingEvent"
             ],
             "type": "object"
@@ -2089,6 +2084,10 @@
                     "$ref": "#/definitions/Derivation",
                     "description": "If no derivation is defined, it is assumed that this version represents the mother roll. [ontology: lrmoo:R76 is derivative of]"
                 },
+                "creation": {
+                    "$ref": "#/definitions/VersionCreation",
+                    "description": "The act that made this version, where it is known: who carried it out, when, and by what rule. [ontology: lrmoo:R17i was created by]"
+                },
                 "edits": {
                     "description": "The list of edits that, applied to the base version, produce this version. [ontology: reo:involvedEdit]",
                     "items": {
@@ -2107,6 +2106,10 @@
                     "description": "A short siglum to identify the version, e.g. \"A\", \"B1\", \"B2_rev\", etc. [ontology: reo:siglum]",
                     "type": "string"
                 },
+                "system": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The reproducing system this version is coded for. One roll was often issued for several of them, and a version is a reading in one system's words: its expression types are that system's vocabulary and its notes sit on that bar's positions. A system the type vocabulary knows carries the IRI of its concept as `id`, from which the export takes the system's own context. [ontology: crm:P2 has type]"
+                },
                 "versionType": {
                     "$ref": "#/definitions/VersionType",
                     "description": "Whether the version served as a master for reproductions or exists on one copy only. [ontology: crm:P2 has type]"
@@ -2127,11 +2130,30 @@
                 "@id",
                 "motivations",
                 "siglum",
+                "system",
                 "@type",
                 "versionType"
             ],
             "type": "object"
         },
+        "VersionCreation": {
+            "description": "How a version was made, where that is known and worth stating.\n\nA roll issued for another system was re-punched by an editor of the publisher's, and that was an editorial act rather than a conversion: Lawson names Kähle as the man who corrected second masters for the green system. The rule he worked by is the procedure named here, and the version's edits carry it out, so the mechanical part of a transfer is stated once instead of being spelled out per note. [ontology: lrmoo:F28 Expression Creation]",
+            "properties": {
+                "actor": {
+                    "$ref": "#/definitions/ActorAssignment",
+                    "description": "Who carried the act out. An `ObjectAssumption`, so an attribution can carry the belief it rests on and the reasons for it. [ontology: crm:P14 carried out by]"
+                },
+                "date": {
+                    "$ref": "#/definitions/DateAssignment",
+                    "description": "When it took place. [ontology: dcterms:date]"
+                },
+                "procedure": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The rule followed, as a term of the vocabulary: the notes stand at their pitch, the expression is re-spelled in the other system's words. [ontology: crm:P33 used specific technique]"
+                }
+            },
+            "type": "object"
+        },
         "VersionType": {
             "description": "The type of a version. An 'edition' version may serve as the master for several roll copies; a 'unicum' version exists only on one specific copy.",
             "enum": [

package/lib/spec/context.json

@@ -76,6 +76,7 @@
             "@type": "@id"
         },
         "creation": "lrmoo:R17i_was_created_by",
+        "procedure": "crm:P33_used_specific_technique",
         "editors": "crm:P14_carried_out_by",
         "publisher": "crm:P14_carried_out_by",
         "publicationDate": {

package/lib/spec/welte-licensee.context.json

@@ -0,0 +1,10 @@
+{
+    "@context": {
+        "@version": 1.1,
+        "expressionType": {
+            "@id": "http://www.cidoc-crm.org/cidoc-crm/P2_has_type",
+            "@type": "@vocab",
+            "@context": { "@vocab": "https://w3id.org/reo/type/welte-t100/" }
+        }
+    }
+}

package/lib/spec/welte-t98.context.json

@@ -0,0 +1,10 @@
+{
+    "@context": {
+        "@version": 1.1,
+        "expressionType": {
+            "@id": "http://www.cidoc-crm.org/cidoc-crm/P2_has_type",
+            "@type": "@vocab",
+            "@context": { "@vocab": "https://w3id.org/reo/type/welte-green/" }
+        }
+    }
+}

package/lib/substitution.d.ts

@@ -0,0 +1,73 @@
+import { CollationTolerance, Locate } from "./Collation";
+import { AnySymbol, Expression } from "./Symbol";
+import { Millimeters, Track } from "./Quantity";
+import { TrackerBar } from "./TrackerBar";
+/**
+ * How a scale spells a command: as a perforation that turns a function
+ * on, one that cancels it, or one that holds it for as long as it lasts.
+ */
+export type Spelling = 'on' | 'off' | 'held';
+/**
+ * A command as what it operates rather than as the word a scale uses
+ * for it, so that two scales can be compared at all.
+ */
+export interface Command {
+    /** The function operated, named the same wherever a scale has it. */
+    operates: string;
+    spelling: Spelling;
+    /**
+     * Whether the half of the keyboard the valve serves is part of the
+     * command. The dynamics are per half; the pedals are not, and the
+     * two Welte scales put them on opposite edges of the paper, so a
+     * rule that compared sides would leave every pedal unpaired.
+     */
+    sided: boolean;
+}
+/** What a command operates, or nothing for a word no scale here knows. */
+export declare const commandOf: (expressionType: string) => Command | undefined;
+/**
+ * A latched function of the older version and the held perforation of
+ * the newer one that stands for it.
+ */
+export interface Substitution {
+    /** The perforation that turned the function on, and the one that cancelled it. */
+    replaced: readonly [Expression, Expression];
+    /**
+     * The perforations that say the same thing in the other scale's
+     * words. Usually one, but a held command is punched as a chain of
+     * round holes with paper bridges rather than as a slot, and a scan
+     * whose analysis reports those singly gives one symbol per punch.
+     */
+    by: readonly Expression[];
+}
+/**
+ * How wide a paper bridge may be for two held perforations to be one
+ * command. The T-98 punches a hold as a chain of round holes on a
+ * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
+ * by hole shows a run where the paper shows one command.
+ */
+export declare const defaultChainGap: import("./Quantity").Quantity<"mm">;
+/**
+ * The position a bar reads its own command for the same function on,
+ * where it has no word for this one.
+ *
+ * A version keeps the perforations it does away with in its deletions,
+ * and those may be a scale the version is not coded for: a green
+ * version deletes the red `SlowCrescendoOn` it inherits. That has no
+ * position on the green bar, so drawing it as a perforation is out of
+ * the question, but an edit still has to be shown somewhere, and the
+ * lane the green scale gives the same function is where it belongs.
+ */
+export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expression) => Track | undefined;
+/**
+ * Where a held perforation of the newer version stands for a latched
+ * function of the older one: the same function, on the same side where
+ * the side counts, spanning the same stretch of the roll.
+ *
+ * Only unambiguous correspondences are reported. Where two held
+ * perforations answer one latched interval, or one answers two, none of
+ * them is reported and the editor is left to say what happened. Nothing
+ * is invented either: both sides are perforations somebody punched, and
+ * all this asserts is which stands for which.
+ */
+export declare const substitutionsBetween: (own: readonly AnySymbol[], inherited: readonly AnySymbol[], locate: Locate, tolerance?: CollationTolerance, chainGap?: Millimeters) => Substitution[];