@gondola-lyrics/kit 0.3.0 → 0.5.0

package/README.md

@@ -10,9 +10,10 @@ npm install @gondola-lyrics/kit
 
 ## Supports
 
-| Format | Parse | Generate | Annotation tracks | Notes                                                                |
-| ------ | ----- | -------- | ----------------- | -------------------------------------------------------------------- |
-| LRC    | ✅    | ✅       | ✅                | Line and enhanced word timing, metadata, translations, romanizations |
+| Format | Line level | Word level | Annotation | Meta |
+| ------ | ---------- | ---------- | ---------- | ---- |
+| LRC    | ✅         | ✅         | ✅         | ✅   |
+| TTML   | ✅         | ✅         | ✅         | ✅   |
 
 ## Usage
 

package/dist/formats.d.ts

@@ -14,6 +14,13 @@ export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
  */
 export declare const detectLrc: (input: unknown) => boolean;
 
+/**
+ * Detects QRC from the original track so annotations cannot change format selection.
+ *
+ * @returns Whether plaintext or a supported XML payload contains a timed QRC row.
+ */
+export declare const detectQrc: (input: unknown) => boolean;
+
 /**
  * Recognition needs a profile hint, since plain TTML says nothing about which profile wrote it.
  *
@@ -25,15 +32,18 @@ export declare const detectTtml: (input: unknown) => boolean;
 /**
  * Generates text in the requested format, which need not match `lyric.format`.
  *
- * The writer map pairs each format's options with its result and requires a writer for every supported format.
+ * The writer map pairs options with results only for formats that have an implemented writer.
  * An unknown target returns `null`.
  */
-export declare const generate: <Target extends LyricFormat>(lyric: runtime.Lyric, target: Target, options?: GenerateOptions[Target]) => GenerateResults[Target] | null;
+export declare const generate: <Target extends GenerateFormat>(lyric: runtime.Lyric, target: Target, options?: GenerateOptions[Target]) => GenerateResults[Target] | null;
+
+export declare type GenerateFormat = keyof GenerateOptions;
 
 /**
  * Generates the LRC text plus the annotations a single file cannot hold.
  *
  * Word tags appear only for a word-timed lyric when `wordTiming` is not `none`; otherwise every line stays whole.
+ * Word romanizations retain token boundaries; explicit line romanizations take precedence for the same language.
  */
 export declare const generateLrc: (lyric: runtime.Lyric, options?: LrcGenerateOptions) => LrcGenerateResult;
 
