@leafo/lml 0.2.0 → 0.3.0

package/dist/music.d.ts

@@ -1,108 +1,604 @@
+/**
+ * MIDI pitch value for middle C (C4).
+ * @example
+ * parseNote("C4") === MIDDLE_C_PITCH // true
+ */
 export declare const MIDDLE_C_PITCH = 60;
+/**
+ * Number of semitones in an octave.
+ */
 export declare const OCTAVE_SIZE = 12;
+/**
+ * Bidirectional mapping between note letters and their semitone offsets from C.
+ * Maps both directions: number -> letter name, and letter name -> number.
+ * Only includes natural notes (no sharps/flats).
+ * @example
+ * OFFSETS[0]   // "C"
+ * OFFSETS["C"] // 0
+ * OFFSETS[7]   // "G"
+ * OFFSETS["G"] // 7
+ */
 export declare const OFFSETS: Record<number | string, string | number>;
+/**
+ * Maps semitone offset (from C) to staff line position (0-6).
+ * Used for determining vertical placement on sheet music.
+ * @example
+ * LETTER_OFFSETS[0]  // 0 (C)
+ * LETTER_OFFSETS[7]  // 4 (G)
+ */
 export declare const LETTER_OFFSETS: Record<number, number>;
-export declare const NOTE_NAME_OFFSETS: Record<string, number>;
+/**
+ * Maps note letter names to staff line position (0-6).
+ * C=0, D=1, E=2, F=3, G=4, A=5, B=6.
+ * @example
+ * NOTE_NAME_OFFSETS["C"] // 0
+ * NOTE_NAME_OFFSETS["G"] // 4
+ */
+export declare const NOTE_NAME_OFFSETS: {
+    readonly C: 0;
+    readonly D: 1;
+    readonly E: 2;
+    readonly F: 3;
+    readonly G: 4;
+    readonly A: 5;
+    readonly B: 6;
+};
+/** Valid note letter names (A through G) */
+export type NoteLetter = keyof typeof NOTE_NAME_OFFSETS;
+/**
+ * Converts a MIDI pitch number to a note name string.
+ * @param pitch - MIDI pitch number (60 = middle C)
+ * @param sharpen - If true, use sharps for accidentals; if false, use flats
+ * @returns Note name with octave (e.g., "C4", "F#5", "Bb3")
+ * @example
+ * noteName(60)        // "C4"
+ * noteName(61)        // "C#4"
+ * noteName(61, false) // "Db4"
+ */
 export declare function noteName(pitch: number, sharpen?: boolean): string;
+/**
+ * Parses a note string into its MIDI pitch number.
+ * @param note - Note string with octave (e.g., "C4", "F#5", "Bb3")
+ * @returns MIDI pitch number (60 = middle C)
+ * @throws Error if note format is invalid
+ * @example
+ * parseNote("C4")  // 60
+ * parseNote("A4")  // 69
+ * parseNote("C#4") // 61
+ */
 export declare function parseNote(note: string): number;
+/**
+ * Calculates the vertical staff position for a note.
+ * Used for positioning notes on sheet music.
+ * @param note - Note string with octave (e.g., "C4", "G5"); letter must be A-G
+ * @returns Staff offset value (higher = higher on staff)
+ * @throws Error if note format is invalid; invalid letters yield NaN
+ * @example
+ * noteStaffOffset("C4") // 28
+ * noteStaffOffset("D4") // 29
+ */
 export declare function noteStaffOffset(note: string): number;
+/**
+ * Compares two notes ignoring octave (enharmonic comparison).
+ * @param a - First note string (with or without octave)
+ * @param b - Second note string (with or without octave)
+ * @returns True if notes are the same pitch class
+ * @example
+ * notesSame("C4", "C5")   // true (same pitch class)
+ * notesSame("C#4", "Db4") // true (enharmonic)
+ * notesSame("C4", "D4")   // false
+ */
 export declare function notesSame(a: string, b: string): boolean;
+/**
+ * Transposes a note by a given interval in semitones.
+ * @param note - Note string with octave (e.g., "C4")
+ * @param halfSteps - Number of semitones to transpose (positive = up, negative = down)
+ * @returns Transposed note string
+ * @example
+ * addInterval("C4", 2)  // "D4" (whole step up)
+ * addInterval("C4", 12) // "C5" (octave up)
+ * addInterval("C4", -1) // "B3" (half step down)
+ */
 export declare function addInterval(note: string, halfSteps: number): string;
