linked-rolls 0.69.0 → 0.71.0

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

@@ -1,26 +1,65 @@
+/**
+ * The Welte-Mignon T-100, the red Welte, as a reproducing system: the
+ * system that plays a version (`welteT100System`), the options it takes,
+ * and the instruments its emulator was fitted as. It needs the optional
+ * peer dependency welte-mignon-emulator.
+ *
+ * @module linked-rolls/welte-t100
+ */
 import { Half, Parameters } from "welte-mignon-emulator";
 import { Instrument, RollNumber } from "welte-mignon-emulator/t100";
 import { NegotiatedEvent, Performance, ReproducingSystem, RollProperties } from "../ReproducingSystem.js";
 import { type WelteOptions } from "../welte.js";
 export type { VelocityMap } from "../velocity.js";
-export { pedalPresetOf, pedalPresets, secondsAt, type PedalPreset } from "../welte.js";
+export { pedalPresetOf, pedalPresets, secondsAt, type PedalPreset, type WelteOptions } from "../welte.js";
+/**
+ * An instrument the T-100 emulator was fitted as: its nuancing constants
+ * for each half of the keyboard, and what they were fitted to and how
+ * well.
+ * @category Systems and emulation
+ */
 export type { Instrument } from "welte-mignon-emulator/t100";
+/**
+ * An instrument the T-100 emulator was fitted as, by name: the
+ * consensus, or the setting that drew one roll's nuance lines, by the
+ * roll's Welte number.
+ * @category Systems and emulation
+ */
 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.
+ * @category Systems and emulation
  */
 export declare const instruments: Readonly<Record<InstrumentName, Instrument>>;
-/** The instruments by name, the consensus first. */
+/**
+ * The instruments by name, the consensus first.
+ * @category Systems and emulation
+ */
 export declare const instrumentNames: readonly InstrumentName[];
-/** The nuancing constants of an instrument, one set for each half of the keyboard. */
+/**
+ * The nuancing constants of an instrument, one set for each half of the keyboard.
+ * @category Systems and emulation
+ */
 export declare const nuanceOf: (instrument: Instrument) => Record<Half, Parameters>;
-/** The instrument a pair of nuancing constants belongs to, if it is one. */
+/**
+ * The instrument a pair of nuancing constants belongs to, if it is one.
+ * @category Systems and emulation
+ */
 export declare const instrumentNameOf: (nuance: Record<Half, Parameters>) => InstrumentName | undefined;
-/** The T-100 takes the options every Welte system does; see `WelteOptions`. */
+/**
+ * The T-100 takes the options every Welte system does; see `WelteOptions`.
+ * @category Systems and emulation
+ */
 export type WelteT100Options = WelteOptions;
+/**
+ * The options the T-100 plays a version with unless others are given:
+ * Welte's spool, the consensus instrument, the damping pedals as a
+ * continuous controller, and the keyboard divided at track 54.
+ * @category Systems and emulation
+ */
 export declare const defaultWelteT100Options: WelteT100Options;
 /**
  * The mechanism, given a way of naming the instrument on the curves it
@@ -29,6 +68,7 @@ export declare const defaultWelteT100Options: WelteT100Options;
  * shares this; what it may not share is the name, since a Licensee playback
  * runs on constants fitted to Freiburg instruments and the curve has to say
  * so, nor the spool, which is the red one it carries over.
+ * @internal
  */
 export declare const performAs: (instrumentOf: (nuance: Record<Half, Parameters>) => string, ownSpool?: boolean) => (events: readonly NegotiatedEvent[], options: WelteT100Options, roll: RollProperties) => Performance;
 /**
@@ -38,5 +78,6 @@ export declare const performAs: (instrumentOf: (nuance: Record<Half, Parameters>
  * 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.
+ * @category Systems and emulation
  */
 export declare const welteT100System: ReproducingSystem<WelteT100Options>;

package/lib/systems/welteT100/system.js