@@ -52,6 +62,7 @@ declare interface GenerateResults {
  *
  * Offsets are baked into timestamps; a negative result or a missing required time throws.
  * Profile mappings retain the lead agent and first AMLL ruby, omitting unsupported fields and instrumental nodes.
+ * Word romanizations are emitted as line text without their token timing.
  */
 export declare const generateTtml: (lyric: runtime.Lyric, options?: TtmlGenerateOptions) => TtmlGenerateResult;
 
@@ -82,6 +93,18 @@ export declare interface LrcGenerateOptions {
 
 export declare type LrcGenerateResult = LrcContent;
 
+export declare interface LrcLineTiming {
+    /**
+     * Clock timestamp precision in milliseconds; unit-suffixed timestamps use 1ms.
+     */
+    precision: number;
+}
+
+export declare interface LrcMetaTag {
+    key: string;
+    value: string;
+}
+
 export declare type LrcParseInput = LrcContent;
 
 export declare interface LrcParseOptions {
@@ -90,28 +113,67 @@ export declare interface LrcParseOptions {
      * Defaults to `0`, which requires an exact match.
      */
     annotationTolerance?: number;
+    /**
+     * Maximum roman token drift outside a matched word, in milliseconds; matched boundaries are adjusted to that word.
+     * Original word timing is preserved, and incomplete word matches retain the source line romanization.
+     *
+     * @default 0
+     */
+    wordAnnotationTolerance?: number;
+    /**
+     * Recovers unmatched roman fragments from unique two-kana combination starts or equal-sized gaps between timing anchors.
+     * Only a base kana followed by its small kana combines; doubled consonants and long vowels retain the whole line romanization.
+     * Recovered token times are clipped to their original word; untimed fragments inherit its range.
+     *
+     * @default false
+     */
+    wordAnnotationFallback?: boolean;
+}
+
+export declare interface LrcReadOptions {
+    /**
+     * Reports each line with its source precision before normalization can change its identity or order.
+     */
+    onLine?: (line: runtime.Line, timing: LrcLineTiming) => void;
+}
+
+export declare interface LrcReadResult {
+    lines: runtime.Line[];
+    metaTags: LrcMetaTag[];
 }
 
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc' | 'ttml';
+export declare type LyricFormat = 'lrc' | 'qrc' | 'ttml';
 
 /**
  * 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.
  */
-export declare const parse: (input: unknown, options?: LrcParseOptions & TtmlParseOptions) => ParseResult | null;
+export declare const parse: (input: unknown, options?: LrcParseOptions & QrcParseOptions & TtmlParseOptions) => ParseResult | null;
 
 /**
- * Source order, empty timed lines, and missing word times are preserved for model validation.
+ * Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
  *
  * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
+ * Complete roman tracks attach to words by timing and optional local recovery; other tracks retain their source line text.
  *
  * `INVALID` means no readable timed lines; the returned diagnostics carry whatever the canonical tree breaks.
  */
 export declare const parseLrc: (input: string | LrcParseInput, options?: LrcParseOptions) => ParseResult;
 
+/**
+ * Parses plaintext or XML QRC, retaining explicit timing, word romanization, and ruby from kana metadata.
+ * Original-track kana supplies ruby and is removed from the returned metadata.
+ *
+ * @param input Original lyrics with optional translation and romanization tracks.
+ * @param options Independent line and word tolerances, with optional local roman recovery.
+ *
+ * @returns Canonical lyrics and source diagnostics; an empty result has INVALID status.
+ */
+export declare const parseQrc: (input: string | QrcParseInput, options?: QrcParseOptions) => ParseResult;
+
 /**
  * A parsed lyric in canonical form, with every rule it breaks.
  */
@@ -128,6 +190,49 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+declare interface QrcContent {
+    original: string;
+    translations?: string;
+    romans?: string;
+}
+
+export declare type QrcParseInput = QrcContent;
+
+export declare interface QrcParseOptions {
+    /**
+     * Extra tolerance in milliseconds for line annotations left after exact time and row order matching.
+     *
+     * @default 0
+     */
+    annotationTolerance?: number;
+    /**
+     * Extra word-boundary tolerance in milliseconds; native QRC tracks allow at least 1ms for rounding.
+     * LRC auxiliary tracks use exact word boundaries by default, and incomplete matches retain the whole line romanization.
+     *
+     * @default 0
+     */
+    wordAnnotationTolerance?: number;
+    /**
+     * Recovers unmatched roman fragments from unique two-kana combination starts or equal-sized gaps between timing anchors.
+     * Only a base kana followed by its small kana combines; doubled consonants and long vowels retain the whole line romanization.
+     * Recovered token times are clipped to their original word; untimed fragments inherit its range.
+     *
+     * @default false
+     */
+    wordAnnotationFallback?: boolean;
+}
+
+/**
+ * Reads one LRC track before normalization so consumers retain source order and timing slots.
+ * The caller owns metadata mapping, annotation attachment, and final normalization.
+ *
+ * @param text Original lyrics or one auxiliary track in LRC syntax.
+ * @param options Optional observer for source timestamp information.
+ *
+ * @returns Model lines in input order and metadata tags with lowercase keys and trimmed values.
+ */
+export declare const readLrc: (text: string, options?: LrcReadOptions) => LrcReadResult;
+
 export declare interface TtmlGenerateOptions {
     /**
      * Defaults to the source TTML profile, or `amll` when the lyric came from another format.