import { ReferenceAssumption } from "./Assumption.js";
import { WithId } from "../shared/utils.js";
/**
 * A symbol is an abstract musical or textual entity carried by one or more
 * physical features on the roll. Symbols are the result of interpreting
 * the physical features (chains of holes, writings, etc.) on the roll copies.
 * @see crm:E90 Symbolic Object
 * @category Format types
 */
export interface Symbol<T extends string> extends WithId {
    type: T;
    /**
     * References to the physical features (e.g. chains of holes) on the roll copies
     * that carry this symbol. Since the association might be debatable,
     * it can be annotated. There might be e.g. doubts about the meaning
     * and correct transcription of a feature on a physical roll.
     * This points to a feature by its `@id`.
     * @see crm:P128i is carried by
     */
    carriers: ReferenceAssumption[];
}
/**
 * Whether the object is a symbol: a note, an expression or a text.
 * @category Lookups
 */
export declare const isSymbol: (object: any) => object is AnySymbol;
/**
 * Whether the symbol is a command, a note or an expression, rather than
 * a text.
 * @category Lookups
 */
export declare const isCommand: (symbol: object | undefined) => symbol is AnyCommand;
/**
 * A command is what the tracker bar reads from a chain of holes: the
 * note it sounds, or the function it operates. It is typically carried
 * by such a chain, but it might also have different physical
 * appearances.
 * @see reo:Command
 * @category Format types
 */
export interface Command<T extends string> extends Symbol<T> {
    /**
     * In piano rolls, commands are often aligned with other commands,
     * e.g. a "crescendo off" might be logically aligned to the start of
     * a note. This points to the command by its `@id`.
     * @see reo:alignedWith
     */
    alignedWith?: ReferenceAssumption;
    /**
     * A command whose onset this one precedes when the roll is
     * performed, without saying by how much: a "crescendo off" ends
     * before the note it leads to begins, even where the copies
     * disagree on it. Where the measurement has it so, nothing moves;
     * where it does not, this one is placed before the reference as
     * far as the copies that agree put it. This points to the command
     * by its `@id`.
     * @see reo:before
     */
    before?: ReferenceAssumption;
    /**
     * A command whose onset this one follows when the roll is
     * performed, the counterpart of `before`. This points to the
     * command by its `@id`.
     * @see reo:after
     */
    after?: ReferenceAssumption;
    /**
     * The command this one forms a pair with, e.g. a "forzando on"
     * with its "forzando off". Any two commands may be paired.
     * The distance between the two is fixed: whatever displaces the
     * one displaces the other. The relation is symmetric and is stated
     * on one side only. This points to the command by its `@id`.
     * @see reo:pairedWith
     */
    pairedWith?: ReferenceAssumption;
}
/**
 * The ways a command may be placed relative to another, in the order
 * `placementsOf` reports them.
 * @category Vocabulary
 */
export declare const placementRelations: readonly ['alignedWith', 'before', 'after'];
/**
 * The ways a command may be placed relative to another.
 * @category Format types
 */
export type PlacementRelation = typeof placementRelations[number];
/** @inline */
type Placeable = Partial<Record<PlacementRelation, ReferenceAssumption>>;
/**
 * A statement placing a command relative to another: how, and relative
 * to which.
 * @category Format types
 */
export type Placement = {
    relation: PlacementRelation;
    reference: ReferenceAssumption;
};
/**
 * The statements placing a command relative to others, alignment first.
 * A command is meant to make one at most; the first is the one a
 * performance applies.
 * @category Lookups
 */
export declare const placementsOf: (command: Placeable) => Placement[];
/** @inline */
type Pairable = WithId & {
    pairedWith?: ReferenceAssumption;
};
/**
 * The pairs among the given commands, each once and in the order the
 * pairing is stated. A pair whose partner is absent is left out.
 * @category Lookups
 */
export declare const pairsAmong: <S extends Pairable>(commands: readonly S[]) => [S, S][];
/**
 * A note symbol, representing a single pitched musical event on the roll.
 * The pitch is encoded via the tracker bar position (track number).
 * @see reo:Note
 * @category Format types
 */
export interface Note extends Command<'note'> {
    /**
     * The MIDI pitch number of the note (e.g. 60 for middle C).
     * @see reo:pitch
     */
    pitch: number;
}
/**
 * The scope of an expression command, indicating whether it applies to
 * the bass or treble register of the piano.
 * @see reo:scope
 * @category Format types
 */
export type ExpressionScope = 'bass' | 'treble';
/**
 * An expression symbol, representing a command that governs dynamics,
 * pedaling, or mechanical functions of the reproducing piano rather
 * than sounding a note. Each expression has a scope (bass or treble)
 * and a specific expression type.
 * @see reo:Expression
 * @category Format types
 */
export interface Expression extends Command<'expression'> {
    /**
     * Whether this expression applies to the bass or treble register.
     * @see reo:scope
     */
    scope: ExpressionScope;
    /**
     * The kind of command, named as the reproducing system of the roll
     * names it: "SustainPedalOn", "ForzandoOff" and so on for the
     * Welte-Mignon T-100. The tracker bar of the system lists the
     * values it reads.
     * @see crm:P2 has type
     */
    expressionType: string;
}
/**
 * A textual symbol, e.g. a label or annotation found on the roll.
 * @see crm:E33 Linguistic Object
 * @category Format types
 */
export interface Text extends Symbol<'text'> {
    type: 'text';
    /**
     * The text content of the symbol.
     * @see crm:P190 has symbolic content
     */
    text: string;
}
/**
 * A symbol can be either a note, an expression, or a text.
 * Notes and expressions are commands; texts are carried by writings.
 * @category Format types
 */
export type AnySymbol = Note | Expression | Text;
/**
 * A command: a note or an expression.
 * @category Format types
 */
export type AnyCommand = Note | Expression;
export {};