@gondola-lyrics/kit 0.1.0 → 0.2.0

package/dist/formats.js

@@ -1,4 +1,4 @@
-import { LineType, LyricStatus, Timing, WordType, deriveLanguageUsages, getWordsText, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineContentText, makeLineContentWords, makeLineNormal, makeLyric, makeMeta, makeText, makeTimeRange, makeUnknownEntry, makeWordNormal, makeWordSpace } from "@gondola-lyrics/model/runtime";
+import { AgentType, CreditRole, LineType, LyricStatus, Timing, WordType, canonicalizeLyric, deriveLanguageUsages, getWordsText, makeAgent, makeLineAnnotation, makeLineAnnotationRoman, makeLineAnnotationTranslation, makeLineBackground, makeLineContentText, makeLineContentWords, makeLineNormal, makeLyric, makeMeta, makeMetaCredit, makeText, makeTimeRange, makeUnknownEntry, makeWordAnnotation, makeWordAnnotationRuby, makeWordAnnotationToken, makeWordNormal, makeWordSpace, validateLyric } from "@gondola-lyrics/model/runtime";
 //#region src/utils/annotation.ts
 /**
 * An annotation line carries its text in either field, depending on whether the track used word tags.
@@ -91,30 +91,69 @@ var attachLineAnnotations = (lines, sources, options = {}) => {
 	});
 };
 //#endregion
-//#region src/utils/index.ts
-var TIME_PATTERN = /^(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d+))?$/;
+//#region src/utils/language.ts
 /**
-* Bare integers are excluded because formats may use them as millisecond counts or offsets.
+* Returns a language tag in the canonical form the model stores, which is lower case.
+*
+* This mirrors the model's own helper, which it does not export.
+* Comparing tags stays with the consumer, since BCP 47 matches by subtag prefix rather than by string equality.
 */
