linked-rolls 0.0.1 → 0.1.0

package/README.md

@@ -8,11 +8,58 @@ and exporting digital editions of piano roll. In particular it allows to:
   - collate differing piano roll copies
   - create an manipulate editorial assumptions 
   - export the edition as JSON-LD (based on the 
-    linked-rolls ontology)
+    [Roll Edition Format](https://pfefferniels.github.io/linked-rolls/))
 
+This library is the foundation of the
+[Roll Desk](https://github.com/pfefferniels/roll-desk).
+
+## Emulation
+
+`Emulation` turns a version of the edition into MIDI. The core of the
+library does the part that belongs to the edition: it negotiates the
+symbols of a version into placed events, hands them to a
+`ReproducingSystem`, and writes the performance out with every note and
+pedal step labelled by the symbol it performs. A reproducing system is a
+tracker bar and a `perform` function; the core does not depend on any one
+instrument's model.
+
+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. What the emulator does not determine is how
+bellows travel maps onto MIDI velocity; `WelteT100Options.velocity`
+anchors that map at the open rail, the Mezzoforte pin and the closed rail,
+and its defaults are midi2exp's.
+
+```ts
+import { Emulation } from 'linked-rolls'
+import { welteT100System } from 'linked-rolls/welte-t100'
+
+const emulation = new Emulation(welteT100System)
+emulation.emulateVersion(version, view)
+const midi = emulation.asMIDI()
+```
+
+The emulator is an optional peer dependency: an application that uses the
+T-100 system installs `welte-t100-emulator` itself, and one that only
+reads editions does not need it. For development on both at once, a
+checkout of [welte-t100](https://github.com/pfefferniels/welte-t100)
+beside this repository, declared as `file:../welte-t100`, works too.
 
 ## Building
 ```
    npm i
    npm run build
 ```
+
+## Releasing
+
+Releases go out through `.github/workflows/publish.yml`, never from a
+laptop: raise the version in `package.json`, commit, and push a tag
+`v<version>`, or run the workflow by hand from the Actions tab. The
+workflow builds, runs the tests and publishes with provenance through
+npm's trusted publishing, so no token is stored. It checks out the
+emulator beside this repository to build the T-100 entry point.

package/lib/Assumption.d.ts

@@ -0,0 +1,124 @@
+import { WithActor, WithNote, WithId } from "./utils";
+export declare const certainties: readonly ["true", "likely", "possible", "unlikely", "false"];
+/**
+ * Certainty levels for beliefs, ranging from 'true' to 'false'
+ * and some values in between.
+ */
+export type Certainty = typeof certainties[number];
+/**
+ * An argumentation provides reasons for a belief and
+ * may be associated with a person carrying out that argumentation.
+ * @see crminf:I1 Argumentation
+ */
+export interface Argumentation<T extends string = 'simpleArgumentation'> extends WithActor, WithNote {
+    type: T;
+}
+/**
+ * A meaning comprehension interprets or disambiguates the meaning of
+ * symbols or features. For example, interpreting a pencil mark
+ * as an instruction to add or remove a perforation or as the dating
+ * of the roll.
+ */
+export interface MeaningComprehension extends Argumentation<'meaningComprehension'> {
+    /**
+     * References (by `@id`) to the symbols or features
+     * whose meaning is being interpreted.
+     * @see crminf:J22 interpreted meaning of
+     */
+    comprehends: string[];
+}
+/**
+ * An inference draws a conclusion from given premises.
+ * @see crminf:I5 Inference Making
+ */
+export interface Inference extends Argumentation<'inference'> {
+    /**
+     * References (by `@id`) to the beliefs or facts
+     * from which the conclusion is drawn.
+     * @see crminf:J1 used as premise
+     */
+    premises: string[];
+}
+/**
+ * A belief adoption adopts someone else's belief. This type is used
+ * to indicate e.g. knowledge through private communication or
+ * from secondary literature.
+ * @see crminf:I7 Belief Adoption
+ */
+export interface BeliefAdoption extends Argumentation<'beliefAdoption'> {
+    /**
+     * A note describing the source of the adopted belief,
+     * e.g. a bibliographic reference or personal communication.
+     * @see crm:P3 has note
+     */
+    note: string;
+}
+/**
+ * An argumentation can be either a plain argumentation, a
+ * meaning comprehension, an inference, or a belief adoption.
+ */
+export type AnyArgumentation = MeaningComprehension | Inference | BeliefAdoption | Argumentation;
+/**
+ * A belief is a temporal object and associates a proposition (i.e.
+ * a statement) with a certainty. It comes into existence through
+ * argumentations (reasons).
+ * @see crminf:I2 Belief
+ */
+export interface Belief extends WithId {
+    type: 'belief';
+    /**
+     * The level of certainty associated with this belief.
+     * @see crminf:J5 holds to be
+     */
+    certainty: Certainty;
+    /**
+     * The argumentations providing reasons for this belief.
+     * @see crminf:J2 was concluded by
+     */
+    reasons: AnyArgumentation[];
+}
+/**
+ * An assumption is the reification of a triple. This leverages the
+ * `@annotation` element from JSON-LD-star. Any property in the edition
+ * can be annotated with a belief to express uncertainty or provide
+ * justification for the stated value.
+ */
+export interface Assumption {
+    /**
+     * An optional annotation expressing a belief about this assumption.
+     * Uses the JSON-LD-star `@annotation` mechanism to attach
+     * epistemic metadata (certainty and reasons) to any triple.
+     */
+    '@annotation'?: WithId & {
+        belief: Belief;
+    };
+}
+/**
+ * A value assumption wraps a literal value, e.g. a string, a number, a date, with an optional annotation.
+ * Used for properties where the value itself may be uncertain,
+ * e.g. dates or alignment references.
+ */
+export interface ValueAssumption<ValueT> extends Assumption {
+    /**
+     * The assumed value.
+     */
+    '@value': ValueT;
+}
+/**
+ * A reference assumption wraps a reference (by `@id`) with an optional annotation.
+ * Used when pointing to another entity whose association may be uncertain.
+ */
+export type ReferenceAssumption = Assumption & WithId;
+/**
+ * An object assumption wraps a complex object with an optional annotation.
+ * Used for structured values (e.g. persons, conditions) whose properties
+ * may be uncertain.
+ */
+export type ObjectAssumption<O extends object> = Assumption & O;
+export declare function valueOf<ValueT>(assumption: ValueAssumption<ValueT>): ValueT;
+export declare function valuesOf<ValueT>(assumptions: ValueAssumption<ValueT>[]): ValueT[];
+export declare function idOf(assumption: ReferenceAssumption): string;
+export declare function idsOf(assumptions: ReferenceAssumption[]): string[];
+export declare function assignValue<ValueT>(value: ValueT): ValueAssumption<ValueT>;
+export declare function assignReference(id: string): ReferenceAssumption;
+export declare function assignObject<O extends object>(obj: O): ObjectAssumption<O>;

package/lib/Assumption.js

@@ -0,0 +1,34 @@
+export const certainties = [
+    'true',
+    'likely',
+    'possible',
+    'unlikely',
+    'false'
+];
+export function valueOf(assumption) {
+    return assumption['@value'];
+}
+export function valuesOf(assumptions) {
+    return assumptions.map(a => a['@value']);
+}
+export function idOf(assumption) {
+    return assumption.id;
+}
+export function idsOf(assumptions) {
+    return assumptions.map(a => a.id);
+}
+export function assignValue(value) {
+    return {
+        '@value': value
+    };
+}
+export function assignReference(id) {
+    return {
+        id
+    };
+}
+export function assignObject(obj) {
+    return {
+        ...obj
+    };
+}

package/lib/Collation.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Tolerance used in collation of roll copies.
+ * The start and end tolerances define the acceptable
+ * deviation (in mm) when aligning features across copies.
+ */
 export interface CollationTolerance {
+    /**
+     * Tolerance at the start position of a feature (in mm).
+     */
     toleranceStart: number;
+    /**
+     * Tolerance at the end position of a feature (in mm).
+     */
     toleranceEnd: number;
 }

package/lib/ConditionState.d.ts

@@ -1,9 +1,14 @@
+import { WithType } from "./utils";
 /**
- * Describes the physical condition of a roll or
+ * Physical condition of a roll or
  * of a feature on the roll (e.g. a damaged
  * or unsuccessful perforation).
  */
-export interface ConditionState<T extends string> {
-    type: T;
+export interface ConditionState<T extends string> extends WithType<T> {
+    /**
+     * A free-text description of the condition, providing
+     * details beyond the type classification.
+     * @see crm:P3 has note
+     */
     description?: string;
 }

package/lib/ConditionState.js

@@ -1,6 +1 @@
-/**
- * Describes the physical condition of a roll or
- * of a feature on the roll (e.g. a damaged
- * or unsuccessful perforation).
- */
 export {};

package/lib/Edit.d.ts

@@ -1,21 +1,51 @@
+import { Assumption, ObjectAssumption } from "./Assumption";
 import { Person } from "./Edition";
-import { EditorialAssumption, Motivation } from "./EditorialAssumption";
 import { AnySymbol } from "./Symbol";
-import { WithId } from "./WithId";
-export declare const editMotivations: readonly ["short-dynamic-differentation", "additional-accent", "add-redundancy", "remove-redundancy", "replace-with-equivalent", "shift", "correct-error", "shorten", "prolong"];
-export type EditMotivation = typeof editMotivations[number];
-export type ActorAssignment = EditorialAssumption<'actorAssignment', Person>;
+import { WithId } from "./utils";
+export declare const editTypes: readonly ["short-dynamic-differentation", "additional-accent", "add-redundancy", "remove-redundancy", "replace-with-equivalent", "shift", "correct-error", "shorten", "prolong"];
 /**
- * Actor should be used to indicate the person who
- * (presumably) carried out the edit.
+ * The type of editorial change applied to a symbol or set of symbols.
+ * Classifies the nature of the edit, e.g. whether it corrects an error,
+ * adds an accent, shifts a note, or shortens/prolongs a perforation.
  */
-export interface Edit extends WithId {
-    actor?: ActorAssignment;
-    motivation?: Motivation<EditMotivation>;
+export type EditType = typeof editTypes[number];
+/**
+ * An actor assignment associates a person with an action.
+ * It is an object assumption so that the attribution can be
+ * annotated with a belief about its certainty.
+ */
+export type ActorAssignment = ObjectAssumption<Person>;
+/**
+ * A set of edits transforms a version of a roll into another version.
+ * Edits insert or delete symbols, or both (= replace).
+ * Edits may be motivated by a given set of reasons, e.g.
+ * to add an additional accent or to correct an error.
+ * If an edit is the interpretation of a metamark,
+ * such as a pencil mark, this should be made explicit
+ * using a meaning comprehension on the `@annotation` field.
+ * @see reo:C8 Edit
+ */
+export interface Edit extends WithId, Assumption {
+    type: 'edit';
+    /**
+     * The type of editorial change (e.g. 'correct-error', 'additional-accent').
+     */
+    editType?: EditType;
+    /**
+     * A textual description of the motivation for this edit,
+     * referencing a motivation defined in the version's motivations list.
+     * @see crm:P17 was motivated by
+     */
+    motivation?: string;
+    /**
+     * The symbols to be inserted by this edit.
+     * @see reo:P7 added
+     */
     insert?: AnySymbol[];
-    delete?: AnySymbol[];
-    intentionOf?: AnySymbol[];
+    /**
+     * References (by `@id`) to the symbols to be deleted by this edit.
+     * @see reo:P8 removed
+     */
+    delete?: string[];
 }
 export declare const isEdit: (object: any) => object is Edit;
-export declare const merge: (selection: Edit[]) => Edit;
-export declare const split: (edit: Edit) => Edit[];

package/lib/Edit.js

@@ -1,7 +1,4 @@
-import { v4 } from "uuid";
-import { assign } from "./EditorialAssumption";
-import { dimensionOf } from "./Symbol";
-export const editMotivations = [
+export const editTypes = [
     /**
      * An additional accent that can only be encoded with
      * sforzando on/off due to the short space left between
@@ -18,95 +15,5 @@ export const editMotivations = [
     'prolong',
 ];
 export const isEdit = (object) => {
-    return 'insert' in object || 'delete' in object;
-};
-const arraysIdentical = (a, b) => {
-    let i = a.length;
-    if (i != b.length)
-        return false;
-    while (i--) {
-        if (Array.isArray(a[i]) && Array.isArray(b[i])) {
-            return arraysIdentical(a[i], b[i]);
-        }
-        if (a[i] !== b[i])
-            return false;
-    }
-    return true;
-};
-const guessMotivation = (edit) => {
-    const inserts = (edit.insert || []);
-    const deletes = (edit.delete || []);
-    const types = [
-        inserts.filter(e => e.type === 'expression').map(e => e.expressionType),
-        deletes.filter(e => e.type === 'expression').map(e => e.expressionType)
-    ];
-    if (arraysIdentical(types, [['SlowCrescendoOn', 'SlowCrescendoOff'], []])) {
-        return 'additional-accent';
-    }
-    else if (arraysIdentical(types, [['ForzandoOn', 'ForzandoOff'], []])) {
-        // TODO: check if the inserts are very close
-        // and return 'short-dynamic-differentation'
-        return 'additional-accent';
-    }
-    else if (types.every(t => t.length > 1) && arraysIdentical(types[0], types[1])) {
-        return 'shift';
-    }
-    else if (types[0].length === 0 && types[1].length === 1) {
-        return 'remove-redundancy';
-    }
-    if (inserts.length === 1 && deletes.length === 1) {
-        const insertDim = dimensionOf(inserts[0]).horizontal;
-        const deleteDim = dimensionOf(deletes[0]).horizontal;
-        if (Math.abs(insertDim.from - deleteDim.from) < 5) {
-            const insertLength = Math.abs(insertDim.to - insertDim.from);
-            const deleteLength = Math.abs(deleteDim.to - deleteDim.from);
-            if (insertLength < deleteLength) {
-                return 'shorten';
-            }
-            else {
-                return 'prolong';
-            }
-        }
-    }
-    return 'correct-error';
-};
-export const merge = (selection) => {
-    const result = selection[0];
-    selection
-        .slice(1)
-        .forEach(edit => {
-        if (result.insert) {
-            result.insert.push(...(edit.insert || []));
-        }
-        else {
-            result.insert = edit.insert;
-        }
-        if (result.delete) {
-            result.delete.push(...(edit.delete || []));
-        }
-        else {
-            result.delete = edit.delete;
-        }
-    });
-    return {
-        ...result,
-        id: v4(),
-        motivation: assign('motivationAssignment', guessMotivation(result)),
-    };
-};
-export const split = (edit) => {
-    const result = [];
-    for (const insert of edit.insert ?? []) {
-        result.push({
-            id: v4(),
-            insert: [insert]
-        });
-    }
-    for (const remove of edit.delete ?? []) {
-        result.push({
-            id: v4(),
-            delete: [remove]
-        });
-    }
-    return result;
+    return 'type' in object && object.type === 'edit';
 };

package/lib/Edition.d.ts

@@ -1,54 +1,194 @@
-import { EditorialAssumption } from "./EditorialAssumption";
-import { WithId } from "./WithId";
+import { WithId } from "./utils";
 import { DateAssignment, RollCopy } from "./RollCopy";
 import { Version } from "./Version";
 import { CollationTolerance } from "./Collation";
+import { ObjectAssumption } from "./Assumption";
+/**
+ * A person, e.g. a pianist, editor, publisher, etc.
+ * @see crm:E21 Person
+ */
 export interface Person extends Partial<WithId> {
+    /**
+     * The full name of the person.
+     * @see rdfs:label
+     * @example "Grünfeld, Alfred"
+     */
     name: string;
+    /**
+     * This property can be used to point to a
+     * GND, Wikidata, or similar entry.
+     * @see owl:sameAs
+     * @example "https://d-nb.info/gnd/116888652"
+     */
     sameAs: string[];
+    /**
+     * The role of the person in the context of the edition,
+     * e.g. 'pianist', 'editor', 'publisher', etc.
+     * @see crm:P2 has type
+     */
     role?: string;
 }
+/**
+ * A place, e.g. a recording location, publishing location, etc.
+ * @see crm:E53 Place
+ */
 export interface Place {
+    /**
+     * The name of the place.
+     * @example "Wien"
+     */
     name: string;
+    /**
+     * This property can be used to point to a
+     * geonames or wikidata entry.
+     */
     sameAs: string[];
 }
+/**
+ * This type describes the creation of an edition,
+ * i.e. the editor, publisher, and publication date.
+ * @see lrm:F28 Expression Creation
+ */
 export interface EditionCreation {
+    /**
+     * The person or institution responsible for publishing the edition.
+     * @see crm:P14 carried out by
+     */
     publisher: Person;
+    /**
+     * The date on which the edition was published.
+     * @format date
+     * @see crm:P4 has time-span
+     */
     publicationDate: Date;
+    /**
+     * The tolerance parameters used when collating (aligning)
+     * the different roll copies for this edition.
+     * @see L13 used parameters
+     */
     collationTolerance?: CollationTolerance;
 }
+/**
+ * Describes the event of recording and documents
+ * the persons involved in the process (e.g. pianist),
+ * the place, and the date of the recording.
+ * @see reo:C14 Recording
+ */
 export interface RecordingEvent {
+    /**
+     * Documents the performance which was recorded.
+     * @see lrm:R81 recorded
+     */
     recorded: {
         pianist: Person;
+        /**
+         * This property should point to a standard
+         * URI, e.g. the GND.
+         */
         playing: string;
     };
+    /**
+     * The place where the recording took place.
+     * @see crm:P7 took place at
+     */
     place: Place;
     /**
      * The recording date of the roll. This is a date
      * assignment so that we can state e.g. the catalogue
      * or the roll label which indicates the date of the recording.
+     * @see crm:P4 has time-span
      */
     date: DateAssignment;
+    /**
+     * The version of the roll which was created in
+     * the recording. Since it is usually not handed
+     * down, this is an optional property.
+     * @see lrm:R17 created
+     */
     created?: Version;
 }
+/**
+ * The abstract concept of a roll, identified
+ * by its catalogue number.
+ * @see lrm:F1 Work
+ */
 export interface Roll {
+    /**
+     * The catalogue number of the roll.
+     * @example "WM 225"
+     */
     catalogueNumber: string;
+    /**
+     * @see lrm:R19i was realized through
+     */
     recordingEvent: RecordingEvent;
 }
+/**
+ * The playback tempo of the roll, specified as a starting
+ * and ending speed. The tempo may change over the course
+ * of the roll due to acceleration effects.
+ */
 export interface RollTempo {
+    /**
+     * The tempo at the beginning of the roll.
+     */
     startsWith: number;
+    /**
+     * The tempo at the end of the roll.
+     */
     endsWith: number;
+    /**
+     * The unit of the tempo measurement (e.g. 'ft/min', 'm/min').
+     */
     unit: string;
 }
-export type TempoAssignment = EditorialAssumption<'tempoAssignment', RollTempo>;
+/**
+ * Describes the specific digital edition of a piano roll.
+ * @see lrm:F2 Expression
+ */
 export interface Edition {
+    /**
+     * The base URI for all entities in this edition.
+     * @example "https://edition.encoded-ghosts.org/wm225"
+     */
     base: string;
+    /**
+     * Information about the creation of this edition,
+     * including publisher and publication date.
+     * @see lrm:R17i was created by
+     */
     creation: EditionCreation;
+    /**
+     * The title of the edition.
+     * @see crm:P102 has title
+     * @example "Alfred Grünfeld spielt Robert Schumann, Träumerei"
+     */
     title: string;
+    /**
+     * The license under which the edition is published.
+     * @see dcterms:license
+     * @example "https://creativecommons.org/licenses/by/4.0/"
+     */
     license: string;
+    /**
+     * The roll which is edited in this edition.
+     * @see lrm:R3i realises
+     */
     roll: Roll;
+    /**
+     * The physical roll copies on which this edition is based.
+     */
     copies: RollCopy[];
+    /**
+     * The different versions of the roll on which
+     * this edition is based.
+     * @see lrm:R76 is derivative of
+     */
     versions: Version[];
-    tempoAdjustment?: TempoAssignment;
+    /**
+     * An optional tempo adjustment for playback of the roll,
+     * annotatable with a belief about its correctness.
+     */
+    tempoAdjustment?: ObjectAssumption<RollTempo>;
 }
 export type EditionMetadata = Pick<Edition, 'base' | 'title' | 'license' | 'creation' | 'roll'>;

package/lib/EditionView.d.ts

@@ -0,0 +1,51 @@
+import { CollationTolerance } from "./Collation";
+import { Edition } from "./Edition";
+import { HorizontalSpan, VerticalSpan, AnyFeature } from "./Feature";
+import { AnySymbol, Expression, Note } from "./Symbol";
+import { Version } from "./Version";
+import { NegotiatedEvent } from "./ReproducingSystem";
+export type Path = (string | number)[];
+export declare const getAt: <T>(path: Path, obj: unknown) => T | undefined;
+export declare class EditionView {
+    readonly edition: Edition;
+    /**
+     * Map from id to object
+     */
+    private readonly byId;
+    /**
+     * Map from id to its path within the edition
+     */
+    private readonly paths;
+    /**
+     * Map from id to paths where it is referenced
+     */
+    private readonly links;
+    /**
+     * Dimensions cache: one frequent operation is to find the average
+     * dimensions of a symbol based on its carriers. This cache stores
+     * the computed dimensions for reuse.
+     */
+    constructor(edition: Edition);
+    atPath<T>(path: Path): T | null;
+    indexObjects(): void;
+    get<T>(anyId: string): T | undefined;
+    getAll<T>(anyIds: readonly string[]): T[];
+    getPath(anyId: string): Path | undefined;
+    linksTo(anyId: string): Path[];
+    travelUp(versionId: string, callback: (version: Readonly<Version>) => void): void;
+    carriersOf(symbol: AnySymbol): Readonly<AnyFeature>[];
+    predecessorOf(versionId: string): Readonly<Version> | undefined;
+    dimensionOf(symbol: AnySymbol): Readonly<{
+        horizontal: HorizontalSpan;
+        vertical: VerticalSpan;
+    }> | undefined;
+    snapshot(versionId: string): readonly Readonly<AnySymbol>[];
+    isCollatable(symbolA: AnySymbol, symbolB: AnySymbol, tolerance?: CollationTolerance): boolean;
+    /**
+     * Assigns a generation (depth) to every node.
+     */
+    withGenerations(): Array<Version & {
+        generation: number;
+    }>;
+    simplifySymbol(symbol: Note | Expression): NegotiatedEvent | null;
+}