@@ -1,3 +1,11 @@
+/**
+ * The Welte-Mignon T-100, the red Welte, as a reproducing system: the
+ * system that plays a version (`welteT100System`), the options it takes,
+ * and the instruments its emulator was fitted as. It needs the optional
+ * peer dependency welte-mignon-emulator.
+ *
+ * @module linked-rolls/welte-t100
+ */
 import { DEFAULT_PUNCH_MM, TRACKER_BORE_MM, WELTE_SPOOL, } from "welte-mignon-emulator";
 import { aperturePorts, CONSENSUS, pneumaticModel, PRESETS, runPedals, } from "welte-mignon-emulator/t100";
 import { welteT100 } from "./bar.js";
@@ -10,14 +18,30 @@ export { pedalPresetOf, pedalPresets, secondsAt } from "../welte.js";
  * 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.
+ * @category Systems and emulation
  */
 export const instruments = { consensus: CONSENSUS, ...PRESETS };
-/** The instruments by name, the consensus first. */
+/**
+ * The instruments by name, the consensus first.
+ * @category Systems and emulation
+ */
 export const instrumentNames = ['consensus', ...Object.keys(PRESETS)];
-/** The nuancing constants of an instrument, one set for each half of the keyboard. */
+/**
+ * The nuancing constants of an instrument, one set for each half of the keyboard.
+ * @category Systems and emulation
+ */
 export const nuanceOf = (instrument) => ({ bass: instrument.bass, treble: instrument.treble });
-/** The instrument a pair of nuancing constants belongs to, if it is one. */
+/**
+ * The instrument a pair of nuancing constants belongs to, if it is one.
+ * @category Systems and emulation
+ */
 export const instrumentNameOf = (nuance) => instrumentNames.find(name => sameParameters(instruments[name].bass, nuance.bass) && sameParameters(instruments[name].treble, nuance.treble));
