@goplayerjuggler/abc-tools 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplayerjuggler/abc-tools",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "sorting algorithm and implementation for ABC tunes; plus other tools for parsing and manipulating ABC tunes",
   "main": "src/index.js",
   "scripts": {

package/src/manipulator.js

@@ -4,6 +4,14 @@ const { parseAbc, getMeter, getUnitLength } = require("./parse/parser.js");
 const { getBarInfo } = require("./parse/getBarInfo.js");
 const { getHeaderValue } = require("./parse/header-parser.js");
 
+const {
+	getKeySignatureAccidentals,
+	getBarAccidentals,
+	addAccidentalsForMergedBar,
+	removeRedundantAccidentals,
+	reconstructMusicFromTokens
+} = require("./parse/accidental-helpers.js");
+
 // ============================================================================
 // ABC manipulation functions
 // ============================================================================
@@ -146,22 +154,25 @@ function hasAnacrucis(abc) {
  * - Converts variant ending markers from |1, |2 to [1, [2 format
  * - Respects section breaks (||, :|, etc.) and resets pairing after them
  * - Handles bars starting with variant endings by keeping the bar line after them
+ * - Adds accidentals when merging bars to restore key signature defaults
  *
  * When going from large to small meters (e.g., 4/2→4/4):
  * - Inserts bar lines at halfway points within each bar
  * - Preserves variant ending markers in [1, [2 format (does not convert back to |1, |2)
  * - Inserts bar lines before variant endings when they occur at the split point
+ * - Removes redundant accidentals in the second half of split bars
  *
  * This is nearly a true inverse operation - going there and back preserves musical content
  * but may change spacing around bar lines and normalises variant ending syntax to [1, [2 format.
- * Correctly handles anacrusis (pickup bars), multi-bar variant endings, partial bars, and preserves line breaks.
+ * Correctly handles anacrusis (pickup bars), multi-bar variant endings, partial bars, preserves line breaks,
+ * and manages accidentals correctly when bars are merged or split.
  *
  * @param {string} abc - ABC notation string
  * @param {Array<number>} smallMeter - The smaller meter signature [numerator, denominator]
  * @param {Array<number>} largeMeter - The larger meter signature [numerator, denominator]
  * @param {Array<number>} currentMeter - The current meter signature [numerator, denominator] of the abc tune - may be omitted. (If omitted, it gets fetched from `abc`)
  * @returns {string} ABC notation with toggled meter
- * @throws {Error} If the current meter doesn’t match either smallMeter or largeMeter
+ * @throws {Error} If the current meter doesn't match either smallMeter or largeMeter
  */
 function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 	if (!currentMeter) currentMeter = getMeter(abc);
@@ -197,6 +208,11 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 
 	if (isSmall) {
 		// Going from small to large: remove every other complete musical bar line
+
+		// Get initial key and build key map
+		const initialKey = getHeaderValue(abc, "K");
+		const keyAtBar = getKeyAtEachBar(barLines, initialKey);
+
 		// Get bar info to understand musical structure
 		getBarInfo(bars, barLines, meter, {
 			barNumbers: true,
@@ -215,27 +231,6 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 		const barLineDecisions = new Map();
 		const barLinesToConvert = new Map(); // variant markers to convert from |N to [N
 
-		//Discarded
-		// // Map bar numbers to their sequential index among complete bars
-		// // This handles cases where bar numbers skip (due to anacrusis or partials)
-		// const completeBarIndexByNumber = new Map();
-		// let completeBarIndex = 0;
-
-		// for (let i = 0; i < barLines.length; i++) {
-		// 	const barLine = barLines[i];
-		// 	if (
-		// 		barLine.barNumber !== null
-		// 		//&& !barLine.isSectionBreak
-		// 	) {
-		// 		const isCompleteMusicBar =
-		// 			!barLine.isPartial || barLine.completesMusicBar === true;
-		// 		if (isCompleteMusicBar) {
-		// 			completeBarIndexByNumber.set(barLine.barNumber, completeBarIndex);
-		// 			completeBarIndex++;
-		// 		}
-		// 	}
-		// }
-
 		const hasAnacrucis = hasAnacrucisFromParsed(null, barLines);
 
 		for (let i = 0; i < barLines.length; i++) {
@@ -256,7 +251,6 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 			// Section breaks are always kept
 			if (barLine.isSectionBreak) {
 				barLineDecisions.set(i, { action: "keep" });
-				// Don't count section breaks - they're structural markers, not part of pairing
 				continue;
 			}
 
@@ -273,10 +267,6 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 			// This is a complete bar - use its barNumber to decide
 			// Without anacrucis: Remove complete bars with even barNumber (0, 2, 4, ...), keep odd ones (1, 3, 5, ...)
 			// With anacrucis: the other way round!
-
-			//Discarded
-			// const index = completeBarIndexByNumber.get(barLine.barNumber);
-			// if (index !== undefined && index % 2 === 0) {
 			const remove = hasAnacrucis
 				? barLine.barNumber % 2 !== 0
 				: barLine.barNumber % 2 === 0;
@@ -305,25 +295,87 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 			}
 		}
 
-		//  --- Debugging - may be helpful ----
-		// console.log(
-		// 	"Bar line decisions:",
-		// 	Array.from(barLineDecisions.entries()).map(([i, d]) => ({
-		// 		index: i,
-		// 		barLine: barLines[i]?.text,
-		// 		sourceIndex: barLines[i]?.sourceIndex,
-		// 		action: d.action
-		// 	}))
-		// );
-
-		// console.log(
-		// 	"Bar lines:",
-		// 	barLines.map((bl) => ({ text: bl.text, sourceIndex: bl.sourceIndex }))
-		// );
-		// console.log(
-		// 	"Bars starting with variants:",
-		// 	Array.from(barStartsWithVariant.entries())
-		// );
+		// === ACCIDENTAL HANDLING ===
+		// Build map of bars to replace: bar start position -> {originalEnd, replacementText}
+
+		const barReplacements = new Map();
+
+		for (let i = 0; i < barLines.length; i++) {
+			const decision = barLineDecisions.get(i);
+
+			if (decision && decision.action === "remove") {
+				// Find which bar comes after this bar line
+				const barLineEnd = barLines[i].sourceIndex + barLines[i].sourceLength;
+
+				let bar2Idx = -1;
+				for (let b = 0; b < bars.length; b++) {
+					if (bars[b].length > 0 && bars[b][0].sourceIndex >= barLineEnd) {
+						bar2Idx = b;
+						break;
+					}
+				}
+
+				// Find the bar that ends at or before this bar line
+				let bar1Idx = -1;
+				for (let b = bars.length - 1; b >= 0; b--) {
+					if (bars[b].length > 0) {
+						const barEnd =
+							bars[b][bars[b].length - 1].sourceIndex +
+							bars[b][bars[b].length - 1].sourceLength;
+						if (barEnd <= barLines[i].sourceIndex) {
+							bar1Idx = b;
+							break;
+						}
+					}
+				}
+
+				if (bar1Idx >= 0 && bar2Idx >= 0 && bar2Idx < bars.length) {
+					// Get current key
+					const currentKey = keyAtBar.get(bar1Idx) || initialKey;
+					const keyAccidentals = getKeySignatureAccidentals(
+						currentKey,
+						normaliseKey
+					);
+
+					// Get accidentals at end of bar 1
+					const firstBarAccidentals = getBarAccidentals(
+						bars[bar1Idx],
+						keyAccidentals
+					);
+
+					// Modify bar 2 tokens
+					const modifiedBar2Tokens = addAccidentalsForMergedBar(
+						bars[bar2Idx],
+						firstBarAccidentals,
+						keyAccidentals,
+						musicText
+					);
+
+					// Reconstruct bar 2 text
+					const bar2Start = bars[bar2Idx][0].sourceIndex;
+					const bar2End =
+						bars[bar2Idx][bars[bar2Idx].length - 1].sourceIndex +
+						bars[bar2Idx][bars[bar2Idx].length - 1].sourceLength;
+
+					const modifiedText = reconstructMusicFromTokens(
+						modifiedBar2Tokens,
+						musicText
+					);
+					// console.log(
+					// 	`Replacement text: "${modifiedText}" (length: ${modifiedText.length})`
+					// );
+					// console.log(`First char code: ${modifiedText.charCodeAt(0)}`);
+
+					// Store replacement: when we reach bar2Start, replace until bar2End with modifiedText
+					barReplacements.set(bar2Start, {
+						originalEnd: bar2End,
+						replacementText: modifiedText
+					});
+				}
+			}
+		}
+
+		// === END ACCIDENTAL HANDLING ===
 
 		// Reconstruct music
 		let newMusic = "";
@@ -361,6 +413,23 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 						skipLength++;
 					}
 					pos += skipLength;
+
+					// NOW check if the bar after this removed bar line needs replacement
+					if (barReplacements.has(pos)) {
+						// const replacement = barReplacements.get(pos);
+						// newMusic += replacement.replacementText;
+						// pos = replacement.originalEnd;
+
+						const replacement = barReplacements.get(pos);
+						// console.log(`REPLACING: adding "${replacement.replacementText}"`);
+						// console.log(
+						// 	`REPLACING: jumping from ${pos} to ${replacement.originalEnd}`
+						// );
+						newMusic += replacement.replacementText;
+						pos = replacement.originalEnd;
+						// console.log(`newMusic so far: "${newMusic}"`);
+					}
+
 					continue;
 				} else if (decision && decision.action === "keep") {
 					// Keep this bar line
@@ -378,17 +447,134 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 		return `${newHeaders.join("\n")}\n${newMusic}`;
 	} else {
 		// Going from large to small: add bar lines at midpoints
+
+		// Get initial key and build key map
+		const initialKey = getHeaderValue(abc, "K");
+		const keyAtBar = getKeyAtEachBar(barLines, initialKey);
+
 		const barInfo = getBarInfo(bars, barLines, meter, {
 			divideBarsBy: 2
 		});
 
 		const { midpoints } = barInfo;
 
+		// === ACCIDENTAL HANDLING ===
+		// Build map of bar sections to replace
+
+		const barReplacements = new Map();
+
+		for (let i = 0; i < bars.length; i++) {
+			const bar = bars[i];
+			if (bar.length === 0) continue;
+
+			const barStart = bar[0].sourceIndex;
+			const barEnd =
+				bar[bar.length - 1].sourceIndex + bar[bar.length - 1].sourceLength;
+			const midpoint = midpoints.find((mp) => mp > barStart && mp < barEnd);
+
+			if (midpoint) {
+				// Get current key
+				const currentKey = keyAtBar.get(i) || initialKey;
+				const keyAccidentals = getKeySignatureAccidentals(
+					currentKey,
+					normaliseKey
+				);
+
+				// Split into first and second half
+				const firstHalfTokens = bar.filter((t) => t.sourceIndex < midpoint);
+				const secondHalfTokens = bar.filter((t) => t.sourceIndex >= midpoint);
+
+				if (secondHalfTokens.length > 0) {
+					// Get accidentals from first half
+					const firstHalfAccidentals = getBarAccidentals(
+						firstHalfTokens,
+						keyAccidentals
+					);
+
+					// Remove redundant accidentals from second half
+					const modifiedSecondHalf = removeRedundantAccidentals(
+						secondHalfTokens,
+						firstHalfAccidentals,
+						keyAccidentals
+					);
+
+					// Reconstruct
+					const secondHalfStart = secondHalfTokens[0].sourceIndex;
+					const secondHalfEnd =
+						secondHalfTokens[secondHalfTokens.length - 1].sourceIndex +
+						secondHalfTokens[secondHalfTokens.length - 1].sourceLength;
+
+					const modifiedText = reconstructMusicFromTokens(
+						modifiedSecondHalf,
+						musicText
+					);
+
+					// console.log(
+					// 	`Replacement text: "${modifiedText}" (length: ${modifiedText.length})`
+					// );
+					// console.log(`First char code: ${modifiedText.charCodeAt(0)}`);
+
+					barReplacements.set(secondHalfStart, {
+						originalEnd: secondHalfEnd,
+						replacementText: modifiedText
+					});
+				}
+			}
+		}
+
+		// Reconstruct music with replacements
+		let newMusic = "";
+		let pos = 0;
+
+		while (pos < musicText.length) {
+			// Check if we're at a bar section that needs replacement
+			if (barReplacements.has(pos)) {
+				// const replacement = barReplacements.get(pos);
+				// newMusic += replacement.replacementText;
+				// pos = replacement.originalEnd;
+				// continue;
+
+				const replacement = barReplacements.get(pos);
+				// console.log(`REPLACING: adding "${replacement.replacementText}"`);
+				// console.log(
+				// 	`REPLACING: jumping from ${pos} to ${replacement.originalEnd}`
+				// );
+				newMusic += replacement.replacementText;
+				pos = replacement.originalEnd;
+				// console.log(`newMusic so far: "${newMusic}"`);
+			}
+
+			// Regular character
+			newMusic += musicText[pos];
+			pos++;
+		}
+
+		// === END ACCIDENTAL HANDLING ===
+
 		// Insert bar lines at calculated positions
 		const insertionPoints = [...midpoints].sort((a, b) => b - a);
-		let newMusic = musicText;
+
+		// Adjust positions based on replacements
+		const adjustedInsertionPoints = [];
 
 		for (const pos of insertionPoints) {
+			let adjustedPos = pos;
+
+			// Calculate offset from replacements before this position
+			for (const [replStart, replInfo] of barReplacements.entries()) {
+				if (replStart < pos) {
+					const originalLength = replInfo.originalEnd - replStart;
+					const newLength = replInfo.replacementText.length;
+					adjustedPos += newLength - originalLength;
+				}
+			}
+
+			adjustedInsertionPoints.push(adjustedPos);
+		}
+
+		// Insert bar lines (in reverse order to maintain positions)
+		adjustedInsertionPoints.sort((a, b) => b - a);
+		for (const pos of adjustedInsertionPoints) {
 			newMusic = newMusic.substring(0, pos) + "| " + newMusic.substring(pos);
 		}
 
@@ -396,6 +582,32 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 	}
 }
 
+/**
+ * Build a map of bar index to active key signature
+ * Tracks key changes from barLines[].newKey
+ *
+ * @param {Array} barLines - Bar line array from parseAbc
+ * @param {string} initialKey - Initial K: header value
+ * @returns {Map<number, string>} - Map from bar index to key signature string
+ */
+function getKeyAtEachBar(barLines, initialKey) {
+	const keyMap = new Map();
+	let currentKey = initialKey;
+
+	// Bar index 0 is before the first bar line (or at it if there's an initial bar line)
+	keyMap.set(0, currentKey);
+
+	for (let i = 0; i < barLines.length; i++) {
+		if (barLines[i].newKey) {
+			currentKey = barLines[i].newKey;
+		}
+		// The key after this bar line applies to the next bar
+		keyMap.set(i + 1, currentKey);
+	}
+
+	return keyMap;
+}
+
 /**
  * Toggle between M:4/4 and M:4/2 by surgically adding/removing bar lines
  * This is a true inverse operation - going there and back preserves the ABC exactly
@@ -408,6 +620,7 @@ function toggleMeter_4_4_to_4_2(abc, currentMeter) {
 const defaultCommentForReelConversion =
 	"*abc-tools: convert to M:4/4 & L:1/16*";
 const defaultCommentForHornpipeConversion = "*abc-tools: convert to M:4/2*";
+const defaultCommentForPolkaConversion = "*abc-tools: convert to M:4/4*";
 const defaultCommentForJigConversion = "*abc-tools: convert to M:12/8*";
 /**
  * Adjusts bar lengths and L, M fields - a 
@@ -470,6 +683,20 @@ function convertStandardJig(jig, comment = defaultCommentForJigConversion) {
 	return result;
 }
 
+function convertStandardPolka(t, comment = defaultCommentForPolkaConversion) {
+	const meter = getMeter(t);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 2 || !meter[1] === 4) {
+		throw new Error("invalid meter");
+	}
+
+	let result = //toggleMeter_4_4_to_4_2(reel, meter);
+		toggleMeterDoubling(t, [2, 4], [4, 4], meter);
+	if (comment) {
+		result = result.replace(/(\nK:)/, `\nN:${comment}$1`);
+	}
+	return result;
+}
+
 /**
  * Adjusts bar lengths and M field to alter a
  * hornpipe written in the normal way (M:6/8) so it’s
@@ -580,6 +807,19 @@ function convertToStandardJig(jig, comment = defaultCommentForJigConversion) {
 	return result;
 }
 
+function convertToStandardPolka(t, comment = defaultCommentForPolkaConversion) {
+	const meter = getMeter(t);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 4 || !meter[1] === 4) {
+		throw new Error("invalid meter");
+	}
+
+	let result = toggleMeterDoubling(t, [2, 4], [4, 4], meter);
+	if (comment) {
+		result = result.replace(`\nN:${comment}`, "");
+	}
+	return result;
+}
+
 function convertToStandardHornpipe(
 	hornpipe,
 	comment = defaultCommentForHornpipeConversion
@@ -821,21 +1061,19 @@ function canDoubleBarLength(abc) {
 		rhythm = getHeaderValue(abc, "R");
 	if (
 		!rhythm ||
-		["reel", "hornpipe", "jig"].indexOf(rhythm.toLowerCase()) < 0
+		["reel", "hornpipe", "jig", "polka"].indexOf(rhythm.toLowerCase()) < 0
 	) {
 		return false;
 	}
 	return (
-		!abc.match(/\[M:/) && //inline meter marking
-		!abc.match(/\[L:/) &&
-		(((rhythm === "reel" || rhythm === "hornpipe") &&
-			l.equals(new Fraction(1, 8)) &&
-			meter[0] === 4 &&
-			meter[1] === 4) ||
-			(rhythm === "jig" &&
+		(!abc.match(/\[M:/) && //inline meter marking
+			!abc.match(/\[L:/) &&
+			(((rhythm === "reel" || rhythm === "hornpipe") &&
 				l.equals(new Fraction(1, 8)) &&
-				meter[0] === 6 &&
-				meter[1] === 8))
+				meter[0] === 4 &&
+				meter[1] === 4) ||
+				(rhythm === "jig" && meter[0] === 6 && meter[1] === 8))) ||
+		(rhythm === "polka" && meter[0] === 2 && meter[1] === 4)
 	);
 }
 function canHalveBarLength(abc) {
@@ -844,17 +1082,11 @@ function canHalveBarLength(abc) {
 		rhythm = getHeaderValue(abc, "R");
 	if (
 		!rhythm ||
-		["reel", "hornpipe", "jig"].indexOf(rhythm.toLowerCase()) < 0
+		["reel", "hornpipe", "jig", "polka"].indexOf(rhythm.toLowerCase()) < 0
 	) {
 		return false;
 	}
 
-	if (
-		!rhythm ||
-		["reel", "hornpipe", "jig"].indexOf(rhythm.toLowerCase()) < 0
-	) {
-		return false;
-	}
 	return (
 		!abc.match(/\[M:/) && //inline meter marking
 		!abc.match(/\[L:/) &&
@@ -866,10 +1098,8 @@ function canHalveBarLength(abc) {
 				l.equals(new Fraction(1, 8)) &&
 				meter[0] === 4 &&
 				meter[1] === 2) ||
-			(rhythm === "jig" &&
-				l.equals(new Fraction(1, 8)) &&
-				meter[0] === 12 &&
-				meter[1] === 8))
+			(rhythm === "jig" && meter[0] === 12 && meter[1] === 8) ||
+			(rhythm === "polka" && meter[0] === 4 && meter[1] === 4))
 	);
 }
 
@@ -878,9 +1108,11 @@ module.exports = {
 	canHalveBarLength,
 	convertStandardJig,
 	convertStandardHornpipe,
+	convertStandardPolka,
 	convertStandardReel,
 	convertToStandardJig,
 	convertToStandardHornpipe,
+	convertToStandardPolka,
 	convertToStandardReel,
 	defaultCommentForReelConversion,
 	doubleBarLength,

package/src/parse/accidental-helpers.js

@@ -0,0 +1,438 @@
+/**
+ * Accidental handling helpers for toggleMeterDoubling
+ * Uses existing parsed token structure from parseAbc
+ */
+
+/**
+ * Extract accidentals implied by a key signature
+ * @param {string} keyHeader - The K: header value (e.g., "D dorian", "F# minor")
+ * @param {Function} normaliseKey - The normaliseKey function from manipulator.js
+ * @returns {Map<string, string>} - Map of note letter to accidental ('^', '_', or null for natural)
+ */
+function getKeySignatureAccidentals(keyHeader, normaliseKey) {
+	// Parse key using existing normaliseKey
+	const parsed = normaliseKey(keyHeader);
+	const tonic = parsed[0];
+	const mode = parsed[1];
+
+	// Remove unicode accidentals from tonic to get base note
+	const baseNote = tonic.replace(/[♯♭]/g, "");
+	const tonicAccidental =
+		tonic.length > 1 ? (tonic.includes("♯") ? "^" : "_") : null;
+
+	// Semitone positions for each natural note
+	const noteValues = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+
+	// Mode patterns (semitones from tonic)
+	const modePatterns = {
+		major: [0, 2, 4, 5, 7, 9, 11], // Ionian
+		minor: [0, 2, 3, 5, 7, 8, 10], // Aeolian
+		mixolydian: [0, 2, 4, 5, 7, 9, 10],
+		dorian: [0, 2, 3, 5, 7, 9, 10],
+		phrygian: [0, 1, 3, 5, 7, 8, 10],
+		lydian: [0, 2, 4, 6, 7, 9, 11],
+		locrian: [0, 1, 3, 5, 6, 8, 10]
+	};
+
+	const pattern = modePatterns[mode] || modePatterns.major;
+	const notes = ["C", "D", "E", "F", "G", "A", "B"];
+
+	// Calculate tonic's actual semitone position
+	let tonicValue = noteValues[baseNote];
+	if (tonicAccidental === "^") tonicValue = (tonicValue + 1) % 12;
+	if (tonicAccidental === "_") tonicValue = (tonicValue + 11) % 12;
+
+	// Build the scale and determine accidentals
+	const accidentals = new Map();
+	for (let i = 0; i < 7; i++) {
+		const noteLetter = notes[(notes.indexOf(baseNote) + i) % 7];
+		const expectedValue = (tonicValue + pattern[i]) % 12;
+		const naturalValue = noteValues[noteLetter];
+
+		const diff = (expectedValue - naturalValue + 12) % 12;
+		if (diff === 1) {
+			accidentals.set(noteLetter, "^"); // Sharp
+		} else if (diff === 11) {
+			accidentals.set(noteLetter, "_"); // Flat
+		}
+		// diff === 0 means natural (no entry)
+	}
+
+	return accidentals;
+}
+
+/**
+ * Extract accidental and note information from a parsed note token
+ * Handles regular notes and chords in brackets
+ *
+ * @param {object} token - Parsed token object from parseAbc
+ * @returns {Array<object>} - Array of {noteLetter, octaveMarkers, accidental} objects
+ */
+function extractNoteInfo(token) {
+	if (!token.pitch) return [];
+
+	const result = [];
+
+	// Handle chord in brackets [CEG]
+	if (token.isChord && token.chordNotes) {
+		// Process each note in the chord
+		for (const chordNote of token.chordNotes) {
+			const info = extractNoteInfo(chordNote);
+			result.push(...info);
+		}
+		return result;
+	}
+
+	// Regular note - extract from the token string
+	// Format: [decorations][accidental]pitch[octave][duration][tie]
+	// We need to extract the accidental, pitch letter, and octave markers
+
+	const tokenStr = token.token;
+
+	// Match pattern: optional accidental (=, ^, _, ^^, __) followed by pitch followed by octave markers
+	const noteMatch = tokenStr.match(/(__|_|=|\^\^|\^)?([A-Ga-g])([',]*)/);
+
+	if (noteMatch) {
+		const accidental = noteMatch[1] || null;
+		const noteLetter = noteMatch[2];
+		const octaveMarkers = noteMatch[3] || "";
+
+		result.push({
+			noteLetter,
+			octaveMarkers,
+			accidental,
+			noteWithOctave: noteLetter + octaveMarkers
+		});
+	}
+
+	return result;
+}
+
+/**
+ * Track accidentals in effect within a bar using parsed tokens
+ * @param {Array<object>} barTokens - Array of parsed tokens from a bar
+ * @param {Map<string, string>} keyAccidentals - Accidentals from key signature
+ * @returns {Map<string, string>} - Map of note (with octave) to its current accidental state
+ */
+function getBarAccidentals(barTokens, keyAccidentals) {
+	const accidentals = new Map();
+
+	for (const token of barTokens) {
+		// Skip non-note tokens
+		if (
+			token.isSilence ||
+			token.isDummy ||
+			token.isInlineField ||
+			token.isChordSymbol ||
+			token.isTuple ||
+			token.isBrokenRhythm ||
+			token.isVariantEnding ||
+			token.isDecoration ||
+			token.isGraceNote
+		) {
+			continue;
+		}
+
+		const noteInfos = extractNoteInfo(token);
+
+		for (const { noteLetter, accidental, noteWithOctave } of noteInfos) {
+			const baseNoteLetter = noteLetter.toUpperCase();
+
+			if (accidental) {
+				// Explicit accidental - record it
+				accidentals.set(noteWithOctave, accidental);
+			} else if (!accidentals.has(noteWithOctave)) {
+				// No explicit accidental, use key signature default
+				const keyAccidental = keyAccidentals.get(baseNoteLetter) || null;
+				accidentals.set(noteWithOctave, keyAccidental);
+			}
+			// If accidental already set for this note in this bar, it carries over
+		}
+	}
+
+	return accidentals;
+}
+
+/**
+ * Add correct accidentals when merging bars
+ * Modifies the tokens in the second bar to add accidentals where needed
+ *
+ * @param {Array<object>} secondBarTokens - Array of parsed tokens from second bar
+ * @param {Map<string, string>} firstBarAccidentals - Accidentals in effect from first bar
+ * @param {Map<string, string>} keyAccidentals - Accidentals from key signature
+ * @param {string} musicText - Original music text for reconstruction
+ * @returns {Array<object>} - Modified tokens with accidentals added
+ */
+function addAccidentalsForMergedBar(
+	secondBarTokens,
+	firstBarAccidentals,
+	keyAccidentals
+) {
+	const modifiedTokens = [];
+	const secondBarAccidentals = new Map();
+
+	for (const token of secondBarTokens) {
+		// Non-note tokens pass through unchanged
+		if (
+			token.isSilence ||
+			token.isDummy ||
+			token.isInlineField ||
+			token.isChordSymbol ||
+			token.isTuple ||
+			token.isBrokenRhythm ||
+			token.isVariantEnding ||
+			token.isDecoration ||
+			token.isGraceNote
+		) {
+			modifiedTokens.push(token);
+			continue;
+		}
+
+		const noteInfos = extractNoteInfo(token);
+
+		// If no notes extracted, pass through
+		if (noteInfos.length === 0) {
+			modifiedTokens.push(token);
+			continue;
+		}
+
+		// Check if we need to modify this token
+		let needsModification = false;
+		const modificationsNeeded = [];
+
+		for (const { noteLetter, accidental, noteWithOctave } of noteInfos) {
+			const baseNoteLetter = noteLetter.toUpperCase();
+			const firstBarAccidental = firstBarAccidentals.get(noteWithOctave);
+			const keyAccidental = keyAccidentals.get(baseNoteLetter) || null;
+
+			if (accidental) {
+				// Has explicit accidental
+				const currentAccidental = secondBarAccidentals.get(noteWithOctave);
+
+				if (currentAccidental !== undefined) {
+					// Already set in this bar (merged context)
+					secondBarAccidentals.set(noteWithOctave, accidental);
+					modificationsNeeded.push(null);
+				} else if (accidental === firstBarAccidental) {
+					// Redundant - same as what's in effect from first bar
+					needsModification = true;
+					secondBarAccidentals.set(noteWithOctave, accidental);
+					modificationsNeeded.push("remove");
+				} else {
+					// Different accidental, keep it
+					secondBarAccidentals.set(noteWithOctave, accidental);
+					modificationsNeeded.push(null);
+				}
+			} else {
+				// No explicit accidental
+				const currentAccidental = secondBarAccidentals.get(noteWithOctave);
+
+				if (currentAccidental !== undefined) {
+					// Already set in this bar, no modification
+					modificationsNeeded.push(null);
+				} else if (
+					firstBarAccidental !== undefined &&
+					firstBarAccidental !== keyAccidental
+				) {
+					// Bar 1 had this note with a different accidental than key signature
+					// Need to add the key signature accidental to restore it
+					needsModification = true;
+					const neededAccidental = keyAccidental || "=";
+					secondBarAccidentals.set(noteWithOctave, neededAccidental);
+					modificationsNeeded.push(neededAccidental);
+				} else {
+					// No modification needed (bar 1 didn't have this note, or had same as key)
+					secondBarAccidentals.set(noteWithOctave, keyAccidental);
+					modificationsNeeded.push(null);
+				}
+			}
+		}
+
+		if (needsModification) {
+			// Reconstruct the token with added accidentals
+			const modifiedToken = { ...token };
+			let modifiedTokenStr = token.token;
+
+			// For simple single notes (not chords), we can modify directly
+			if (!token.isChord && modificationsNeeded[0]) {
+				// Find where the note letter starts (after decorations)
+				const noteMatch = modifiedTokenStr.match(
+					/(^[~.MPSTHUV!]*(?:![^!]+!)*\s*)?(__|_|=|\^\^|\^)?([A-Ga-g])/
+				);
+				if (noteMatch) {
+					const prefix = noteMatch[1] || "";
+					const existingAcc = noteMatch[2] || "";
+					const noteLetter = noteMatch[3];
+					const afterNote = modifiedTokenStr.substring(
+						prefix.length + existingAcc.length + noteLetter.length
+					);
+
+					if (modificationsNeeded[0] === "remove") {
+						// Remove the existing accidental
+						modifiedTokenStr = prefix + noteLetter + afterNote;
+					} else {
+						// Add or change the accidental
+						modifiedTokenStr =
+							prefix + modificationsNeeded[0] + noteLetter + afterNote;
+					}
+				}
+			}
+			// For chords, this is more complex - we'd need to modify the chord parsing
+			// For now, mark that it needs modification and handle in integration
+
+			modifiedToken.token = modifiedTokenStr;
+			modifiedToken.needsAccidentalModification = needsModification;
+			modifiedToken.accidentalModifications = modificationsNeeded;
+			modifiedTokens.push(modifiedToken);
+		} else {
+			modifiedTokens.push(token);
+		}
+	}
+
+	return modifiedTokens;
+}
+
+/**
+ * Remove redundant accidentals when splitting a bar
+ *
+ * @param {Array<object>} secondHalfTokens - Tokens from second half after split
+ * @param {Map<string, string>} firstHalfAccidentals - Accidentals from first half
+ * @param {Map<string, string>} keyAccidentals - Accidentals from key signature
+ * @returns {Array<object>} - Modified tokens with redundant accidentals removed
+ */
+function removeRedundantAccidentals(
+	secondHalfTokens,
+	firstHalfAccidentals,
+	keyAccidentals
+) {
+	const modifiedTokens = [];
+	const secondHalfAccidentals = new Map();
+
+	for (const token of secondHalfTokens) {
+		// Non-note tokens pass through
+		if (
+			token.isSilence ||
+			token.isDummy ||
+			token.isInlineField ||
+			token.isChordSymbol ||
+			token.isTuple ||
+			token.isBrokenRhythm ||
+			token.isVariantEnding ||
+			token.isDecoration ||
+			token.isGraceNote
+		) {
+			modifiedTokens.push(token);
+			continue;
+		}
+
+		const noteInfos = extractNoteInfo(token);
+
+		if (noteInfos.length === 0) {
+			modifiedTokens.push(token);
+			continue;
+		}
+
+		// Check if we need to remove accidentals
+		let needsModification = false;
+		const modificationsNeeded = [];
+
+		for (const { noteLetter, accidental, noteWithOctave } of noteInfos) {
+			const baseNoteLetter = noteLetter.toUpperCase();
+			const keyAccidental = keyAccidentals.get(baseNoteLetter) || null;
+			const currentAccidental = secondHalfAccidentals.get(noteWithOctave);
+
+			// Normalize accidentals for comparison: treat '=' and null as equivalent (both natural)
+			const normalizedAccidental = accidental === "=" ? null : accidental;
+			const normalizedKeyAccidental =
+				keyAccidental === "=" ? null : keyAccidental;
+
+			if (currentAccidental !== undefined) {
+				// Already set in second half
+				modificationsNeeded.push(null);
+			} else if (
+				normalizedAccidental === normalizedKeyAccidental &&
+				accidental !== null
+			) {
+				// Redundant - explicit accidental matches key signature
+				// (only remove explicit accidentals, not implicit ones)
+				needsModification = true;
+				secondHalfAccidentals.set(noteWithOctave, accidental);
+				modificationsNeeded.push("remove");
+			} else {
+				// Keep it
+				if (accidental) {
+					secondHalfAccidentals.set(noteWithOctave, accidental);
+				} else {
+					secondHalfAccidentals.set(noteWithOctave, keyAccidental);
+				}
+				modificationsNeeded.push(null);
+			}
+		}
+
+		if (needsModification) {
+			const modifiedToken = { ...token };
+			let modifiedTokenStr = token.token;
+
+			// For simple single notes
+			if (!token.isChord && modificationsNeeded[0] === "remove") {
+				// Remove the accidental
+				const noteMatch = modifiedTokenStr.match(
+					/(^[~.MPSTHUV!]*(?:![^!]+!)*\s*)?(__|_|=|\^\^|\^)?([A-Ga-g])/
+				);
+				if (noteMatch && noteMatch[2]) {
+					const prefix = noteMatch[1] || "";
+					const accToRemove = noteMatch[2];
+					const noteLetter = noteMatch[3];
+					const afterNote = modifiedTokenStr.substring(
+						prefix.length + accToRemove.length + noteLetter.length
+					);
+
+					modifiedTokenStr = prefix + noteLetter + afterNote;
+				}
+			}
+
+			modifiedToken.token = modifiedTokenStr;
+			modifiedToken.needsAccidentalModification = needsModification;
+			modifiedToken.accidentalModifications = modificationsNeeded;
+			modifiedTokens.push(modifiedToken);
+		} else {
+			modifiedTokens.push(token);
+		}
+	}
+
+	return modifiedTokens;
+}
+
+/**
+ * Reconstruct music text from tokens
+ * @param {Array<object>} tokens - Array of token objects
+ * @returns {string} - Reconstructed music text
+ */
+function reconstructMusicFromTokens(tokens) {
+	if (tokens.length === 0) return "";
+
+	let result = "";
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+
+		// Add the token (possibly modified)
+		result += token.token;
+
+		// Add spacing after token (but not after the last token)
+		if (i < tokens.length - 1 && token.spacing && token.spacing.whitespace) {
+			result += token.spacing.whitespace;
+		}
+	}
+
+	return result;
+}
+
+module.exports = {
+	getKeySignatureAccidentals,
+	getBarAccidentals,
+	extractNoteInfo,
+	addAccidentalsForMergedBar,
+	removeRedundantAccidentals,
+	reconstructMusicFromTokens
+};

package/src/parse/getMetadata.js

@@ -1,50 +1,72 @@
 const { normaliseKey } = require("../manipulator");
 
 /**
- * Extracts data in the ABC header T R C M K S F D N fields
+ * Extracts data in the ABC _header_ T R C M K S F D N H fields
  * and returns it in a object with properties: title, rhythm, composer, meter, key,
- * source, url, recording, and comments.
+ * source, url, recording, comments, and hComments.
  * Minimal parsing, but a few features:
  * - only extracts the first T title; subsequent T entries are ignored
  * - the key is normalised, so C, Cmaj, C maj, C major will all map to key:"C major"
- * - the comments go in an array, with one array entry per N: line.
+ * - the comments (i.e. the N / notes) go in an array called `comments`, with one array entry per N: line
+ * - the history (H) lines are joined up with spaces into a single line that is returned as `hComments`
+ * - the field continuation `+:` is handled only for lines following an initial H (history)
+ * - if there’s more than one T (title), then titles after the first one are returned in an array `titles`
  * @param {*} abc
  * @returns {object} - The header info
  */
 function getMetadata(abc) {
 	const lines = abc.split("\n"),
 		metadata = {},
-		comments = [];
+		comments = [],
+		hComments = [],
+		titles = [];
+
+	let currentHeader = "";
 
 	for (const line of lines) {
 		const trimmed = line.trim();
-		if (trimmed.startsWith("T:") && !metadata.title) {
-			metadata.title = trimmed.substring(2).trim();
+		const trimmed2 = trimmed.substring(2).trim().replace(/%.+/, "");
+		if (trimmed.startsWith("T:")) {
+			if (!metadata.title) metadata.title = trimmed2;
+			else titles.push(trimmed2);
 		} else if (trimmed.startsWith("R:")) {
-			metadata.rhythm = trimmed.substring(2).trim().toLowerCase();
+			metadata.rhythm = trimmed2.toLowerCase();
 		} else if (trimmed.startsWith("C:")) {
-			metadata.composer = trimmed.substring(2).trim();
+			metadata.composer = trimmed2;
 		} else if (trimmed.startsWith("M:")) {
-			metadata.meter = trimmed.substring(2).trim();
+			metadata.meter = trimmed2;
 		} else if (trimmed.startsWith("K:")) {
-			metadata.key = normaliseKey(trimmed.substring(2).trim()).join(" ");
+			metadata.key = normaliseKey(trimmed2).join(" ");
 			// metadata.indexOfKey = i
 			break;
 		} else if (trimmed.startsWith("S:")) {
-			metadata.source = trimmed.substring(2).trim();
+			metadata.source = trimmed2;
 		} else if (trimmed.startsWith("O:")) {
-			metadata.origin = trimmed.substring(2).trim();
+			metadata.origin = trimmed2;
 		} else if (trimmed.startsWith("F:")) {
-			metadata.url = trimmed.substring(2).trim();
+			metadata.url = trimmed2;
 		} else if (trimmed.startsWith("D:")) {
-			metadata.recording = trimmed.substring(2).trim();
+			metadata.recording = trimmed2;
 		} else if (trimmed.startsWith("N:")) {
-			comments.push(trimmed.substring(2).trim());
+			comments.push(trimmed2);
+		} else if (trimmed.startsWith("H:")) {
+			currentHeader = "H";
+			hComments.push(trimmed2);
+		} else if (trimmed.startsWith("+:")) {
+			switch (currentHeader) {
+				case "H":
+					hComments.push(trimmed2);
+					break;
+			}
 		}
 	}
 	if (comments.length > 0) {
 		metadata.comments = comments;
 	}
+	if (hComments.length > 0) {
+		metadata.hComments = hComments.join(" ");
+	}
+	if (titles.length > 0) metadata.titles = titles;
 
 	return metadata;
 }

package/src/parse/token-utils.js

@@ -38,8 +38,8 @@ const // captures not only |1 |2, but also :|1 :||1 :|2 :||2
 			return String.raw`(?:${this.bangDecoration}\s*)*`;
 		},
 
-		// Accidental: :, ^, _ (natural, sharp, flat)
-		accidental: String.raw`[:^_]?`,
+		// Accidental: :, ^, _ (natural, sharp, flat; and double flat/sharp; and even add rarer ones like natural+sharp)
+		accidental: String.raw`(_|\^|=|\^\^|__|==|=_|=\^)?`,
 
 		// Note pitch: A-G (lower octave), a-g (middle octave), z/x (rest), y (dummy)
 		// Or chord in brackets: [CEG], [DF#A]