chordsheetjs 15.0.0 → 15.1.0

package/lib/pdf/main.d.ts

@@ -0,0 +1,1696 @@
+import { ImageCompression, ImageOptions, RGBAData, TextOptionsLight, jsPDFOptions } from "jspdf";
+import { Blob } from "buffer";
+interface PdfDoc {
+    get internal(): {
+        pageSize: {
+            getWidth(): number;
+        };
+    };
+    addImage(imageData: string | HTMLImageElement | HTMLCanvasElement | Uint8Array | RGBAData, format: string, x: number, y: number, width: number, height: number, alias?: string, compression?: ImageCompression, rotation?: number): PdfDoc;
+    addImage(imageData: string | HTMLImageElement | HTMLCanvasElement | Uint8Array | RGBAData, x: number, y: number, width: number, height: number, alias?: string, compression?: ImageCompression, rotation?: number): PdfDoc;
+    addImage(options: ImageOptions): PdfDoc;
+    circle(x: number, y: number, r: number, style?: string | null): PdfDoc;
+    getTextDimensions(text: string, options?: TextOptionsLight): {
+        w: number;
+        h: number;
+    };
+    line(x1: number, y1: number, x2: number, y2: number, style?: string | null): PdfDoc;
+    roundedRect(x: number, y: number, w: number, h: number, rx: number, ry: number, style?: string | null): PdfDoc;
+    save(filename: string, options: {
+        returnPromise: true;
+    }): Promise<void>;
+    save(filename?: string): PdfDoc;
+    setDrawColor(ch1: string | number, ch2?: number, ch3?: number, ch4?: number): PdfDoc;
+    setFont(fontName: string, fontStyle?: string, fontWeight?: string | number): PdfDoc;
+    setFontSize(size: number): PdfDoc;
+    setPage(page: number): PdfDoc;
+    setLineWidth(width: number): PdfDoc;
+    setTextColor(ch1: string): PdfDoc;
+    setTextColor(ch1: number): PdfDoc;
+    setTextColor(ch1: number, ch2: number, ch3: number, ch4?: number): PdfDoc;
+    text(text: string | string[], x: number, y: number, options?: TextOptionsLight, transform?: any): PdfDoc;
+    addFileToVFS(fileName: string, data: string): PdfDoc;
+    addFont(postScriptName: string, id: string, fontStyle: string, fontWeight?: string | number, encoding?: 'StandardEncoding' | 'MacRomanEncoding' | 'Identity-H' | 'WinAnsiEncoding', isStandardFont?: boolean): string;
+}
+type PdfConstructor = new (options?: jsPDFOptions) => PdfDoc;
+type ParagraphType = 'abc' | 'bridge' | 'chorus' | 'grid' | 'indeterminate' | 'ly' | 'none' | 'svg' | 'tab' | 'textblock' | 'verse' | 'part' | string;
+type Accidental = '#' | 'b';
+type NoAccidental = 'NM';
+type AccidentalMaybe = Accidental | NoAccidental;
+type ChordType = 'symbol' | 'solfege' | 'numeric' | 'numeral';
+type FretNumber = number;
+type OpenFret = 0;
+type NonSoundingString = '-1' | 'N' | 'x';
+type Fret = FretNumber | OpenFret | NonSoundingString;
+type ContentType = 'tab' | 'abc' | 'ly' | 'svg' | 'grid' | 'textblock';
+interface ChordProperties {
+    root?: Key | null;
+    suffix?: string | null;
+    quality?: string | null;
+    extensions?: string | null;
+    bass?: Key | null;
+    optional?: boolean;
+}
+interface ChordConstructorOptions {
+    base?: string | number | null;
+    accidental?: Accidental | null;
+    suffix?: string | null;
+    quality?: string | null;
+    extensions?: string | null;
+    bassBase?: string | number | null;
+    bassAccidental?: Accidental | null;
+    root?: Key | null;
+    bass?: Key | null;
+    chordType?: ChordType | null;
+    optional?: boolean;
+}
+/**
+ * Represents a Chord, consisting of a root, suffix (quality) and bass
+ */
+declare class Chord implements ChordProperties {
+    bass: Key | null;
+    root: Key | null;
+    get suffix(): string | null;
+    get quality(): string | null;
+    get extensions(): string | null;
+    optional: boolean;
+    /**
+     * Tries to parse a chord string into a chord
+     * Any leading or trailing whitespace is removed first, so a chord like `  \n  E/G# \r ` is valid.
+     * @param chordString the chord string, eg `Esus4/G#` or `1sus4/#3`.
+     * @returns {Chord|null}
+     */
+    static parse(chordString: string): Chord | null;
+    static parseOrFail(chordString: string): Chord;
+    /**
+     * Returns a deep copy of the chord
+     * @returns {Chord}
+     */
+    clone(): Chord;
+    /**
+     * Converts the chord to a chord symbol, using the supplied key as a reference.
+     * For example, a numeric chord `#4` with reference key `E` will return the chord symbol `A#`.
+     * When the chord is already a chord symbol, it will return a clone of the object.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a
+     * numeric or numeral.
+     * @returns {Chord} the chord symbol
+     */
+    toChordSymbol(referenceKey?: Key | string | null): Chord;
+    /**
+     * Converts the chord to a chord symbol string, using the supplied key as a reference.
+     * For example, a numeric chord `#4` with reference key `E` will return the chord symbol `A#`.
+     * When the chord is already a chord symbol, it will return a string version of the chord.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a
+     * numeric or numeral.
+     * @returns {string} the chord symbol string
+     * @see {toChordSymbol}
+     */
+    toChordSymbolString(referenceKey?: Key | string | null): string;
+    /**
+     * Determines whether the chord is a chord symbol
+     * @returns {boolean}
+     */
+    isChordSymbol(): boolean;
+    /**
+     * Converts the chord to a chord solfege, using the supplied key as a reference.
+     * For example, a numeric chord `#4` with reference key `Mi` will return the chord symbol `La#`.
+     * When the chord is already a chord solfege, it will return a clone of the object.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a
+     * numeric or numeral.
+     * @returns {Chord} the chord solfege
+     */
+    toChordSolfege(referenceKey?: Key | string | null): Chord;
+    /**
+     * Converts the chord to a chord solfege string, using the supplied key as a reference.
+     * For example, a numeric chord `#4` with reference key `E` will return the chord solfege `A#`.
+     * When the chord is already a chord solfege, it will return a string version of the chord.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a
+     * numeric or numeral.
+     * @returns {string} the chord solfege string
+     * @see {toChordSolfege}
+     */
+    toChordSolfegeString(referenceKey?: Key | string | null): string;
+    /**
+     * Determines whether the chord is a chord solfege
+     * @returns {boolean}
+     */
+    isChordSolfege(): boolean;
+    /**
+     * Converts the chord to a numeric chord, using the supplied key as a reference.
+     * For example, a chord symbol A# with reference key E will return the numeric chord #4.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a chord symbol
+     * @returns {Chord} the numeric chord
+     */
+    toNumeric(referenceKey?: Key | string | null): Chord;
+    /**
+     * Converts the chord to a numeral chord, using the supplied key as a reference.
+     * For example, a chord symbol A# with reference key E will return the numeral chord #IV.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a chord symbol
+     * @returns {Chord} the numeral chord
+     */
+    toNumeral(referenceKey?: Key | string | null): Chord;
+    /**
+     * Converts the chord to a numeral chord string, using the supplied kye as a reference.
+     * For example, a chord symbol A# with reference key E will return the numeral chord #4.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a chord symbol
+     * @returns {string} the numeral chord string
+     * @see {toNumeral}
+     */
+    toNumeralString(referenceKey?: Key | string | null): string;
+    /**
+     * Determines whether the chord is numeric
+     * @returns {boolean}
+     */
+    isNumeric(): boolean;
+    /**
+     * Converts the chord to a numeric chord string, using the supplied kye as a reference.
+     * For example, a chord symbol A# with reference key E will return the numeric chord #4.
+     * @param {Key|string|null} [referenceKey=null] the reference key. The key is required when converting a chord symbol
+     * @returns {string} the numeric chord string
+     * @see {toNumeric}
+     */
+    toNumericString(referenceKey?: Key | string | null): string;
+    /**
+     * Determines whether the chord is a numeral
+     * @returns {boolean}
+     */
+    isNumeral(): boolean;
+    /**
+     * Converts the chord to a string, eg `Esus4/G#` or `1sus4/#3`
+     * @param {Object} [configuration={}] options
+     * @param {boolean} [configuration.useUnicodeModifier=false] Whether or not to use unicode modifiers.
+     * This will make `#` (sharp) look like `♯` and `b` (flat) look like `♭`
+     * @returns {string} the chord string
+     */
+    toString({ useUnicodeModifier }?: {
+        useUnicodeModifier?: boolean | undefined;
+    }): string;
+    /**
+     * Normalizes the chord root and bass notes:
+     * - Fab becomes Mi
+     * - Dob becomes Si
+     * - Si# becomes Do
+     * - Mi# becomes Fa
+     * - Fb becomes E
+     * - Cb becomes B
+     * - B# becomes C
+     * - E# becomes F
+     * - 4b becomes 3
+     * - 1b becomes 7
+     * - 7# becomes 1
+     * - 3# becomes 4
+     *
+     * Besides that it normalizes the suffix if `normalizeSuffix` is `true`.
+     * For example, `sus2` becomes `2`, `sus4` becomes `sus`.
+     * All suffix normalizations can be found in `src/normalize_mappings/suffix-mapping.txt`.
+     *
+     * When the chord is minor, bass notes are normalized off of the relative major
+     * of the root note. For example, `Em/A#` becomes `Em/Bb`.
+     * @param {Key|string} [key=null] the key to normalize to
+     * @param {Object} [options={}] options
+     * @param {boolean} [options.normalizeSuffix=true] whether to normalize the chord suffix after transposing
+     * @returns {Chord} the normalized chord
+     */
+    normalize(key?: Key | string | null, { normalizeSuffix }?: {
+        normalizeSuffix?: boolean;
+    }): Chord;
+    /**
+     * Switches to the specified accidental
+     * @param newAccidental the accidental to use: `'#'` or `'b'`
+     * @returns {Chord} the new, changed chord
+     */
+    useAccidental(newAccidental: Accidental): Chord;
+    /**
+     * @deprecated Use useAccidental instead
+     */
+    useModifier(newAccidental: Accidental): Chord;
+    /**
+     * Transposes the chord up by 1 semitone. Eg. A becomes A#, Eb becomes E
+     * @returns {Chord} the new, transposed chord
+     */
+    transposeUp(): Chord;
+    /**
+     * Transposes the chord down by 1 semitone. Eg. A# becomes A, E becomes Eb
+     * @returns {Chord} the new, transposed chord
+     */
+    transposeDown(): Chord;
+    /**
+     * Transposes the chord by the specified number of semitones
+     * @param delta de number of semitones
+     * @returns {Chord} the new, transposed chord
+     */
+    transpose(delta: number): Chord;
+    constructor(options: ChordConstructorOptions);
+    equals(otherChord: Chord): boolean;
+    static determineRoot(options: ChordConstructorOptions & {
+        suffix?: string | null;
+    }): Key | null;
+    static determineBass(options: ChordConstructorOptions): Key | null;
+    isMinor(): boolean;
+    makeMinor(): Chord;
+    set(properties: ChordProperties): Chord;
+    private get normalizedSuffix();
+}
+/**
+ * Represents a comment. See https://www.chordpro.org/chordpro/chordpro-file-format-specification/#overview
+ */
+declare class Comment {
+    content: string;
+    parentLine: Line | null;
+    constructor(content: string);
+    /**
+     * Indicates whether a Comment should be visible in a formatted chord sheet (except for ChordPro sheets)
+     * @returns {boolean}
+     */
+    isRenderable(): boolean;
+    /**
+     * Returns a deep copy of the Comment, useful when programmatically transforming a song
+     * @returns {Comment}
+     */
+    clone(): Comment;
+    toString(): string;
+}
+type Size = 'px' | '%';
+declare class FontSize {
+    /**
+     * The size unit, either `"px"` or `"%"`
+     * @member {string}
+     */
+    unit: Size;
+    /**
+     * The font size
+     * @member {number}
+     */
+    fontSize: number;
+    constructor(fontSize: number, kind: Size);
+    clone(): FontSize;
+    multiply(percentage: any): FontSize;
+    /**
+     * Stringifies the font size by concatenating size and unit
+     *
+     * @example
+     * // Returns "30px"
+     * new FontSize(30, 'px').toString()
+     * @example
+     * // Returns "120%"
+     * new FontSize(120, '%').toString()
+     *
+     * @return {string} The font size
+     */
+    toString(): string;
+    static parse(fontSize: string, parent: FontSize | null): FontSize;
+    static parseNotANumber(parent: FontSize | null): FontSize;
+    static parsePercentage(parsedFontSize: number, parent: FontSize | null): FontSize;
+}
+interface FontProperties {
+    font?: string | null;
+    size?: FontSize | null;
+    colour?: string | null;
+}
+declare class Font {
+    /**
+     * The font
+     * @member {string | null}
+     */
+    font: string | null;
+    /**
+     * The font size, expressed in either pixels or percentage.
+     * @member {FontSize | null}
+     */
+    size: FontSize | null;
+    /**
+     * The font color
+     * @member {string | null}
+     */
+    colour: string | null;
+    constructor({ font, size, colour }?: FontProperties);
+    clone(): Font;
+    /**
+     * Converts the font, size and color to a CSS string.
+     * If possible, font and size are combined to the `font` shorthand.
+     * If `font` contains double quotes (`"`) those will be converted to single quotes (`'`).
+     *
+     * @example
+     * // Returns "font-family: 'Times New Roman'"
+     * new Font({ font: '"Times New Roman"' }).toCssString()
+     * @example
+     * // Returns "color: red; font-family: Verdana"
+     * new Font({ font: 'Verdana', colour: 'red' }).toCssString()
+     * @example
+     * // Returns "font: 30px Verdana"
+     * new Font({ font: 'Verdana', size: '30' }).toCssString()
+     * @example
+     * // Returns "color: blue; font: 30% Verdana"
+     * new Font({ font: 'Verdana', size: '30%', colour: 'blue' }).toCssString()
+     *
+     * @return {string} The CSS string
+     */
+    toCssString(): string;
+}
+interface TraceInfo {
+    line?: number | null;
+    column?: number | null;
+    offset?: number | null;
+}
+declare abstract class AstComponent {
+    parentLine: Line | null;
+    line: number | null;
+    column: number | null;
+    offset: number | null;
+    protected constructor(traceInfo?: TraceInfo | null);
+    abstract clone(): AstComponent;
+}
+declare abstract class MetadataAccessors {
+    abstract getMetadataValue(_name: string): string | string[] | null;
+    abstract getSingleMetadataValue(_name: string): string | null;
+    get key(): string | null;
+    get title(): string | null;
+    get subtitle(): string | null;
+    get capo(): string | string[] | null;
+    get duration(): string | null;
+    get tempo(): string | null;
+    get time(): string | string[] | null;
+    get year(): string | null;
+    get album(): string | string[] | null;
+    get copyright(): string | null;
+    get lyricist(): string | string[] | null;
+    get artist(): string | string[] | null;
+    get composer(): string | string[] | null;
+}
+/**
+ * Represents a chord definition.
+ *
+ * Definitions are made using the `{chord}` or `{define}` directive.
+ * A chord definitions overrides a previous chord definition for the exact same chord.
+ *
+ * @see https://chordpro.org/chordpro/directives-define/
+ * @see https://chordpro.org/chordpro/directives-chord/
+ */
+declare class ChordDefinition {
+    /**
+     * The chord name, e.g. `C`, `Dm`, `G7`.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Defines the offset for the chord, which is the position of the topmost finger.
+     * The offset must be 1 or higher.
+     * @type {number}
+     */
+    baseFret: number;
+    /**
+     * Defines the string positions.
+     * Strings are enumerated from left (lowest) to right (highest), as they appear in the chord diagrams.
+     * Fret positions are relative to the offset minus one, so with base-fret 1 (the default),
+     * the topmost fret position is 1. With base-fret 3, fret position 1 indicates the 3rd position.
+     * `0` (zero) denotes an open string. Use `-1`, `N` or `x` to denote a non-sounding string.
+     * @type {Fret[]}
+     */
+    frets: Fret[];
+    /**
+     * defines finger settings. This part may be omitted.
+     *
+     * For the frets and the fingers positions, there must be exactly as many positions as there are strings,
+     * which is 6 by default. For the fingers positions, values corresponding to open or damped strings are ignored.
+     * Finger settings may be numeric (0 .. 9) or uppercase letters (A .. Z).
+     * Note that the values -, x, X, and N are used to designate a string without finger setting.
+     * @type {number[]}
+     */
+    fingers: number[];
+    constructor(name: string, baseFret: number, frets: Fret[], fingers?: number[]);
+    /**
+     * Parses a chord definition in the form of:
+     * - <name> base-fret <offset> frets <pos> <pos> … <pos>
+     * - <name> base-fret <offset> frets <pos> <pos> … <pos> fingers <pos> <pos> … <pos>
+     * @param chordDefinition
+     * @returns {ChordDefinition}
+     * @see https://chordpro.org/chordpro/directives-define/#common-usage
+     */
+    static parse(chordDefinition: string): ChordDefinition;
+    clone(): ChordDefinition;
+}
+/**
+ * Represents a tag/directive. See https://www.chordpro.org/chordpro/chordpro-directives/
+ */
+declare class Tag extends AstComponent {
+    _isMetaTag: boolean;
+    _originalName: string;
+    _name: string;
+    _value: string;
+    chordDefinition?: ChordDefinition;
+    selector: string | null;
+    isNegated: boolean;
+    /**
+     * The tag attributes. For example, section related tags can have a label:
+     * `{start_of_verse: label="Verse 1"}`
+     * @type {Record<string, string>}
+     */
+    attributes: Record<string, string>;
+    constructor(name: string, value?: string | null, traceInfo?: TraceInfo | null, attributes?: Record<string, string>, selector?: string | null, isNegated?: boolean);
+    static parse(tag: string | Tag): Tag | null;
+    static parseWithRegex(tag: string, regex: RegExp): Tag | null;
+    static parseOrFail(tag: string | Tag): Tag;
+    get label(): string;
+    isSectionDelimiter(): boolean;
+    isSectionStart(): boolean;
+    isSectionEnd(): boolean;
+    isInlineFontTag(): boolean;
+    /**
+     * Checks whether the tag is a comment tag ({comment} or {c}).
+     */
+    isComment(): boolean;
+    /**
+     * Checks whether the tag is an image tag ({image}).
+     */
+    isImage(): boolean;
+    set name(name: string);
+    /**
+     * The tag full name. When the original tag used the short name, `name` will return the full name.
+     * @member
+     * @type {string}
+     */
+    get name(): string;
+    /**
+     * The original tag name that was used to construct the tag.
+     * @member
+     * @type {string}
+     */
+    get originalName(): string;
+    set value(value: string);
+    /**
+     * The tag value
+     * @member
+     * @type {string}
+     */
+    get value(): string;
+    /**
+     * Checks whether the tag value is a non-empty string.
+     * @returns {boolean}
+     */
+    hasValue(): boolean;
+    hasAttributes(): boolean;
+    hasLabel(): boolean;
+    /**
+     * Checks whether the tag is usually rendered inline. It currently only applies to comment tags.
+     * @returns {boolean}
+     */
+    isRenderable(): boolean;
+    /**
+     * Check whether this tag's label (if any) should be rendered, as applicable to tags like
+     * `start_of_verse` and `start_of_chorus`.
+     * See https://chordpro.org/chordpro/directives-env_chorus/, https://chordpro.org/chordpro/directives-env_verse/,
+     * https://chordpro.org/chordpro/directives-env_bridge/, https://chordpro.org/chordpro/directives-env_tab/
+     */
+    hasRenderableLabel(): boolean;
+    /**
+     * Checks whether the tag is a standard meta tag, a custom meta directive (`{x_some_name}`)
+     * or a non-standard meta tag (`{meta: name value}`)
+     * @returns {boolean}
+     */
+    isMetaTag(): boolean;
+    /**
+     * Checks whether this tag is a standard meta tag or a custom meta directive (`{x_some_name}`)
+     * @returns {boolean}
+     */
+    isStandardOrCustomMetaTag(): boolean;
+    /**
+     * Returns a clone of the tag.
+     * @returns {Tag} The cloned tag
+     */
+    clone(): Tag;
+    toString(): string;
+    set({ value }: {
+        value: string;
+    }): Tag;
+    setAttribute(name: string, value: string): Tag;
+}
+type MetadataProvider = () => string | null;
+/**
+ * Stores song metadata. Properties can be accessed using the get() method:
+ *
+ * const metadata = new Metadata({ author: 'John' });
+ * metadata.get('author')   // => 'John'
+ *
+ * See {@link Metadata#get}
+ */
+declare class Metadata extends MetadataAccessors implements Iterable<[string, string | string[]]> {
+    metadata: Record<string, string | string[]>;
+    providers: Map<string, MetadataProvider>;
+    constructor(metadata?: Record<string, string | string[]> | Metadata);
+    merge(metadata?: Record<string, string | string[]> | Metadata): Metadata;
+    contains(key: string): boolean;
+    add(key: string, value: string): void;
+    appendValue(key: string, value: string): void;
+    setProvider(key: string, provider: MetadataProvider): void;
+    set(key: string, value: string | null): void;
+    getMetadataValue(name: string): string | string[] | null;
+    getSingleMetadataValue(name: string): string | null;
+    /**
+     * Reads a metadata value by key. This method supports simple value lookup, as well as fetching single array values.
+     *
+     * This method deprecates direct property access, eg: metadata['author']
+     *
+     * @example
+     * const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] });
+     * metadata.get('lyricist') // => 'Pete'
+     * metadata.get('author')   // => ['John', 'Mary']
+     * metadata.get('author.1') // => 'John'
+     * metadata.get('author.2') // => 'Mary'
+     *
+     * Using a negative index will start counting at the end of the list:
+     *
+     * const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] });
+     * metadata.get('author.-1') // => 'Mary'
+     * metadata.get('author.-2') // => 'John'
+     *
+     * @param prop the property name
+     * @returns {Array<String>|String} the metadata value(s). If there is only one value, it will return a String,
+     * else it returns an array of strings.
+     */
+    get(prop: string): string | string[] | null;
+    /**
+     * Returns all metadata values, including provider values and generated values like `_key`.
+     * @returns {Object.<string, string|string[]>} the metadata values
+     */
+    all(): Record<string, string | string[]>;
+    ownMetadata(): Record<string, string | string[]>;
+    [Symbol.iterator](): IterableIterator<[string, string | string[]]>;
+    /**
+     * Returns a single metadata value. If the actual value is an array, it returns the first value. Else, it returns
+     * the value.
+     * @ignore
+     * @param {string} prop the property name
+     * @returns {String} The metadata value
+     */
+    getSingle(prop: string): string | null;
+    parseArrayKey(prop: string): [string, number] | null;
+    getArrayItem(prop: string): string | null;
+    /**
+     * Returns a deep clone of this Metadata object
+     * @returns {Metadata} the cloned Metadata object
+     */
+    clone(): Metadata;
+    calculateKeyFromCapo(): string | null;
+    assign(metadata: Record<string, string | string[] | null>): void;
+}
+declare abstract class Evaluatable extends AstComponent {
+    abstract evaluate(_metadata: Metadata, _metadataSeparator: string, _variable?: string | null): string;
+    abstract clone(): Evaluatable;
+}
+declare class Literal extends Evaluatable {
+    string: string;
+    constructor(string: string);
+    evaluate(): string;
+    isRenderable(): boolean;
+    clone(): Literal;
+}
+type TernaryProperties = TraceInfo & {
+    variable?: string | null;
+    valueTest?: string | null;
+    trueExpression?: Evaluatable[];
+    falseExpression?: Evaluatable[];
+};
+declare class Ternary extends Evaluatable {
+    variable: string | null;
+    valueTest: string | null;
+    trueExpression: Evaluatable[];
+    falseExpression: Evaluatable[];
+    constructor({ variable, valueTest, trueExpression, falseExpression, line, column, offset, }: TernaryProperties);
+    /**
+     * Evaluate the meta expression
+     * @param {Metadata} metadata The metadata object to use for evaluating the expression
+     * @param {string} [metadataSeparator=null] The metadata separator to use if necessary
+     * @returns {string} The evaluated expression
+     */
+    evaluate(metadata: Metadata, metadataSeparator: string, upperContext?: string | null): string;
+    evaluateToString(value: string[] | string, metadataSeparator: string): string;
+    evaluateWithVariable(metadata: Metadata, metadataSeparator: string): string;
+    evaluateForTruthyValue(metadata: Metadata, metadataSeparator: string, value: string | string[]): string;
+    isRenderable(): boolean;
+    clone(): Ternary;
+}
+type Item = ChordLyricsPair | Comment | Tag | Ternary | Literal;
+type MapItemFunc = (_item: Item) => Item | null;
+/**
+ * Represents a line in a chord sheet, consisting of items of type ChordLyricsPair or Tag
+ */
+declare class Line {
+    /**
+     * The items ({@link ChordLyricsPair} or {@link Tag} or {@link Comment}) of which the line consists
+     * @type {Array.<(ChordLyricsPair|Tag|Comment)>}
+     */
+    items: Item[];
+    /**
+     * The line type, This is set by the ChordProParser when it read tags like {start_of_chorus} or {start_of_verse}
+     * It uses the following mapping to determine the line type from directives:
+     * - `start_of_abc` => {@link ABC}
+     * - `start_of_bridge` => {@link BRIDGE}
+     * - `start_of_chorus` => {@link CHORUS}
+     * - `start_of_grid` => {@link GRID}
+     * - `start_of_ly` => {@link LILYPOND}
+     * - `start_of_tab` => {@link TAB}
+     * - `start_of_verse` => {@link VERSE}
+     *
+     * There are two special cases:
+     * - {@link INDETERMINATE} when the paragraph lines do not have a consistent type
+     * - {@link NONE} when no type is derived
+     * @type {string}
+     */
+    type: string;
+    currentChordLyricsPair: ChordLyricsPair;
+    key: string | null;
+    transposeKey: string | null;
+    lineNumber: number | null;
+    selector: string | null;
+    selectorIsNegated: boolean;
+    /**
+     * The text font that applies to this line. Is derived from the directives:
+     * `textfont`, `textsize` and `textcolour`
+     * See: https://www.chordpro.org/chordpro/directives-props_text_legacy/
+     * @type {Font}
+     */
+    textFont: Font;
+    /**
+     * The chord font that applies to this line. Is derived from the directives:
+     * `chordfont`, `chordsize` and `chordcolour`
+     * See: https://www.chordpro.org/chordpro/directives-props_chord_legacy/
+     * @type {Font}
+     */
+    chordFont: Font;
+    constructor({ type, items }?: {
+        type: string;
+        items: Item[];
+    });
+    /**
+     * Indicates whether the line contains any items
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+    /**
+     * Adds an item ({@link ChordLyricsPair} or {@link Tag}) to the line
+     * @param {ChordLyricsPair|Tag} item The item to be added
+     */
+    addItem(item: Item): void;
+    /**
+     * Indicates whether the line contains items that are renderable
+     * @returns {boolean}
+     */
+    hasRenderableItems(): boolean;
+    /**
+     * Returns a deep copy of the line and all of its items
+     * @returns {Line}
+     */
+    clone(): Line;
+    mapItems(func: MapItemFunc | null): Line;
+    /**
+     * Indicates whether the line type is {@link BRIDGE}
+     * @returns {boolean}
+     */
+    isBridge(): boolean;
+    /**
+     * Indicates whether the line type is {@link CHORUS}
+     * @returns {boolean}
+     */
+    isChorus(): boolean;
+    /**
+     * Indicates whether the line type is {@link GRID}
+     * @returns {boolean}
+     */
+    isGrid(): boolean;
+    /**
+     * Indicates whether the line type is {@link TAB}
+     * @returns {boolean}
+     */
+    isTab(): boolean;
+    /**
+     * Indicates whether the line type is {@link VERSE}
+     * @returns {boolean}
+     */
+    isVerse(): boolean;
+    /**
+     * Indicates whether the line type is {@link PART}
+     * @returns {boolean}
+     */
+    isPart(): boolean;
+    /**
+     * Indicates whether the line contains items that are renderable. Please use {@link hasRenderableItems}
+     * @deprecated
+     * @returns {boolean}
+     */
+    hasContent(): boolean;
+    addChordLyricsPair(chords?: ChordLyricsPair | string | null, lyrics?: null): ChordLyricsPair;
+    ensureChordLyricsPair(): void;
+    chords(chr: string): void;
+    lyrics(chr: string): void;
+    addTag(nameOrTag: Tag | string, value?: string | null): Tag;
+    addComment(content: Comment | string): Comment;
+    set(properties: {
+        type?: string;
+        items?: Item[];
+    }): Line;
+    get _tag(): Tag | null;
+    isSectionStart(): boolean;
+    isSectionEnd(): boolean;
+}
+/**
+ * Represents a chord with the corresponding (partial) lyrics
+ */
+declare class ChordLyricsPair {
+    chords: string;
+    lyrics: string | null;
+    annotation: string | null;
+    isRhythmSymbol: boolean;
+    parentLine: Line | null;
+    /**
+     * Initialises a ChordLyricsPair
+     * @param {string} chords The chords
+     * @param {string | null} lyrics The lyrics
+     * @param {string | null} annotation The annotation
+     * @param {Chord | null} chordObj Optional pre-parsed Chord object
+     * @param {boolean} isRhythmSymbol Whether this pair represents a rhythm symbol
+     */
+    constructor(chords?: string, lyrics?: string | null, annotation?: string | null, chordObj?: Chord | null, isRhythmSymbol?: boolean);
+    /** Returns the Chord object if available, otherwise parses from string */
+    get chord(): Chord | null;
+    /**
+     * Indicates whether a ChordLyricsPair should be visible in a formatted chord sheet (except for ChordPro sheets)
+     * @returns {boolean}
+     */
+    isRenderable(): boolean;
+    /**
+     * Indicates whether the ChordLyricsPair has non-empty lyrics.
+     */
+    hasLyrics(): boolean;
+    /**
+     * Returns a deep copy of the ChordLyricsPair, useful when programmatically transforming a song
+     * @returns {ChordLyricsPair}
+     */
+    clone(): ChordLyricsPair;
+    toString(): string;
+    set({ chords, lyrics, annotation, chordObj, isRhythmSymbol, }: {
+        chords?: string;
+        lyrics?: string;
+        annotation?: string;
+        chordObj?: Chord | null;
+        isRhythmSymbol?: boolean;
+    }): ChordLyricsPair;
+    setLyrics(lyrics: string): ChordLyricsPair;
+    setAnnotation(annotation: string): ChordLyricsPair;
+    transpose(delta: number, key?: string | Key | null, { normalizeChordSuffix }?: {
+        normalizeChordSuffix: boolean;
+    }): ChordLyricsPair;
+    useAccidental(accidental: Accidental): ChordLyricsPair;
+    /**
+     * @deprecated Use useAccidental instead
+     */
+    useModifier(accidental: Accidental): ChordLyricsPair;
+    changeChord(func: (chord: Chord) => Chord): ChordLyricsPair;
+}
+/**
+ * Utility type that creates a deep partial type
+ * This makes all properties optional recursively through the entire object
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+interface KeyProperties {
+    grade?: number | null;
+    number?: number | null;
+    type?: ChordType;
+    minor?: boolean;
+    accidental?: Accidental | null;
+    referenceKeyGrade?: number | null;
+    referenceKeyMode?: string | null;
+    preferredAccidental?: Accidental | null;
+    explicitAccidental?: boolean;
+}
+interface ConstructorOptions {
+    grade?: number | null;
+    number?: number | null;
+    minor: boolean;
+    type: ChordType;
+    accidental: Accidental | null;
+    referenceKeyGrade?: number | null;
+    referenceKeyMode?: string | null;
+    originalKeyString?: string | null;
+    preferredAccidental: Accidental | null;
+    explicitAccidental?: boolean;
+}
+/**
+ * Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).
+ *
+ * The only function considered public API is `Key.distance`
+ */
+declare class Key implements KeyProperties {
+    grade: number | null;
+    number: number | null;
+    accidental: Accidental | null;
+    type: ChordType;
+    get unicodeAccidental(): string | null;
+    /** @deprecated Use unicodeAccidental instead */
+    get unicodeModifier(): string | null;
+    /** @deprecated Use accidental instead */
+    get modifier(): Accidental | null;
+    /** @deprecated Use preferredAccidental instead */
+    get preferredModifier(): Accidental | null;
+    minor: boolean;
+    referenceKeyGrade: number | null;
+    referenceKeyMode: string | null;
+    originalKeyString: string | null;
+    preferredAccidental: Accidental | null;
+    explicitAccidental: boolean;
+    static parse(keyString: string | null): null | Key;
+    static parseAsType(trimmed: string, keyType: ChordType): Key | null;
+    static resolve({ key, keyType, minor, accidental, }: {
+        key: string | number;
+        keyType: ChordType;
+        minor: string | boolean;
+        accidental: Accidental | null;
+    }): Key | null;
+    static getNumberFromKey(keyString: string, keyType: ChordType): number;
+    static keyWithAccidental(key: string, accidental: Accidental | null, type: ChordType): string;
+    /** @deprecated Use keyWithAccidental instead */
+    static keyWithModifier(key: string, accidental: Accidental | null, type: ChordType): string;
+    static toGrade(key: string, accidental: AccidentalMaybe, type: ChordType, isMinor: boolean): number | null;
+    static isMinor(key: string, keyType: ChordType, minor: string | undefined | boolean): boolean;
+    static parseOrFail(keyString: string | null): Key;
+    static wrap(keyStringOrObject: Key | string | null): Key | null;
+    static wrapOrFail(keyStringOrObject?: Key | string | null): Key;
+    static toString(keyStringOrObject: Key | string): string;
+    /**
+     * Calculates the distance in semitones between one key and another.
+     * @param {Key | string} oneKey the key
+     * @param {Key | string} otherKey the other key
+     * @return {number} the distance in semitones
+     */
+    static distance(oneKey: Key | string, otherKey: Key | string): number;
+    constructor({ grade, number, minor, type, accidental, referenceKeyGrade, referenceKeyMode, originalKeyString, preferredAccidental, explicitAccidental, }: ConstructorOptions);
+    distanceTo(otherKey: Key | string): number;
+    get effectiveGrade(): number;
+    isMinor(): boolean;
+    makeMinor(): Key;
+    get relativeMajor(): Key;
+    get relativeMinor(): Key;
+    toMajor(): Key;
+    clone(): Key;
+    toChordSymbol(key: Key | string | null, referenceKeyWasMinor?: boolean): Key;
+    toChordSolfege(key: Key | string | null, referenceKeyWasMinor?: boolean): Key;
+    toChordSymbolString(key: Key): string;
+    toChordSolfegeString(key: Key): string;
+    is(type: ChordType): boolean;
+    isNumeric(): boolean;
+    isChordSymbol(): boolean;
+    isChordSolfege(): boolean;
+    isNumeral(): boolean;
+    equals(otherKey: Key): boolean;
+    static equals(oneKey: Key | null, otherKey: Key | null): boolean;
+    toNumeric(key?: Key | string | null): Key;
+    toNumericString(key?: Key | null): string;
+    toNumeral(key?: Key | string | null): Key;
+    toNumeralString(key?: Key | null): string;
+    toString({ showMinor, useUnicodeModifier }?: {
+        showMinor?: boolean | undefined;
+        useUnicodeModifier?: boolean | undefined;
+    }): string;
+    get note(): string;
+    get minorSign(): "" | "m";
+    transpose(delta: number): Key;
+    changeGrade(delta: any): Key;
+    transposeUp(): Key;
+    transposeDown(): Key;
+    canBeFlat(): boolean;
+    canBeSharp(): boolean;
+    setGrade(newGrade: number): Key;
+    static shiftGrade(grade: number): number;
+    useAccidental(newAccidental: Accidental | null): Key;
+    /** @deprecated Use useAccidental instead */
+    useModifier(newAccidental: Accidental | null): Key;
+    normalize(): Key;
+    normalizeEnharmonics(key: Key | string | null): Key;
+}
+type Delegate = (_string: string) => string;
+interface MetadataRule {
+    match: string | string[] | RegExp | ((key: string) => boolean);
+    visible?: boolean;
+    sortMethod?: 'preserve' | 'alphabetical' | 'custom';
+    customSort?: (a: string, b: string) => number;
+}
+interface MetadataConfiguration {
+    separator: string;
+    order: (string | MetadataRule)[];
+}
+interface InstrumentConfiguration {
+    type?: string;
+    description?: string;
+    tuning?: string;
+}
+interface UserConfigurationProperties {
+    name?: string;
+    fullname?: string;
+}
+interface BaseFormatterConfiguration {
+    decapo: boolean;
+    delegates: Partial<Record<ContentType, Delegate>>;
+    evaluate: boolean;
+    expandChorusDirective: boolean;
+    instrument: InstrumentConfiguration | null;
+    key: Key | null;
+    metadata: MetadataConfiguration;
+    normalizeChords: boolean;
+    useUnicodeModifiers: boolean;
+    user: UserConfigurationProperties | null;
+}
+/**
+ * Configuration options for rendering a chord diagram, controlling dimensions, colors, and visual styling.
+ */
+interface ChordDiagramRenderingConfig {
+    /** Vertical position of the chord title. */
+    titleY: number;
+    /** Width of the guitar neck area. */
+    neckWidth: number;
+    /** Height of the guitar neck area. */
+    neckHeight: number;
+    /** Thickness of the nut (top bar) at the first fret. */
+    nutThickness: number;
+    /** Color of the nut. */
+    nutColor: number | string;
+    /** Thickness of regular fret bars. */
+    fretThickness: number;
+    /** Color of the fret lines. */
+    fretColor: number | string;
+    /** Color of the strings. */
+    stringColor: number | string;
+    /** Size of open/muted string indicators above the nut. */
+    stringIndicatorSize: number;
+    /** Size of finger position markers on the fretboard. */
+    fingerIndicatorSize: number;
+    /** Vertical offset adjustment for finger indicators. */
+    fingerIndicatorOffset: number;
+    /** Thickness of the string lines. */
+    stringThickness: number;
+    /** Thickness of the fret lines. */
+    fretLineThickness: number;
+    /** Line thickness for open string (circle) indicators. */
+    openStringIndicatorThickness: number;
+    /** Line thickness for muted string (X) indicators. */
+    unusedStringIndicatorThickness: number;
+    /** Line thickness for finger position markers. */
+    markerThickness: number;
+    /** Line thickness for barre indicators. */
+    barreThickness: number;
+    /** Font size for the chord title. */
+    titleFontSize: number;
+    /** Font size for the base fret number (when transposed). */
+    baseFretFontSize: number;
+    /** Font size for finger numbers below the diagram. */
+    fingerNumberFontSize: number;
+    /** Whether to display finger numbers below the diagram. */
+    showFingerNumbers: boolean;
+    /** Horizontal spacing between multiple diagrams. */
+    diagramSpacing: number;
+    /** Maximum number of diagrams per row (optional). */
+    maxDiagramsPerRow?: number | null;
+}
+interface PDFLayoutConfig extends MeasurementBasedLayoutConfig {
+    header: MeasurementBasedLayoutConfig['header'];
+    footer: MeasurementBasedLayoutConfig['footer'];
+    sections: SectionsConfig;
+    chordDiagrams: ChordDiagramsConfig;
+}
+interface PDFFormatterConfiguration extends MeasurementBasedFormatterConfiguration {
+    version: string;
+    layout: PDFLayoutConfig;
+}
+/**
+ * Base formatter class that provides configuration handling for all formatters
+ */
+declare class Formatter<T extends BaseFormatterConfiguration = BaseFormatterConfiguration> {
+    configuration: T;
+    /**
+     * Instantiate
+     * @param {DeepPartial<T>} [configuration={}] options
+     * @param {boolean} [configuration.evaluate=false] Whether or not to evaluate meta expressions.
+     * For more info about meta expressions, see: https://bit.ly/2SC9c2u
+     * @param {object} [configuration.metadata={}]
+     * @param {string} [configuration.metadata.separator=", "] The separator to be used when rendering a
+     * metadata value that has multiple values. See: https://bit.ly/2SC9c2u
+     * @param {Key|string} [configuration.key=null] The key to use for rendering. The chord sheet will be
+     * transposed from the song's original key (as indicated by the `{key}` directive) to the specified key.
+     * Note that transposing will only work if the original song key is set.
+     * @param {boolean} [configuration.expandChorusDirective=false] Whether or not to expand `{chorus}` directives
+     * by rendering the last defined chorus inline after the directive.
+     * @param {boolean} [configuration.useUnicodeModifiers=false] Whether or not to use unicode flat and sharp
+     * symbols.
+     * @param {boolean} [configuration.normalizeChords=true] Whether or not to automatically normalize chords
+     */
+    constructor(configuration?: DeepPartial<T>);
+    /**
+     * Configure the formatter with new options
+     * @param {DeepPartial<T>} config New configuration options
+     * @returns {this} The formatter instance for chaining
+     */
+    configure(config: DeepPartial<T>): this;
+    /**
+     * Get the default configuration for this formatter type
+     * Should be implemented by subclasses to return the appropriate default configuration
+     */
+    protected getDefaultConfiguration(): T;
+}
+type DefinitionSet = Record<string, ChordDefinition>;
+declare class ChordDefinitionSet {
+    definitions: DefinitionSet;
+    constructor(definitions?: DefinitionSet);
+    get(chord: string): ChordDefinition | null;
+    withDefaults(): ChordDefinitionSet;
+    add(chord: string, definition: ChordDefinition): void;
+    has(chord: string): boolean;
+    clone(): ChordDefinitionSet;
+}
+interface FormattingContext {
+    configuration: BaseFormatterConfiguration;
+    metadata: Metadata;
+}
+/**
+ * Represents a paragraph of lines in a chord sheet
+ */
+declare class Paragraph {
+    /**
+     * The {@link Line} items of which the paragraph consists
+     * @member
+     * @type {Line[]}
+     */
+    lines: Line[];
+    addLine(line: any): void;
+    /**
+     * Indicates whether the paragraph only contains literals. If true, {@link contents} can be used to retrieve
+     * the paragraph contents as one string where lines are separated by newlines.
+     * @see {@link contents}
+     * @returns {boolean}
+     */
+    isLiteral(): boolean;
+    /**
+     * Returns the paragraph contents as one string where lines are separated by newlines
+     * @returns {string}
+     */
+    get contents(): string;
+    /**
+     * Returns the label of the paragraph. The label is the value of the first section delimiter tag
+     * in the first line.
+     * @returns {string|null}
+     */
+    get label(): string | null;
+    /**
+     * Tries to determine the common type for all lines. If the types for all lines are equal, it returns that type.
+     * If not, it returns {@link INDETERMINATE}
+     * For the possible values, see {@link Line.type}
+     * @returns {string}
+     */
+    get type(): string;
+    get selector(): string | null;
+    get selectorIsNegated(): boolean;
+    /**
+     * Indicates whether the paragraph contains lines with renderable items.
+     * @see {@link Line.hasRenderableItems}
+     * @returns {boolean}
+     */
+    hasRenderableItems(): boolean;
+    isEmpty(): boolean;
+}
+/**
+ * Represents a parser warning, currently only used by ChordProParser.
+ */
+declare class ParserWarning {
+    /**
+     * The warning message
+     * @member
+     * @type {string}
+     */
+    message: string;
+    /**
+     * The chord sheet line number on which the warning occurred
+     * @member
+     * @type {number}
+     */
+    lineNumber: number | null;
+    /**
+     * The chord sheet column on which the warning occurred
+     * @member
+     * @type {number}
+     */
+    column: number | null;
+    /**
+     * @hideconstructor
+     */
+    constructor(message: string, lineNumber: number | null, column: number | null);
+    /**
+     * Returns a stringified version of the warning
+     * @returns {string} The string warning
+     */
+    toString(): string;
+}
+type MapItemsCallback = (_item: Item) => Item | Item[] | null;
+/**
+ * Represents a song in a chord sheet. Currently a chord sheet can only have one song.
+ */
+declare class Song extends MetadataAccessors {
+    /**
+     * The {@link Line} items of which the song consists
+     * @member {Line[]}
+     */
+    lines: Line[];
+    _bodyLines: Line[] | null;
+    _bodyParagraphs: Paragraph[] | null;
+    _renderParagraphs: Paragraph[] | null;
+    warnings: ParserWarning[];
+    _metadata: Metadata | null;
+    /**
+     * Creates a new {Song} instance
+     * @param metadata {Record<string, string | string[]>|Metadata} predefined metadata
+     */
+    constructor(metadata?: Record<string, string | string[]> | Metadata | null);
+    /** Returns song lines, skipping leading empty/meta-only lines. @returns {Line[]} */
+    get bodyLines(): Line[];
+    /** Returns song paragraphs, skipping paragraphs with only empty lines. @returns {Paragraph[]} */
+    get bodyParagraphs(): Paragraph[];
+    get renderParagraphs(): Paragraph[];
+    set renderParagraphs(paragraphs: Paragraph[]);
+    selectRenderableItems(items: (Line | Paragraph)[]): (Line | Paragraph)[];
+    /** The {@link Paragraph} items of which the song consists @member {Paragraph[]} */
+    get paragraphs(): Paragraph[];
+    /** The body paragraphs with any `{chorus}` tag expanded into the targeted chorus */
+    get expandedBodyParagraphs(): Paragraph[];
+    filterParagraphs(paragraphs: Paragraph[], configuration: Configuration): Paragraph[];
+    linesToParagraphs(lines: Line[]): Paragraph[];
+    /** Returns a deep clone of the song @returns {Song} */
+    clone(): Song;
+    getMetadataValue(name: string): string | string[] | null;
+    getSingleMetadataValue(name: string): string | null;
+    /**
+     * Returns a copy of the song with the key value set to the specified key. It changes:
+     * - the value for `key` in the {@link metadata} set
+     * - any existing `key` directive
+     * @param {number|null} key the key. Passing `null` will:
+     * - remove the current key from {@link metadata}
+     * - remove any `key` directive
+     * @returns {Song} The changed song
+     */
+    setKey(key: string | number | null): Song;
+    /**
+     * Returns a copy of the song with the key value set to the specified capo. It changes:
+     * - the value for `capo` in the {@link metadata} set
+     * - any existing `capo` directive
+     * @param {number|null} capo the capo. Passing `null` will:
+     * - remove the current key from {@link metadata}
+     * - remove any `capo` directive
+     * @returns {Song} The changed song
+     */
+    setCapo(capo: number | null): Song;
+    /**
+     * Transposes the song by the specified delta. It will:
+     * - transpose all chords, see: {@link Chord#transpose}
+     * - transpose the song key in {@link metadata}
+     * - update any existing `key` directive
+     * @param {number} delta The number of semitones (positive or negative) to transpose with
+     * @param {Object} [options={}] options
+     * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
+     * @returns {Song} The transposed song
+     */
+    transpose(delta: number, { accidental, normalizeChordSuffix }?: {
+        accidental?: Accidental | null;
+        normalizeChordSuffix?: boolean;
+    }): Song;
+    /**
+     * Transposes the song up by one semitone. It will:
+     * - transpose all chords, see: {@link Chord#transpose}
+     * - transpose the song key in {@link metadata}
+     * - update any existing `key` directive
+     * @param {Object} [options={}] options
+     * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
+     * @returns {Song} The transposed song
+     */
+    transposeUp({ normalizeChordSuffix }?: {
+        normalizeChordSuffix?: boolean;
+    }): Song;
+    /**
+     * Transposes the song down by one semitone. It will:
+     * - transpose all chords, see: {@link Chord#transpose}
+     * - transpose the song key in {@link metadata}
+     * - update any existing `key` directive
+     * @param {Object} [options={}] options
+     * @param {boolean} [options.normalizeChordSuffix=false] whether to normalize the chord suffixes after transposing
+     * @returns {Song} The transposed song
+     */
+    transposeDown({ normalizeChordSuffix }?: {
+        normalizeChordSuffix?: boolean;
+    }): Song;
+    /**
+     * Returns a copy of the song with the key set to the specified key. It changes:
+     * - the value for `key` in the {@link metadata} set
+     * - any existing `key` directive
+     * - all chords, those are transposed according to the distance between the current and the new key
+     * @param {string} newKey The new key.
+     * @returns {Song} The changed song
+     */
+    changeKey(newKey: string | Key): Song;
+    /**
+     * Returns a copy of the song with all chords changed to the specified accidental.
+     *
+     * Examples:
+     *
+     * ```js
+     * song.useAccidental('#');
+     * song.useAccidental('b');
+     * ```
+     *
+     * @param {Accidental} accidental the new accidental
+     * @returns {Song} the changed song
+     */
+    useAccidental(accidental: Accidental): Song;
+    /**
+     * @deprecated Use useAccidental instead
+     */
+    useModifier(accidental: Accidental): Song;
+    /**
+     * Returns a copy of the song with all chords normalized to the specified key. See {@link Chord#normalize}.
+     * @param key the key to normalize to
+     * @param options options
+     * @param options.normalizeSuffix whether to normalize the chord suffixes
+     */
+    normalizeChords(key?: Key | string | null, { normalizeSuffix }?: {
+        normalizeSuffix?: boolean;
+    }): Song;
+    mapChordLyricsPairs(func: (pair: ChordLyricsPair) => ChordLyricsPair): Song;
+    changeChords(func: (chord: Chord) => Chord): Song;
+    get currentKey(): Key | null;
+    requireCurrentKey(): Key;
+    /**
+     * Returns a copy of the song with the directive value(s) set to the specified value(s).
+     * - when there is a matching directive in the song, it will update the directive
+     * - when there is no matching directive, it will be inserted
+     * If `value` is `null` it will act as a delete, any directive matching `name` will be removed.
+     *
+     * @example
+     * ```javascript
+     * song.changeMetadata('author', 'John');
+     * song.changeMetadata('composer', ['Jane', 'John']);
+     * song.changeMetadata('key', null); // Remove key directive
+     * ```
+     * @param name The directive name
+     * @param {string | string[] | null} value The value to set, or `null` to remove the directive
+     * @return {Song} The changed song
+     */
+    changeMetadata(name: string, value: string | string[] | null): Song;
+    /**
+     * Returns a copy of the song with the metadata changed. It will:
+     * - update the metadata
+     * - update any existing directive matching the metadata key
+     * - insert a new directive if it does not exist
+     * @example
+     * ```javascript
+     * song.changeMetadata({
+     *   author: 'John',
+     *   composer: ['Jane', 'John'],
+     *   key: null, // Remove key directive
+     * });
+     * ```
+     * @param {Record<string, string | string[] | null>} metadata The metadata to change
+     */
+    changeMetadata(metadata: Record<string, string | string[] | null>): Song;
+    addLine(line: Line): void;
+    /**
+     * Change the song contents inline. Return a new {@link Item} to replace it. Return `null` to remove it.
+     * @example
+     * // transpose all chords:
+     * song.mapItems((item) => {
+     *   if (item instanceof ChordLyricsPair) {
+     *     return item.transpose(2, 'D');
+     *   }
+     *
+     *   return item;
+     * });
+     * @param {MapItemsCallback} func the callback function
+     * @returns {Song} the changed song
+     */
+    mapItems(func: MapItemsCallback): Song;
+    foreachItem(func: (_item: Item) => void): void;
+    /**
+     * Returns all unique chords used in the song
+     * @returns {string[]} the chords
+     */
+    getChords(): string[];
+    /**
+     * Returns all chord definitions from the song.
+     * Definitions are made using the `{chord}` or `{define}` directive.
+     * A chord definitions overrides a previous chord definition for the exact same chord.
+     * @returns {Record<string, ChordDefinition>} the chord definitions
+     * @see https://chordpro.org/chordpro/directives-define/
+     * @see https://chordpro.org/chordpro/directives-chord/
+     */
+    getChordDefinitions(context?: FormattingContext): Record<string, ChordDefinition>;
+    /**
+     * The song's metadata. When there is only one value for an entry, the value is a string. Else, the value is
+     * an array containing all unique values for the entry.
+     * @type {Metadata}
+     */
+    get metadata(): Metadata;
+    getMetadata(configuration?: Configuration): Metadata;
+    get chordDefinitions(): ChordDefinitionSet;
+    /**
+     * Change the song contents inline. Return a new {@link Line} to replace it. Return `null` to remove it.
+     * @example
+     * // remove lines with only Tags:
+     * song.mapLines((line) => {
+     *   if (line.items.every(item => item instanceof Tag)) {
+     *     return null;
+     *   }
+     *
+     *   return line;
+     * });
+     * @param {MapLinesCallback} func the callback function
+     * @returns {Song} the changed song
+     */
+    mapLines(func: (_line: Line) => Line | null): Song;
+}
+interface TextDimensions {
+    width: number;
+    height: number;
+}
+interface Measurer {
+    /**
+     * Measures the dimensions of text with the given font configuration
+     * @param text The text to measure
+     * @param fontConfig The font configuration to apply
+     * @returns The dimensions of the text
+     */
+    measureText(text: string, fontConfig: FontConfiguration): TextDimensions;
+    /**
+     * Measures the width of text with the given font configuration
+     * @param text The text to measure
+     * @param fontConfig The font configuration to apply
+     * @returns The width of the text
+     */
+    measureTextWidth(text: string, fontConfig: FontConfiguration): number;
+    /**
+     * Measures the height of text with the given font configuration
+     * @param text The text to measure
+     * @param fontConfig The font configuration to apply
+     * @returns The height of the text
+     */
+    measureTextHeight(text: string, fontConfig: FontConfiguration): number;
+    /**
+     * Splits text into lines that fit within the given width
+     * @param text The text to split
+     * @param maxWidth The maximum width of each line
+     * @param fontConfig The font configuration to apply
+     * @returns The lines of text
+     */
+    splitTextToSize(text: string, maxWidth: number, fontConfig: FontConfiguration): string[];
+}
+/**
+ * Base class for implementing measurers with common functionality
+ */
+declare abstract class BaseMeasurer implements Measurer {
+    abstract measureText(text: string, fontConfig: FontConfiguration): TextDimensions;
+    measureTextWidth(text: string, fontConfig: FontConfiguration): number;
+    measureTextHeight(text: string, fontConfig: FontConfiguration): number;
+    abstract splitTextToSize(text: string, maxWidth: number, fontConfig: FontConfiguration): string[];
+    protected splitTextWithMeasure(text: string, maxWidth: number, measure: (value: string) => number): string[];
+    protected wrapParagraph(paragraph: string, maxWidth: number, measure: (value: string) => number): string[];
+    protected splitWord(word: string, maxWidth: number, measure: (value: string) => number): {
+        lines: string[];
+        remainder: string;
+    };
+}
+/**
+ * Measures text using jsPDF
+ */
+export class JsPdfMeasurer extends BaseMeasurer {
+    constructor(doc: DocWrapper);
+    measureText(text: string, fontConfig: FontConfiguration): TextDimensions;
+    splitTextToSize(text: string, maxWidth: number, fontConfig: FontConfiguration): string[];
+}
+/**
+ * Base formatter for formatters that need measurements to position elements
+ */
+declare abstract class MeasurementBasedFormatter<T extends MeasurementBasedFormatterConfiguration = MeasurementBasedFormatterConfiguration> extends Formatter<T> {
+    /**
+     * Instantiate a measurement-based formatter.
+     * @param configuration - The formatter configuration.
+     */
+    constructor(configuration?: DeepPartial<T>);
+    /**
+     * Get the default configuration for this formatter type
+     * Uses the measurement-based default configuration
+     */
+    protected getDefaultConfiguration(): T;
+}
+interface Margins {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+type FontSection = 'title' | 'subtitle' | 'metadata' | 'text' | 'chord' | 'comment' | 'annotation' | 'sectionLabel';
+type Alignment = 'left' | 'center' | 'right' | number;
+type MeasurerType = 'canvas' | 'dom' | 'jspdf';
+type ConditionRule = Partial<{
+    equals: any;
+    not_equals: any;
+    greater_than: number;
+    greater_than_equal: number;
+    less_than: number;
+    less_than_equal: number;
+    like: string;
+    contains: string;
+    in: any[];
+    not_in: any[];
+    all: any[];
+    exists: boolean;
+    first: boolean;
+    last: boolean;
+}>;
+type SingleCondition = Record<string, ConditionRule>;
+type ConditionalRule = Partial<{
+    and: SingleCondition[];
+    or: SingleCondition[];
+}> | SingleCondition;
+interface Position {
+    x: Alignment;
+    y: number;
+    width?: number;
+    height?: number;
+    offsetX?: number;
+    clip?: boolean;
+    ellipsis?: boolean;
+}
+interface Dimension {
+    width: number;
+    height: number;
+}
+interface FontConfiguration {
+    name: string;
+    style: string;
+    weight?: string | number;
+    size: number;
+    lineHeight?: number;
+    color: string | number;
+    underline?: boolean;
+    inherit?: string;
+    textTransform?: string;
+    textDecoration?: string;
+    letterSpacing?: string;
+}
+type FontConfigurations = Record<FontSection, FontConfiguration>;
+type ChordDiagramFontConfigurations = Record<'title' | 'fingerings' | 'baseFret', FontConfiguration>;
+interface SectionDisplay {
+    labelStyle?: 'uppercase';
+    showLabel?: boolean;
+    lyricsOnly?: boolean;
+    indent?: number;
+    compact?: boolean;
+    repeatedSections?: 'hide' | 'title_only' | 'lyrics_only' | 'full';
+}
+interface SectionTypeConfig {
+    fonts?: FontConfigurations;
+    display?: SectionDisplay;
+    overrides?: {
+        condition: ConditionalRule;
+        display: Partial<SectionDisplay>;
+    }[];
+}
+interface ColumnConfig {
+    columnCount?: number;
+    columnSpacing: number;
+    minColumnWidth?: number;
+    maxColumnWidth?: number;
+}
+interface SectionsConfig {
+    global: {
+        columnWidth: number;
+        spacingBottom?: number;
+        spacingAfter?: number;
+        chordLyricSpacing: number;
+        linePadding: number;
+        paragraphSpacing?: number;
+        chordSpacing: number;
+    } & ColumnConfig;
+    base: SectionTypeConfig;
+    types?: Record<ParagraphType, SectionTypeConfig | undefined>;
+}
+interface ILayoutContentItem {
+    type: string;
+    position: Position;
+    condition?: ConditionalRule;
+}
+interface LayoutContentItemWithText extends ILayoutContentItem {
+    type: 'text';
+    style: FontConfiguration;
+    value?: string;
+    template?: string;
+    cssClass?: string;
+    elementStyle?: Record<string, string>;
+}
+interface LayoutContentItemWithValue extends LayoutContentItemWithText {
+    value: string;
+}
+interface LayoutContentItemWithTemplate extends LayoutContentItemWithText {
+    template: string;
+}
+interface LayoutContentItemWithImage extends ILayoutContentItem {
+    type: 'image';
+    src: string;
+    position: Position;
+    compression: ImageCompression;
+    size: Dimension;
+    alias?: string;
+    rotation?: number;
+}
+interface LineStyle {
+    color: string;
+    width: number;
+    dash?: number[];
+}
+interface LayoutContentItemWithLine {
+    type: 'line';
+    style: LineStyle;
+    position: {
+        x?: number;
+        y: number;
+        width: number | 'auto';
+        height?: number;
+    };
+    condition?: ConditionalRule;
+}
+type LayoutContentItem = LayoutContentItemWithValue | LayoutContentItemWithTemplate | LayoutContentItemWithImage | LayoutContentItemWithLine;
+interface LayoutItem {
+    height: number;
+    content: LayoutContentItem[];
+}
+interface ChordDiagramOverrides {
+    hide?: boolean;
+    definition?: string;
+}
+interface ChordDiagramsConfig {
+    enabled: boolean;
+    renderingConfig?: ChordDiagramRenderingConfig;
+    definitions?: {
+        hiddenChords: string[];
+    };
+    overrides?: {
+        global?: Record<string, ChordDiagramOverrides>;
+        byKey?: Record<string, Record<string, ChordDiagramOverrides>>;
+    };
+    fonts: ChordDiagramFontConfigurations;
+}
+interface MeasurementBasedLayoutConfig {
+    global: {
+        margins: Margins;
+    };
+    header: LayoutItem;
+    footer: LayoutItem;
+    sections?: SectionsConfig;
+    chordDiagrams?: ChordDiagramsConfig;
+}
+interface MeasurementBasedFormatterConfiguration extends BaseFormatterConfiguration {
+    fonts: FontConfigurations;
+    measurer: MeasurerType;
+    layout: MeasurementBasedLayoutConfig;
+}
+type Configuration = BaseFormatterConfiguration;
+declare class DocWrapper {
+    currentPage: number;
+    fontConfiguration: FontConfiguration;
+    totalPages: number;
+    doc: any;
+    static setup(docConstructor: PdfConstructor, options?: jsPDFOptions): DocWrapper;
+    constructor(DocConstructor: PdfConstructor, options: jsPDFOptions);
+    get pageSize(): {
+        width: number;
+        height: number;
+    };
+    save(filename: string): void;
+    output(): any;
+    eachPage(callback: () => void): void;
+    newPage(): void;
+    setPage(page: number): void;
+    setFont(fontName: string, fontStyle?: string, fontWeight?: string | number): void;
+    getFont(): any;
+    getFontSize(): any;
+    getFillColor(): any;
+    setFillColor(color: number | string): void;
+    setFontStyle(styleConfig: FontConfiguration): void;
+    setFontSize(size: number): void;
+    withFontConfiguration(fontConfiguration: FontConfiguration | null, callback: () => any): any;
+    setTextColor(color: string | number): void;
+    getTextDimensions(text: string, fontStyle?: FontConfiguration): {
+        w: number;
+        h: number;
+    };
+    getTextWidth(text: string, fontStyle?: FontConfiguration): number;
+    getTextHeight(text: string, fontStyle?: FontConfiguration): number;
+    getSpaceWidth(): number;
+    text(text: string, x: number, y: number, style?: FontConfiguration): void;
+    setDrawColor(color: number | string): void;
+    setLineWidth(width: number): void;
+    splitTextToSize(text: string | null, maxWidth: number, fontStyle?: FontConfiguration): any;
+    addImage(imageData: string, format: string, x: number, y: number, width: number, height: number, alias?: string, compression?: ImageCompression, rotation?: number): void;
+    setLineStyle(style: LineStyle): void;
+    resetDash(): void;
+    line(x1: number, y1: number, x2: number, y2: number): void;
+    circle(x: number, y: number, r: number, style?: string | null): void;
+    roundedRect(x: number, y: number, w: number, h: number, rx: number, ry: number, style?: string | null): void;
+    rect(x: number, y: number, w: number, h: number, style?: string | null): void;
+    withDrawColor(drawColor: number | string, callback: () => void): void;
+    withFillColor(fillColor: number | string, callback: () => void): void;
+    withFontSize(fontSize: number, callback: () => void): void;
+    withLineWidth(lineWidth: number, callback: () => void): void;
+}
+/**
+ * PdfFormatter formats a song into a PDF document.
+ */
+export class PdfFormatter extends MeasurementBasedFormatter<PDFFormatterConfiguration> {
+    /**
+     * Get the default configuration for PDF formatter
+     */
+    protected getDefaultConfiguration(): PDFFormatterConfiguration;
+    /**
+     * Formats a song into a PDF.
+     * @param song - The song to format.
+     * @param docConstructor - The PDF document constructor.
+     */
+    format(song: Song, docConstructor?: PdfConstructor): void;
+    /**
+     * Save the formatted document as a PDF file
+     */
+    save(): void;
+    /**
+     * Generate the PDF as a Blob object
+     */
+    generatePDF(): Promise<Blob>;
+    /**
+     * Get the document wrapper - primarily for testing purposes.
+     */
+    getDocumentWrapper(): DocWrapper;
+}
+
+//# sourceMappingURL=main.d.ts.map