+/**
+ * Compares two notes and returns the difference in semitones.
+ * @param a - First note string with octave
+ * @param b - Second note string with octave
+ * @returns 0 if equal, negative if a < b, positive if a > b
+ * @example
+ * compareNotes("C4", "C4") // 0
+ * compareNotes("C4", "D4") // -2
+ * compareNotes("D4", "C4") // 2
+ */
 export declare function compareNotes(a: string, b: string): number;
+/**
+ * Checks if the first note is lower than the second.
+ * @param a - First note string with octave
+ * @param b - Second note string with octave
+ * @returns True if a is lower than b
+ * @example
+ * notesLessThan("C4", "D4") // true
+ * notesLessThan("C5", "C4") // false
+ */
 export declare function notesLessThan(a: string, b: string): boolean;
+/**
+ * Checks if the first note is higher than the second.
+ * @param a - First note string with octave
+ * @param b - Second note string with octave
+ * @returns True if a is higher than b
+ * @example
+ * notesGreaterThan("D4", "C4") // true
+ * notesGreaterThan("C4", "D4") // false
+ */
 export declare function notesGreaterThan(a: string, b: string): boolean;
+/**
+ * Represents a musical key signature with a given number of sharps or flats.
+ * Positive count = sharps, negative count = flats, zero = C major/A minor.
+ * @example
+ * const gMajor = new KeySignature(1)  // G major (1 sharp)
+ * const fMajor = new KeySignature(-1) // F major (1 flat)
+ * gMajor.name() // "G"
+ * gMajor.accidentalNotes() // ["F"]
+ */
 export declare class KeySignature {
+    /** Circle of fifths note names */
     static FIFTHS: string[];
+    /** Natural note names in order of fifths (for accidental calculation) */
     static FIFTHS_TRUNCATED: string[];
     private static cache;
+    /**
+     * Returns all standard key signatures (excludes chromatic).
+     * Uses flat spellings for 6 accidentals (Gb instead of F#).
+     * @returns Array of KeySignature instances for standard major keys
+     */
     static allKeySignatures(): KeySignature[];
+    /**
+     * Gets a cached KeySignature instance for the given accidental count.
+     * @param count - Number of accidentals (positive = sharps, negative = flats)
+     * @returns KeySignature instance, or undefined if count is out of range
+     */
     static forCount(count: number): KeySignature | undefined;
+    /** Number of accidentals: positive = sharps, negative = flats, 0 = C major */
     count: number;
+    /**
+     * Creates a new KeySignature.
+     * @param count - Number of accidentals (positive = sharps, negative = flats)
+     */
     constructor(count: number);
+    /** Returns the number of accidentals in this key signature. */
     getCount(): number;
+    /** Returns true if this is a chromatic key signature. */
     isChromatic(): boolean;
+    /** Returns true if this key has sharps. */
     isSharp(): boolean;
+    /** Returns true if this key has flats. */
     isFlat(): boolean;
+    /**
+     * Returns the name of the major key (e.g., "G", "F", "Bb").
+     * @returns Key name string
+     * @example
+     * new KeySignature(0).name()  // => "C"
+     * new KeySignature(1).name()  // => "G" (1 sharp)
+     * new KeySignature(2).name()  // => "D" (2 sharps)
+     * new KeySignature(-1).name() // => "F" (1 flat)
+     * new KeySignature(-2).name() // => "Bb" (2 flats)
+     */
     name(): string;
+    /** Returns the key name as a string. */
     toString(): string;
+    /**
+     * Returns the root note for building scales from this key signature.
+     * @returns Note name (e.g., "G", "F")
+     */
     scaleRoot(): string;
+    /**
+     * Returns the default scale for this key signature.
+     * @returns A MajorScale rooted on this key
+     */
     defaultScale(): MajorScale;
+    /**
+     * Converts a note to its enharmonic equivalent that fits this key signature.
+     * Sharp keys convert flats to sharps; flat keys convert sharps to flats.
+     * @param note - Note string with octave
+     * @returns Enharmonic equivalent note string
+     * @example
+     * new KeySignature(1).enharmonic("Db4") // "C#4" (G major uses sharps)
+     * new KeySignature(-1).enharmonic("C#4") // "Db4" (F major uses flats)
+     */
     enharmonic(note: string): string;
+    /**
+     * Converts a MIDI pitch to a note name with correct enharmonic spelling for this key.
+     * Uses sharps for sharp keys and flats for flat keys.
+     * @param pitch - MIDI pitch number
+     * @returns Note name string with appropriate accidentals for this key
+     * @example
+     * new KeySignature(1).noteName(61)  // => "C#4" (G major uses sharps)
+     * new KeySignature(-1).noteName(61) // => "Db4" (F major uses flats)
+     * new KeySignature(0).noteName(61)  // => "C#4" (C major defaults to sharps)
+     */
     noteName(pitch: number): string;
+    /**
+     * Returns the note letters that have accidentals in this key.
+     * @returns Array of note letters (e.g., ["F"] for G major, ["B", "E"] for Bb major)
+     * @example
+     * new KeySignature(1).accidentalNotes()  // ["F"] (F# in G major)
+     * new KeySignature(-2).accidentalNotes() // ["B", "E"] (Bb, Eb)
+     */
     accidentalNotes(): string[];
+    /**
+     * Converts a note without accidentals to its actual pitch in this key.
+     * For example, in G major, "F" becomes "F#".
+     * @param note - Note string or MIDI pitch
+     * @returns Note string with appropriate accidentals applied
+     */
     unconvertNote(note: string | number): string;
+    /**
+     * Converts a note with accidentals to its staff spelling in this key.
+     * This is the inverse of unconvertNote - it strips accidentals that are
+     * implied by the key signature.
+     *
+     * Note: This only strips # or b accidentals. Notes without accidentals are
+     * returned unchanged. To determine if a natural sign is needed (e.g., F
+     * natural in D major), use {@link accidentalsForNote} which returns 0 when
+     * a natural is required.
+     *
+     * @param note - Note string with accidentals
+     * @returns Note string as it would appear on a staff with this key signature
+     * @example
+     * // In G major (1 sharp on F):
+     * new KeySignature(1).convertNote("F#4") // "F4" (sharp implied by key)
+     * new KeySignature(1).convertNote("C#4") // "C#4" (not in key, keep accidental)
+     * // In F major (1 flat on B):
+     * new KeySignature(-1).convertNote("Bb4") // "B4" (flat implied by key)
+     * // Notes without accidentals are unchanged:
+     * new KeySignature(2).convertNote("F4")  // "F4" (use accidentalsForNote to check if natural needed)
+     */
+    convertNote(note: string): string;
+    /**
+     * Determines how many accidentals should display for a note in this key.
+     * @param note - Note string or MIDI pitch
+     * @returns null if no accidental needed, 0 for natural, 1 for sharp, -1 for flat, etc.
+     * @example
+     * // In G major (1 sharp on F):
+     * new KeySignature(1).accidentalsForNote("F#4") // null (already in key)
+     * new KeySignature(1).accidentalsForNote("F4")  // 0 (natural needed)
+     * new KeySignature(1).accidentalsForNote("C#4") // 1 (sharp not in key)
+     */
     accidentalsForNote(note: string | number): number | null;
+    /**
+     * Returns the notes that need accidentals within a given pitch range.
+     * The returned notes are natural note names at specific octaves.
+     * @param min - Minimum note (string or MIDI pitch)
+     * @param max - Maximum note (string or MIDI pitch)
+     * @returns Array of note strings that need accidentals in this range
+     */
     notesInRange(min: string | number, max: string | number): string[];
 }
