linked-rolls 0.0.1 → 0.1.0

package/lib/Plan.js

@@ -0,0 +1,555 @@
+import { getAt } from "./EditionView";
+import { v4 } from "uuid";
+import { asSymbols } from "./RollCopy";
+import { assignReference, idOf } from "./Assumption";
+export const isPlan = (obj) => {
+    return obj && typeof obj.build === 'function' && typeof obj.setView === 'function';
+};
+export class BasePlan {
+    constructor() {
+        Object.defineProperty(this, "view", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "setView", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (view) => {
+                this.view = view;
+            }
+        });
+    }
+}
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export class ConnectVersions extends BasePlan {
+    constructor(childId, parentId, tolerance = {
+        toleranceEnd: 5,
+        toleranceStart: 5
+    }) {
+        super();
+        Object.defineProperty(this, "childId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: childId
+        });
+        Object.defineProperty(this, "parentId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: parentId
+        });
+        Object.defineProperty(this, "tolerance", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: tolerance
+        });
+    }
+    build() {
+        if (!this.view)
+            return [];
+        const view = this.view;
+        const result = [];
+        const parentSnapshot = view.snapshot(this.parentId);
+        const childSnapshot = view.snapshot(this.childId);
+        const treatedSymbols = [];
+        // can the symbol be collated with any of the
+        // symbols of the tradition, i.e. the ones 
+        // included in the current snapshot?
+        const insertions = [...childSnapshot];
+        for (const symbol of childSnapshot) {
+            parentSnapshot
+                .filter(toCompare => view.isCollatable(symbol, toCompare, this.tolerance))
+                .forEach(parentSymbol => {
+                result.push(draft => {
+                    const symbolPath = view.getPath(parentSymbol.id);
+                    if (!symbolPath)
+                        return;
+                    const correspSymbol = getAt(symbolPath, draft);
+                    if (!correspSymbol)
+                        return;
+                    correspSymbol.carriers.push(...symbol.carriers);
+                });
+                insertions.splice(insertions.indexOf(symbol), 1);
+                treatedSymbols.push(parentSymbol);
+            });
+        }
+        const edits = insertions.map((symbol) => {
+            return {
+                type: 'edit',
+                id: v4(),
+                insert: [symbol],
+                delete: [],
+            };
+        });
+        const deletions = parentSnapshot.filter(sym => {
+            return !treatedSymbols.includes(sym);
+        });
+        for (const symbol of deletions) {
+            edits.push({
+                type: 'edit',
+                id: v4(),
+                insert: [],
+                delete: [symbol.id],
+            });
+        }
+        result.push(draft => {
+            const v = draft.versions.find(v => v.id === this.childId);
+            if (!v)
+                return;
+            v.edits = edits;
+            v.basedOn = assignReference(this.parentId);
+        });
+        return result;
+    }
+}
+/**
+ * Walks through the versions. If it finds a symbol that is still
+ * part of the tradition (i.e. it is included in the current snapshot)
+ * and is equivalent with the given symbol, it will add the feature
+ * carrying the symbol to the collated symbol. Otherwise, the
+ * given symbol will be added to the current version's insertions.
+ *
+ * All symbols of the tradition that are not included in the given
+ * symbols are considered to be deleted.
+ *
+ * @param creation
+ * @param symbols
+ * @returns
+ */
+export class CreateVersion extends BasePlan {
+    constructor(siglum, copy) {
+        super();
+        Object.defineProperty(this, "siglum", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: siglum
+        });
+        Object.defineProperty(this, "copy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: copy
+        });
+    }
+    build() {
+        const view = this.view;
+        if (!view)
+            return [];
+        const result = [];
+        result.push(draft => {
+            draft.copies.push(this.copy);
+            const newVersion = {
+                siglum: this.siglum,
+                id: v4(),
+                edits: asSymbols(this.copy.features).map((symbol) => {
+                    return {
+                        type: 'edit',
+                        id: v4(),
+                        insert: [symbol],
+                        delete: [],
+                    };
+                }),
+                type: 'edition',
+                motivations: []
+            };
+            draft.versions.push(newVersion);
+        });
+        return result;
+    }
+}
+/**
+ * Creates a new version based on the given version
+ * calculating the effect of a cover on existing symbols.
+ 
+export class CoverPerforation extends BasePlan {
+    constructor(
+        private copyId: string,
+        private versionId: string,
+        private coverDimension: { horizontal: HorizontalSpan, vertical: VerticalSpan },
+        private material: string | undefined = undefined,
+    ) {
+        super()
+    }
+
+    build(): EditionOp[] {
+        const view = this.view
+        if (!view) return []
+
+        return [
+            (draft: Draft<Edition>): void => {
+                const version = draft.versions.find(v => v.id === this.versionId)
+                const copy = draft.copies.find(c => c.id === this.copyId)
+                if (!version || !copy) return
+
+                // find perforations in the snapshot that
+                // overlap with the cover
+                const overlappingSymbols =
+                    view.snapshot(this.versionId)
+                        .filter(symbol => {
+                            const dimension = view.dimensionOf(symbol)
+                            if (!dimension) return false
+
+                            return (
+                                (symbol.type === 'note' || symbol.type === 'expression') &&
+                                overlaps(dimension, this.coverDimension)
+                            )
+                        })
+
+                if (!overlappingSymbols.length) return undefined
+
+                const deepClone = JSON.parse(JSON.stringify(overlappingSymbols)) as AnySymbol[]
+
+                for (const symbol of deepClone) {
+                    //symbol.id = v4();
+                    const dimension = structuredClone(view.dimensionOf(symbol))
+                    if (!dimension) continue
+
+                    // check if the cover partially covers the beginning
+                    if (dimension.horizontal.from >= this.coverDimension.horizontal.from &&
+                        dimension.horizontal.from <= this.coverDimension.horizontal.to
+                    ) {
+                        dimension.horizontal.from = this.coverDimension.horizontal.to
+                    }
+
+                    // check if the cover partially covers the ending
+                    if (dimension.horizontal.to >= this.coverDimension.horizontal.from &&
+                        dimension.horizontal.to <= this.coverDimension.horizontal.to
+                    ) {
+                        dimension.horizontal.to = this.coverDimension.horizontal.from
+                    }
+
+                    const newFeature: RollFeature = {
+                        ...dimension,
+                        id: v4(),
+                    }
+
+                    copy.features.push(newFeature)
+                    symbol.id = `symbol-${v4().slice(0, 8)}`
+                    symbol.carriers = [assignReference(newFeature.id)]
+                }
+
+                const coverId = `cover-${v4().slice(0, 8)}`
+                copy.features.push({
+                    ...this.coverDimension,
+                    id: coverId,
+                })
+
+                const edit: Edit = {
+                    type: 'edit',
+                    id: v4(),
+                    delete: overlappingSymbols.map(s => s.id),
+                    insert: deepClone,
+                    intentionOf: [{
+                        type: 'cover',
+                        id: v4(),
+                        note: this.material,
+                        carriers: [assignReference(coverId)],
+                    }]
+                }
+
+                draft.versions.push({
+                    edits: [edit],
+                    id: v4(),
+                    basedOn: assignReference(version.id),
+                    siglum: version.siglum + ' rev',
+                    type: 'authorised-revision',
+                    motivations: [
+                        {
+                            type: 'motivation',
+                            note: 'Stanzfehler korrigiert',
+                            id: v4(),
+                        }
+                    ],
+                })
+            }]
+    }
+}
+    */
+export class DetachVersion extends BasePlan {
+    constructor(versionId) {
+        super();
+        Object.defineProperty(this, "versionId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: versionId
+        });
+    }
+    build() {
+        if (!this.view)
+            return [];
+        const snapshot = this.view.snapshot(this.versionId);
+        const newEdits = snapshot.map((symbol) => ({
+            type: 'edit',
+            id: v4(),
+            insert: [symbol],
+            delete: [],
+        }));
+        return [draft => {
+                const v = draft.versions.find(ver => ver.id === this.versionId);
+                if (!v)
+                    return;
+                v.edits = newEdits;
+                delete v.basedOn;
+                v.motivations = [];
+            }];
+    }
+}
+export class RemoveFeature extends BasePlan {
+    constructor(copyID, featureIDs) {
+        super();
+        Object.defineProperty(this, "copyID", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: copyID
+        });
+        Object.defineProperty(this, "featureIDs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: featureIDs
+        });
+    }
+    build() {
+        const view = this.view;
+        if (!view)
+            return [];
+        return [
+            (draft) => {
+                const copy = draft.copies.find(c => c.id === this.copyID);
+                if (!copy)
+                    return;
+                copy.features = copy.features.filter(f => !this.featureIDs.includes(f.id));
+                this.featureIDs.forEach(featureId => {
+                    // expect a path of format:
+                    // ['versions', index, 'edits', index, 'insert', index, 'carriers', index, 'id']
+                    const carrierPath = view.linksTo(featureId).at(0);
+                    if (!carrierPath)
+                        return;
+                    // expect to find the parent symbol at:
+                    // ['versions', index, 'edits', index, 'insert', index]
+                    const symbol = getAt(carrierPath.slice(0, 6), draft);
+                    if (!symbol)
+                        return;
+                    symbol.carriers = symbol.carriers.filter(c => idOf(c) !== featureId);
+                    // if the symbol has no more carriers, remove it
+                    if (symbol.carriers.length === 0) {
+                        // expect to find the parent edit at:
+                        // ['versions', index, 'edits', index]
+                        const inserts = getAt(carrierPath.slice(0, 5), draft);
+                        if (!inserts)
+                            return;
+                        inserts.splice(inserts.findIndex(s => s.id === symbol.id), 1);
+                        if (inserts.length === 0) {
+                            const edit = getAt(carrierPath.slice(0, 4), draft);
+                            if (!edit)
+                                return;
+                            if (!edit.insert?.length && !edit.delete?.length) {
+                                const edits = getAt(carrierPath.slice(0, 3), draft);
+                                if (!edits)
+                                    return;
+                                edits.splice(edits.findIndex(e => e.id === edit.id), 1);
+                            }
+                        }
+                    }
+                });
+            }
+        ];
+    }
+}
+export class MergeEdits extends BasePlan {
+    constructor(versionId, toMerge) {
+        super();
+        Object.defineProperty(this, "versionId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: versionId
+        });
+        Object.defineProperty(this, "toMerge", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: toMerge
+        });
+    }
+    guessMotivation(edit) {
+        const view = this.view;
+        if (!view)
+            return 'correct-error';
+        const inserts = (edit.insert || []);
+        const deletes = view.getAll(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 = view.dimensionOf(inserts[0])?.horizontal;
+            const deleteDim = view.dimensionOf(deletes[0])?.horizontal;
+            if (!insertDim || !deleteDim) {
+                return 'correct-error';
+            }
+            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';
+    }
+    build() {
+        const view = this.view;
+        if (!view)
+            return [];
+        const result = structuredClone(this.toMerge[0]);
+        this.toMerge
+            .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;
+            }
+        });
+        const edit = {
+            ...result,
+            id: v4(),
+            motivation: this.guessMotivation(result),
+        };
+        return ([draft => {
+                const version = draft.versions.find(v => v.id === this.versionId);
+                if (!version)
+                    return;
+                // remove all edits that were merged
+                for (const e of this.toMerge) {
+                    const index = version.edits.findIndex(ve => ve.id === e.id);
+                    if (index !== -1)
+                        version.edits.splice(index, 1);
+                }
+                version.edits.push(edit);
+            }]);
+    }
+}
+export class SplitEdit extends BasePlan {
+    constructor(versionId, toSplit) {
+        super();
+        Object.defineProperty(this, "versionId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: versionId
+        });
+        Object.defineProperty(this, "toSplit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: toSplit
+        });
+    }
+    build() {
+        const view = this.view;
+        if (!view)
+            return [];
+        const result = [];
+        for (const insert of this.toSplit.insert ?? []) {
+            result.push({
+                type: 'edit',
+                id: v4(),
+                insert: [insert]
+            });
+        }
+        for (const remove of this.toSplit.delete ?? []) {
+            result.push({
+                type: 'edit',
+                id: v4(),
+                delete: [remove]
+            });
+        }
+        return ([draft => {
+                const version = draft.versions.find(v => v.id === this.versionId);
+                if (!version)
+                    return;
+                // remove the edit that is split
+                const index = version.edits.findIndex(ve => ve.id === this.toSplit.id);
+                if (index !== -1)
+                    version.edits.splice(index, 1);
+                version.edits.push(...result);
+            }]);
+    }
+}
+/*
+type LazyDimension = Partial<{ from: number, to: number }>;
+
+type LazyArea = {
+    horizontal: LazyDimension;
+    vertical: LazyDimension;
+}
+
+const overlaps = (a: LazyArea, b: LazyArea): boolean => {
+    const overlapsDimension = (a: LazyDimension, b: LazyDimension): boolean =>
+        (a.from ?? 0) < (b.to ?? Infinity) && (b.from ?? 0) < (a.to ?? Infinity);
+
+    // console.log('do the dimensions overlap?', a, b)
+
+    return overlapsDimension(a.horizontal, b.horizontal);
+}
+    */
+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;
+};

