linked-rolls 0.0.1 → 0.1.0

package/lib/spec/context.json

@@ -1,192 +1,173 @@
 {
     "@context": {
-        "crm": "http://www.cidoc-crm.org/cidoc-crm/",
-        "lrmoo": "http://iflastandards.info/ns/lrm/lrmoo/",
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
         "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
         "owl": "http://www.w3.org/2002/07/owl#",
+        "dcterms": "http://purl.org/dc/terms/",
+        "crm": "http://www.cidoc-crm.org/cidoc-crm/",
+        "crmdig": "http://www.ics.forth.gr/isl/CRMdig/",
+        "crminf": "http://www.cidoc-crm.org/cidoc-crm/CRMinf/",
+        "lrmoo": "http://iflastandards.info/ns/lrm/lrmoo/",
         "reo": "http://linked-rolls.org/reo/",
         "@vocab": "http://linked-rolls.org/reo/",
-        "C11_Derivation": {
-            "@id": "reo:C11_Derivation",
-            "@context": {
-                "original": {
-                    "@id": "reo:P10_used",
-                    "@type": "@id"
-                }
-            }
+        "Edition": "lrmoo:F2_Expression",
+        "RollCopy": "reo:C1_Witness",
+        "Addition": "crm:E79_Part_Addition",
+        "Removal": "crm:E80_Part_Removal",
+        "title": "crm:P102_has_title",
+        "license": {
+            "@id": "dcterms:license",
+            "@type": "@id"
         },
-        "C12_Version": {
-            "@id": "reo:C12_Version",
-            "@context": {
-                "siglum": {
-                    "@id": "reo:P22_is_identified_by",
-                    "@type": "xsd:string"
-                },
-                "witnesses": {
-                    "@id": "reo:P2i_is_witnessed_by",
-                    "@type": "@id"
-                }
-            }
+        "name": "rdfs:label",
+        "sameAs": {
+            "@id": "owl:sameAs",
+            "@type": "@id"
         },
-        "C13_Version_Creation": {
-            "@id": "reo:C13_Version_Creation",
-            "@context": {
-                "created": {
-                    "@id": "reo:P15_created_version",
-                    "@type": "reo:C12_Version"
-                },
-                "basedOn": {
-                    "@id": "reo:P10i_is_based_on",
-                    "@type": "reo:C11_Derivation"
-                },
-                "edits": {
-                    "@id": "reo:P16_involved_edit",
-                    "@type": "reo:C8_Edit"
-                },
-                "intentions": {
-                    "@id": "reo:P18_was_motivated_by",
-                    "@type": "reo:C9_Assumed_Intention"
-                }
-            }
+        "role": "crm:P2_has_type",
+        "date": "crm:P4_has_time-span",
+        "actor": "crm:P14_carried_out_by",
+        "description": "crm:P3_has_note",
+        "depiction": {
+            "@id": "crm:P62i_is_depicted_by",
+            "@type": "@id"
         },
-        "C9_Assument_Intention": {
-            "@id": "reo:C9_Assumed_Intention",
+        "horizontal": "crm:P43_has_dimension",
+        "vertical": "crm:P43_has_dimension",
+        "unit": "crm:P91_has_unit",
+        "scan": {
+            "@id": "crm:P138i_has_representation",
+            "@type": "@id"
+        },
+        "carriers": {
+            "@id": "crm:P128i_is_carried_by",
+            "@type": "@id"
+        },
+        "pitch": "reo:P5_has_pitch",
+        "scope": "reo:P6_has_scope",
+        "expressionType": "crm:P2_has_type",
+        "alignedWith": "reo:P3_aligned_with",
+        "material": "crm:P45_consists_of",
+        "condition": "crm:P44_has_condition",
+        "creation": {
+            "@id": "lrmoo:R17i_was_created_by",
             "@context": {
-                "description": {
-                    "@id": "reo:P23_has_description",
-                    "@type": "xsd:string"
+                "publisher": "crm:P14_carried_out_by",
+                "publicationDate": {
+                    "@id": "crm:P4_has_time-span",
+                    "@type": "xsd:date"
                 },
-                "belief": {
-                    "@id": "crminf:J4i_is_subject_to",
-                    "@type": "crminf:I2_Belief"
-                }
+                "collationTolerance": "crmdig:L13_used_parameters"
             }
         },
-        "crminf:I2_Belief": {
-            "@id": "crminf:I2_Belief",
+        "roll": {
+            "@id": "lrmoo:R3i_realises",
             "@context": {
-                "certainty": {
-                    "@id": "crminf:J5_holds_to_be",
-                    "@type": "xsd:string"
-                },
-                "reasons": {
-                    "@id": "crminf:J2i_was_concluded_by",
-                    "@type": "crminf:Argumentation"
+                "catalogueNumber": "crm:P1_is_identified_by",
+                "recordingEvent": {
+                    "@id": "lrmoo:R19i_was_realised_through",
+                    "@context": {
+                        "recorded": {
+                            "@id": "lrmoo:R81_recorded",
+                            "@context": {
+                                "pianist": "crm:P14_carried_out_by",
+                                "playing": {
+                                    "@type": "@id"
+                                }
+                            }
+                        },
+                        "place": "crm:P7_took_place_at",
+                        "created": "lrmoo:R17_created"
+                    }
                 }
             }
         },
-        "C1_Witness": {
+        "copies": {
+            "@id": "lrmoo:R2_is_derivative_of",
             "@context": {
-                "@base": "copy/",
-                "siglum": {
-                    "@id": "reo:P21_is_identified_by",
-                    "@type": "xsd:string"
-                },
-                "productionEvent": {
+                "location": "crm:P55_has_current_location",
+                "production": {
                     "@id": "lrmoo:R28i_was_produced_by",
-                    "@type": "lrmoo:F33_Reproduction_Event",
                     "@context": {
-                        "date": {
-                            "@id": "crm:P4_has_time-span",
-                            "@type": "xsd:dateTime"
-                        },
-                        "paper": {
-                            "@id": "crm:P126_employed",
-                            "@type": "@id"
-                        },
-                        "company": {
-                            "@id": "crm:P14_was_carried_out_by",
-                            "@type": "@id"
-                        }
+                        "company": "crm:P14_carried_out_by",
+                        "paper": "crm:P126_employed"
                     }
                 },
-                "location": {
-                    "@id": "crm:P53_has_current_or_former_location",
-                    "@type": "xsd:string"
+                "conditions": "crm:P44_has_condition",
+                "modifications": {
+                    "@id": "crm:P31i_was_modified_by",
+                    "@context": {
+                        "added": "crm:P111_added",
+                        "removed": "crm:P113_removed",
+                        "purpose": "crm:P21_had_general_purpose"
+                    }
                 },
                 "measurements": {
                     "@id": "crm:P39i_was_measured_by",
-                    "@type": "reo:RollMeasurement",
                     "@context": {
-                        "date": {
-                            "@id": "crm:P4_has_time-span",
-                            "@type": "xsd:dateTime"
-                        },
-                        "software": {
-                            "@id": "crmdig:L23_used_software_or_firmware",
-                            "@type": "@id"
+                        "measuredBy": {
+                            "@context": {
+                                "software": "crmdig:L23_used_software_or_firmware"
+                            }
                         }
                     }
                 },
-                "events": {
-                    "@id": "crm:P128_carries",
+                "features": {
+                    "@id": "crm:P56_bears_feature",
                     "@context": {
-                        "measurement": {
-                            "@id": "crmdig:L20i_was_created_by",
-                            "@type": "@id"
-                        },
-                        "annotates": {
-                            "@id": "crm:P62i_is_depicted_by",
-                            "@type": "@id"
-                        },
-                        "horizontal": {
-                            "@id": "crm:P43_has_dimension",
-                            "@type": "reo:C5_Event_Span"
-                        },
-                        "vertical": {
-                            "@id": "crm:P43_has_dimension",
-                            "@type": "reo:C5_Event_Span"
-                        }
+                        "method": "crm:P2_has_type",
+                        "transcription": "crm:P128_carries",
+                        "pattern": "crm:P2_has_type",
+                        "features": "crm:P56_bears_feature"
                     }
                 }
             }
         },
-        "stamp": {
-            "@type": "reo:C7_Stamp",
+        "versions": {
+            "@id": "lrmoo:R76_is_derivative_of",
             "@context": {
-                "text": {
-                    "@id": "reo:has_text"
+                "siglum": "reo:P22_is_identified_by",
+                "basedOn": {
+                    "@id": "reo:P10i_is_based_on",
+                    "@type": "@id"
+                },
+                "motivations": "@included",
+                "edits": {
+                    "@id": "reo:P16_involved_edit",
+                    "@context": {
+                        "editType": "crm:P2_has_type",
+                        "motivation": {
+                            "@id": "crm:P17_was_motivated_by",
+                            "@type": "@id"
+                        },
+                        "insert": "reo:P7_added",
+                        "delete": {
+                            "@id": "reo:P8_removed",
+                            "@type": "@id"
+                        }
+                    }
                 }
             }
         },
-        "publicationEvent": {
-            "@id": "lrmoo:R17i_was_created_by",
-            "@type": "lrmoo:F28_Expression_Creation",
+        "belief": {
+            "@id": "crminf:J4i_is_subject_to",
             "@context": {
-                "publicationDate": {
-                    "@id": "crm:P4_has_time-span",
-                    "@type": "xsd:dateTime"
-                },
-                "publisher": {
-                    "@id": "crm:P14_carried_out_by",
-                    "@type": "crm:E21_Person",
+                "belief": "crminf:I2_Belief",
+                "certainty": "crminf:J5_holds_to_be",
+                "reasons": {
+                    "@id": "crminf:J2i_was_concluded_by",
                     "@context": {
-                        "name": {
-                            "@id": "rdfs:label",
-                            "@type": "xsd:string"
+                        "comprehends": {
+                            "@id": "crminf:J22_interpreted_meaning_of",
+                            "@type": "@id"
                         },
-                        "sameAs": {
-                            "@id": "owl:sameAs",
+                        "premises": {
+                            "@id": "crminf:J1_used_as_premise",
                             "@type": "@id"
                         }
                     }
                 }
             }
-        },
-        "title": "crm:P102_has_title",
-        "license": {
-            "@id": "crm:P104_is_subject_to",
-            "@type": "@id"
-        },
-        "copies": {
-            "@id": "lrmoo:R2_is_derivative_of",
-            "@type": "reo:C1_Witness"
-        },
-        "collation": "crm:P9_consists_of",
-        "versions": {
-            "@id": "crm:P9_consists_of",
-            "@type": "reo:C13_Version_Creation"
-        },
-        "questions": "crm:P9_consists_of"
+        }
     }
 }

package/lib/systems/welteT100.d.ts

@@ -0,0 +1,55 @@
+import { Half, Parameters, PedalMode, Spool } from "welte-t100-emulator";
+import { ReproducingSystem } from "../ReproducingSystem";
+/**
+ * MIDI velocity at the open rail of the Nuancierbalg, at the Mezzoforte pin,
+ * and at the closed rail, joined linearly in between. Nothing in the
+ * mechanism determines how bellows travel maps onto hammer velocity, so
+ * these are anchors rather than measurements; the three values are the
+ * ones midi2exp publishes.
+ */
+export type VelocityMap = {
+    piano: number;
+    mezzoforte: number;
+    forte: number;
+};
+export type WelteT100Options = {
+    /**
+     * The take-up spool, which sets the time axis: it is held at a constant
+     * 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. */
+    nuance: Record<Half, Parameters>;
+    /** Constants of the two pedal actions. */
+    pedals: Parameters;
+    velocity: VelocityMap;
+    /**
+     * How the pedals go out: as a continuous controller carrying the travel
+     * of the bellows, or thresholded to the two values a switching renderer
+     * understands.
+     */
+    pedalMode: PedalMode;
+    /** Diameter of the tracker-bar bore, in mm. */
+    trackerBore: number;
+    /** Punch diameter in mm, for an edition whose copies record none. */
+    punchDiameter: number;
+    /**
+     * The track at which the keyboard is divided, so that notes from
+     * here upwards follow the treble expression and the ones below it
+     * the bass. Which side an expression perforation itself belongs to
+     * is not decided here but read off the tracker bar.
+     */
+    division: number;
+};
+export declare const defaultWelteT100Options: WelteT100Options;
+/** When the spool brings a place on the roll, in mm, to the tracker bar. */
+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.
+ */
+export declare const welteT100System: ReproducingSystem<WelteT100Options>;

package/lib/systems/welteT100.js

@@ -0,0 +1,191 @@
+import { aperturePorts, DEFAULT_PUNCH_MM, geometryInMm, Grid, levelChanges, mezzoforteTravel, noteDensity, paperSeconds, pedalDefaults, playbackParameters, pneumaticModel, ROWS_PER_MM, runPedals, TRACKER_BORE_MM, travelBetweenRails, WELTE_SPOOL, } from "welte-t100-emulator";
+import { welteT100 } from "../TrackerBar";
+export const defaultWelteT100Options = {
+    spool: WELTE_SPOOL,
+    nuance: {
+        bass: playbackParameters('bass'),
+        treble: playbackParameters('treble')
+    },
+    pedals: pedalDefaults,
+    velocity: { piano: 35, mezzoforte: 60, forte: 90 },
+    pedalMode: 'continuous',
+    trackerBore: TRACKER_BORE_MM,
+    punchDiameter: DEFAULT_PUNCH_MM,
+    division: 54
+};
+/** What each expression code operates, in the emulator's terms. */
+const CODES = new Map([
+    ['MezzoforteOn', ['mezzoforte', 'on']],
+    ['MezzoforteOff', ['mezzoforte', 'off']],
+    ['SlowCrescendoOn', ['crescendo', 'on']],
+    ['SlowCrescendoOff', ['crescendo', 'off']],
+    ['ForzandoOn', ['sforzando', 'on']],
+    ['ForzandoOff', ['sforzando', 'off']],
+    ['SustainPedalOn', ['sustainPedal', 'on']],
+    ['SustainPedalOff', ['sustainPedal', 'off']],
+    ['SoftPedalOn', ['hammerRail', 'on']],
+    ['SoftPedalOff', ['hammerRail', 'off']],
+    ['MotorOn', ['windResistance', 'on']],
+    ['MotorOff', ['windResistance', 'off']],
+    ['Rewind', ['rewind', 'on']],
+    ['ElectricCutOff', ['electricCutoff', 'on']]
+]);
+/** Paper the grid runs on past the last hole, so that a final pedal release completes. */
+const RUN_OUT_MM = 100;
+/**
+ * Which stack of valves an expression perforation belongs to. The symbol
+ * usually says so, having been read off the tracker bar already; where it
+ * does not, the bar is asked again, since sending a perforation to neither
+ * side would quietly flatten the dynamics.
+ */
+const scopeOf = (event) => {
+    if (event.scope)
+        return event.scope;
+    const meaning = welteT100.meaningOf(event.vertical.from);
+    return meaning?.type === 'expression' ? meaning.scope : undefined;
+};
+const isNote = (event) => event.type === 'note';
+const isExpression = (event) => event.type === 'expression';
+const rowOf = (mm) => mm * ROWS_PER_MM;
+/** When the spool brings a place on the roll, in mm, to the tracker bar. */
+export const secondsAt = (spool, mm) => paperSeconds(spool, mm / 10);
+const halfOf = (note, division) => note.vertical.from >= division ? 'treble' : 'bass';
+const readingOf = (event) => {
+    const code = CODES.get(event.expressionType);
+    const half = scopeOf(event);
+    if (!code || !half)
+        return undefined;
+    const [control, action] = code;
+    return {
+        event,
+        punch: { half, control, action, rowOn: rowOf(event.horizontal.from), rowOff: rowOf(event.horizontal.to) }
+    };
+};
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/**
+ * The velocity map joined linearly through its three anchors, with the
+ * middle one at the Mezzoforte pin of the half in question.
+ */
+const velocityOf = (travel, hook, map) => {
+    const position = clamp(travel, 0, 1);
+    if (position <= hook) {
+        return map.piano + (position / hook) * (map.mezzoforte - map.piano);
+    }
+    return map.mezzoforte + ((position - hook) / (1 - hook)) * (map.forte - map.mezzoforte);
+};
+/**
+ * One sample per row of the scan the constants were fitted on, from the
+ * beginning of the roll to a little past the last hole. The rows are
+ * equally spaced on the paper and not in time, which is what the
+ * emulator expects.
+ */
+const gridOver = (events, spool) => {
+    const lastMm = events.reduce((furthest, event) => Math.max(furthest, event.horizontal.to), 0);
+    const length = Math.ceil(rowOf(lastMm + RUN_OUT_MM)) + 1;
+    const seconds = Float64Array.from({ length }, (_, row) => secondsAt(spool, row / ROWS_PER_MM));
+    return new Grid(0, seconds);
+};
+const nuanceCurves = (grid, ports, samples, events, options) => {
+    const onsetRows = (half) => events
+        .filter(isNote)
+        .filter(note => halfOf(note, options.division) === half)
+        .map(note => rowOf(note.horizontal.from));
+    const density = {
+        bass: noteDensity(grid, onsetRows('bass')),
+        treble: noteDensity(grid, onsetRows('treble')),
+    };
+    const totalNoteDensity = Float64Array.from(density.bass, (value, index) => value + density.treble[index]);
+    const curveOf = (half) => {
+        const params = options.nuance[half];
+        const output = pneumaticModel.run({ grid, half, ports, noteDensity: density[half], totalNoteDensity }, params);
+        const travel = travelBetweenRails(output, params);
+        const hook = clamp(mezzoforteTravel(params), 0.01, 0.99);
+        return {
+            ...samples,
+            name: half,
+            kind: 'dynamics',
+            travel,
+            velocity: Float64Array.from(travel, value => velocityOf(value, hook, options.velocity))
+        };
+    };
+    return { bass: curveOf('bass'), treble: curveOf('treble') };
+};
+const pedalCurves = (grid, ports, samples, options) => {
+    const travel = runPedals({ grid, ports }, options.pedals);
+    return {
+        damper: { ...samples, name: 'damper', kind: 'pedal', travel: travel.damper },
+        hammerRail: { ...samples, name: 'hammerRail', kind: 'pedal', travel: travel.hammerRail }
+    };
+};
+const performNotes = (events, grid, nuance, options) => events
+    .filter(isNote)
+    .flatMap((note) => {
+    const curve = nuance[halfOf(note, options.division)];
+    const velocity = curve.velocity[grid.indexOfRow(rowOf(note.horizontal.from))];
+    return [
+        { type: 'noteOn', performs: note, pitch: note.pitch, velocity, at: secondsAt(options.spool, note.horizontal.from) },
+        { type: 'noteOff', performs: note, pitch: note.pitch, velocity: 127, at: secondsAt(options.spool, note.horizontal.to) }
+    ];
+});
+/**
+ * The travel of one pedal as controller steps. Each step is attributed to
+ * the last perforation of that pedal the tracker bar has reached, which is
+ * the one whose reading it follows from.
+ */
+const performPedal = (type, curve, grid, readings, mode) => {
+    if (readings.length === 0)
+        return [];
+    const ordered = readings.toSorted((a, b) => a.punch.rowOn - b.punch.rowOn);
+    const causeOf = (row) => ordered[Math.max(ordered.findLastIndex(reading => reading.punch.rowOn <= row), 0)].event;
+    return levelChanges(curve.travel, { mode })
+        .filter(change => change.index > 0)
+        .map(change => ({
+        type,
+        performs: causeOf(grid.rowAt(change.index)),
+        value: change.value,
+        at: curve.seconds[change.index]
+    }));
+};
+/**
+ * The edition's tempo adjustment is left aside: it is stated as a paper
+ * speed, and what the spool holds constant is its rate of revolution, so
+ * the two are not the same quantity. The spool in the options sets the speed.
+ */
+const perform = (events, options, roll) => {
+    const readings = events
+        .filter(isExpression)
+        .map(readingOf)
+        .filter((reading) => reading !== undefined);
+    const grid = gridOver(events, options.spool);
+    const geometry = geometryInMm(roll.punchDiameter ?? options.punchDiameter, options.trackerBore);
+    const ports = aperturePorts(grid, readings.map(reading => reading.punch), geometry);
+    const samples = {
+        place: Float64Array.from(grid.seconds, (_, row) => row / ROWS_PER_MM),
+        seconds: grid.seconds
+    };
+    const nuance = nuanceCurves(grid, ports, samples, events, options);
+    const pedals = pedalCurves(grid, ports, samples, options);
+    const readingsOf = (control) => readings.filter(reading => reading.punch.control === control);
+    return {
+        events: [
+            ...performNotes(events, grid, nuance, options),
+            ...performPedal('damper', pedals.damper, grid, readingsOf('sustainPedal'), options.pedalMode),
+            ...performPedal('hammerRail', pedals.hammerRail, grid, readingsOf('hammerRail'), options.pedalMode)
+        ],
+        curves: [nuance.bass, nuance.treble, pedals.damper, pedals.hammerRail]
+    };
+};
+/**
+ * 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.
+ */
+export const welteT100System = {
+    name: 'Welte-Mignon T100',
+    trackerBar: welteT100,
+    defaultOptions: defaultWelteT100Options,
+    perform
+};

package/lib/utils.d.ts

@@ -0,0 +1,29 @@
+import { Person } from "./Edition";
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type WithType<T extends string> = {
+    /**
+     * The type discriminator for this object.
+     * @see rdf:type
+     */
+    readonly type: T;
+};
+export type WithId = {
+    /**
+     * A unique identifier for this object.
+     */
+    readonly id: string;
+};
+export type WithActor = {
+    /**
+     * The person who carried out this activity.
+     * @see crm:P14 carried out by
+     */
+    actor?: Person;
+};
+export type WithNote = {
+    /**
+     * A free-text note providing additional context.
+     * @see crm:P3 has note
+     */
+    note?: string;
+};

package/lib/validate.d.ts

@@ -0,0 +1,3 @@
+import { Edition } from "./Edition";
+declare const validate: import("ajv").ValidateFunction<Edition>;
+export { validate };

package/lib/validate.js

@@ -0,0 +1,10 @@
+import Ajv from "ajv";
+import * as schema from "./schema.json";
+const ajv = new Ajv({
+    strict: false,
+    formats: {
+        "date": true
+    }
+});
+const validate = ajv.compile(schema);
+export { validate };