+/**
+ * A special key signature for chromatic contexts where all 12 notes are equally valid.
+ * Renders as C major (no accidentals in the key signature) but allows all chromatic notes.
+ */
 export declare class ChromaticKeySignature extends KeySignature {
     constructor();
+    /** Returns true (this is always a chromatic key signature). */
     isChromatic(): boolean;
+    /** Returns "Chromatic" as the key name. */
     name(): string;
+    /** Returns "C" as the scale root. */
     scaleRoot(): string;
+    /** Returns a ChromaticScale as the default scale. */
     defaultScale(): ChromaticScale;
 }
+/**
+ * Base class for musical scales. A scale is defined by a root note and
+ * a pattern of intervals (steps) in semitones.
+ * @example
+ * const cMajor = new MajorScale("C")
+ * cMajor.getRange(4, 8) // ["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"]
+ * cMajor.containsNote("D") // true
+ * cMajor.containsNote("Db") // false
+ */
 export declare class Scale {
+    /** Root note of the scale (e.g., "C", "G", "Bb") */
     root: string;
+    /** Interval pattern in semitones (e.g., [2,2,1,2,2,2,1] for major) */
     steps: number[];
+    /** True if this is a minor scale (affects enharmonic spelling) */
     minor: boolean;
+    /** True if this is a chromatic scale */
     chromatic: boolean;
+    /**
+     * Creates a new Scale.
+     * @param root - Root note as string (e.g., "C") or KeySignature
+     */
     constructor(root: string | KeySignature);
+    /**
+     * Returns all notes in the scale across 8 octaves.
+     * @returns Array of note strings covering the full playable range
+     */
     getFullRange(): string[];
+    /**
+     * Returns scale notes within a pitch range (inclusive).
+     * @param min - Minimum note string (e.g., "C3")
+     * @param max - Maximum note string (e.g., "C6")
+     * @returns Array of scale notes within the range
+     */
     getLooseRange(min: string, max: string): string[];
+    /**
+     * Returns a range of notes from the scale starting at a given octave.
+     * @param octave - Starting octave number
+     * @param count - Number of notes to return (default: one octave)
+     * @param offset - Scale degree offset (negative = start below root)
+     * @returns Array of note strings
+     * @example
+     * new MajorScale("C").getRange(4, 8)    // ["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"]
+     * new MajorScale("C").getRange(4, 3, 2) // ["E4", "F4", "G4"] (start from 3rd degree)
+     */
     getRange(octave: number, count?: number, offset?: number): string[];
+    /**
+     * Determines if this scale should use flats for accidentals.
+     * Based on the circle of fifths position of the root.
+     * @returns True if the scale should use flats
+     */
     isFlat(): boolean;
+    /**
+     * Checks if a note (any octave) belongs to this scale.
+     * @param note - Note string (with or without octave)
+     * @returns True if the note is in the scale
+     * @example
+     * new MajorScale("C").containsNote("D")  // true
+     * new MajorScale("C").containsNote("Db") // false
+     */
     containsNote(note: string): boolean;
+    /**
+     * Converts a scale degree number to a note name (without octave).
+     * Degrees are 1-indexed: 1 = root, 2 = second, etc.
+     * @param degree - Scale degree (1-indexed)
+     * @returns Note name string (e.g., "C", "D", "E")
+     * @example
+     * new MajorScale("C").degreeToName(1) // "C"
+     * new MajorScale("C").degreeToName(5) // "G"
+     */
     degreeToName(degree: number): string;
+    /**
+     * Gets the scale degree of a note.
+     * Degrees are 1-indexed: root = 1, second = 2, etc.
+     * @param note - Note string (with or without octave)
+     * @returns Scale degree number
+     * @throws Error if note is not in the scale
+     * @example
+     * new MajorScale("C").getDegree("C") // 1
+     * new MajorScale("C").getDegree("G") // 5
+     */
     getDegree(note: string): number;
+    /**
+     * Builds chord intervals by stacking thirds from a scale degree.
+     * @param degree - Starting scale degree (1-indexed)
+     * @param count - Number of intervals to generate (2 = triad, 3 = seventh chord)
+     * @returns Array of intervals in semitones
+     * @example
+     * new MajorScale("C").buildChordSteps(1, 2) // [4, 3] (C major triad intervals)
+     * new MajorScale("C").buildChordSteps(2, 2) // [3, 4] (D minor triad intervals)
+     */
     buildChordSteps(degree: number, count: number): number[];
+    /**
+     * Generates all diatonic chords in this scale.
+     * @param noteCount - Number of notes per chord (3 = triads, 4 = seventh chords)
+     * @returns Array of Chord instances built on each scale degree
+     * @example
+     * new MajorScale("C").allChords(3) // [C, Dm, Em, F, G, Am, Bdim]
+     */
     allChords(noteCount?: number): Chord[];
 }
