linked-rolls 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2024-2026 Niels Pfeffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The ontology and type vocabulary in the ontology directory and the
+documentation generated from them are licensed separately under
+Creative Commons Attribution 4.0 International,
+https://creativecommons.org/licenses/by/4.0/.

package/README.md

@@ -13,6 +13,26 @@ and exporting digital editions of piano roll. In particular it allows to:
 This library is the foundation of the
 [Roll Desk](https://github.com/pfefferniels/roll-desk).
 
+## Vocabulary
+
+The JSON-LD export uses the Roll Edition Ontology (REO), namespace
+`https://w3id.org/reo/`, prefix `reo`, alongside CIDOC CRM, LRMoo and
+CRMinf. The ontology lives in `ontology/`, and the context every
+export references is `https://w3id.org/reo/context.jsonld`. The
+ontology, its type vocabulary and the context are published at
+https://pfefferniels.github.io/linked-rolls/reo/; the w3id.org
+identifiers are not registered yet. `ontology/README.md` records the
+naming decisions.
+
+## Format revisions
+
+Files written by linked-rolls 0.1 load unchanged: `importJsonLd`
+recognises their shapes and brings them to the current format, in
+which versions and conditions carry a typology key beside their type,
+the keeper and the production metadata are nodes with a name and
+authority links, and the roll names its reproducing system. Exports
+are always in the current format.
+
 ## Emulation
 
 `Emulation` turns a version of the edition into MIDI. The core of the
@@ -49,6 +69,21 @@ 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.
 
+### Alignment and pairing
+
+A perforation takes its place from the holes that carry it. Two fields
+on a perforation let an editor state where the measurement should give
+way. `alignedWith` names another perforation whose onset this one takes
+in the performance, as a "crescendo off" is meant to fall on the note
+it belongs to. `pairedWith` names a partner whose distance to this one
+is fixed, as a "forzando on" belongs with its "forzando off": whatever
+displaces the one displaces the other. Any two perforations may be
+paired, the relation is symmetric, and it is stated on one side only.
+Both are applied when a version is emulated. `constraintProblems` lists,
+version by version, the cases in which the statements cannot hold: a
+reference or partner that is absent, a perforation claimed by several
+pairs, or a pair whose members are both aligned.
+
 ## Building
 ```
    npm i

package/lib/Assumption.d.ts

@@ -18,6 +18,7 @@ export interface Argumentation<T extends string = 'simpleArgumentation'> extends
  * 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.
+ * @see crminf:I16 Meaning Comprehension
  */
 export interface MeaningComprehension extends Argumentation<'meaningComprehension'> {
     /**
@@ -73,7 +74,7 @@ export interface Belief extends WithId {
     certainty: Certainty;
     /**
      * The argumentations providing reasons for this belief.
-     * @see crminf:J2 was concluded by
+     * @see crminf:J2i was concluded by
      */
     reasons: AnyArgumentation[];
 }
@@ -90,13 +91,17 @@ export interface Assumption {
      * epistemic metadata (certainty and reasons) to any triple.
      */
     '@annotation'?: WithId & {
+        /**
+         * The belief held about the annotated statement.
+         * @see crminf:J4i is subject of
+         */
         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.
+ * e.g. dates.
  */
 export interface ValueAssumption<ValueT> extends Assumption {
     /**

package/lib/ConditionState.d.ts

@@ -3,8 +3,15 @@ import { WithType } from "./utils";
  * Physical condition of a roll or
  * of a feature on the roll (e.g. a damaged
  * or unsuccessful perforation).
+ * @see crm:E3 Condition State
  */
-export interface ConditionState<T extends string> extends WithType<T> {
+export interface ConditionState<T extends string> extends WithType<'ConditionState'> {
+    /**
+     * The kind of condition, from the list the roll or
+     * the kind of feature allows.
+     * @see crm:P2 has type
+     */
+    conditionType: T;
     /**
      * A free-text description of the condition, providing
      * details beyond the type classification.

package/lib/Edit.d.ts

@@ -23,12 +23,13 @@ export type ActorAssignment = ObjectAssumption<Person>;
  * 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
+ * @see reo:Edit
  */
 export interface Edit extends WithId, Assumption {
     type: 'edit';
     /**
      * The type of editorial change (e.g. 'correct-error', 'additional-accent').
+     * @see crm:P2 has type
      */
     editType?: EditType;
     /**
@@ -39,12 +40,12 @@ export interface Edit extends WithId, Assumption {
     motivation?: string;
     /**
      * The symbols to be inserted by this edit.
-     * @see reo:P7 added
+     * @see reo:added
      */
     insert?: AnySymbol[];
     /**
      * References (by `@id`) to the symbols to be deleted by this edit.
-     * @see reo:P8 removed
+     * @see reo:removed
      */
     delete?: string[];
 }

package/lib/Edition.d.ts

@@ -4,50 +4,60 @@ 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
+ * Something with a name and, where one exists, an authority record.
  */
-export interface Person extends Partial<WithId> {
+export interface Named {
     /**
-     * The full name of the person.
+     * The name, e.g. "Grünfeld, Alfred", "Wien", "M. Welte & Söhne".
      * @see rdfs:label
-     * @example "Grünfeld, Alfred"
      */
     name: string;
     /**
-     * This property can be used to point to a
-     * GND, Wikidata, or similar entry.
+     * Authority records for the same thing: GND, Wikidata,
+     * geonames or similar.
      * @see owl:sameAs
      * @example "https://d-nb.info/gnd/116888652"
      */
     sameAs: string[];
+}
+export declare const agentRoles: readonly ["pianist", "editor", "publisher"];
+/**
+ * The role an agent plays in the context of the edition.
+ */
+export type AgentRole = typeof agentRoles[number];
+/**
+ * A person or a group: a pianist, an editor, a publisher,
+ * a manufacturer, a library.
+ * @see crm:E39 Actor
+ */
+export interface Agent extends Named, Partial<WithId> {
     /**
-     * The role of the person in the context of the edition,
-     * e.g. 'pianist', 'editor', 'publisher', etc.
+     * The role of the agent in the context of the edition.
      * @see crm:P2 has type
      */
-    role?: string;
+    role?: AgentRole;
 }
+/**
+ * An agent that is a person.
+ */
+export type Person = Agent;
 /**
  * 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[];
+export interface Place extends Named {
+}
+/**
+ * A term from a vocabulary, such as a roll system or a kind of
+ * paper. A term the type vocabulary knows carries its IRI as `id`.
+ * @see crm:E55 Type
+ */
+export interface Concept extends Named, Partial<WithId> {
 }
 /**
  * This type describes the creation of an edition,
  * i.e. the editor, publisher, and publication date.
- * @see lrm:F28 Expression Creation
+ * @see lrmoo:F28 Expression Creation
  */
 export interface EditionCreation {
     /**
@@ -58,13 +68,13 @@ export interface EditionCreation {
     /**
      * The date on which the edition was published.
      * @format date
-     * @see crm:P4 has time-span
+     * @see dcterms:date
      */
     publicationDate: Date;
     /**
      * The tolerance parameters used when collating (aligning)
      * the different roll copies for this edition.
-     * @see L13 used parameters
+     * Not exported to RDF.
      */
     collationTolerance?: CollationTolerance;
 }
@@ -72,18 +82,23 @@ export interface EditionCreation {
  * 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
+ * @see lrmoo:F28 Expression Creation
  */
 export interface RecordingEvent {
     /**
      * Documents the performance which was recorded.
-     * @see lrm:R81 recorded
+     * @see lrmoo:R81 recorded
      */
     recorded: {
+        /**
+         * The pianist who gave the recorded performance.
+         * @see crm:P14 carried out by
+         */
         pianist: Person;
         /**
          * This property should point to a standard
          * URI, e.g. the GND.
+         * @see lrmoo:R80 performed
          */
         playing: string;
     };
@@ -96,30 +111,39 @@ export interface RecordingEvent {
      * 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
+     * @see dcterms:date
      */
     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
+     * @see lrmoo:R17 created
      */
     created?: Version;
 }
 /**
  * The abstract concept of a roll, identified
  * by its catalogue number.
- * @see lrm:F1 Work
+ * @see lrmoo:F1 Work
  */
 export interface Roll {
     /**
      * The catalogue number of the roll.
      * @example "WM 225"
+     * @see dcterms:identifier
      */
     catalogueNumber: string;
     /**
-     * @see lrm:R19i was realized through
+     * The reproducing system the roll was cut for. A system the
+     * type vocabulary knows carries the IRI of its concept as `id`,
+     * from which the export takes the system's own context, so that
+     * the expression types are read as that system's.
+     * @see crm:P2 has type
+     */
+    system: Concept;
+    /**
+     * @see lrmoo:R19i was realised through
      */
     recordingEvent: RecordingEvent;
 }
@@ -127,24 +151,28 @@ export interface Roll {
  * 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.
+ * @see crm:E54 Dimension
  */
 export interface RollTempo {
     /**
      * The tempo at the beginning of the roll.
+     * @see reo:from
      */
     startsWith: number;
     /**
      * The tempo at the end of the roll.
+     * @see reo:to
      */
     endsWith: number;
     /**
      * The unit of the tempo measurement (e.g. 'ft/min', 'm/min').
+     * @see crm:P91 has unit
      */
     unit: string;
 }
 /**
  * Describes the specific digital edition of a piano roll.
- * @see lrm:F2 Expression
+ * @see lrmoo:F2 Expression
  */
 export interface Edition {
     /**
@@ -155,12 +183,12 @@ export interface Edition {
     /**
      * Information about the creation of this edition,
      * including publisher and publication date.
-     * @see lrm:R17i was created by
+     * @see lrmoo:R17i was created by
      */
     creation: EditionCreation;
     /**
      * The title of the edition.
-     * @see crm:P102 has title
+     * @see dcterms:title
      * @example "Alfred Grünfeld spielt Robert Schumann, Träumerei"
      */
     title: string;
@@ -172,22 +200,24 @@ export interface Edition {
     license: string;
     /**
      * The roll which is edited in this edition.
-     * @see lrm:R3i realises
+     * @see lrmoo:R3i realises
      */
     roll: Roll;
     /**
      * The physical roll copies on which this edition is based.
+     * @see reo:witness
      */
     copies: RollCopy[];
     /**
      * The different versions of the roll on which
      * this edition is based.
-     * @see lrm:R76 is derivative of
+     * @see lrmoo:R75 incorporates
      */
     versions: Version[];
     /**
      * An optional tempo adjustment for playback of the roll,
      * annotatable with a belief about its correctness.
+     * @see reo:tempo
      */
     tempoAdjustment?: ObjectAssumption<RollTempo>;
 }

package/lib/Edition.js

@@ -1 +1 @@
-export {};
+export const agentRoles = ['pianist', 'editor', 'publisher'];

package/lib/Emulation.js

@@ -1,5 +1,6 @@
 import { MIDIControlEvents } from "midifile-ts";
-import { valueOf } from "./Assumption";
+import { idOf } from "./Assumption";
+import { pairsAmong } from "./Symbol";
 /** The punch diameter the edition's copies report, where any of them does. */
 const punchDiameterOf = (view) => {
     const measured = view.edition.copies
@@ -13,6 +14,33 @@ const propertiesOf = (view) => ({
     punchDiameter: punchDiameterOf(view),
     tempo: view.edition.tempoAdjustment
 });
+/**
+ * How far each event has to move, in mm, for the alignments to hold:
+ * an aligned event takes the onset of its reference, and a paired
+ * event follows its partner so that the distance between the two
+ * is kept. Events that stay where they are do not appear.
+ */
+const displacementsOf = (events) => {
+    const byId = new Map(events.map(event => [event.id, event]));
+    const referenceOf = (event) => event.alignedWith && byId.get(idOf(event.alignedWith));
+    const alignedOnsetOf = (event, visited = new Set()) => {
+        const reference = referenceOf(event);
+        if (!reference || visited.has(event.id))
+            return event.horizontal.from;
+        return alignedOnsetOf(reference, visited.add(event.id));
+    };
+    const displacements = new Map(events
+        .filter(event => referenceOf(event) !== undefined)
+        .map((event) => [event, alignedOnsetOf(event) - event.horizontal.from]));
+    pairsAmong(events).forEach(([one, other]) => {
+        const shared = displacements.get(one) ?? displacements.get(other);
+        if (shared === undefined)
+            return;
+        displacements.set(one, shared);
+        displacements.set(other, shared);
+    });
+    return displacements;
+};
 /**
  * A version of the edition, performed: the symbols are negotiated into
  * placed events, the reproducing system plays them, and the result goes
@@ -62,15 +90,9 @@ export class Emulation {
         this.options = options;
     }
     applyConstraints() {
-        this.negotiatedEvents
-            .filter((e) => e.alignedWith !== undefined)
-            .forEach(e => {
-            const ref = this.negotiatedEvents.find(ev => ev.id === valueOf(e.alignedWith));
-            if (!ref)
-                return;
-            const distance = ref.horizontal.from - e.horizontal.from;
-            e.horizontal.from += distance;
-            e.horizontal.to += distance;
+        displacementsOf(this.negotiatedEvents).forEach((distance, event) => {
+            event.horizontal.from += distance;
+            event.horizontal.to += distance;
         });
     }
     emulateVersion(version, view, { range, skipToFirstNote = false } = {}) {

package/lib/Feature.d.ts

@@ -6,6 +6,7 @@ import { PartialBy, WithId, WithType } from "./utils";
  * Describes the horizontal extent of a feature on the roll,
  * measured in millimeters from the beginning of the roll.
  * The `from` value is the start position and `to` is the end position.
+ * @see crm:E54 Dimension
  */
 export interface HorizontalSpan {
     /**
@@ -17,11 +18,13 @@ export interface HorizontalSpan {
     /**
      * The start position of the feature in millimeters
      * from the beginning of the roll.
+     * @see reo:from
      */
     from: number;
     /**
      * The end position of the feature in millimeters
      * from the beginning of the roll.
+     * @see reo:to
      */
     to: number;
 }
@@ -29,20 +32,23 @@ export interface HorizontalSpan {
  * Describes the vertical extent of a feature on the roll,
  * measured in track numbers. Track numbers correspond to
  * positions on the tracker bar.
+ * @see crm:E54 Dimension
  */
 export interface VerticalSpan {
     /**
-     * The unit of measurement for horizontal positions.
+     * The unit of measurement for vertical positions.
      * @see crm:P91 has unit
      */
     unit: 'track';
     /**
      * The start track number of the feature.
+     * @see reo:from
      */
     from: number;
     /**
      * The end track number, if the feature spans multiple tracks.
      * If omitted, the feature occupies a single track.
+     * @see reo:to
      */
     to?: number;
 }
@@ -51,12 +57,12 @@ export type FeatureType = typeof featureTypes[number];
 /**
  * A physical feature on the roll, e.g. a perforation, a tear, a mark, etc.,
  * defined by its horizontal and vertical position and extent.
- * @see reo:C2 Feature
+ * @see crm:E26 Physical Feature
  */
 export interface RollFeature<T extends FeatureType, DamageT extends string> extends WithId, WithType<T> {
     /**
      * IIIF region pointing to a depiction of this feature in the scan.
-     * @see crm:P62 is depicted by
+     * @see crm:P138i has representation
      */
     depiction?: string;
     /**
@@ -72,6 +78,7 @@ export interface RollFeature<T extends FeatureType, DamageT extends string> exte
     /**
      * This can be used e.g. to indicate a perforation
      * which is torn out or in any other way damaged.
+     * @see crm:P44 has condition
      */
     condition?: ObjectAssumption<ConditionState<DamageT>>;
 }
@@ -90,7 +97,10 @@ export interface Hole extends RollFeature<'Hole', typeof conditions.Hole[number]
     /**
      * The punching pattern of the hole. Regular holes have evenly-spaced
      * bridges, accelerating holes have decreasing bridge widths, and
-     * staggering holes alternate between adjacent tracks (cf. Phillips).
+     * staggering holes do not align in rows across the tracks, the mark
+     * of an asynchronous perforator with a separate driver for each
+     * punch (Phillips 2016, p. 112).
+     * @see reo:pattern
      */
     pattern?: 'regular' | 'accelerating' | 'staggering';
 }
@@ -110,23 +120,27 @@ export type WritingMethod = typeof writingMethods[number];
  * A piece of writing found on the roll, such as a label,
  * catalogue number, or annotation. Writings have a method
  * of production and a transcription of their content.
+ * @see crm:E25 Human-Made Feature
  */
 export interface Writing extends Trace<'Writing'> {
     /**
      * The method by which this writing was produced
      * (e.g. through print, handwriting, or stamping).
+     * @see crm:P2 has type
      */
     method: WritingMethod;
     /**
      * A transcription of the text content of the writing.
      * This is an object assumption so that the transcription
      * can be annotated with a belief about its correctness.
+     * @see crm:P128 carries
      */
     transcription: ObjectAssumption<Omit<Text, 'carriers'>>;
 }
 /**
  * A visible mark on the roll, such as a pencil mark,
  * ink mark, or other non-textual annotation.
+ * @see crm:E25 Human-Made Feature
  */
 export interface Mark extends Trace<'Mark'> {
 }
@@ -135,6 +149,7 @@ export interface Mark extends Trace<'Mark'> {
  * Glued-on features are typically used to cover perforations (for corrections)
  * or to reinforce damaged areas. They may themselves carry other features
  * such as writings or additional holes.
+ * @see crm:E22 Human-Made Object
  */
 export interface GluedOn extends RollFeature<'GluedOn', typeof conditions.GluedOn[number]> {
     /**

package/lib/Plan.js

@@ -158,6 +158,7 @@ export class CreateVersion extends BasePlan {
         result.push(draft => {
             draft.copies.push(this.copy);
             const newVersion = {
+                type: 'Version',
                 siglum: this.siglum,
                 id: v4(),
                 edits: asSymbols(this.copy.features).map((symbol) => {
@@ -168,7 +169,7 @@ export class CreateVersion extends BasePlan {
                         delete: [],
                     };
                 }),
-                type: 'edition',
+                versionType: 'edition',
                 motivations: []
             };
             draft.versions.push(newVersion);