linked-rolls 0.6.0 → 0.8.0

package/README.md

@@ -47,9 +47,11 @@ The first system is the red Welte, `linked-rolls/welte-t100`, built on
 [welte-t100-emulator](https://github.com/pfefferniels/welte-t100): the
 take-up spool sets the time axis, the Nuancierbälge fill through their
 conduits and are arrested by the Mezzoforte pin, and the two pedals travel
-rather than switch. The constants are those fitted against the hand-drawn
-nuance lines of roll 3309, with the terms that describe the drawing
-apparatus switched off. The pedals leave no drawn line, so their constants
+rather than switch. The nuancing constants come as `instruments`: the
+consensus fitted across the hand-drawn nuance lines of six rolls, which
+is the default, and the setting that drew each of those rolls, named by
+its Welte number, all with the terms that describe the drawing apparatus
+switched off. The pedals leave no drawn line, so their constants
 come as two readings, `pedalPresets.damping`, under which every lift the
 rolls punch damps, and `pedalPresets.brushing`, under which the quick runs
 of latch changes brush the strings without damping. What the emulator does

package/lib/Agent.d.ts

@@ -16,11 +16,17 @@ export interface Named {
      */
     sameAs: string[];
 }
-export declare const agentRoles: readonly ["pianist", "editor", "publisher"];
+export declare const editorialRoles: readonly ["editor", "transcription", "collation", "encoding", "commentary", "proofreading"];
+/**
+ * The part an editor took in the editorial work.
+ */
+export type EditorialRole = typeof editorialRoles[number];
+declare const nonEditorialRoles: readonly ["pianist", "publisher"];
 /**
  * The role an agent plays in the context of the edition.
  */
-export type AgentRole = typeof agentRoles[number];
+export type AgentRole = EditorialRole | typeof nonEditorialRoles[number];
+export declare const agentRoles: readonly AgentRole[];
 /**
  * A person or a group: a pianist, an editor, a publisher,
  * a manufacturer, a library.
@@ -37,6 +43,16 @@ export interface Agent extends Named, Partial<WithId> {
  * An agent that is a person.
  */
 export type Person = Agent;
+/**
+ * A person who took part in preparing the edition.
+ */
+export interface Editor extends Person {
+    /**
+     * The part this person took in the editorial work.
+     * @see crm:P2 has type
+     */
+    role: EditorialRole;
+}
 export type WithActor = {
     /**
      * The person who carried out this activity.
@@ -57,3 +73,4 @@ export interface Place extends Named {
  */
 export interface Concept extends Named, Partial<WithId> {
 }
+export {};

package/lib/Agent.js

@@ -1 +1,10 @@
-export const agentRoles = ['pianist', 'editor', 'publisher'];
+export const editorialRoles = [
+    'editor',
+    'transcription',
+    'collation',
+    'encoding',
+    'commentary',
+    'proofreading'
+];
+const nonEditorialRoles = ['pianist', 'publisher'];
+export const agentRoles = [...nonEditorialRoles, ...editorialRoles];

package/lib/Edition.d.ts

@@ -2,7 +2,7 @@ import { RollCopy } from "./RollCopy";
 import { Version } from "./Version";
 import { CollationTolerance } from "./Collation";
 import { DateAssignment, ObjectAssumption } from "./Assumption";
-import { Concept, Person, Place } from "./Agent";
+import { Concept, Editor, Person, Place } from "./Agent";
 import { RollTempo } from "./ReproducingSystem";
 /**
  * This type describes the creation of an edition,
@@ -10,6 +10,13 @@ import { RollTempo } from "./ReproducingSystem";
  * @see lrmoo:F28 Expression Creation
  */
 export interface EditionCreation {
+    /**
+     * The persons who prepared the edition, each with the part
+     * they took in the editorial work. An edition written before
+     * this field existed carries none.
+     * @see crm:P14 carried out by
+     */
+    editors?: Editor[];
     /**
      * The person or institution responsible for publishing the edition.
      * @see crm:P14 carried out by

package/lib/migrate.js

@@ -75,4 +75,8 @@ const withRollSystem = (edition) => {
     const system = { '@id': id, ...concept, ...(stated && { name: stated }) };
     return { ...edition, roll: { ...edition.roll, system } };
 };
-export const migrate = (edition) => walk(withRollSystem(edition));
+/** An edition written before the editors were carried names none. */
+const withEditors = (edition) => !edition.creation || edition.creation.editors
+    ? edition
+    : { ...edition, creation: { ...edition.creation, editors: [] } };
+export const migrate = (edition) => walk(withRollSystem(withEditors(edition)));

package/lib/schema.json

@@ -39,13 +39,20 @@
             "type": "object"
         },
         "AgentRole": {
-            "description": "The role an agent plays in the context of the edition.",
-            "enum": [
-                "pianist",
-                "editor",
-                "publisher"
+            "anyOf": [
+                {
+                    "$ref": "#/definitions/EditorialRole"
+                },
+                {
+                    "const": "pianist",
+                    "type": "string"
+                },
+                {
+                    "const": "publisher",
+                    "type": "string"
+                }
             ],
-            "type": "string"
+            "description": "The role an agent plays in the context of the edition."
         },
         "AnyArgumentation": {
             "anyOf": [
@@ -406,6 +413,13 @@
                     "$ref": "#/definitions/CollationTolerance",
                     "description": "The tolerance parameters used when collating (aligning) the different roll copies for this edition. Not exported to RDF."
                 },
+                "editors": {
+                    "description": "The persons who prepared the edition, each with the part they took in the editorial work. An edition written before this field existed carries none. [ontology: crm:P14 carried out by]",
+                    "items": {
+                        "$ref": "#/definitions/Editor"
+                    },
+                    "type": "array"
+                },
                 "publicationDate": {
                     "description": "The date on which the edition was published. [ontology: dcterms:date]",
                     "format": "date",
@@ -422,6 +436,51 @@
             ],
             "type": "object"
         },
+        "Editor": {
+            "description": "A person who took part in preparing the edition.",
+            "properties": {
+                "name": {
+                    "description": "The name, e.g. \"Grünfeld, Alfred\", \"Wien\", \"M. Welte & Söhne\". [ontology: rdfs:label]",
+                    "type": "string"
+                },
+                "role": {
+                    "$ref": "#/definitions/EditorialRole",
+                    "description": "The part this person took in the editorial work. [ontology: crm:P2 has type]"
+                },
+                "sameAs": {
+                    "description": "Authority records for the same thing: GND, Wikidata, geonames or similar. [ontology: owl:sameAs]",
+                    "examples": [
+                        "https://d-nb.info/gnd/116888652"
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
+                "@id": {
+                    "description": "A unique identifier for this object.",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "name",
+                "role",
+                "sameAs"
+            ],
+            "type": "object"
+        },
+        "EditorialRole": {
+            "description": "The part an editor took in the editorial work.",
+            "enum": [
+                "editor",
+                "transcription",
+                "collation",
+                "encoding",
+                "commentary",
+                "proofreading"
+            ],
+            "type": "string"
+        },
         "Expression": {
             "description": "An expression symbol, representing a perforation on the roll that governs dynamics, pedaling, or mechanical functions of the reproducing piano. Each expression has a scope (bass or treble) and a specific expression type. [ontology: reo:Expression]",
             "properties": {

package/lib/spec/context.json

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

package/lib/systems/welteT100/system.d.ts

@@ -1,4 +1,4 @@
-import { Half, Parameters, PedalMode, Spool } from "welte-t100-emulator";
+import { Half, Instrument, Parameters, PedalMode, RollNumber, Spool } from "welte-t100-emulator";
 import { ReproducingSystem } from "../../ReproducingSystem";
 /**
  * MIDI velocity at the open rail of the Nuancierbalg, at the Mezzoforte pin,
@@ -12,6 +12,21 @@ export type VelocityMap = {
     mezzoforte: number;
     forte: number;
 };
+export type { Instrument } from "welte-t100-emulator";
+export type InstrumentName = 'consensus' | RollNumber;
+/**
+ * The instruments the emulator was fitted as: the consensus over the six
+ * rolls with drawn nuance lines, and the setting that drew each of them,
+ * named by the roll's Welte number. The provenance beside each says what
+ * it was fitted to and how well.
+ */
+export declare const instruments: Readonly<Record<InstrumentName, Instrument>>;
+/** The instruments by name, the consensus first. */
+export declare const instrumentNames: readonly InstrumentName[];
+/** The nuancing constants of an instrument, one set for each half of the keyboard. */
+export declare const nuanceOf: (instrument: Instrument) => Record<Half, Parameters>;
+/** The instrument a pair of nuancing constants belongs to, if it is one. */
+export declare const instrumentNameOf: (nuance: Record<Half, Parameters>) => InstrumentName | undefined;
 /**
  * The two readings of the pedal mechanism the emulator offers, by name.
  * Under `damping` the dampers reach the strings within the shortest lift
@@ -33,7 +48,7 @@ export type WelteT100Options = {
      * rate of revolution, so the paper runs faster as the spool fills.
      */
     spool: Spool;
-    /** Constants of the nuancing mechanism, one set for each half of the keyboard. */
+    /** Constants of the nuancing mechanism, one set for each half of the keyboard: `nuanceOf` an instrument, or a set of one's own. */
     nuance: Record<Half, Parameters>;
     /** Constants of the two pedal actions, one of `pedalPresets` or a set of one's own. */
     pedals: Parameters;
@@ -63,8 +78,8 @@ export declare const secondsAt: (spool: Spool, mm: number) => number;
  * The red Welte, as welte-t100-emulator models it: the take-up spool sets
  * the time axis, the Nuancierbälge fill through their conduits and are
  * arrested by the Mezzoforte pin, and the two pedals travel rather than
- * switch. The constants are those fitted against the hand-drawn nuance
- * lines of roll 3309, with the terms that describe the drawing apparatus
- * switched off.
+ * switch. The constants are the consensus fitted across the hand-drawn
+ * nuance lines of six rolls, with the terms that describe the drawing
+ * apparatus switched off; `instruments` offers each roll's own setting.
  */
 export declare const welteT100System: ReproducingSystem<WelteT100Options>;

package/lib/systems/welteT100/system.js

@@ -1,5 +1,20 @@
-import { aperturePorts, DEFAULT_PUNCH_MM, geometryInMm, Grid, levelChanges, mezzoforteTravel, paperSeconds, pedalBrushing, pedalDefaults, playbackParameters, pneumaticModel, ROWS_PER_MM, runPedals, TRACKER_BORE_MM, travelBetweenRails, WELTE_SPOOL, } from "welte-t100-emulator";
+import { aperturePorts, CONSENSUS, DEFAULT_PUNCH_MM, geometryInMm, Grid, levelChanges, mezzoforteTravel, paperSeconds, pedalBrushing, pedalDefaults, pneumaticModel, PRESETS, ROWS_PER_MM, runPedals, TRACKER_BORE_MM, travelBetweenRails, WELTE_SPOOL, } from "welte-t100-emulator";
 import { welteT100 } from "./bar";
+/**
+ * The instruments the emulator was fitted as: the consensus over the six
+ * rolls with drawn nuance lines, and the setting that drew each of them,
+ * named by the roll's Welte number. The provenance beside each says what
+ * it was fitted to and how well.
+ */
+export const instruments = { consensus: CONSENSUS, ...PRESETS };
+/** The instruments by name, the consensus first. */
+export const instrumentNames = ['consensus', ...Object.keys(PRESETS)];
+const sameParameters = (a, b) => Object.keys(a).length === Object.keys(b).length
+    && Object.entries(a).every(([name, value]) => b[name] === value);
+/** The nuancing constants of an instrument, one set for each half of the keyboard. */
+export const nuanceOf = (instrument) => ({ bass: instrument.bass, treble: instrument.treble });
+/** The instrument a pair of nuancing constants belongs to, if it is one. */
+export const instrumentNameOf = (nuance) => instrumentNames.find(name => sameParameters(instruments[name].bass, nuance.bass) && sameParameters(instruments[name].treble, nuance.treble));
 /**
  * The two readings of the pedal mechanism the emulator offers, by name.
  * Under `damping` the dampers reach the strings within the shortest lift
@@ -12,16 +27,11 @@ export const pedalPresets = {
     damping: pedalDefaults,
     brushing: pedalBrushing
 };
-const sameParameters = (a, b) => Object.keys(a).length === Object.keys(b).length
-    && Object.entries(a).every(([name, value]) => b[name] === value);
 /** The preset a set of pedal constants is, if it is one. */
 export const pedalPresetOf = (pedals) => Object.keys(pedalPresets).find(name => sameParameters(pedalPresets[name], pedals));
 export const defaultWelteT100Options = {
     spool: WELTE_SPOOL,
-    nuance: {
-        bass: playbackParameters('bass'),
-        treble: playbackParameters('treble')
-    },
+    nuance: nuanceOf(instruments.consensus),
     pedals: pedalPresets.damping,
     velocity: { piano: 35, mezzoforte: 60, forte: 90 },
     pedalMode: 'continuous',
@@ -188,9 +198,9 @@ const perform = (events, options, roll) => {
  * The red Welte, as welte-t100-emulator models it: the take-up spool sets
  * the time axis, the Nuancierbälge fill through their conduits and are
  * arrested by the Mezzoforte pin, and the two pedals travel rather than
- * switch. The constants are those fitted against the hand-drawn nuance
- * lines of roll 3309, with the terms that describe the drawing apparatus
- * switched off.
+ * switch. The constants are the consensus fitted across the hand-drawn
+ * nuance lines of six rolls, with the terms that describe the drawing
+ * apparatus switched off; `instruments` offers each roll's own setting.
  */
 export const welteT100System = {
     name: 'Welte-Mignon T100',

package/package.json

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