+/**
+ * Major scale with the interval pattern W-W-H-W-W-W-H (whole and half steps).
+ * @example
+ * new MajorScale("C").getRange(4, 8) // ["C4", "D4", "E4", "F4", "G4", "A4", "B4", "C5"]
+ */
 export declare class MajorScale extends Scale {
     constructor(root: string | KeySignature);
 }
+/**
+ * Natural minor scale (Aeolian mode) with pattern W-H-W-W-H-W-W.
+ * @example
+ * new MinorScale("A").getRange(4, 8) // ["A4", "B4", "C5", "D5", "E5", "F5", "G5", "A5"]
+ */
 export declare class MinorScale extends Scale {
     minor: boolean;
     constructor(root: string | KeySignature);
 }
+/**
+ * Harmonic minor scale with raised 7th degree.
+ * Pattern: W-H-W-W-H-A2-H (A2 = augmented second, 3 semitones).
+ */
 export declare class HarmonicMinorScale extends Scale {
     minor: boolean;
     constructor(root: string | KeySignature);
 }
+/**
+ * Ascending melodic minor scale with raised 6th and 7th degrees.
+ * Pattern: W-H-W-W-W-W-H.
+ */
 export declare class AscendingMelodicMinorScale extends Scale {
     minor: boolean;
     constructor(root: string | KeySignature);
 }
