linked-rolls 0.20.0 → 0.22.0

package/lib/systems/welteT98/system.js

@@ -0,0 +1,245 @@
+import { geometryInMm, Grid, levelChanges, mezzoforteTravel, paperSeconds, pedalBrushing, pedalDefaults, ROWS_PER_MM, travelBetweenRails, WELTE_T98_SPOOL, } from "welte-mignon-emulator";
+import { aperturePorts, CHAIN_GAP_MM, DERIVED, GENUINE, instrumentT98Of, labelOf, nuanceOf, PUNCH_T98_MM, pneumaticT98Model, rewindAt, runPedals, sforzandoPianoLift, STARTING_VALUES, TRACKER_BORE_T98_MM, } from "welte-mignon-emulator/t98";
+import { welteT98 } from "./bar";
+import { inCentimeters, mm, seconds, track } from "../../Quantity";
+import { partitionPoint } from "../../sorted";
+import { defaultVelocityMap, velocityOf } from "../velocity";
+/**
+ * The instruments the emulator offers for the green Welte, in three groups that
+ * answer three different questions and must not be listed as one.
+ *
+ * A **genuine** instrument is fitted to the drawn nuance line of a green roll
+ * and says what a green Welte did. A **derived** instrument is fitted so that
+ * the green code of a recording reproduces what the fitted T-100 emulator makes
+ * of the *red* copy of the same recording, and says what Welte's editor meant
+ * the green roll to sound like; its provenance names the T-100 instrument it
+ * inherits, since it is only as good as the red reading behind it. The
+ * difference between the two, in the printed ordinate both scales share, is how
+ * far the transfer of a red reading onto the green mechanism succeeded.
+ *
+ * Neither has been fitted yet, so both groups are empty and what a playback runs
+ * on until then is the third group: the **unfitted** starting values, arithmetic
+ * from Welte's regulation controls and the T-100 consensus with no green roll
+ * behind any of it. A curve produced with them says so in its own `instrument`
+ * field, and nothing should be published from them.
+ */
+export const instruments = { genuine: GENUINE, derived: DERIVED, unfitted: { 'starting-values': STARTING_VALUES } };
+export const instrumentNames = [
+    ...Object.keys(GENUINE).map(genuine => ({ genuine })),
+    ...Object.keys(DERIVED).map(derived => ({ derived })),
+    { unfitted: 'starting-values' }
+];
+const sameParameters = (a, b) => Object.keys(a).length === Object.keys(b).length
+    && Object.entries(a).every(([name, value]) => b[name] === value);
+/** The instrument a pair of nuancing constants belongs to, if it is one. */
+export const instrumentNameOf = (nuance) => instrumentNames.find(name => {
+    const instrument = instrumentT98Of(name);
+    return instrument !== undefined
+        && sameParameters(instrument.bass, nuance.bass)
+        && sameParameters(instrument.treble, nuance.treble);
+});
+export { instrumentT98Of, labelOf, nuanceOf };
+/**
+ * The two readings of the pedal mechanism, which is the T-100's below the
+ * command: Hagmann has the valves and bellows that carry out the movements "in
+ * beiden Systemen dieselbe" (p. 106), and only the Vorpneumatik differs.
+ */
+export const pedalPresets = {
+    damping: pedalDefaults,
+    brushing: pedalBrushing
+};
+export const pedalPresetOf = (pedals) => Object.keys(pedalPresets).find(name => sameParameters(pedalPresets[name], pedals));
+export const defaultWelteT98Options = {
+    spool: WELTE_T98_SPOOL,
+    nuance: nuanceOf(STARTING_VALUES),
+    instrument: { unfitted: 'starting-values' },
+    pedals: pedalPresets.damping,
+    velocity: defaultVelocityMap,
+    pedalMode: 'continuous',
+    trackerBore: mm(TRACKER_BORE_T98_MM),
+    punchDiameter: mm(PUNCH_T98_MM),
+    chainGap: mm(CHAIN_GAP_MM),
+    division: track(52),
+    rewind: 'stop'
+};
+/**
+ * What each expression code operates, in the emulator's terms. There is no
+ * action: a T-98 function lasts exactly as long as its perforation, so a symbol
+ * carries its own extent and nothing cancels it. `SoftPedal` maps to the
+ * emulator's `hammerRail`, which keeps Hagmann's part name rather than the
+ * roll's function name.
+ */
+const CODES = {
+    SforzandoPiano: 'sforzandoPiano',
+    SforzandoForte: 'sforzandoForte',
+    Mezzoforte: 'mezzoforte',
+    Crescendo: 'crescendo',
+    SustainPedal: 'sustainPedal',
+    SoftPedal: 'hammerRail'
+};
+const isWelteT98ExpressionType = (type) => Object.hasOwn(CODES, type);
+const codeOf = (expressionType) => isWelteT98ExpressionType(expressionType) ? CODES[expressionType] : undefined;
+/** Paper the grid runs on past the last hole, so that a final pedal release completes. */
+const RUN_OUT = mm(100);
+const isNote = (event) => event.type === 'note';
+const isExpression = (event) => event.type === 'expression';
+const paperOf = (toOwnPaper) => ({
+    rowOf: place => place * toOwnPaper * ROWS_PER_MM,
+    placeOfRow: row => mm(row / (toOwnPaper * ROWS_PER_MM)),
+    paperOfRow: row => mm(row / ROWS_PER_MM)
+});
+/** When the spool brings a place on the roll to the tracker bar. */
+export const secondsAt = (spool, place) => seconds(paperSeconds(spool, inCentimeters(place)));
+const halfOf = (note, division) => note.vertical.from >= division ? 'treble' : 'bass';
+const readingOf = (paper) => (event) => {
+    const control = codeOf(event.expressionType);
+    if (!control)
+        return undefined;
+    const half = event.scope;
+    return {
+        event,
+        punch: {
+            half,
+            control,
+            rowOn: paper.rowOf(event.horizontal.from),
+            rowOff: paper.rowOf(event.horizontal.to)
+        }
+    };
+};
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/**
+ * 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.
+ */
+const gridOver = (events, spool, paper) => {
+    const last = mm(events.reduce((furthest, event) => Math.max(furthest, event.horizontal.to), 0));
+    const length = Math.ceil(paper.rowOf(last) + RUN_OUT * ROWS_PER_MM) + 1;
+    const times = new Float64Array(length).map((_, row) => secondsAt(spool, paper.paperOfRow(row)));
+    return new Grid(0, times);
+};
+const nuanceCurves = (grid, ports, samples, options) => {
+    const instrument = `Welte-Mignon T-98, ${labelOf(options.instrument)}`;
+    const curveOf = (half) => {
+        const params = options.nuance[half];
+        const output = pneumaticT98Model.run({ grid, half, ports }, params);
+        const travel = travelBetweenRails(output, params);
+        const hook = clamp(mezzoforteTravel(params), 0.01, 0.99);
+        return {
+            ...samples,
+            name: half,
+            kind: 'dynamics',
+            instrument,
+            travel,
+            velocity: travel.map(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, paper) => events
+    .filter(isNote)
+    .flatMap((note) => {
+    const curve = nuance[halfOf(note, options.division)];
+    const velocity = curve.velocity[grid.indexOfRow(paper.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 attributed to the last
+ * perforation of that pedal the tracker bar has reached.
+ */
+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(partitionPoint(ordered, reading => reading.punch.rowOn <= row) - 1, 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: seconds(curve.seconds[change.index])
+    }));
+};
+/**
+ * The row at which the Abstellbalg trips and the roll goes back, or the end of
+ * the grid where it never does. The shut-off hangs on the bass sforzando-piano
+ * valve and reads the same perforations the dynamic does, so this asks the
+ * emulator for that valve's lift and integrates it.
+ */
+const rewindRow = (grid, ports, options) => {
+    if (options.rewind === 'ignore')
+        return grid.length;
+    const lift = sforzandoPianoLift({ grid, half: 'bass', ports }, options.nuance.bass);
+    return rewindAt(lift, grid.dt) ?? grid.length;
+};
+const truncated = (events, until) => events.filter(event => event.at <= until);
+const cutCurve = (curve, rows) => ({
+    ...curve,
+    place: curve.place.slice(0, rows),
+    seconds: curve.seconds.slice(0, rows),
+    travel: curve.travel.slice(0, rows),
+    ...(curve.kind === 'dynamics' ? { velocity: curve.velocity.slice(0, rows) } : {})
+});
+/**
+ * The edition's tempo adjustment is left aside, as on the T-100: it is stated as
+ * a paper speed, and what the spool holds constant is its rate of revolution.
+ */
+const perform = (events, options, roll) => {
+    const paper = paperOf(roll.toOwnPaper ?? 1);
+    const readings = events
+        .filter(isExpression)
+        .map(readingOf(paper))
+        .filter((reading) => reading !== undefined);
+    const grid = gridOver(events, options.spool, paper);
+    const geometry = geometryInMm(roll.punchDiameter ?? options.punchDiameter, options.trackerBore);
+    const gap = options.chainGap * ROWS_PER_MM;
+    const ports = aperturePorts(grid, readings.map(reading => reading.punch), geometry, gap);
+    const samples = {
+        place: grid.seconds.map((_, row) => paper.placeOfRow(row)),
+        seconds: grid.seconds
+    };
+    const nuance = nuanceCurves(grid, ports, samples, options);
+    const pedals = pedalCurves(grid, ports, samples, options);
+    const readingsOf = (control) => readings.filter(reading => reading.punch.control === control);
+    const stops = rewindRow(grid, ports, options);
+    const until = seconds(grid.seconds[Math.min(stops, grid.length - 1)]);
+    const rows = Math.min(stops + 1, grid.length);
+    return {
+        events: truncated([
+            ...performNotes(events, grid, nuance, options, paper),
+            ...performPedal('damper', pedals.damper, grid, readingsOf('sustainPedal'), options.pedalMode),
+            ...performPedal('hammerRail', pedals.hammerRail, grid, readingsOf('hammerRail'), options.pedalMode)
+        ], until),
+        curves: [nuance.bass, nuance.treble, pedals.damper, pedals.hammerRail].map(curve => cutCurve(curve, rows))
+    };
+};
+/**
+ * The green Welte, as welte-mignon-emulator models it. Everything downstream of
+ * the relay is the T-100's, on Hagmann's authority that the nuancing unit is
+ * built the same for both tracker scales (p. 96); what differs is in front of
+ * it. Each function is held for exactly as long as its own perforation runs
+ * over the glide block, four conduits stand on one bellows and their drives add
+ * as flows, the crescendo's ceiling is the balance of throttle 98 against the
+ * permanently open bore 100, and a long perforation on the bass sforzando-piano
+ * line sends the roll back.
+ *
+ * Its constants are **not fitted**. `instruments.genuine` and
+ * `instruments.derived` are empty until their fits run, and what a playback runs
+ * on until then is the unfitted starting values, which every curve says.
+ */
+export const welteT98System = {
+    name: 'Welte-Mignon T98',
+    trackerBar: welteT98,
+    defaultOptions: defaultWelteT98Options,
+    perform
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,14 @@
       "types": "./lib/systems/welteT100/system.d.ts",
       "default": "./lib/systems/welteT100/system.js"
     },
+    "./welte-t98": {
+      "types": "./lib/systems/welteT98/system.d.ts",
+      "default": "./lib/systems/welteT98/system.js"
+    },
+    "./welte-licensee": {
+      "types": "./lib/systems/welteLicensee/system.d.ts",
+      "default": "./lib/systems/welteLicensee/system.js"
+    },
     "./lib/*": "./lib/*",
     "./package.json": "./package.json"
   },
@@ -40,13 +48,13 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0",
-    "welte-t100-emulator": "^0.4.0"
+    "welte-mignon-emulator": "^1.0.0"
   },
   "peerDependencies": {
-    "welte-t100-emulator": "^0.4.0"
+    "welte-mignon-emulator": "^1.0.0"
   },
   "peerDependenciesMeta": {
-    "welte-t100-emulator": {
+    "welte-mignon-emulator": {
       "optional": true
     }
   },