+/**
+ * The options the T-100 plays a version with unless others are given:
+ * Welte's spool, the consensus instrument, the damping pedals as a
+ * continuous controller, and the keyboard divided at track 54.
+ * @category Systems and emulation
+ */
 export const defaultWelteT100Options = {
     spool: WELTE_SPOOL,
     nuance: nuanceOf(instruments.consensus),
@@ -60,6 +84,7 @@ const punchOf = (event, rows) => {
  * shares this; what it may not share is the name, since a Licensee playback
  * runs on constants fitted to Freiburg instruments and the curve has to say
  * so, nor the spool, which is the red one it carries over.
+ * @internal
  */
 export const performAs = (instrumentOf, ownSpool = true) => (events, options, roll) => {
     const { events: performed, curves } = performWelte(events, options, roll, {
@@ -79,6 +104,7 @@ export const performAs = (instrumentOf, ownSpool = true) => (events, options, ro
  * 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.
+ * @category Systems and emulation
  */
 export const welteT100System = {
     name: 'Welte-Mignon T100',

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

@@ -7,8 +7,13 @@ import { TrackerBar } from "../TrackerBar.js";
  * as long as one continuous perforation lasts (Hagmann, pp. 89 f. and
  * 100–103; Phillips, p. 121), so none of these is an On or an Off. The
  * two sforzando valves name the end of the range they pull towards.
+ * @category Systems and emulation
  */
 export declare const welteT98ExpressionTypes: readonly ['SforzandoPiano', 'SforzandoForte', 'Mezzoforte', 'Crescendo', 'SustainPedal', 'SoftPedal'];
+/**
+ * A command of the Welte-Mignon T-98.
+ * @category Systems and emulation
+ */
 export type WelteT98ExpressionType = typeof welteT98ExpressionTypes[number];
 /**
  * Welte-Mignon T-98 ("green Welte"), cf. Hagmann, Anhang 11 (p. 179)
@@ -40,5 +45,6 @@ export type WelteT98ExpressionType = typeof welteT98ExpressionTypes[number];
  * 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.
+ * @category Systems and emulation
  */
 export declare const welteT98: TrackerBar;

package/lib/systems/welteT98/bar.js

@@ -8,6 +8,7 @@ import { metersPerMinute, mm } from "../../model/Quantity.js";
  * as long as one continuous perforation lasts (Hagmann, pp. 89 f. and
  * 100–103; Phillips, p. 121), so none of these is an On or an Off. The
  * two sforzando valves name the end of the range they pull towards.
+ * @category Systems and emulation
  */
 export const welteT98ExpressionTypes = [
     'SforzandoPiano',
@@ -60,6 +61,7 @@ const welteT98Operations = {
  * 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.
+ * @category Systems and emulation
  */
 export const welteT98 = describeTrackerBar({
     id: 'welte-green',

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

@@ -1,11 +1,33 @@
+/**
+ * The Welte-Mignon T-98, the green Welte, as a reproducing system: the
+ * system that plays a version (`welteT98System`), the options it takes,
+ * and the green instruments its emulator offers, genuine, derived and
+ * unfitted. It needs the optional peer dependency welte-mignon-emulator.
+ *
+ * @module linked-rolls/welte-t98
+ */
 import { Half, Parameters } from "welte-mignon-emulator";
-import { instrumentT98Of, labelOf, nuanceOf, WelteT98InstrumentName } from "welte-mignon-emulator/t98";
+import { instrumentT98Of, labelOf, WelteT98InstrumentName } from "welte-mignon-emulator/t98";
 import { ReproducingSystem } from "../ReproducingSystem.js";
 import { Millimeters } from "../../model/Quantity.js";
 import { type WelteOptions } from "../welte.js";
+/** @category Systems and emulation */
 export type { VelocityMap } from "../velocity.js";
-export { pedalPresetOf, pedalPresets, secondsAt, type PedalPreset } from "../welte.js";
-export type { WelteT98Instrument, WelteT98InstrumentName } from "welte-mignon-emulator/t98";
+/** @category Systems and emulation */
+export { pedalPresetOf, pedalPresets, secondsAt, type PedalPreset, type WelteOptions } from "../welte.js";
+/**
+ * A set of nuancing constants for the green Welte, with what it was
+ * fitted to: a genuine, a derived or an unfitted instrument.
+ * @category Systems and emulation
+ */
+export type { WelteT98Instrument } from "welte-mignon-emulator/t98";
+/**
+ * A green instrument by name: a genuine one by the Welte number of its
+ * roll or as their consensus, a derived one by the recording it was
+ * fitted on, or the unfitted starting values.
+ * @category Systems and emulation
+ */
+export type { 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.
@@ -32,6 +54,7 @@ export type { WelteT98Instrument, WelteT98InstrumentName } from "welte-mignon-em
  * are 0.029 to 0.066, because a shared mechanism describes none of them well.
  * That spread is a property of the instruments rather than of the fit, and
  * Gottschewski's finding that they were out of regulation is visible in it.
+ * @category Systems and emulation
  */
 export declare const instruments: {
     genuine: Readonly<Partial<Record<"consensus" | import("welte-mignon-emulator/t98").GenuineRoll, import("welte-mignon-emulator/t98").WelteT98Instrument>>>;
@@ -40,10 +63,30 @@ export declare const instruments: {
         'starting-values': import("welte-mignon-emulator/t98").WelteT98Instrument;
     };
 };
+/**
+ * The names of the green instruments, the genuine ones first, then the
+ * derived ones and the unfitted starting values.
+ * @category Systems and emulation
+ */
 export declare const instrumentNames: readonly WelteT98InstrumentName[];
-/** The instrument a pair of nuancing constants belongs to, if it is one. */
+/**
+ * The instrument a pair of nuancing constants belongs to, if it is one.
+ * @category Systems and emulation
+ */
 export declare const instrumentNameOf: (nuance: Record<Half, Parameters>) => WelteT98InstrumentName | undefined;
-export { instrumentT98Of, labelOf, nuanceOf };
+/**
+ * The green instrument of that name, where the emulator has one.
+ * @category Systems and emulation
+ */
+export { instrumentT98Of };
+/** @category Systems and emulation */
+export { labelOf };
+/**
+ * The nuancing constants of a green instrument, one set for each half of
+ * the keyboard.
+ * @category Systems and emulation
+ */
+export declare const nuanceOf: (instrument: import("welte-mignon-emulator/t98").WelteT98Instrument) => Record<Half, Parameters>;
 /**
  * The options every Welte system takes (see `WelteOptions`), with what the
  * T-98 adds. No source states a T-98 spool geometry, so the default keeps the
@@ -56,6 +99,7 @@ export { instrumentT98Of, labelOf, nuanceOf };
  * configuration independently gives the last bass note as MIDI 66. 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.
+ * @category Systems and emulation
  */
 export type WelteT98Options = WelteOptions & {
     /** Which instrument the nuancing constants are, so that a curve can say so. */
@@ -80,6 +124,14 @@ export type WelteT98Options = WelteOptions & {
      */
     rewind: 'stop' | 'ignore';
 };
+/**
+ * The options the T-98 plays a version with unless others are given:
+ * the green spool, the consensus of the genuine instruments, the
+ * damping pedals as a continuous controller, the keyboard divided at
+ * track 52, and the performance ending where a long perforation sends
+ * the roll back.
+ * @category Systems and emulation
+ */
 export declare const defaultWelteT98Options: WelteT98Options;
 /**
  * The green Welte, as welte-mignon-emulator models it. Everything downstream of
@@ -95,5 +147,6 @@ export declare const defaultWelteT98Options: WelteT98Options;
  * playback runs on the consensus across them unless the caller names another
  * instrument. Where the roll being played is one of the five, its own instrument
  * is the better choice and `instruments.genuine` carries it.
+ * @category Systems and emulation
  */
 export declare const welteT98System: ReproducingSystem<WelteT98Options>;

package/lib/systems/welteT98/system.js

@@ -1,9 +1,18 @@
+/**
+ * The Welte-Mignon T-98, the green Welte, as a reproducing system: the
+ * system that plays a version (`welteT98System`), the options it takes,
+ * and the green instruments its emulator offers, genuine, derived and
+ * unfitted. It needs the optional peer dependency welte-mignon-emulator.
+ *
+ * @module linked-rolls/welte-t98
+ */
 import { ROWS_PER_MM, 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 { aperturePorts, CHAIN_GAP_MM, DERIVED, GENUINE, instrumentT98Of, labelOf, nuanceOf as emulatorNuanceOf, PUNCH_T98_MM, pneumaticT98Model, rewindAt, runPedals, sforzandoPianoLift, STARTING_VALUES, TRACKER_BORE_T98_MM, } from "welte-mignon-emulator/t98";
 import { welteT98 } from "./bar.js";
 import { mm, seconds, track } from "../../model/Quantity.js";
 import { defaultVelocityMap } from "../velocity.js";
 import { pedalPresets, performWelte, sameParameters } from "../welte.js";
+/** @category Systems and emulation */
 export { pedalPresetOf, pedalPresets, secondsAt } from "../welte.js";
 /**
  * The instruments the emulator offers for the green Welte, in three groups that
@@ -31,21 +40,50 @@ export { pedalPresetOf, pedalPresets, secondsAt } from "../welte.js";
  * are 0.029 to 0.066, because a shared mechanism describes none of them well.
  * That spread is a property of the instruments rather than of the fit, and
  * Gottschewski's finding that they were out of regulation is visible in it.
+ * @category Systems and emulation
  */
 export const instruments = { genuine: GENUINE, derived: DERIVED, unfitted: { 'starting-values': STARTING_VALUES } };
+/**
+ * The names of the green instruments, the genuine ones first, then the
+ * derived ones and the unfitted starting values.
+ * @category Systems and emulation
+ */
 export const instrumentNames = [
     ...Object.keys(GENUINE).map(genuine => ({ genuine })),
     ...Object.keys(DERIVED).map(derived => ({ derived })),
     { unfitted: 'starting-values' }
 ];
-/** The instrument a pair of nuancing constants belongs to, if it is one. */
+/**
+ * The instrument a pair of nuancing constants belongs to, if it is one.
+ * @category Systems and emulation
+ */
 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 green instrument of that name, where the emulator has one.
+ * @category Systems and emulation
+ */
+export { instrumentT98Of };
+/** @category Systems and emulation */
+export { labelOf };
+/**
+ * The nuancing constants of a green instrument, one set for each half of
+ * the keyboard.
+ * @category Systems and emulation
+ */
+export const nuanceOf = emulatorNuanceOf;
+/**
+ * The options the T-98 plays a version with unless others are given:
+ * the green spool, the consensus of the genuine instruments, the
+ * damping pedals as a continuous controller, the keyboard divided at
+ * track 52, and the performance ending where a long perforation sends
+ * the roll back.
+ * @category Systems and emulation
+ */
 export const defaultWelteT98Options = {
     spool: WELTE_T98_SPOOL,
     nuance: nuanceOf(GENUINE.consensus),
@@ -135,6 +173,7 @@ const perform = (events, options, roll) => {
  * playback runs on the consensus across them unless the caller names another
  * instrument. Where the roll being played is one of the five, its own instrument
  * is the better choice and `instruments.genuine` carries it.
+ * @category Systems and emulation
  */
 export const welteT98System = {
     name: 'Welte-Mignon T98',

package/lib/validate.d.ts

@@ -1,12 +1,28 @@
+/**
+ * Checks an edition's JSON-LD document, as `asJsonLd` writes one, against
+ * the schema of the format. The same `validate` is exported from the root
+ * module; this entry point offers it alone.
+ *
+ * @module linked-rolls/validate
+ */
 import { type ErrorObject } from "ajv";
 import { Edition } from "./model/Edition.js";
 /**
  * Holds a document against the edition schema. `errors` says what the
  * last call found wrong, and is empty where it found nothing.
+ * @category Reading and writing
  */
 export interface ValidateEdition {
     (document: unknown): document is Edition;
     errors?: ErrorObject[] | null;
 }
+/**
+ * Whether the document is an edition as the schema of the format
+ * describes it, such as `asJsonLd` writes. What a call found wrong is in
+ * `validate.errors` until the next call. A document written by an earlier
+ * release may fail where `importJsonLd` would still read it, since the
+ * import migrates it first (`migrate`).
+ * @category Reading and writing
+ */
 declare const validate: ValidateEdition;
 export { validate };

package/lib/validate.js

@@ -1,3 +1,10 @@
+/**
+ * Checks an edition's JSON-LD document, as `asJsonLd` writes one, against
+ * the schema of the format. The same `validate` is exported from the root
+ * module; this entry point offers it alone.
+ *
+ * @module linked-rolls/validate
+ */
 import Ajv from "ajv";
 // A default import, not a namespace one: Node's ESM gives a JSON module
 // only a default export, so `import * as` hands ajv the namespace object
@@ -9,6 +16,14 @@ const compileEditionSchema = () => new Ajv({ strict: false, formats: { "date": t
  * pay for it, so the compiled form is made on first use and kept.
  */
 let compiled;
+/**
+ * Whether the document is an edition as the schema of the format
+ * describes it, such as `asJsonLd` writes. What a call found wrong is in
+ * `validate.errors` until the next call. A document written by an earlier
+ * release may fail where `importJsonLd` would still read it, since the
+ * import migrates it first (`migrate`).
+ * @category Reading and writing
+ */
 const validate = (document) => {
     compiled ?? (compiled = compileEditionSchema());
     const valid = compiled(document);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -46,6 +46,7 @@
     "lint": "oxlint -c .oxlintrc.json src test scripts schema",
     "build:schema": "npx ts-json-schema-generator --additional-properties --validation-keywords see --path 'src/**/*.ts' --type 'Edition' > schema_.json && node schema/postprocess.js && rm schema_.json && mv schema.json src/schema.json",
     "build:docs": "node schema/docs/generate.ts src/schema.json docs/index.html",
+    "build:api": "npm ci --prefix tools/typedoc --silent --no-audit --no-fund && tools/typedoc/node_modules/.bin/typedoc",
     "smoke": "node scripts/smoke.mjs"
   },
   "devDependencies": {