+/**
+ * Major blues scale (6 notes).
+ * Notes in C: C, D, Eb, E, G, A.
+ */
 export declare class MajorBluesScale extends Scale {
     constructor(root: string | KeySignature);
 }
+/**
+ * Minor blues scale (6 notes).
+ * Notes in C: C, Eb, F, Gb, G, Bb.
+ */
 export declare class MinorBluesScale extends Scale {
     minor: boolean;
     constructor(root: string | KeySignature);
 }
+/**
+ * Chromatic scale containing all 12 semitones.
+ */
 export declare class ChromaticScale extends Scale {
     chromatic: boolean;
     constructor(root: string | KeySignature);
 }
+/**
+ * Represents a musical chord as a special kind of scale.
+ * Chords are defined by a root note and interval pattern.
+ * @example
+ * const cMajor = new Chord("C", "M")
+ * cMajor.getRange(4, 3) // ["C4", "E4", "G4"]
+ * Chord.notes("C4", "m7") // ["C4", "Eb4", "G4", "Bb4"]
+ */
 export declare class Chord extends Scale {
-    static SHAPES: Record<string, number[]>;
-    static notes(note: string, chordName: string, inversion?: number, notesCount?: number): string[];
-    constructor(root: string | KeySignature, intervals: string | number[]);
+    /**
+     * Predefined chord shapes as interval arrays (in semitones).
+     * - M: Major triad [4, 3]
+     * - m: Minor triad [3, 4]
+     * - dim: Diminished triad [3, 3]
+     * - aug: Augmented triad [4, 4]
+     * - 7: Dominant 7th [4, 3, 3]
+     * - M7: Major 7th [4, 3, 4]
+     * - m7: Minor 7th [3, 4, 3]
+     * - And more...
+     */
+    static SHAPES: {
+        readonly M: readonly [4, 3];
+        readonly m: readonly [3, 4];
+        readonly dim: readonly [3, 3];
+        readonly dimM7: readonly [3, 3, 5];
+        readonly dim7: readonly [3, 3, 3];
+        readonly aug: readonly [4, 4];
+        readonly augM7: readonly [4, 4, 3];
+        readonly M6: readonly [4, 3, 2];
+        readonly m6: readonly [3, 4, 2];
+        readonly M7: readonly [4, 3, 4];
+        readonly "7": readonly [4, 3, 3];
+        readonly m7: readonly [3, 4, 3];
+        readonly m7b5: readonly [3, 3, 4];
+        readonly mM7: readonly [3, 4, 4];
+        readonly Q: readonly [5, 5];
+        readonly Qb4: readonly [4, 5];
+    };
+    /**
+     * Static helper to get chord notes at a specific position.
+     * @param note - Root note with octave (e.g., "C4")
+     * @param chordName - Chord type from SHAPES (e.g., "M", "m7")
+     * @param inversion - Inversion number (0 = root position, 1 = first inversion, etc.)
+     * @param notesCount - Number of notes to return (0 = all chord tones)
+     * @returns Array of note strings
+     * @throws Error if note format is invalid or chordName is unknown
+     * @example
+     * Chord.notes("C4", "M")    // ["C4", "E4", "G4"]
+     * Chord.notes("C4", "M", 1) // ["E4", "G4", "C5"] (first inversion)
+     */
+    static notes(note: string, chordName: ChordShapeName, inversion?: number, notesCount?: number): string[];
+    /**
+     * Creates a new Chord.
+     * @param root - Root note as string (e.g., "C") or KeySignature
+     * @param intervals - Chord shape name (e.g., "M", "m7") or array of intervals in semitones
+     * @example
+     * new Chord("C", "M")      // C major from shape name
+     * new Chord("C", [4, 3])   // C major from intervals
+     */
+    constructor(root: string | KeySignature, intervals: ChordShapeName | readonly number[] | number[]);
+    /**
+     * Checks if this chord functions as a dominant (major or dominant 7th).
+     * @returns True if chord is major triad or dominant 7th
+     */
     isDominant(): boolean;
+    /**
+     * Gets possible resolution targets for this chord as a secondary dominant.
+     * A secondary dominant resolves down a fifth (up a fourth).
+     * @param noteCount - Number of notes in target chords (3 = triads, 4 = sevenths)
+     * @returns Array of possible target Chords (major and minor variants)
+     * @throws Error if this chord is not a dominant type
+     */
     getSecondaryDominantTargets(noteCount?: number): Chord[];
-    chordShapeName(): string | undefined;
+    /**
+     * Gets the name of this chord's shape from SHAPES (e.g., "M", "m7", "dim").
+     * @returns Shape name string, or undefined if no matching shape found
+     */
+    chordShapeName(): ChordShapeName | undefined;
+    /**
+     * Checks if all given notes belong to this chord.
+     * @param notes - Array of note strings to check
+     * @returns True if all notes are chord tones
+     * @example
+     * new Chord("C", "M").containsNotes(["C4", "E4", "G4"]) // true
+     * new Chord("C", "M").containsNotes(["C4", "F4"]) // false
+     */
     containsNotes(notes: string[]): boolean;
+    /**
+     * Counts how many notes two chords have in common.
+     * @param otherChord - Chord to compare with
+     * @returns Number of shared notes
+     */
     countSharedNotes(otherChord: Chord): number;
+    /**
+     * Returns the chord name as a string (e.g., "C", "Am7", "Bdim").
+     * @returns Chord name with root and quality
+     */
     toString(): string;
 }
