@goplayerjuggler/abc-tools 1.0.16 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplayerjuggler/abc-tools",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "sorting algorithm and implementation for ABC tunes; plus other tools for parsing and manipulating ABC tunes",
   "main": "src/index.js",
   "scripts": {
@@ -44,13 +44,13 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.37.0",
-    "baseline-browser-mapping": "^2.9.19",
     "clipboardy": "^5.0.1",
     "eslint": "^9.37.0",
     "eslint-plugin-jest": "^29.0.1",
     "globals": "^16.4.0",
     "jest": "^30.2.0",
-    "jsdoc": "^4.0.5"
+    "jsdoc": "^4.0.5",
+    "prettier": "^3.8.1"
   },
   "jest": {
     "testEnvironment": "node",

package/src/incipit.js

@@ -278,7 +278,7 @@ function sanitise(theTune) {
 function getIncipit(data) {
 	let {
 		abc,
-		numBars, //, part=null
+		numBars //, part=null
 	} = typeof data === "string" ? { abc: data } : data;
 
 	const { withAnacrucis = true } =
@@ -313,7 +313,7 @@ function getIncipitForContourGeneration(
 	return getIncipit({
 		abc,
 		withAnacrucis: false,
-		numBars,
+		numBars
 	});
 }
 
@@ -322,7 +322,7 @@ function getContourFromFullAbc(
 	{
 		withSvg = true,
 		withSwingTransform = false,
-		numBars = new Fraction(3, 2),
+		numBars = new Fraction(3, 2)
 	} = {}
 ) {
 	if (Array.isArray(abc)) {
@@ -331,12 +331,12 @@ function getContourFromFullAbc(
 	}
 	return getContour(getIncipitForContourGeneration(abc, { numBars }), {
 		withSvg,
-		withSwingTransform,
+		withSwingTransform
 	});
 }
 
 module.exports = {
 	getIncipit,
 	getIncipitForContourGeneration,
-	getContourFromFullAbc,
+	getContourFromFullAbc
 };

package/src/index.js

@@ -34,8 +34,7 @@ module.exports = {
 	...contourToSvg,
 	...getContour,
 
-
 	// other
 	javascriptify,
-	...math,
+	...math
 };

package/src/javascriptify.js

@@ -12,8 +12,12 @@ function javascriptify(value, indent = 0) {
 	const nextIndentStr = "  ".repeat(indent + 1);
 
 	// Handle null and undefined
-	if (value === null) {return "null";}
-	if (value === undefined) {return "undefined";}
+	if (value === null) {
+		return "null";
+	}
+	if (value === undefined) {
+		return "undefined";
+	}
 
 	// Handle primitives
 	if (typeof value === "number") {
@@ -39,7 +43,9 @@ function javascriptify(value, indent = 0) {
 
 	// Handle arrays
 	if (Array.isArray(value)) {
-		if (value.length === 0) {return "[]";}
+		if (value.length === 0) {
+			return "[]";
+		}
 
 		const items = value
 			.map((item) => nextIndentStr + javascriptify(item, indent + 1))
@@ -54,15 +60,23 @@ function javascriptify(value, indent = 0) {
 		const keys = Object.keys(value).filter((k) => {
 			const val = value[k];
 			// Omit all falsey values (including false, but keep 0)
-			if (val === 0) {return true;}
+			if (val === 0) {
+				return true;
+			}
 			//if (val === null || val === undefined || val === "") return false;
-			if (!val) {return false;}
+			if (!val) {
+				return false;
+			}
 			// Omit empty arrays
-			if (Array.isArray(val) && val.length === 0) {return false;}
+			if (Array.isArray(val) && val.length === 0) {
+				return false;
+			}
 			return true;
 		});
 
-		if (keys.length === 0) {return "{}";}
+		if (keys.length === 0) {
+			return "{}";
+		}
 
 		const properties = keys
 			.map((key) => {

package/src/manipulator.js

@@ -2,6 +2,7 @@ const { Fraction } = require("./math.js");
 const { parseAbc, getMeter, getUnitLength } = require("./parse/parser.js");
 
 const { getBarInfo } = require("./parse/getBarInfo.js");
+const { getHeaderValue } = require("./parse/header-parser.js");
 
 // ============================================================================
 // ABC manipulation functions
@@ -56,7 +57,7 @@ function normaliseKey(keyHeader) {
 		lyd: "lydian",
 		lydian: "lydian",
 		loc: "locrian",
-		locrian: "locrian",
+		locrian: "locrian"
 	};
 	const mode = Object.keys(modeMap).find((m) => key.includes(m)) || "major";
 
@@ -104,7 +105,7 @@ function hasAnacrucisFromParsed(parsed, barLines) {
 		getBarInfo(bars, barLines, meter, {
 			barNumbers: true,
 			isPartial: true,
-			cumulativeDuration: false,
+			cumulativeDuration: false
 		});
 	}
 
@@ -178,6 +179,7 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 
 	const parsed = parseAbc(abc);
 	const { headerLines, barLines, musicText, bars, meter } = parsed;
+
 	// throw if there's a change of meter or unit length in the tune
 	if (barLines.find((bl) => bl.newMeter || bl.newUnitLength)) {
 		throw new Error("change of meter or unit length not handled");
@@ -198,7 +200,7 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 		// Get bar info to understand musical structure
 		getBarInfo(bars, barLines, meter, {
 			barNumbers: true,
-			isPartial: true,
+			isPartial: true
 		});
 
 		// Build a map of which bars start with variant endings
@@ -268,13 +270,6 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 				continue;
 			}
 
-			// If the current bar starts with a variant, keep its bar line
-			const currentBarVariant = barStartsWithVariant.get(i);
-			if (currentBarVariant) {
-				barLineDecisions.set(i, { action: "keep" });
-				continue;
-			}
-
 			// 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!
@@ -286,12 +281,21 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 				? barLine.barNumber % 2 !== 0
 				: barLine.barNumber % 2 === 0;
 			if (remove) {
+				// Check if current bar starts with variant
+				if (barStartsWithVariant.has(i)) {
+					const variantToken = barStartsWithVariant.get(i);
+					barLinesToConvert.set(variantToken.sourceIndex, {
+						oldLength: variantToken.sourceLength,
+						oldText: variantToken.token
+					});
+				}
+				// Also check if next bar starts with variant
 				const nextBarIdx = i + 1;
 				if (nextBarIdx < bars.length && barStartsWithVariant.has(nextBarIdx)) {
 					const variantToken = barStartsWithVariant.get(nextBarIdx);
 					barLinesToConvert.set(variantToken.sourceIndex, {
 						oldLength: variantToken.sourceLength,
-						oldText: variantToken.token,
+						oldText: variantToken.token
 					});
 				}
 				barLineDecisions.set(i, { action: "remove" });
@@ -301,6 +305,26 @@ 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())
+		// );
+
 		// Reconstruct music
 		let newMusic = "";
 		let pos = 0;
@@ -355,7 +379,7 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
 	} else {
 		// Going from large to small: add bar lines at midpoints
 		const barInfo = getBarInfo(bars, barLines, meter, {
-			divideBarsBy: 2,
+			divideBarsBy: 2
 		});
 
 		const { midpoints } = barInfo;
@@ -382,11 +406,13 @@ function toggleMeter_4_4_to_4_2(abc, currentMeter) {
 }
 
 const defaultCommentForReelConversion =
-	"*abc-tools: convert reel to M:4/4 & L:1/16*";
+	"*abc-tools: convert to M:4/4 & L:1/16*";
+const defaultCommentForHornpipeConversion = "*abc-tools: convert to M:4/2*";
+const defaultCommentForJigConversion = "*abc-tools: convert to M:12/8*";
 /**
- * Adjusts bar lengths and L field to convert a
- * reel written in the normal way (M:4/4 L:1/8) to the same reel
- * written with M:4/4 L:1/16.
+ * Adjusts bar lengths and L, M fields - a 
+ * reel written in the normal way (M:4/4 L:1/8) is written
+ * written with M:4/4 and L:1/16 (or M:4/2 and L:1/8, if withSemiquavers is unflagged)
  * Bars are twice as long, and the quick notes are semiquavers
  * rather than quavers.
  * @param {string} reel
@@ -420,6 +446,56 @@ function convertStandardReel(
 	return result;
 }
 
+/**
+ * Adjusts bar lengths and M field to alter a
+ * jig written in the normal way (M:6/8) so it’s
+ * written with M:12/8.
+ * Bars are twice as long.
+ * @param {string} jig
+ * @param {string} comment - when non falsey, the comment will be injected as an N: header
+
+ * @returns
+ */
+function convertStandardJig(jig, comment = defaultCommentForJigConversion) {
+	const meter = getMeter(jig);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 6 || !meter[1] === 8) {
+		throw new Error("invalid meter");
+	}
+
+	let result = //toggleMeter_4_4_to_4_2(reel, meter);
+		toggleMeterDoubling(jig, [6, 8], [12, 8], 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
+ * written with M:12/8.
+ * Bars are twice as long.
+ * @param {string} hornpipe
+ * @param {string} comment - when non falsey, the comment will be injected as an N: header
+
+ * @returns
+ */
+function convertStandardHornpipe(
+	hornpipe,
+	comment = defaultCommentForHornpipeConversion
+) {
+	const meter = getMeter(hornpipe);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 4 || !meter[1] === 4) {
+		throw new Error("invalid meter");
+	}
+
+	let result = toggleMeter_4_4_to_4_2(hornpipe, meter);
+
+	if (comment) {
+		result = result.replace(/(\nK:)/, `\nN:${comment}$1`);
+	}
+	return result;
+}
 function doubleBarLength(abc, comment = null) {
 	const meter = getMeter(abc);
 	if (!Array.isArray(meter) || !meter) {
@@ -457,7 +533,9 @@ function convertToStandardReel(
 	withSemiquavers = true
 ) {
 	if (withSemiquavers) {
-		reel = reel.replace("M:4/4", "M:4/2").reel("L:1/16", "L:1/8");
+		reel = reel
+			.replace(/\nM:\s*4\/4/, "\nM:4/2")
+			.replace(/\nL:\s*1\/16/, "\nL:1/8");
 	}
 
 	const unitLength = getUnitLength(reel);
@@ -476,6 +554,51 @@ function convertToStandardReel(
 	}
 	return result;
 }
+/**
+ * Adjusts bar lengths to rewrite a
+ * jig written in the abnormal way (M:12/8) to M:6/8, the normal or standard way.
+ * Bars are half as long. Inverse operation to convertStandardJig
+ * @param {string} jig
+ * @param {string} comment - when non falsey, the comment (as an N:) will removed from the header
+ * @param {bool} withSemiquavers - when unflagged, the original jig was written in M:4/2 L:1/8
+ * @returns
+ */
+function convertToStandardJig(jig, comment = defaultCommentForJigConversion) {
+	const unitLength = getUnitLength(jig);
+	if (unitLength.den !== 8) {
+		throw new Error("invalid L header");
+	}
+	const meter = getMeter(jig);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 12 || !meter[1] === 8) {
+		throw new Error("invalid meter");
+	}
+
+	let result = toggleMeter_6_8_to_12_8(jig); // toggleMeter_4_4_to_4_2(jig, meter);
+	if (comment) {
+		result = result.replace(`\nN:${comment}`, "");
+	}
+	return result;
+}
+
+function convertToStandardHornpipe(
+	hornpipe,
+	comment = defaultCommentForHornpipeConversion
+) {
+	const unitLength = getUnitLength(hornpipe);
+	if (unitLength.den !== 8) {
+		throw new Error("invalid L header");
+	}
+	const meter = getMeter(hornpipe);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 4 || !meter[1] === 2) {
+		throw new Error("invalid meter");
+	}
+
+	let result = toggleMeter_4_4_to_4_2(hornpipe); // toggleMeter_4_4_to_4_2(jig, meter);
+	if (comment) {
+		result = result.replace(`\nN:${comment}`, "");
+	}
+	return result;
+}
 
 /**
  * Toggle between M:6/8 and M:12/8 by surgically adding/removing bar lines
@@ -528,7 +651,7 @@ function getFirstBars(
 		barNumbers: true,
 		isPartial: true,
 		cumulativeDuration: true,
-		stopAfterBarNumber,
+		stopAfterBarNumber
 	});
 
 	const enrichedBarLines = barInfo.barLines;
@@ -692,8 +815,72 @@ function getFirstBars(
 	)}`;
 }
 
+function canDoubleBarLength(abc) {
+	const meter = getMeter(abc),
+		l = getUnitLength(abc),
+		rhythm = getHeaderValue(abc, "R");
+	if (
+		!rhythm ||
+		["reel", "hornpipe", "jig"].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" &&
+				l.equals(new Fraction(1, 8)) &&
+				meter[0] === 6 &&
+				meter[1] === 8))
+	);
+}
+function canHalveBarLength(abc) {
+	const meter = getMeter(abc),
+		l = getUnitLength(abc),
+		rhythm = getHeaderValue(abc, "R");
+	if (
+		!rhythm ||
+		["reel", "hornpipe", "jig"].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:/) &&
+		((rhythm === "reel" &&
+			l.equals(new Fraction(1, 16)) &&
+			meter[0] === 4 &&
+			meter[1] === 4) ||
+			((rhythm === "reel" || rhythm === "hornpipe") &&
+				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))
+	);
+}
+
 module.exports = {
+	canDoubleBarLength,
+	canHalveBarLength,
+	convertStandardJig,
+	convertStandardHornpipe,
 	convertStandardReel,
+	convertToStandardJig,
+	convertToStandardHornpipe,
 	convertToStandardReel,
 	defaultCommentForReelConversion,
 	doubleBarLength,
@@ -703,5 +890,5 @@ module.exports = {
 	normaliseKey,
 	toggleMeter_4_4_to_4_2,
 	toggleMeter_6_8_to_12_8,
-	toggleMeterDoubling,
+	toggleMeterDoubling
 };

package/src/math.js

@@ -105,6 +105,6 @@ if (typeof module !== "undefined" && module.exports) {
 	module.exports = {
 		// lcm,
 		// gcd,
-		Fraction,
+		Fraction
 	};
 }

package/src/parse/barline-parser.js

@@ -40,7 +40,7 @@ function parseBarLine(barLineStr) {
 	const trimmed = barLineStr.trim();
 	const result = {
 		text: barLineStr,
-		trimmed,
+		trimmed
 	};
 	// Start repeat
 	if (trimmed.match(/:$/)) {
@@ -60,5 +60,5 @@ function parseBarLine(barLineStr) {
 }
 
 module.exports = {
-	parseBarLine,
+	parseBarLine
 };

package/src/parse/getBarInfo.js

@@ -21,7 +21,7 @@ function processSkippedBarLines(barLines, skippedBarLineIndexes) {
 		// Copy any properties from the preceding barLine not already in the skipped barLine
 		barLines[skippedIndex] = {
 			...barLines[skippedIndex - 1],
-			...barLines[skippedIndex],
+			...barLines[skippedIndex]
 		};
 	}
 }
@@ -101,7 +101,7 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 		isPartial = true,
 		cumulativeDuration = true,
 		divideBarsBy = null,
-		stopAfterBarNumber = null,
+		stopAfterBarNumber = null
 	} = options;
 
 	if (divideBarsBy !== null && divideBarsBy !== 2) {
@@ -205,7 +205,7 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 						durationSinceLastComplete: durationBeforeVariant.clone(),
 						lastCompleteBarLineIdx: lastCompleteBarLineIdx,
 						meter: [...currentMeter],
-						fullBarDuration: fullBarDuration.clone(),
+						fullBarDuration: fullBarDuration.clone()
 					};
 					variantCounter = 0;
 					currentVariantId = variantCounter;
@@ -287,7 +287,7 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 					processSkippedBarLines(barLines, skippedBarLineIndexes);
 					return {
 						barLines: barLines.slice(0, barLineIdx + 1),
-						midpoints,
+						midpoints
 					};
 				}
 			}
@@ -313,7 +313,7 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 			if (cumulativeDuration) {
 				barLine.cumulativeDuration = {
 					sinceLastBarLine: barDuration.clone(),
-					sinceLastComplete: durationSinceLastComplete.clone(),
+					sinceLastComplete: durationSinceLastComplete.clone()
 				};
 			}
 
@@ -425,10 +425,10 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 	processSkippedBarLines(barLines, skippedBarLineIndexes);
 	return {
 		barLines,
-		midpoints,
+		midpoints
 	};
 }
 
 module.exports = {
-	getBarInfo,
+	getBarInfo
 };

package/src/parse/header-parser.js

@@ -77,7 +77,13 @@ function getUnitLength(abc) {
  * @returns {[string]} - array of titles
  */
 function getTitles(abc) {
-	return [...abc.matchAll(/^(?:T:\s*.(.+)\n)/gm)];
+	return [...abc.matchAll(/^(?:T:\s*(.+)\n)/gm)];
+}
+
+function getHeaderValue(abc, header) {
+	const r = new RegExp(String.raw`(?:${header}:\s*(.+)\n)`, "m"),
+		m = abc.match(r);
+	return m ? m[1]?.trim() : null;
 }
 
 /**
@@ -138,7 +144,7 @@ function getMusicLines(abc) {
 				originalLine: line,
 				content: trimmed,
 				comment,
-				hasContinuation,
+				hasContinuation
 			});
 
 			// Track position where newline would be (unless continuation)
@@ -155,15 +161,16 @@ function getMusicLines(abc) {
 		lineMetadata,
 		newlinePositions,
 		headerLines,
-		headerEndIndex,
+		headerEndIndex
 	};
 }
 
 module.exports = {
-	getTonalBase,
+	getHeaderValue,
+	getKey,
 	getMeter,
-	getUnitLength,
 	getMusicLines,
 	getTitles,
-	getKey,
+	getTonalBase,
+	getUnitLength
 };

package/src/parse/misc-parser.js

@@ -21,7 +21,7 @@ function analyzeSpacing(segment, tokenEndPos) {
 			whitespace: "",
 			backquotes: 0,
 			beamBreak: false,
-			lineBreak: false,
+			lineBreak: false
 		};
 	}
 
@@ -35,7 +35,7 @@ function analyzeSpacing(segment, tokenEndPos) {
 			whitespace: "",
 			backquotes: 0,
 			beamBreak: false,
-			lineBreak: false,
+			lineBreak: false
 		};
 	}
 
@@ -51,7 +51,7 @@ function analyzeSpacing(segment, tokenEndPos) {
 		whitespace,
 		backquotes,
 		beamBreak: whitespace.length > 1 || whitespace.includes("\n"), // Multiple spaces or newline breaks beam
-		lineBreak: whitespace.includes("\n"),
+		lineBreak: whitespace.includes("\n")
 	};
 }
 
@@ -68,7 +68,7 @@ function parseTuplet(token, isCompoundTimeSignature) {
 		const pqr = {
 			p: parseInt(tupleMatch[1]),
 			q: tupleMatch[2],
-			r: tupleMatch[3],
+			r: tupleMatch[3]
 		};
 		const { p } = pqr;
 		let { q, r } = pqr;
@@ -107,12 +107,12 @@ function parseTuplet(token, isCompoundTimeSignature) {
 			isTuple: true,
 			p,
 			q,
-			r,
+			r
 		};
 	}
 	return null;
 }
 module.exports = {
 	analyzeSpacing,
-	parseTuplet,
+	parseTuplet
 };

package/src/parse/note-parser.js

@@ -38,7 +38,7 @@ function parseDecorations(noteStr) {
 		T: "trill",
 		H: "fermata",
 		u: "upbow",
-		v: "downbow",
+		v: "downbow"
 	};
 
 	for (const [symbol, name] of Object.entries(symbolDecorations)) {
@@ -82,7 +82,7 @@ function parseAnnotation(noteStr) {
 	if (annotationMatch) {
 		return {
 			position: annotationMatch[1],
-			text: annotationMatch[2],
+			text: annotationMatch[2]
 		};
 	}
 	return null;
@@ -190,7 +190,7 @@ function parseChord(chordStr, unitLength) {
 	}
 	return {
 		isChord: true,
-		notes,
+		notes
 	};
 }
 
@@ -256,7 +256,7 @@ function parseGraceNotes(graceStr) {
 					isGraceNote: true,
 					duration: new Fraction(0, 1),
 					isChord: true,
-					chordNotes: chord.notes,
+					chordNotes: chord.notes
 				});
 			}
 		} else {
@@ -266,7 +266,7 @@ function parseGraceNotes(graceStr) {
 				graceNotes.push({
 					...pitchData,
 					isGraceNote: true,
-					duration: new Fraction(0, 1),
+					duration: new Fraction(0, 1)
 				});
 			}
 		}
@@ -298,7 +298,7 @@ function parseBrokenRhythm(token) {
 		return {
 			isBrokenRhythm: true,
 			direction: symbol[0],
-			dots: symbol.length,
+			dots: symbol.length
 		};
 	}
 	return null;
@@ -375,7 +375,7 @@ function parseNote(noteStr, unitLength, currentTuple) {
 	if (cleanStr.match(/^y$/)) {
 		return {
 			isDummy: true,
-			duration: new Fraction(0, 1, decorations, annotation),
+			duration: new Fraction(0, 1, decorations, annotation)
 		};
 	}
 
@@ -385,7 +385,7 @@ function parseNote(noteStr, unitLength, currentTuple) {
 		const duration = getDuration({
 			unitLength,
 			noteString: cleanStr,
-			currentTuple,
+			currentTuple
 		});
 		const result = { isSilence: true, duration, text: silenceMatch[0] };
 		if (decorations) {
@@ -427,7 +427,7 @@ function parseNote(noteStr, unitLength, currentTuple) {
 			const duration = getDuration({
 				unitLength,
 				noteString: cleanStr,
-				currentTuple,
+				currentTuple
 			});
 			topNote.duration = duration;
 			// Apply duration to all notes in chord
@@ -442,7 +442,7 @@ function parseNote(noteStr, unitLength, currentTuple) {
 				chordSymbol: chordSymbol || chord.chordSymbol,
 				decorations: decorations || chord.decorations,
 				isChord: true,
-				tied,
+				tied
 			};
 		}
 	}
@@ -453,7 +453,7 @@ function parseNote(noteStr, unitLength, currentTuple) {
 	const duration = getDuration({
 		unitLength,
 		noteString: cleanStr,
-		currentTuple,
+		currentTuple
 	});
 
 	const result = { pitch, octave, duration, tied };
@@ -480,5 +480,5 @@ module.exports = {
 	parseNote,
 	parseBrokenRhythm,
 	applyBrokenRhythm,
-	parseGraceNotes,
+	parseGraceNotes
 };

package/src/parse/parser.js

@@ -4,19 +4,19 @@ const {
 	getMeter,
 	getKey,
 	getUnitLength,
-	getMusicLines,
+	getMusicLines
 } = require("./header-parser.js");
 const {
 	parseNote,
 	parseBrokenRhythm,
 	applyBrokenRhythm,
-	parseGraceNotes,
+	parseGraceNotes
 } = require("./note-parser.js");
 const { parseBarLine } = require("./barline-parser.js");
 const {
 	getTokenRegex,
 	parseInlineField,
-	repeat_1Or2,
+	repeat_1Or2
 } = require("./token-utils.js");
 const { analyzeSpacing, parseTuplet } = require("./misc-parser.js");
 
@@ -338,7 +338,7 @@ function parseAbc(abc, options = {}) {
 		lineMetadata,
 		headerLines,
 		headerEndIndex,
-		newlinePositions,
+		newlinePositions
 	} = getMusicLines(abc);
 
 	// Create a Set of newline positions for O(1) lookup
@@ -413,8 +413,8 @@ function parseAbc(abc, options = {}) {
 											whitespace: "",
 											backquotes: 0,
 											beamBreak: false,
-											lineBreak: false,
-									  },
+											lineBreak: false
+										}
 						});
 					});
 					// Grace notes don’t update previousRealNote
@@ -432,7 +432,7 @@ function parseAbc(abc, options = {}) {
 					token: fullToken,
 					sourceIndex: tokenStartPos,
 					sourceLength: fullToken.length,
-					spacing,
+					spacing
 				};
 				currentBar.push(inlineFieldObj);
 
@@ -482,7 +482,7 @@ function parseAbc(abc, options = {}) {
 
 							// Add the broken rhythm marker to the bar
 							currentBar.push({
-								...brokenRhythm,
+								...brokenRhythm
 							});
 
 							// Add the next note to the bar
@@ -491,7 +491,7 @@ function parseAbc(abc, options = {}) {
 								token: nextToken,
 								sourceIndex: nextTokenStartPos,
 								sourceLength: nextToken.length,
-								spacing: nextSpacing,
+								spacing: nextSpacing
 							};
 							currentBar.push(nextNoteObj);
 							previousRealNote = null; //can’t have successive broken rhythms
@@ -518,7 +518,7 @@ function parseAbc(abc, options = {}) {
 						...tuple,
 						token: fullToken,
 						sourceIndex: tokenStartPos,
-						sourceLength: fullToken.length,
+						sourceLength: fullToken.length
 					});
 					previousRealNote = null; // Tuplet markers break note sequences
 					continue;
@@ -533,7 +533,7 @@ function parseAbc(abc, options = {}) {
 					token: fullToken,
 					sourceIndex: tokenStartPos,
 					sourceLength: fullToken.length,
-					spacing,
+					spacing
 				});
 				// Chord symbols don’t break note sequences
 				continue;
@@ -547,7 +547,7 @@ function parseAbc(abc, options = {}) {
 					token: fullToken,
 					sourceIndex: tokenStartPos,
 					sourceLength: fullToken.length,
-					spacing,
+					spacing
 				});
 				// Decorations don’t break note sequences
 				continue;
@@ -562,7 +562,7 @@ function parseAbc(abc, options = {}) {
 						token: fullToken,
 						sourceIndex: tokenStartPos,
 						sourceLength: fullToken.length,
-						spacing,
+						spacing
 					};
 					currentBar.push(noteObj);
 					// Only track as previous note if it has non-zero duration (for broken rhythms)
@@ -581,7 +581,7 @@ function parseAbc(abc, options = {}) {
 					token: fullToken,
 					sourceIndex: tokenStartPos,
 					sourceLength: fullToken.length,
-					spacing,
+					spacing
 				};
 				firstOrSecondRepeat = !!fullToken.match(new RegExp(repeat_1Or2));
 				if (firstOrSecondRepeat) {
@@ -606,8 +606,8 @@ function parseAbc(abc, options = {}) {
 							? { barLineText: musicText, barLinePos: musicText.length }
 							: {
 									barLineText: fullToken,
-									barLinePos: tokenStartPos,
-							  };
+									barLinePos: tokenStartPos
+								};
 
 					//if (lastBarPos > 0) lastBarPos--; //the last character in a barline expression may be needed to match variant endings - eg `|1`
 
@@ -625,7 +625,7 @@ function parseAbc(abc, options = {}) {
 						sourceIndex: barLinePos,
 						sourceLength: barLineText.length,
 						//barNumber: barCount,
-						hasLineBreak: hasLineBreakAfterBar,
+						hasLineBreak: hasLineBreakAfterBar
 					});
 
 					// Update the last token in current bar to mark lineBreak if bar line has one
@@ -681,7 +681,7 @@ function parseAbc(abc, options = {}) {
 			lineMetadata,
 			headerLines,
 			headerEndIndex,
-			musicText,
+			musicText
 		};
 	}
 }
@@ -768,5 +768,5 @@ module.exports = {
 	getUnitLength,
 	getMusicLines,
 	analyzeSpacing,
-	parseBarLine,
+	parseBarLine
 };

package/src/parse/token-utils.js

@@ -84,7 +84,7 @@ const // captures not only |1 |2, but also :|1 :||1 :|2 :||2
 		 *
 		 * Strategy: Match `[` only when NOT followed by inline field or digit; match `|` and `]` freely
 		 */
-		barLine: String.raw`:*\.*(?:[|\]]|\[(?![KLMP]:|[0-9]))*(?:\||::+)(?:[|\]:]|\[(?![KLMP]:|[0-9]))* *`,
+		barLine: String.raw`:*\.*(?:[|\]]|\[(?![KLMP]:|[0-9]))*(?:\||::+)(?:[|\]:]|\[(?![KLMP]:|[0-9]))* *`
 	};
 
 /**
@@ -133,7 +133,7 @@ const getTokenRegex = (options = {}) => {
 		s.broken,
 		s.variantEnding,
 		s.repeat_1Or2,
-		s.barLine,
+		s.barLine
 	].join("|");
 
 	return new RegExp(fullPattern, "g");
@@ -157,7 +157,7 @@ function parseInlineField(token) {
 	if (fieldMatch) {
 		return {
 			field: fieldMatch[1],
-			value: fieldMatch[2].trim(),
+			value: fieldMatch[2].trim()
 		};
 	}
 	return null;
@@ -165,5 +165,5 @@ function parseInlineField(token) {
 module.exports = {
 	repeat_1Or2,
 	getTokenRegex,
-	parseInlineField,
+	parseInlineField
 };

package/src/sort/contour-sort.js

@@ -181,8 +181,8 @@ function getAbcForContour_default(tune) {
 		tune.incipit
 			? tune.incipit
 			: Array.isArray(tune.abc)
-			? tune.abc[0]
-			: tune.abc
+				? tune.abc[0]
+				: tune.abc
 	);
 }
 
@@ -200,13 +200,13 @@ function sort(arr, options = {}) {
 		comparable = [
 			["jig", "slide", "single jig", "double jig"],
 			["reel", "single reel", "reel (single)", "strathspey", "double reel"],
-			["hornpipe", "barndance", "fling"],
+			["hornpipe", "barndance", "fling"]
 		],
 		applySwingTransform = ["hornpipe", "barndance", "fling", "mazurka"],
 		getAbc: getAbcForContour = getAbcForContour_default,
 		getContourOptions = {
-			withSvg: true,
-		},
+			withSvg: true
+		}
 	} = options;
 
 	const comparableMap = {};
@@ -245,16 +245,16 @@ function sort(arr, options = {}) {
 					? -1
 					: 1
 				: canBeCompared(a, b)
-				? compare(a.contour, b.contour)
-				: a.contour && !b.contour
-				? -1
-				: b.contour && !a.contour
-				? 1
-				: a.name !== b.name
-				? a.name < b.name
-					? -1
-					: 1
-				: 0;
+					? compare(a.contour, b.contour)
+					: a.contour && !b.contour
+						? -1
+						: b.contour && !a.contour
+							? 1
+							: a.name !== b.name
+								? a.name < b.name
+									? -1
+									: 1
+								: 0;
 		return comparison;
 	});
 	arr.forEach((t) => delete t.baseRhythm);
@@ -296,5 +296,5 @@ module.exports = {
 	compare,
 	sort,
 	simpleSort,
-	decodeChar,
+	decodeChar
 };

package/src/sort/contour-svg.js

@@ -61,7 +61,7 @@ const contourToSvg_defaultConfig = {
 	yAxisWidth: 0.5,
 	yAxisTickLength: 4,
 	yAxisTonicTickLength: 6,
-	yAxisTickWidth: 0.5,
+	yAxisTickWidth: 0.5
 };
 
 /**
@@ -150,7 +150,7 @@ function contourToSvg(contour, svgConfig = {}) {
 			width: segmentWidth,
 			position: decoded.position,
 			isHeld: decoded.isHeld,
-			isSilence: decoded.isSilence,
+			isSilence: decoded.isSilence
 		});
 
 		xPosition += segmentWidth;
@@ -332,5 +332,5 @@ function contourToSvg(contour, svgConfig = {}) {
 
 module.exports = {
 	contourToSvg,
-	contourToSvg_defaultConfig,
+	contourToSvg_defaultConfig
 };

package/src/sort/display-contour.js

@@ -63,5 +63,5 @@ function sortKeyToString(sortKey, showHeld = false) {
 
 module.exports = {
 	positionToString,
-	sortKeyToString,
+	sortKeyToString
 };

package/src/sort/encode.js

@@ -52,9 +52,15 @@ function decodeChar(char) {
 	return { position, isHeld, isSilence: false };
 }
 
+function shiftChar(char, nbOctaves) {
+	const { position, isHeld } = decodeChar(char);
+	return encodeToChar(position + nbOctaves * OCTAVE_SHIFT, isHeld);
+}
+
 module.exports = {
 	calculateModalPosition,
 	encodeToChar,
 	decodeChar,
-	silenceChar,
+	shiftChar,
+	silenceChar
 };

package/src/sort/get-contour.js

@@ -4,13 +4,14 @@ const {
 	calculateModalPosition,
 	encodeToChar,
 	silenceChar,
+	shiftChar
 } = require("./encode.js");
 
 const {
 	getTonalBase,
 	getUnitLength,
 	parseAbc,
-	getMeter,
+	getMeter
 } = require("../parse/parser.js");
 
 const { contourToSvg } = require("./contour-svg.js");
@@ -28,11 +29,12 @@ const { contourToSvg } = require("./contour-svg.js");
 function getContour(
 	abc,
 	{
+		contourShift = null,
 		withSvg = false,
 		withSwingTransform = false,
-		maxNbBars = new Fraction(3, 2),
+		maxNbBars = new Fraction(3, 1),
 		maxNbUnitLengths = 12,
-		svgConfig = {},
+		svgConfig = {}
 	} = {}
 ) {
 	const tonalBase = getTonalBase(abc);
@@ -52,10 +54,10 @@ function getContour(
 	const maxDuration = maxNbBars.multiply(meterFraction);
 
 	const {
-		bars,
+		bars
 	} = //todo: could add as an argument; default null
 		parseAbc(abc, {
-			maxBars: Math.ceil(maxNbBars.toNumber()),
+			maxBars: Math.ceil(maxNbBars.toNumber())
 		});
 
 	let cumulatedDuration = new Fraction(0, 1);
@@ -65,6 +67,7 @@ function getContour(
 	let index = 0;
 	// get the parsed notes - notes are tokens with a duration
 	const notes = [];
+	let totalPosition = 0;
 	let tied = false,
 		previousPosition = null;
 	for (let i = 0; i < bars.length; i++) {
@@ -90,6 +93,10 @@ function getContour(
 			? { encoded: silenceChar, encodedHeld: silenceChar, position: 0 }
 			: getEncodedFromNote(note, tonalBase, tied, previousPosition);
 
+		if (!isSilence) {
+			totalPosition += position;
+		}
+
 		if (note.tied) {
 			tied = true;
 			previousPosition = position;
@@ -140,8 +147,27 @@ function getContour(
 		}
 	});
 
+	// next loops shift the base octave so as to mninimise the average absolute distance
+	if (contourShift !== 0) {
+		if (Number.isInteger(contourShift))
+			sortKey.forEach((c, i) => (sortKey[i] = shiftChar(c, contourShift)));
+		else {
+			let avg = totalPosition / notes.length;
+			if (avg > 0)
+				while (avg >= 7) {
+					sortKey.forEach((c, i) => (sortKey[i] = shiftChar(c, -1)));
+					avg -= 7;
+				}
+			else
+				while (avg < -5) {
+					sortKey.forEach((c, i) => (sortKey[i] = shiftChar(c, 1)));
+					avg += 7;
+				}
+		}
+	}
+
 	const result = {
-		sortKey: sortKey.join(""),
+		sortKey: sortKey.join("")
 		//debugPositions: debugPositions.join(","),
 	};
 	if (durations.length > 0) {
@@ -304,7 +330,7 @@ function pushShortNote(
 	const relativeDuration = duration.divide(unitLength),
 		d = {
 			i: index,
-			d: relativeDuration.den,
+			d: relativeDuration.den
 		};
 	if (relativeDuration.num !== 1) {
 		d.n = relativeDuration.num;
@@ -324,10 +350,10 @@ function getEncodedFromNote(note, tonalBase, tied, previousPosition) {
 	return {
 		encoded: tied && position === previousPosition ? encodedHeld : encoded,
 		encodedHeld,
-		position,
+		position
 	};
 }
 
 module.exports = {
-	getContour,
+	getContour
 };