linked-rolls 0.19.1 → 0.21.0

package/lib/systems/welteT98/bar.js

@@ -1,5 +1,5 @@
 import { describeTrackerBar } from "../../TrackerBar";
-import { mm } from "../../Quantity";
+import { metersPerMinute, mm } from "../../Quantity";
 /**
  * The commands of the Welte-Mignon T-98, as its tracker bar reads them.
  *
@@ -32,8 +32,21 @@ export const welteT98ExpressionTypes = [
  *
  * Measured against Julian Dyer's scan of the T-98 copy of roll 225
  * (Grünfeld, Träumerei): 98 columns 2.818 mm apart on paper 285.6 mm
- * wide, notes on the middle 80 columns, the sustain valve punched 53
- * times where the T-100 copy latches its sustain on 53 times.
+ * wide, notes on the middle 80 columns, the sustain valve punched 52
+ * times in the music where the T-100 copy latches its sustain on 52
+ * times. A 53rd perforation on that track belongs to the test pattern
+ * after the rewind.
+ *
+ * The paper speed is the Deutsches Museum's figure for its Welte grün /
+ * T 98 rolls, 220 cm/min. Phillips gives 7 ft/min = 2.134 m/min (p. 121);
+ * midi2exp's and PlaySK's green defaults of 72.2 and 72.27, read as the
+ * Stanford convention of feet per minute times ten, are 2.201 m/min, which
+ * is the museum's figure; and the two copies of roll 225 last the same
+ * time if the green starts at about 7.30 ft/min. Welte's own booklets give
+ * no speed, only that the roll must run from the first "A" of the chromatic
+ * scale to the cross-line bearing the dial number in half a minute
+ * (Skala-Rolle 98 §1b). This is documentation; what sets the emulator's
+ * time axis is the spool.
  */
 export const welteT98 = describeTrackerBar({
     id: 'welte-green',
@@ -41,7 +54,22 @@ export const welteT98 = describeTrackerBar({
     width: mm(286),
     trackCount: 98,
     notes: { from: 6, to: 93, lowestPitch: 21 },
+    paperSpeed: { value: metersPerMinute(2.2), unit: 'm/min' },
     rewindTrack: 1,
+    /**
+     * The T-98 gives the rewind no line of its own — Welte's Forzando P line
+     * doubles as it — so a perforation there is the rewind only when it is far
+     * longer than the command that line usually carries. On the Monteurscala
+     * the rewind is a single continuous 103.8 mm perforation (Kontrolle 10, 40
+     * punches with gaps of 0.51–0.93 mm), where a commanded sforzando-piano
+     * runs a couple of millimetres — a median of 0.06 s against the rewind's
+     * 10.2 s on WM 184. Dyer's scan of the green 225 says the same a third time:
+     * of the 30 perforations its track 1 carries, exactly one reaches 40 mm and
+     * it is 386 mm long. So the threshold is not a fitted number and does not
+     * need to be — every measurement of it so far leaves an order of magnitude
+     * either side.
+     */
+    rewindHold: mm(40),
     expressions: new Map([
         [1, 'SforzandoPiano'],
         [2, 'Mezzoforte'],

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

@@ -0,0 +1,119 @@
+import { Half, Parameters, PedalMode, Spool } from "welte-mignon-emulator";
+import { instrumentT98Of, labelOf, nuanceOf, WelteT98InstrumentName } from "welte-mignon-emulator/t98";
+import { ReproducingSystem } from "../../ReproducingSystem";
+import { Millimeters, Seconds, Track } from "../../Quantity";
+import { type VelocityMap } from "../velocity";
+export type { VelocityMap } from "../velocity";
+export type { WelteT98Instrument, WelteT98InstrumentName } from "welte-mignon-emulator/t98";
+/**
+ * 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 declare const instruments: {
+    genuine: Readonly<Partial<Record<"consensus" | import("welte-mignon-emulator/t98").GenuineRoll, import("welte-mignon-emulator/t98").WelteT98Instrument>>>;
+    derived: Readonly<Partial<Record<"225", import("welte-mignon-emulator/t98").WelteT98Instrument>>>;
+    unfitted: {
+        'starting-values': import("welte-mignon-emulator/t98").WelteT98Instrument;
+    };
+};
+export declare const instrumentNames: readonly WelteT98InstrumentName[];
+/** The instrument a pair of nuancing constants belongs to, if it is one. */
+export declare const instrumentNameOf: (nuance: Record<Half, Parameters>) => WelteT98InstrumentName | undefined;
+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 declare const pedalPresets: {
+    damping: Readonly<Record<string, number>>;
+    brushing: Readonly<Record<string, number>>;
+};
+export type PedalPreset = keyof typeof pedalPresets;
+export declare const pedalPresetOf: (pedals: Parameters) => PedalPreset | undefined;
+export type WelteT98Options = {
+    /**
+     * The take-up spool, which sets the time axis. No source states a T-98
+     * spool geometry, so the default keeps the red circumference and layer and
+     * sets the revolution to make the initial paper speed 220 cm/min. It is
+     * better varied than trusted: it scales every conductance by k and every
+     * time constant by 1/k, and touches nothing dimensionless.
+     */
+    spool: Spool;
+    /** Constants of the nuancing mechanism, one set for each half of the keyboard. */
+    nuance: Record<Half, Parameters>;
+    /** Which instrument those constants are, so that a curve can say so. */
+    instrument: WelteT98InstrumentName;
+    /** Constants of the two pedal actions, one of `pedalPresets` or a set of one's own. */
+    pedals: Parameters;
+    velocity: VelocityMap;
+    pedalMode: PedalMode;
+    /** Diameter of the tracker-bar bore. No source gives the T-98's; the red figure is carried over. */
+    trackerBore: Millimeters;
+    /** Punch diameter for an edition whose copies record none. */
+    punchDiameter: Millimeters;
+    /**
+     * Chained punches whose gap is shorter than this are one perforation. A held
+     * T-98 command is punched as a chain of round holes on a 2.66 mm grid with
+     * paper bridges of about a millimetre, not as one slot, so a raw scan and an
+     * edition whose collation has already made one symbol of the chain see the
+     * same port only if the chain is merged.
+     */
+    chainGap: Millimeters;
+    /**
+     * 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.
+     * Welte puts the division between f♯ and g (Betriebsanleitung p. 7), which
+     * on this bar is track 52; PlaySK's green configuration independently gives
+     * the last bass note as MIDI 66. Which side an expression perforation
+     * belongs to is not decided here but read off the tracker bar.
+     *
+     * A green roll re-cut from a Mignon master uses only the middle 80 of the 88
+     * note positions, so the division falls inside the used compass either way.
+     */
+    division: Track;
+    /**
+     * What a long perforation on the bass sforzando-piano line does. It is the
+     * same valve and the same hole as the dynamic (Skala-Rolle §10), so it
+     * always acts as a sforzando-piano; `stop` additionally ends the performance
+     * there, which is what the instrument does — during rewind the suction to
+     * the primary pneumatics is cut and the Hauptventil closes, so no note
+     * sounds and the expression apparatus is out of action (Betriebsanleitung
+     * p. 17). `ignore` is for an edition that is a fragment, or that carries a
+     * rewind in the middle for some reason of its own.
+     */
+    rewind: 'stop' | 'ignore';
+};
+export declare const defaultWelteT98Options: WelteT98Options;
+/** When the spool brings a place on the roll to the tracker bar. */
+export declare const secondsAt: (spool: Spool, place: Millimeters) => Seconds;
+/**
+ * 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 declare const welteT98System: ReproducingSystem<WelteT98Options>;

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.19.1",
+  "version": "0.21.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
     }
   },