-var isTime = (body) => {
-	const trimmed = body.trim();
-	return (trimmed.includes(":") || trimmed.includes(".")) && TIME_PATTERN.test(trimmed);
+var lowerTag = (tag) => {
+	return tag ? tag.toLowerCase() : void 0;
 };
+//#endregion
+//#region src/utils/time.ts
+var CLOCK_PATTERN = /^(?:(?:(\d+):)?(\d+):)?(\d+)(?:\.(\d+))?$/;
+var OFFSET_PATTERN = /^(\d+(?:\.\d+)?)(ms|h|m|s)$/iu;
 /**
-* Fractional seconds are padded or truncated to millisecond precision.
+* Reads a clock value, where the fraction is padded or truncated to millisecond precision.
 *
-* Invalid clock syntax returns `undefined`; time bounds are left to model validation.
+* `14.514` is fourteen seconds, not fourteen minutes: a colon, not a dot, introduces the larger units.
 */
-var parseTime = (body) => {
-	if (!isTime(body)) return;
-	const match = TIME_PATTERN.exec(body.trim());
+var parseClock = (value) => {
+	if (!value.includes(":") && !value.includes(".")) return;
+	const match = CLOCK_PATTERN.exec(value);
+	if (!match) return;
 	const hour = Number(match[1] ?? 0);
 	const minute = Number(match[2] ?? 0);
-	const second = Number(match[3]);
+	const second = Number(match[3] ?? 0);
 	const millisecond = Number((match[4] ?? "").padEnd(3, "0").slice(0, 3));
 	return ((hour * 60 + minute) * 60 + second) * 1e3 + millisecond;
 };
 /**
+* Reads an offset such as `1.5s`, `2m`, `500ms`, or `1h`.
+*/
+var parseOffset = (value) => {
+	const match = OFFSET_PATTERN.exec(value);
+	if (!match) return;
+	const amount = Number(match[1]);
+	if (!Number.isFinite(amount)) return;
+	switch ((match[2] ?? "").toLowerCase()) {
+		case "h": return Math.round(amount * 36e5);
+		case "m": return Math.round(amount * 6e4);
+		case "ms": return Math.round(amount);
+		default: return Math.round(amount * 1e3);
+	}
+};
+/**
+* Reports whether a value reads as a time.
+*/
+var isTime = (body) => {
+	return parseTime(body) !== void 0;
+};
+/**
+* Reads a time value into milliseconds.
+*
+* A clock reading accepts `ss.fraction`, `mm:ss.fraction`, and `hh:mm:ss.fraction`.
+* An offset accepts a number with an `h`, `m`, `s`, or `ms` suffix.
+* A bare number returns `undefined`, and so does anything else.
+*/
+var parseTime = (body) => {
+	const trimmed = body.trim();
+	if (trimmed === "") return;
+	return parseOffset(trimmed) ?? parseClock(trimmed);
+};
+/**
 * Tokens `h`, `m`, `s`, and `S` select hours, minutes, seconds, and fractional seconds.
 * Repeated unit tokens set minimum width; `S` tokens select up to three fractional digits.
 *
@@ -139,6 +178,482 @@ var formatTime = (time, format = "mm:ss.SSS") => {
 	});
 };
 //#endregion
+//#region src/utils/xml/utils.ts
+var XmlNodeType = {
+	element: 1,
+	text: 2,
+	cdata: 3
+};
+/**
+* Only prefixed names need their split cached, since an unprefixed one keeps its name as the local part.
+* The cache is bounded, which keeps an adversarial document from growing it without limit.
+*/
+var prefixedNames = /* @__PURE__ */ new Map();
+/**
+* Splits a qualified name into its namespace prefix and local name.
+*/
+var splitXmlName = (name) => {
+	const cached = prefixedNames.get(name);
+	if (cached !== void 0) return cached;
+	const colon = name.indexOf(":");
+	const split = colon === -1 ? {
+		namespacePrefix: "",
+		localName: name
+	} : {
+		namespacePrefix: name.slice(0, colon),
+		localName: name.slice(colon + 1)
+	};
+	if (split.namespacePrefix !== "" && prefixedNames.size < 1024) prefixedNames.set(name, split);
+	return split;
+};
+/**
+* Writes the prefix and local part onto a node that already carries the full name.
+*/
+var applyXmlNameParts = (name, target) => {
+	if (name.indexOf(":") === -1) {
+		target.namespacePrefix = "";
+		target.localName = name;
+		return;
+	}
+	const split = splitXmlName(name);
+	target.namespacePrefix = split.namespacePrefix;
+	target.localName = split.localName;
+};
+/**
+* Creates an attribute from its full name and value.
+*/
+var createXmlAttribute = (qualifiedName, value) => {
+	const attribute = {
+		qualifiedName,
+		value,
+		namespacePrefix: "",
+		localName: qualifiedName
+	};
+	applyXmlNameParts(qualifiedName, attribute);
+	return attribute;
+};
+/**
+* Returns the value of one attribute, matched by its local name so the prefix never has to be known.
+*/
+var getXmlAttribute = (element, localName) => {
+	const attributes = element.attributes;
+	for (let index = 0; index < attributes.length; index += 1) {
+		const attribute = attributes[index];
+		if (attribute !== void 0 && attribute.localName === localName) return attribute.value;
+	}
+};
+/**
+* Returns the value of one attribute, matched by its full name including the prefix.
+*/
+var getXmlQualifiedAttribute = (element, qualifiedName) => {
+	const attributes = element.attributes;
+	for (let index = 0; index < attributes.length; index += 1) {
+		const attribute = attributes[index];
+		if (attribute !== void 0 && attribute.qualifiedName === qualifiedName) return attribute.value;
+	}
+};
+/**
+* Returns the direct element children carrying one local name.
+*/
+var getXmlChildElements = (element, localName) => {
+	const result = [];
+	const children = element.children;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && child.nodeType === XmlNodeType.element && child.localName === localName) result.push(child);
+	}
+	return result;
+};
+/**
+* Reports whether the element has a direct child with one local name.
+*/
+var hasXmlChildElement = (element, localName) => {
+	const children = element.children;
+	for (let index = 0; index < children.length; index += 1) {
+		const child = children[index];
+		if (child !== void 0 && child.nodeType === XmlNodeType.element && child.localName === localName) return true;
+	}
+	return false;
+};
+/**
+* Returns the first element carrying one local name, the element itself included, in document order.
+*/
+var findXmlElement = (element, localName) => {
+	const stack = [element];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (node === void 0 || node.nodeType !== XmlNodeType.element) continue;
+		if (node.localName === localName) return node;
+		for (let index = node.children.length - 1; index >= 0; index -= 1) {
+			const child = node.children[index];
+			if (child !== void 0) stack.push(child);
+		}
+	}
+};
+/**
+* Returns every element carrying one local name, the element itself included, in document order.
+*/
+var findXmlElements = (element, localName) => {
+	const result = [];
+	const stack = [element];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		if (node === void 0 || node.nodeType !== XmlNodeType.element) continue;
+		if (node.localName === localName) result.push(node);
+		for (let index = node.children.length - 1; index >= 0; index -= 1) {
+			const child = node.children[index];
+			if (child !== void 0) stack.push(child);
+		}
+	}
+	return result;
+};
+/**
+* Joins the text and CDATA content of a node and its descendants, in document order.
+*/
+var getXmlTextContent = (node) => {
+	if (node.nodeType !== XmlNodeType.element) return node.text;
+	const parts = [];
+	const stack = [node];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0) continue;
+		if (current.nodeType === XmlNodeType.element) {
+			for (let index = current.children.length - 1; index >= 0; index -= 1) {
+				const child = current.children[index];
+				if (child !== void 0) stack.push(child);
+			}
+			continue;
+		}
+		parts.push(current.text);
+	}
+	return parts.join("");
+};
+//#endregion
+//#region src/utils/xml/reader.ts
+var LESS_THAN = 60;
+var GREATER_THAN = 62;
+var SLASH = 47;
+var EQUALS = 61;
+var DOUBLE_QUOTE = 34;
+var SINGLE_QUOTE = 39;
+var EXCLAMATION = 33;
+var QUESTION = 63;
+var AMPERSAND = 38;
+var HASH = 35;
+var HYPHEN = 45;
+var LOWER_X = 120;
+var UPPER_X = 88;
+var BYTE_ORDER_MARK = 65279;
+var ROOT_NAME = "#document";
+var DECIMAL_DIGITS = /^\d+$/;
+var HEX_DIGITS = /^[0-9a-fA-F]+$/;
+/**
+* Resolves one entity reference body, leaving anything unrecognized as written.
+*/
+var decodeReference = (body) => {
+	switch (body) {
+		case "lt": return "<";
+		case "gt": return ">";
+		case "amp": return "&";
+		case "quot": return "\"";
+		case "apos": return "'";
+	}
+	if (body.charCodeAt(0) !== HASH) return `&${body};`;
+	const hexadecimal = body.charCodeAt(1) === LOWER_X || body.charCodeAt(1) === UPPER_X;
+	const digits = hexadecimal ? body.slice(2) : body.slice(1);
+	if (!(hexadecimal ? HEX_DIGITS : DECIMAL_DIGITS).test(digits)) return `&${body};`;
+	const code = Number.parseInt(digits, hexadecimal ? 16 : 10);
+	if (!Number.isFinite(code) || code > 1114111) return `&${body};`;
+	return String.fromCodePoint(code);
+};
+/**
+* Replaces entity references in one run of text, leaving bare ampersands alone.
+*/
+var decodeText = (text) => {
+	const parts = [];
+	const length = text.length;
+	let start = 0;
+	let cursor = 0;
+	while (cursor < length) {
+		if (text.charCodeAt(cursor) !== AMPERSAND) {
+			cursor += 1;
+			continue;
+		}
+		const end = text.indexOf(";", cursor + 1);
+		if (end === -1) {
+			cursor += 1;
+			continue;
+		}
+		parts.push(text.slice(start, cursor), decodeReference(text.slice(cursor + 1, end)));
+		cursor = end + 1;
+		start = cursor;
+	}
+	if (parts.length === 0) return text;
+	parts.push(text.slice(start));
+	return parts.join("");
+};
+/**
+* Reads a document into a tree, or returns `null` when it is not well formed.
+*/
+var parseXml = (source) => {
+	const length = source.length;
+	let position = length > 0 && source.charCodeAt(0) === BYTE_ORDER_MARK ? 1 : 0;
+	let valid = true;
+	const stack = [];
+	const root = {
+		nodeType: XmlNodeType.element,
+		qualifiedName: ROOT_NAME,
+		namespacePrefix: "",
+		localName: ROOT_NAME,
+		attributes: [],
+		children: []
+	};
+	stack.push(root);
+	/**
+	* Appends a text node to the element being read.
+	*/
+	const readTextNode = (end) => {
+		const start = position;
+		position = end;
+		if (start === end) return;
+		const parent = stack[stack.length - 1];
+		if (parent === void 0) {
+			valid = false;
+			return;
+		}
+		const raw = source.slice(start, end);
+		parent.children.push({
+			nodeType: XmlNodeType.text,
+			text: raw.indexOf("&") === -1 ? raw : decodeText(raw)
+		});
+	};
+	/**
+	* Reads one quoted value, starting at `position`, and leaves `position` after the closing quote.
+	*/
+	const readQuotedValue = () => {
+		const quote = source.charCodeAt(position);
+		if (quote !== DOUBLE_QUOTE && quote !== SINGLE_QUOTE) {
+			valid = false;
+			return "";
+		}
+		position += 1;
+		const end = source.indexOf(quote === DOUBLE_QUOTE ? "\"" : "'", position);
+		if (end === -1) {
+			valid = false;
+			return "";
+		}
+		const raw = source.slice(position, end);
+		position = end + 1;
+		return raw.indexOf("&") === -1 ? raw : decodeText(raw);
+	};
+	/**
+	* Reads a start tag with its attributes, and opens the element unless it closes itself.
+	*/
+	const readStartTag = () => {
+		let cursor = position + 1;
+		const nameStart = cursor;
+		while (cursor < length) {
+			const code = source.charCodeAt(cursor);
+			if (code <= 32 || code === GREATER_THAN || code === SLASH || code === EQUALS) break;
+			cursor += 1;
+		}
+		if (cursor === nameStart) {
+			valid = false;
+			return;
+		}
+		const qualifiedName = source.slice(nameStart, cursor);
+		const attributes = [];
+		const element = {
+			nodeType: XmlNodeType.element,
+			qualifiedName,
+			namespacePrefix: "",
+			localName: qualifiedName,
+			attributes,
+			children: []
+		};
+		applyXmlNameParts(qualifiedName, element);
+		let closed = false;
+		let selfClosing = false;
+		while (cursor < length) {
+			let code = source.charCodeAt(cursor);
+			while (code <= 32) {
+				cursor += 1;
+				if (cursor >= length) break;
+				code = source.charCodeAt(cursor);
+			}
+			if (cursor >= length) break;
+			if (code === GREATER_THAN) {
+				cursor += 1;
+				closed = true;
+				break;
+			}
+			if (code === SLASH) {
+				cursor += 1;
+				if (cursor < length && source.charCodeAt(cursor) === GREATER_THAN) {
+					cursor += 1;
+					closed = true;
+					selfClosing = true;
+					break;
+				}
+				valid = false;
+				return;
+			}
+			const attributeStart = cursor;
+			do {
+				cursor += 1;
+				if (cursor >= length) break;
+				code = source.charCodeAt(cursor);
+			} while (code > 32 && code !== GREATER_THAN && code !== SLASH && code !== EQUALS);
+			if (cursor === attributeStart) {
+				valid = false;
+				return;
+			}
+			const attributeName = source.slice(attributeStart, cursor);
+			while (cursor < length && source.charCodeAt(cursor) <= 32) cursor += 1;
+			if (cursor >= length || source.charCodeAt(cursor) !== EQUALS) {
+				valid = false;
+				return;
+			}
+			cursor += 1;
+			while (cursor < length && source.charCodeAt(cursor) <= 32) cursor += 1;
+			position = cursor;
+			const value = readQuotedValue();
+			if (!valid) return;
+			cursor = position;
+			for (let index = 0; index < attributes.length; index += 1) if (attributes[index]?.qualifiedName === attributeName) {
+				valid = false;
+				return;
+			}
+			attributes.push(createXmlAttribute(attributeName, value));
+		}
+		if (!closed) {
+			valid = false;
+			return;
+		}
+		position = cursor;
+		const parent = stack[stack.length - 1];
+		if (parent === void 0) {
+			valid = false;
+			return;
+		}
+		parent.children.push(element);
+		if (!selfClosing) stack.push(element);
+	};
+	/**
+	* Closes the innermost element, which has to be the one the tag names.
+	*/
+	const readEndTag = () => {
+		let cursor = position + 2;
+		const nameStart = cursor;
+		while (cursor < length) {
+			const code = source.charCodeAt(cursor);
+			if (code <= 32 || code === GREATER_THAN) break;
+			cursor += 1;
+		}
+		const name = source.slice(nameStart, cursor);
+		const end = source.indexOf(">", cursor);
+		if (end === -1) {
+			valid = false;
+			return;
+		}
+		position = end + 1;
+		if (stack.length <= 1) {
+			valid = false;
+			return;
+		}
+		const top = stack[stack.length - 1];
+		if (top === void 0 || top.qualifiedName !== name) {
+			valid = false;
+			return;
+		}
+		stack.pop();
+	};
+	/**
+	* Skips a comment, CDATA section, or any other declaration such as a DOCTYPE.
+	*/
+	const readMarkupDeclaration = () => {
+		if (source.charCodeAt(position + 2) === HYPHEN && source.charCodeAt(position + 3) === HYPHEN) {
+			const end = source.indexOf("-->", position + 4);
+			if (end === -1) {
+				valid = false;
+				return;
+			}
+			position = end + 3;
+			return;
+		}
+		if (source.startsWith("[CDATA[", position + 2)) {
+			const start = position + 9;
+			const end = source.indexOf("]]>", start);
+			if (end === -1) {
+				valid = false;
+				return;
+			}
+			const parent = stack[stack.length - 1];
+			if (parent === void 0) {
+				valid = false;
+				return;
+			}
+			parent.children.push({
+				nodeType: XmlNodeType.cdata,
+				text: source.slice(start, end)
+			});
+			position = end + 3;
+			return;
+		}
+		let cursor = position + 2;
+		let depth = 1;
+		while (cursor < length && depth > 0) {
+			const code = source.charCodeAt(cursor);
+			if (code === LESS_THAN) depth += 1;
+			else if (code === GREATER_THAN) depth -= 1;
+			cursor += 1;
+		}
+		if (depth > 0) {
+			valid = false;
+			return;
+		}
+		position = cursor;
+	};
+	/**
+	* Skips a processing instruction, which carries nothing the kit reads.
+	*/
+	const readProcessingInstruction = () => {
+		const end = source.indexOf("?>", position + 2);
+		if (end === -1) {
+			valid = false;
+			return;
+		}
+		position = end + 2;
+	};
+	/**
+	* Reads content until the end of input or the end tag of the innermost element.
+	*/
+	const readNodes = () => {
+		while (position < length) {
+			const open = source.indexOf("<", position);
+			if (open === -1) {
+				readTextNode(length);
+				return;
+			}
+			if (open > position) {
+				readTextNode(open);
+				if (!valid) return;
+			}
+			position = open;
+			const next = source.charCodeAt(open + 1);
+			if (next === SLASH) readEndTag();
+			else if (next === EXCLAMATION) readMarkupDeclaration();
+			else if (next === QUESTION) readProcessingInstruction();
+			else readStartTag();
+			if (!valid) return;
+		}
+	};
+	readNodes();
+	if (!valid || stack.length !== 1) return null;
+	for (let index = 0; index < root.children.length; index += 1) if (root.children[index]?.nodeType === XmlNodeType.element) return root;
+	return null;
+};
+//#endregion
 //#region src/formats/lrc/common.ts
 var readLrcContent = (input) => {
 	if (typeof input === "string") return { original: input };
@@ -328,6 +843,20 @@ var generateLrc = (lyric, options = {}) => {
 	return result;
 };
 //#endregion
+//#region src/formats/result.ts
+/**
+* Canonicalizes and validates one parser's output, so every format hands back the same shape.
+*
+* Canonicalization runs first because validation reports paths against the canonical tree.
+*/
+var finalizeLyric = (input) => {
+	const lyric = canonicalizeLyric(input);
+	return {
+		lyric,
+		diagnostics: validateLyric(lyric)
+	};
+};
+//#endregion
 //#region src/formats/lrc/parser.ts
 var isBareNumber = (value) => {
 	return /^\d+$/.test(value.trim());
@@ -440,7 +969,7 @@ var readMetaTags = (tags) => {
 * A tag opens a segment; untagged words continue from the previous end so the timeline has no holes.
 * Explicit word ends are kept as written, so duration tags survive unchanged.
 */
-var readWords = (text, lineStart) => {
+var readWords$1 = (text, lineStart) => {
 	const drafts = [];
 	const open = /* @__PURE__ */ new Set();
 	const closeSegment = (boundary) => {
@@ -491,9 +1020,9 @@ var readWords = (text, lineStart) => {
 * A line ends at the next line's start; without one, it ends at its final word's end.
 * An open word is closed by the next timed word, or by the line end, so every sung word stays inside the line.
 */
-var readLine = (text, start, nextStart) => {
+var readLine$1 = (text, start, nextStart) => {
 	const wordTimed = isWordTimed(text);
-	const { drafts, closeSegment } = wordTimed ? readWords(text, start) : {
+	const { drafts, closeSegment } = wordTimed ? readWords$1(text, start) : {
 		drafts: [],
 		closeSegment: () => {}
 	};
@@ -529,7 +1058,7 @@ var readLines = (timed) => {
 	const lines = [];
 	for (const [index, item] of timed.entries()) {
 		const next = timed[index + 1]?.start;
-		lines.push(readLine(item.text, item.start, next));
+		lines.push(readLine$1(item.text, item.start, next));
 	}
 	return lines;
 };
@@ -557,23 +1086,627 @@ var parseLrcText = (text) => {
 *
 * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
 *
-* `INVALID` means no readable timed lines; `VALID` does not imply model validation has passed.
+* `INVALID` means no readable timed lines; the returned diagnostics carry whatever the canonical tree breaks.
 */
 var parseLrc = (input, options = {}) => {
 	const source = readLrcContent(input) ?? { original: "" };
 	const lyric = parseLrcText(source.original);
-	if (lyric.status === LyricStatus.INVALID) return lyric;
+	if (lyric.status === LyricStatus.INVALID) return finalizeLyric(lyric);
 	const translations = source.translations === void 0 ? [] : readLines(readTimedLines(source.translations).timed);
 	const romans = source.romans === void 0 ? [] : readLines(readTimedLines(source.romans).timed);
-	if (translations.length === 0 && romans.length === 0) return lyric;
+	if (translations.length === 0 && romans.length === 0) return finalizeLyric(lyric);
 	const lines = attachLineAnnotations(lyric.lines, {
 		translations,
 		romans
 	}, { tolerance: options.annotationTolerance });
-	return {
+	return finalizeLyric({
 		...lyric,
 		lines
+	});
+};
+//#endregion
+//#region src/formats/ttml/common.ts
+var FORMAT = "ttml";
+var AMLL_HINT_PATTERN = /xmlns:amll|amll:meta/iu;
+var ITUNES_HINT_PATTERN = /xmlns:itunes|iTunesMetadata|itunes:timing=/iu;
+var readTtmlContent = (input) => {
+	if (typeof input === "string") return { original: input };
+	if (!input || typeof input !== "object") return null;
+	const source = input;
+	if (typeof source.original !== "string") return null;
+	return { original: source.original };
+};
+var readTtmlProfile = (source) => {
+	return AMLL_HINT_PATTERN.test(source) ? "amll" : "itunes";
+};
+//#endregion
+//#region src/formats/ttml/detect.ts
+/**
+* Recognition needs a profile hint, since plain TTML says nothing about which profile wrote it.
+*
+* A bare `tt` root also counts, which is what a hand-written document has.
+* This is a format probe, not a validity check, so an input of another shape is simply not TTML.
+*/
+var detectTtml = (input) => {
+	const content = readTtmlContent(input);
+	if (!content) return false;
+	if (AMLL_HINT_PATTERN.test(content.original) || ITUNES_HINT_PATTERN.test(content.original)) return true;
+	const root = parseXml(content.original);
+	if (!root) return false;
+	for (const child of root.children) if (child.nodeType === XmlNodeType.element && child.localName === "tt") return true;
+	return false;
+};
+var TIMING_WORD = "Word";
+var TIMING_LINE = "Line";
+//#endregion
+//#region src/formats/ttml/parser.ts
+/**
+* Reads the span time range, which a word needs both ends of to be sung.
+*/
+var readSpanTime = (element) => {
+	const begin = getXmlAttribute(element, "begin");
+	const end = getXmlAttribute(element, "end");
+	if (!begin || !end) return;
+	const start = parseTime(begin);
+	const finish = parseTime(end);
+	if (start === void 0 || finish === void 0) return;
+	return {
+		start,
+		end: finish
+	};
+};
+/**
+* Reads the line time range, which may leave its end open for the next line to supply.
+*/
+var readLineTime = (element) => {
+	const begin = getXmlAttribute(element, "begin");
+	if (!begin) return;
+	const start = parseTime(begin);
+	if (start === void 0) return;
+	const end = getXmlAttribute(element, "end");
+	return {
+		start,
+		end: end ? parseTime(end) : void 0
+	};
+};
+/**
+* Turns a run of text into drafts, keeping the separators as space words.
+*
+* A span's own trailing space is part of the word it follows, so leading and trailing runs both survive.
+*/
+var splitWords = (text) => {
+	const words = [];
+	for (const run of text.split(/(\s+)/)) if (run !== "") words.push({
+		text: run,
+		space: !run.trim(),
+		rubies: []
+	});
+	return words;
+};
+/**
+* Reads an AMLL ruby container into one word plus its per-syllable annotation.
+*/
+var readRuby = (container) => {
+	let base = "";
+	const tokens = [];
+	for (const child of getXmlChildElements(container, "span")) {
+		const kind = getXmlAttribute(child, "ruby");
+		if (kind === "base") {
+			base = getXmlTextContent(child).trim();
+			continue;
+		}
+		if (kind !== "textContainer") continue;
+		for (const text of getXmlChildElements(child, "span")) {
+			if (getXmlAttribute(text, "ruby") !== "text") continue;
+			const time = readSpanTime(text);
+			const content = getXmlTextContent(text).trim();
+			if (time === void 0 || !content) continue;
+			tokens.push({
+				start: time.start,
+				end: time.end,
+				text: content
+			});
+		}
+	}
+	const first = tokens[0];
+	const last = tokens[tokens.length - 1];
+	if (!base || first === void 0 || last === void 0) return;
+	return {
+		text: base,
+		space: false,
+		start: first.start,
+		end: last.end,
+		rubies: [{
+			start: first.start,
+			end: last.end,
+			tokens
+		}]
+	};
+};
+/**
+* Reports whether a text run holds nothing but formatting whitespace, which only a pretty-printed source produces.
+*/
+var isFormattingWhitespace = (text) => {
+	return text.trim() === "" && text.includes("\n");
+};
+/**
+* Collects the words of one span-bearing element.
+*
+* Text between spans carries the separators, and a span without both ends contributes its text untimed.
+* A span carrying a role is annotation rather than a word, so it is skipped here.
+* Indentation between tags is dropped, since the words themselves keep their own trailing spaces.
+*/
+var readWords = (element) => {
+	const words = [];
+	let wordLevel = false;
+	for (const child of element.children) {
+		if (child.nodeType === XmlNodeType.text) {
+			if (!isFormattingWhitespace(child.text)) words.push(...splitWords(child.text));
+			continue;
+		}
+		if (child.nodeType !== XmlNodeType.element || child.localName !== "span") continue;
+		if (getXmlAttribute(child, "role") !== void 0) continue;
+		if (getXmlAttribute(child, "ruby") === "container") {
+			const ruby = readRuby(child);
+			if (ruby !== void 0) {
+				words.push(ruby);
+				wordLevel = true;
+			}
+			continue;
+		}
+		const text = getXmlTextContent(child).trim();
+		if (!text) continue;
+		const time = readSpanTime(child);
+		if (time === void 0) {
+			words.push({
+				text,
+				space: false,
+				rubies: []
+			});
+			continue;
+		}
+		wordLevel = true;
+		words.push({
+			text,
+			space: false,
+			start: time.start,
+			end: time.end,
+			rubies: []
+		});
+	}
+	return {
+		words,
+		wordLevel
+	};
+};
+/**
+* Reads one paragraph, pulling its inline annotations and background lines out of the word stream.
+*/
+var readLine = (element) => {
+	const time = readLineTime(element);
+	if (time === void 0) return;
+	const draft = {
+		start: time.start,
+		end: time.end,
+		agentId: getXmlAttribute(element, "agent"),
+		key: getXmlAttribute(element, "key"),
+		words: [],
+		translations: [],
+		romans: [],
+		backgrounds: [],
+		wordLevel: false
+	};
+	if (!hasXmlChildElement(element, "span")) {
+		const plain = getXmlTextContent(element).trim();
+		if (!plain) return;
+		draft.words = splitWords(plain);
+		return draft;
+	}
+	const read = readWords(element);
+	draft.words = read.words;
+	draft.wordLevel = read.wordLevel;
+	for (const span of getXmlChildElements(element, "span")) {
+		const role = getXmlAttribute(span, "role");
+		if (!role) continue;
+		if (role === "x-bg") {
+			const background = readBackground(span);
+			if (background) draft.backgrounds.push(background);
+			continue;
+		}
+		const text = getXmlTextContent(span).trim();
+		if (!text) continue;
+		const item = {
+			language: lowerTag(getXmlAttribute(span, "lang")),
+			text
+		};
+		if (role === "x-translation") draft.translations.push(item);
+		else if (role === "x-roman") draft.romans.push(item);
+	}
+	return draft;
+};
+/**
+* Reads a background line, whose end may stay open because its parent's end covers it.
+*
+* A background line states no time of its own in AMLL files, so its range comes from its words.
+*/
+var readBackground = (element) => {
+	const read = readWords(element);
+	if (read.words.length === 0) return;
+	const begin = getXmlAttribute(element, "begin");
+	const end = getXmlAttribute(element, "end");
+	const first = read.words.find((word) => {
+		return !word.space && word.start !== void 0;
+	});
+	const last = read.words.findLast((word) => {
+		return !word.space && word.start !== void 0;
+	});
+	const start = begin === void 0 ? first?.start ?? 0 : parseTime(begin);
+	if (start === void 0) return;
+	return {
+		start,
+		end: end === void 0 ? last?.end : parseTime(end),
+		agentId: getXmlAttribute(element, "agent"),
+		key: getXmlAttribute(element, "key"),
+		words: read.words,
+		translations: [],
+		romans: [],
+		backgrounds: [],
+		wordLevel: read.wordLevel
+	};
+};
+/**
+* Builds the model words of one draft line.
+*/
+var buildWords = (draft) => {
+	const words = [];
+	for (const word of draft.words) {
+		if (word.space) {
+			words.push(makeWordSpace({ text: word.text }));
+			continue;
+		}
+		const time = word.start === void 0 ? void 0 : makeTimeRange({
+			start: word.start,
+			end: word.end
+		});
+		if (word.rubies.length === 0) {
+			words.push(makeWordNormal({
+				text: word.text,
+				time
+			}));
+			continue;
+		}
+		const rubies = word.rubies.map((ruby) => {
+			return makeWordAnnotationRuby({
+				time: makeTimeRange({
+					start: ruby.start,
+					end: ruby.end
+				}),
+				tokens: ruby.tokens.map((token) => {
+					return makeWordAnnotationToken({
+						text: token.text,
+						time: makeTimeRange({
+							start: token.start,
+							end: token.end
+						})
+					});
+				})
+			});
+		});
+		words.push(makeWordNormal({
+			text: word.text,
+			time,
+			annotation: makeWordAnnotation({ rubies })
+		}));
+	}
+	return words;
+};
+/**
+* Builds a line's annotation container, which the model only keeps when it holds something.
+*/
+var buildLineAnnotation = (draft) => {
+	if (draft.translations.length === 0 && draft.romans.length === 0) return;
+	return makeLineAnnotation({
+		translations: draft.translations.map((item) => {
+			return makeLineAnnotationTranslation({
+				text: item.text,
+				language: item.language
+			});
+		}),
+		romans: draft.romans.map((item) => {
+			return makeLineAnnotationRoman({
+				text: item.text,
+				language: item.language
+			});
+		})
+	});
+};
+/**
+* Builds one background line.
+*/
+var buildBackground = (draft) => {
+	return makeLineBackground({
+		id: draft.key,
+		time: makeTimeRange({
+			start: draft.start,
+			end: draft.end
+		}),
+		agents: draft.agentId === void 0 ? [] : [draft.agentId],
+		content: makeLineContentWords(buildWords(draft)),
+		annotation: buildLineAnnotation(draft)
+	});
+};
+/**
+* Builds one normal line, keeping plain text whole unless the source timed its words.
+*/
+var buildLine = (draft) => {
+	const content = draft.wordLevel ? makeLineContentWords(buildWords(draft)) : makeLineContentText(draft.words.map((word) => {
+		return word.text;
+	}).join("").trim());
+	return makeLineNormal({
+		id: draft.key,
+		time: makeTimeRange({
+			start: draft.start,
+			end: draft.end
+		}),
+		agents: draft.agentId === void 0 ? [] : [draft.agentId],
+		content,
+		annotation: buildLineAnnotation(draft),
+		backgrounds: draft.backgrounds.map(buildBackground)
+	});
+};
+/**
+* Maps one iTunes agent type onto the model's.
+*
+* The model requires `raw` on `OTHER`, since it cannot tell whether the source stated that word or the reader gave up.
+*/
+var readAgentType = (raw) => {
+	switch (raw) {
+		case "person": return {
+			type: AgentType.PERSON,
+			raw: void 0
+		};
+		case "group": return {
+			type: AgentType.GROUP,
+			raw: void 0
+		};
+		default: return {
+			type: AgentType.OTHER,
+			raw: raw ?? "other"
+		};
+	}
+};
+/**
+* Reads the head's agents, which lines reference by id.
+*/
+var readAgents = (metadata) => {
+	if (!metadata) return [];
+	const agents = [];
+	for (const element of findXmlElements(metadata, "agent")) {
+		const id = getXmlQualifiedAttribute(element, "xml:id") ?? getXmlAttribute(element, "id");
+		if (!id) continue;
+		const names = getXmlChildElements(element, "name").map((name) => {
+			return getXmlTextContent(name).trim();
+		}).filter((name) => {
+			return name !== "";
+		});
+		const kind = readAgentType(getXmlAttribute(element, "type"));
+		agents.push(makeAgent({
+			id,
+			type: kind.type,
+			raw: kind.raw,
+			names: names.map((name) => {
+				return makeText({ text: name });
+			})
+		}));
+	}
+	return agents;
+};
+/**
+* Reads the head's songwriters as one lyricist credit, since TTML does not split the role further.
+*
+* AMLL wraps these in `iTunesMetadata`, so the whole head is searched rather than its direct children.
+*/
+var readCredits = (metadata, meta) => {
+	if (!metadata) return;
+	const names = findXmlElements(metadata, "songwriter").map((element) => {
+		return getXmlTextContent(element).trim();
+	}).filter((name) => {
+		return name !== "";
+	});
+	if (names.length === 0) return;
+	meta.credits.push(makeMetaCredit({
+		role: CreditRole.LYRICIST,
+		names: names.map((name) => {
+			return makeText({ text: name });
+		})
+	}));
+};
+/**
+* Reads one `amll:meta` entry, keeping an unknown key as written so a round trip loses nothing.
+*/
+var applyAmllMeta = (meta, element) => {
+	const key = getXmlAttribute(element, "key");
+	const value = getXmlAttribute(element, "value")?.trim();
+	if (!key || !value) return;
+	switch (key) {
+		case "musicName":
+			meta.titles.push(makeText({ text: value }));
+			return;
+		case "artists":
+			meta.artists.push(makeText({ text: value }));
+			return;
+		case "album":
+			meta.albums.push(makeText({ text: value }));
+			return;
+		case "isrc":
+			meta.isrcs.push(value);
+			return;
+		case "ttmlAuthorGithubLogin":
+			meta.authors.push(makeText({ text: value }));
+			return;
+		default: meta.unknowns.push(makeUnknownEntry({
+			key,
+			value
+		}));
+	}
+};
+/**
+* Splits one annotation text into its main part and any background pieces it embeds.
+*/
+var splitBackgroundText = (element) => {
+	let main = "";
+	const backgrounds = [];
+	for (const child of element.children) {
+		if (child.nodeType === XmlNodeType.element && child.localName === "span" && getXmlAttribute(child, "role") === "x-bg") {
+			backgrounds.push({
+				text: getXmlTextContent(child).trim(),
+				key: getXmlAttribute(child, "for")
+			});
+			continue;
+		}
+		main += getXmlTextContent(child);
+	}
+	return {
+		main: main.trim(),
+		backgrounds
+	};
+};
+/**
+* Attaches head translations and transliterations to the lines they name by `itunes:key`.
+*
+* A replacement translation rewrites the line's text, which is how a source swaps one script for another.
+*/
+var attachHeadAnnotations = (metadata, lineMap, backgroundMap) => {
+	if (!metadata || lineMap.size === 0) return;
+	const attach = (blocks, kind) => {
+		for (const block of blocks) {
+			const language = lowerTag(getXmlAttribute(block, "lang"));
+			const type = getXmlQualifiedAttribute(block, "type") ?? getXmlAttribute(block, "type");
+			for (const text of getXmlChildElements(block, "text")) {
+				const key = getXmlAttribute(text, "for");
+				const line = key ? lineMap.get(key) : void 0;
+				if (!line) continue;
+				const { main, backgrounds } = splitBackgroundText(text);
+				if (kind === "translation" && type === "replacement") {
+					if (main) {
+						line.words = splitWords(main);
+						line.wordLevel = false;
+					}
+					continue;
+				}
+				if (main) {
+					const item = {
+						language,
+						text: main
+					};
+					if (kind === "translation") line.translations.push(item);
+					else line.romans.push(item);
+				}
+				for (const background of backgrounds) {
+					if (!background.text) continue;
+					const target = background.key ? backgroundMap.get(background.key) : void 0;
+					if (!target) continue;
+					const item = {
+						language,
+						text: background.text
+					};
+					if (kind === "translation") target.translations.push(item);
+					else target.romans.push(item);
+				}
+			}
+		}
 	};
+	attach(findXmlElements(metadata, "translation"), "translation");
+	attach(findXmlElements(metadata, "transliteration"), "roman");
+};
+/**
+* Returns the paragraphs of a body, including any nested inside a div.
+*/
+var findParagraphs = (body) => {
+	const result = [];
+	const stack = [body];
+	while (stack.length > 0) {
+		const element = stack.pop();
+		if (!element) continue;
+		if (element.localName === "p") {
+			result.push(element);
+			continue;
+		}
+		const children = element.children;
+		for (let index = children.length - 1; index >= 0; index -= 1) {
+			const child = children[index];
+			if (child && child.nodeType === XmlNodeType.element) stack.push(child);
+		}
+	}
+	return result;
+};
+var readDeclaredTiming = (root) => {
+	switch (getXmlQualifiedAttribute(root, "itunes:timing")) {
+		case TIMING_WORD: return Timing.WORD;
+		case TIMING_LINE: return Timing.LINE;
+		default: return;
+	}
+};
+/**
+* Reads a TTML document into the model.
+*
+* The profile only changes where metadata comes from, so one reader serves both.
+* A document that parses but holds no timed paragraph is `INVALID` rather than an error.
+*/
+var parseTtml = (input, options = {}) => {
+	const content = readTtmlContent(input);
+	if (!content) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta: makeMeta()
+	}));
+	const extra = { profile: readTtmlProfile(content.original) };
+	const document = parseXml(content.original);
+	const root = document ? findXmlElement(document, "tt") : void 0;
+	if (!root) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta: makeMeta(),
+		extra
+	}));
+	const body = findXmlElement(root, "body");
+	const metadata = findXmlElement(root, "metadata");
+	const meta = makeMeta();
+	const language = lowerTag(getXmlQualifiedAttribute(root, "xml:lang")) ?? lowerTag(options.language);
+	if (language !== void 0) meta.language = language;
+	readCredits(metadata, meta);
+	for (const element of metadata ? findXmlElements(metadata, "meta") : []) applyAmllMeta(meta, element);
+	const drafts = [];
+	const lineMap = /* @__PURE__ */ new Map();
+	const backgroundMap = /* @__PURE__ */ new Map();
+	for (const element of body ? findParagraphs(body) : []) {
+		const draft = readLine(element);
+		if (!draft) continue;
+		drafts.push(draft);
+		if (draft.key) lineMap.set(draft.key, draft);
+		for (const background of draft.backgrounds) if (background.key) backgroundMap.set(background.key, background);
+	}
+	attachHeadAnnotations(metadata, lineMap, backgroundMap);
+	if (drafts.length === 0) return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.INVALID,
+		meta,
+		extra
+	}));
+	const lines = drafts.map(buildLine);
+	const wordLevel = drafts.some((draft) => {
+		return draft.wordLevel;
+	});
+	return finalizeLyric(makeLyric({
+		format: FORMAT,
+		status: LyricStatus.VALID,
+		timing: readDeclaredTiming(root) ?? (wordLevel ? Timing.WORD : Timing.LINE),
+		meta,
+		extra,
+		agents: readAgents(metadata),
+		languages: deriveLanguageUsages(lines),
+		lines
+	}));
 };
 //#endregion
 //#region src/formats/index.ts
@@ -584,9 +1717,10 @@ var parseLrc = (input, options = {}) => {
 */
 var detectFormat = (input) => {
 	if (detectLrc(input)) return "lrc";
+	if (detectTtml(input)) return "ttml";
 };
 /**
-* Unrecognized text returns `null`; a recognized format returns a lyric with its parser-assigned status.
+* Unrecognized text returns `null`; a recognized format returns its canonical lyric and diagnostics.
 * Annotation tracks travel with the source and are attached by the format's parser.
 */
 var parse = (input, options = {}) => {
@@ -594,17 +1728,21 @@ var parse = (input, options = {}) => {
 	if (!format) return null;
 	switch (format) {
 		case "lrc": return parseLrc(input, options);
+		case "ttml": return parseTtml(input, options);
 	}
 };
 /**
 * Generates text in the requested format, which need not match `lyric.format`.
+*
+* A format without a writer has no branch here, so adding one to `LyricFormat` makes this fail to compile.
 */
 var generate = (lyric, target, options = {}) => {
 	switch (target) {
 		case "lrc": return generateLrc(lyric, options);
+		case "ttml": throw new Error("ttml generation is not implemented yet");
 	}
 };
 //#endregion
-export { detectFormat, detectLrc, generate, generateLrc, parse, parseLrc };
+export { AMLL_HINT_PATTERN, FORMAT, ITUNES_HINT_PATTERN, detectFormat, detectLrc, detectTtml, generate, generateLrc, parse, parseLrc, parseTtml, readTtmlContent, readTtmlProfile };
 
 //# sourceMappingURL=formats.js.map