package/lib/ReproducingSystem.d.ts

@@ -0,0 +1,80 @@
+import { RollTempo } from "./Edition";
+import { Hole } from "./Feature";
+import { Expression, Note } from "./Symbol";
+import { TrackerBar } from "./TrackerBar";
+/**
+ * A note or expression of a version with the dimensions of its carriers
+ * averaged in and the editorial assumptions applied, which is all a
+ * performance needs to know of a symbol.
+ */
+export type NegotiatedEvent = Omit<Note | Expression, 'carriers'> & Pick<Hole, 'horizontal' | 'vertical'>;
+interface PerformedRollFeature<T> {
+    type: T;
+    performs: NegotiatedEvent;
+    /** Seconds from the beginning of the roll. */
+    at: number;
+}
+interface PerformedNoteEvent<T> extends PerformedRollFeature<T> {
+    pitch: number;
+    velocity: number;
+}
+export interface PerformedNoteOnEvent extends PerformedNoteEvent<'noteOn'> {
+}
+export interface PerformedNoteOffEvent extends PerformedNoteEvent<'noteOff'> {
+}
+/**
+ * One step of a pedal. A pedal driven by a bellows takes time to travel,
+ * so a single perforation results in a run of these; `performs` is the
+ * perforation whose reading the step follows from.
+ */
+export interface PerformedPedalEvent extends PerformedRollFeature<'damper' | 'hammerRail'> {
+    /** 0 with the pedal up and 127 with it fully down. */
+    value: number;
+}
+export type AnyPerformedRollFeature = PerformedNoteOnEvent | PerformedNoteOffEvent | PerformedPedalEvent;
+interface CurveSamples {
+    readonly name: string;
+    /** Paper position of each sample, in mm from the beginning of the roll. */
+    readonly place: Float64Array;
+    readonly seconds: Float64Array;
+    /**
+     * Position between the two ends of a travel: 0 with a bellows open and
+     * 1 with it closed, 0 with a pedal up and 1 with it down.
+     */
+    readonly travel: Float64Array;
+}
+/** The dynamics of one part of the keyboard, with the velocity the travel maps onto. */
+export type DynamicsCurve = CurveSamples & {
+    readonly kind: 'dynamics';
+    readonly velocity: Float64Array;
+};
+export type PedalCurve = CurveSamples & {
+    readonly kind: 'pedal';
+};
+export type EmulatedCurve = DynamicsCurve | PedalCurve;
+/** What the edition records about the roll that a mechanism may want to know. */
+export type RollProperties = {
+    /** Diameter of the punches in mm, where the copies record it. */
+    punchDiameter?: number;
+    /** The tempo the edition adjusts the roll to, where it states one. */
+    tempo?: RollTempo;
+};
+export type Performance = {
+    readonly events: readonly AnyPerformedRollFeature[];
+    readonly curves: readonly EmulatedCurve[];
+};
+/**
+ * A reproducing piano as the edition sees it, from two sides: the tracker
+ * bar reads the holes into symbols, and the mechanism plays the symbols.
+ * Implementations live outside the core of this library, so that it does
+ * not depend on any one instrument's model; `linked-rolls/welte-t100` is
+ * the first.
+ */
+export interface ReproducingSystem<Options extends object> {
+    readonly name: string;
+    readonly trackerBar: TrackerBar;
+    readonly defaultOptions: Options;
+    /** Performs the events of a version, given in order of place. */
+    perform(events: readonly NegotiatedEvent[], options: Options, roll: RollProperties): Performance;
+}
+export {};