linked-rolls 0.0.1

package/README.md

@@ -0,0 +1,18 @@
+# linked-rolls
+
+linked-rolls is a lightweight Typescript library for creating, manipulating
+and exporting digital editions of piano roll. In particular it allows to:
+
+  - import piano rolls from different formats (such
+    as SUPRA's roll analysis files, DSP, etc.)
+  - collate differing piano roll copies
+  - create an manipulate editorial assumptions 
+  - export the edition as JSON-LD (based on the 
+    linked-rolls ontology)
+
+
+## Building
+```
+   npm i
+   npm run build
+```

package/lib/Collation.d.ts

@@ -0,0 +1,4 @@
+export interface CollationTolerance {
+    toleranceStart: number;
+    toleranceEnd: number;
+}

package/lib/Collation.js

@@ -0,0 +1 @@
+export {};

package/lib/Condition.d.ts

@@ -0,0 +1,10 @@
+import { WithId } from "./WithId";
+/**
+ * Describes the 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> extends WithId {
+    type: T;
+    description?: string;
+}

package/lib/Condition.js

@@ -0,0 +1 @@
+export {};

package/lib/ConditionState.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Describes the 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;
+    description?: string;
+}

package/lib/ConditionState.js

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,21 @@
+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>;
+/**
+ * Actor should be used to indicate the person who
+ * (presumably) carried out the edit.
+ */
+export interface Edit extends WithId {
+    actor?: ActorAssignment;
+    motivation?: Motivation<EditMotivation>;
+    insert?: AnySymbol[];
+    delete?: AnySymbol[];
+    intentionOf?: AnySymbol[];
+}
+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

@@ -0,0 +1,112 @@
+import { v4 } from "uuid";
+import { assign } from "./EditorialAssumption";
+import { dimensionOf } from "./Symbol";
+export const editMotivations = [
+    /**
+     * An additional accent that can only be encoded with
+     * sforzando on/off due to the short space left between
+     * the notes to be differentiated.
+     */
+    'short-dynamic-differentation',
+    'additional-accent',
+    'add-redundancy',
+    'remove-redundancy',
+    'replace-with-equivalent',
+    'shift',
+    'correct-error',
+    'shorten',
+    '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;
+};

package/lib/Edition.d.ts

@@ -0,0 +1,54 @@
+import { EditorialAssumption } from "./EditorialAssumption";
+import { WithId } from "./WithId";
+import { DateAssignment, RollCopy } from "./RollCopy";
+import { Version } from "./Version";
+import { CollationTolerance } from "./Collation";
+export interface Person extends Partial<WithId> {
+    name: string;
+    sameAs: string[];
+    role?: string;
+}
+export interface Place {
+    name: string;
+    sameAs: string[];
+}
+export interface EditionCreation {
+    publisher: Person;
+    publicationDate: Date;
+    collationTolerance?: CollationTolerance;
+}
+export interface RecordingEvent {
+    recorded: {
+        pianist: Person;
+        playing: string;
+    };
+    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.
+     */
+    date: DateAssignment;
+    created?: Version;
+}
+export interface Roll {
+    catalogueNumber: string;
+    recordingEvent: RecordingEvent;
+}
+export interface RollTempo {
+    startsWith: number;
+    endsWith: number;
+    unit: string;
+}
+export type TempoAssignment = EditorialAssumption<'tempoAssignment', RollTempo>;
+export interface Edition {
+    base: string;
+    creation: EditionCreation;
+    title: string;
+    license: string;
+    roll: Roll;
+    copies: RollCopy[];
+    versions: Version[];
+    tempoAdjustment?: TempoAssignment;
+}
+export type EditionMetadata = Pick<Edition, 'base' | 'title' | 'license' | 'creation' | 'roll'>;

package/lib/Edition.js

@@ -0,0 +1 @@
+export {};

package/lib/EditorialAssumption.d.ts

@@ -0,0 +1,67 @@
+import { WithId } from "./WithId";
+import { Person } from "./Edition";
+export declare const certainties: readonly ["true", "likely", "possible", "unlikely", "false"];
+export type Certainty = typeof certainties[number];
+export type WithActor = {
+    actor?: Person;
+};
+export type WithNote = {
+    note?: string;
+};
+export interface Argumentation<T extends string = 'simpleArgumentation'> extends WithActor, WithNote {
+    type: T;
+}
+export interface MeaningComprehension<T> extends Argumentation<'meaningComprehension'> {
+    comprehends: T[];
+}
+export interface Inference extends Argumentation<'inference'> {
+    premises: Belief[];
+}
+export interface BeliefAdoption extends Argumentation<'beliefAdoption'> {
+    note: string;
+}
+export type AnyArgumentation = MeaningComprehension<any> | Inference | BeliefAdoption | Argumentation;
+export declare function isMeaningComprehension<AboutT>(object: AnyArgumentation, aboutGuard: (x: any) => x is AboutT): object is MeaningComprehension<AboutT>;
+export interface Belief extends WithId {
+    type: 'belief';
+    certainty: Certainty;
+    reasons: AnyArgumentation[];
+}
+/**
+ * An editorial assumpton is always a One-Proposition Set.
+ */
+export interface EditorialAssumption<Name, AssignedType> extends WithId {
+    type: Name;
+    assigned: AssignedType;
+    belief?: Belief;
+}
+export declare function flat<Name, Type>(assumption: EditorialAssumption<Name, Type>): Type;
+export declare function flat<Name, Type>(assumption: EditorialAssumption<Name, Type>[]): Type[];
+export declare function assign<Type extends string, T>(type: Type, object: T): EditorialAssumption<Type, T>;
+export type DimensionMarker = {
+    point: 'start' | 'end';
+    of: Symbol;
+};
+type PlacementType = 'after' | 'before' | 'with';
+export interface Constraint {
+    placed: DimensionMarker;
+    placement: PlacementType;
+    relativeTo: DimensionMarker | {
+        number: number;
+        unit: string;
+    };
+}
+export interface Motivation<MotivationT> extends EditorialAssumption<'motivationAssignment', MotivationT> {
+}
+export declare const isMotivation: (object: any) => object is Motivation<any>;
+export interface QuestionMaking extends WithActor {
+    premises: (Belief | Question)[];
+    raise: Question;
+}
+/**
+ * Modelled on IAM's Question, cf. M. Doerr et al., p. 12
+ */
+export interface Question {
+    question: string;
+}
+export {};

package/lib/EditorialAssumption.js

@@ -0,0 +1,26 @@
+import { v4 } from "uuid";
+export const certainties = [
+    'true',
+    'likely',
+    'possible',
+    'unlikely',
+    'false'
+];
+export function isMeaningComprehension(object, aboutGuard) {
+    return object.type === 'meaningComprehension' && object.comprehends.every(aboutGuard);
+}
+export function flat(assumption) {
+    return Array.isArray(assumption)
+        ? assumption.map(a => a.assigned)
+        : assumption.assigned;
+}
+export function assign(type, object) {
+    return {
+        type,
+        id: v4(),
+        assigned: object
+    };
+}
+export const isMotivation = (object) => {
+    return 'type' in object && object.type === 'motivationAssignment';
+};

package/lib/Emulation.d.ts

@@ -0,0 +1,76 @@
+import { MidiFile } from "midifile-ts";
+import { AnySymbol, Expression, Note } from "./Symbol";
+import { PlaceTimeConversion } from "./PlaceTimeConversion";
+import { Version } from "./Version";
+import { RollFeature } from "./Feature";
+import { RollTempo } from "./Edition";
+interface PerformedRollFeature<T> {
+    type: T;
+    performs: (AnySymbol | NegotiatedEvent);
+    at: number;
+}
+interface PerformedNoteEvent<T> extends PerformedRollFeature<T> {
+    pitch: number;
+    velocity: number;
+}
+export interface PerformedNoteOnEvent extends PerformedNoteEvent<'noteOn'> {
+}
+export interface PerformedNoteOffEvent extends PerformedNoteEvent<'noteOff'> {
+}
+export interface PerformedSustainPedalOnEvent extends PerformedRollFeature<'sustainPedalOn'> {
+}
+export interface PerformedSustainPedalOffEvent extends PerformedRollFeature<'sustainPedalOff'> {
+}
+export interface PerformedSoftPedalOnEvent extends PerformedRollFeature<'softPedalOn'> {
+}
+export interface PerformedSoftPedalOffEvent extends PerformedRollFeature<'softPedalOff'> {
+}
+export type AnyPerformedRollFeature = PerformedNoteOnEvent | PerformedNoteOffEvent | PerformedSustainPedalOnEvent | PerformedSustainPedalOffEvent | PerformedSoftPedalOnEvent | PerformedSoftPedalOffEvent;
+type AssumedPhysicalTimeSpan = {
+    assumedPhysicalTime?: [number, number];
+};
+export type NegotiatedEvent = Omit<Note | Expression, 'carriers'> & Pick<RollFeature, 'horizontal' | 'vertical'> & AssumedPhysicalTimeSpan;
+export type EmulationOptions = {
+    welte_p: number;
+    welte_f: number;
+    welte_mf: number;
+    welte_loud: number;
+    slow_decay_rate: number;
+    fastC_decay_rate: number;
+    fastD_decay_rate: number;
+    trackerBarDiameter: number;
+    punchExtensionFraction: number;
+    slow_step?: number;
+    fastC_step?: number;
+    fastD_step?: number;
+    division: number;
+};
+export declare class Emulation {
+    placeTimeConversion: PlaceTimeConversion;
+    midiEvents: (AnyPerformedRollFeature)[];
+    negotiatedEvents: NegotiatedEvent[];
+    trebleVelocities: number[];
+    bassVelocities: number[];
+    startTempo?: number;
+    endTempo?: number;
+    source?: string;
+    options: EmulationOptions;
+    constructor(options?: EmulationOptions);
+    private findRollTempo;
+    private assignPhysicalTime;
+    private applyTrackerBarExtension;
+    private convertEventsToMIDI;
+    emulateFromRoll(events: (Note | Expression)[]): AnyPerformedRollFeature[];
+    emulateVersion(version: Version, rollTempo?: RollTempo, skipToFirstNote?: boolean): AnyPerformedRollFeature[];
+    /**
+     * The original code of the calculateVelocities() method,
+     * written by Kitty Shi and Craig Stuart Sapp,
+     * was taken from the midi2exp project (https://github.com/pianoroll/midi2exp)
+     * and adapted to the different data representation.
+     */
+    calculateVelocities(scope: 'treble' | 'bass'): void;
+    private insertNote;
+    findEventsPerforming(id: string): AnyPerformedRollFeature[];
+    asMIDI(): MidiFile;
+}
+export {};