+/** Valid chord shape names from Chord.SHAPES */
+export type ChordShapeName = keyof typeof Chord.SHAPES;
+/**
+ * Represents a musical staff with clef and note range information.
+ * Used for rendering notes on sheet music.
+ * @example
+ * const treble = Staff.forName("treble")
+ * treble.lowerNote // "E5" (bottom line)
+ * treble.upperNote // "F6" (top line)
+ */
 export declare class Staff {
     private static cache;
+    /**
+     * Gets a Staff instance by name.
+     * @param name - Staff name ("treble" or "bass")
+     * @returns Staff instance, or undefined if not found
+     */
     static forName(name: string): Staff | undefined;
+    /**
+     * Returns all available staff types.
+     * @returns Array of Staff instances
+     */
     static allStaves(): Staff[];
+    /** Staff name (e.g., "treble", "bass") */
     name: string;
+    /** Note on the bottom line of the staff */
     lowerNote: string;
+    /** Note on the top line of the staff */
     upperNote: string;
+    /** Note where the clef is positioned */
     clefNote: string;
+    /**
+     * Creates a new Staff.
+     * @param name - Staff identifier
+     * @param lowerNote - Note on bottom line (e.g., "E5" for treble)
+     * @param upperNote - Note on top line (e.g., "F6" for treble)
+     * @param clefNote - Note at clef position (e.g., "G5" for treble G-clef)
+     */
     constructor(name: string, lowerNote: string, upperNote: string, clefNote: string);
+    /**
+     * Gets the letter name of the clef (e.g., "G" for treble, "F" for bass).
+     * @returns Single letter clef name
+     */
     clefName(): string;
 }
+/**
+ * Transposes a key signature by a given number of semitones using circle of fifths.
+ * Each semitone = 7 steps on the circle of fifths (mod 12).
+ * @param currentKs - Current key signature count (positive = sharps, negative = flats)
+ * @param semitones - Number of semitones to transpose (positive = up, negative = down)
+ * @returns New key signature count, normalized to -6..5 range
+ * @example
+ * transposeKeySignature(0, 1)   // -5 (C major + 1 semitone = Db major)
+ * transposeKeySignature(1, 1)   // -4 (G major + 1 semitone = Ab major)
+ * transposeKeySignature(0, 12)  // 0  (octave transposition = no change)
+ */
+export declare function transposeKeySignature(currentKs: number, semitones: number): number;
 //# sourceMappingURL=music.d.ts.map

package/dist/music.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../src/music.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../src/music.ts"],"names":[],"mappings":"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"}