@gondola-lyrics/kit 0.4.0 → 0.6.0

package/dist/formats.d.ts

@@ -1,6 +1,20 @@
 import { Diagnostic } from '@gondola-lyrics/model/runtime';
+import { Meta } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
+/**
+ * Attaches whole-word ruby without changing the source text, segmentation, or timing.
+ *
+ * @param lines Original timed rows before filtering or sorting.
+ * @param sources Readings with source coverage lengths and optional token times.
+ *
+ * @returns Annotated rows and matched source indices, preserving unchanged nodes.
+ */
+export declare const attachRubies: (lines: runtime.Line[], sources: RubySource[]) => {
+    lines: runtime.Line[];
+    matched: Set<number>;
+};
+
 /**
  * Recognition reads only the original text; the annotation tracks never decide the format.
  *
@@ -8,12 +22,33 @@ import { runtime } from '@gondola-lyrics/model';
  */
 export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
+/**
+ * Recognizes native KRC from a duration line carrying a complete three-field word tag, or from the Kugou language container.
+ *
+ * Both signals live in the original plaintext, so an auxiliary track still cannot decide the format.
+ *
+ * @returns Whether the original plaintext contains a strong KRC syntax signal.
+ */
+export declare const detectKrc: (input: unknown) => boolean;
+
+/**
+ * Recognizes octal parameters with encoded clock rows, or a complete marked bilingual sequence.
+ */
+export declare const detectKwrc: (input: unknown) => boolean;
+
 /**
  * A single readable time tag is enough for recognition; metadata alone is not.
  * This is a format probe, not a validity check, so an input of another shape is simply not LRC.
  */
 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.
  *
@@ -22,18 +57,28 @@ export declare const detectLrc: (input: unknown) => boolean;
  */
 export declare const detectTtml: (input: unknown) => boolean;
 
+/**
+ * Recognizes native word tags or a JSON display line accompanied by LRC content in the original track.
+ *
+ * @returns Whether the original plaintext carries a YRC signal stronger than its shared QRC line header.
+ */
+export declare const detectYrc: (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,9 +97,42 @@ 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;
 
+/**
+ * Kugou writes `//` where it holds no translation, in QRC source rows and in its language payload alike.
+ *
+ * @returns Whether the trimmed text is that sentinel instead of real content.
+ */
+export declare const isPlaceholderText: (text: string) => boolean;
+
+declare interface JsonLine {
+    start: number;
+    text: string;
+    complete: boolean;
+    credit?: {
+        raw: string;
+        names: string[];
+    };
+}
+
+declare interface KrcContent {
+    original: string;
+}
+
+export declare type KrcParseInput = KrcContent;
+
+export declare interface KrcReadResult {
+    lines: runtime.Line[];
+    metaTags: LrcMetaTag[];
+}
+
+export declare interface KwrcParseInput {
+    original: string;
+}
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -82,6 +160,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 +180,99 @@ 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 and zero-based physical row before normalization changes its identity or order.
+     */
+    onLine?: (line: runtime.Line, timing: LrcLineTiming, row: number) => void;
+    /**
+     * Reports metadata with its zero-based physical row so container fields can preserve their relative order.
+     */
+    onMeta?: (tag: LrcMetaTag, row: number) => 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' | 'krc' | 'kwrc' | 'yrc' | 'ttml';
+
+export declare const META_PATTERN: RegExp;
 
 /**
  * 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 & YrcParseOptions) => ParseResult | null;
+
+/**
+ * Parses decrypted Kugou lyrics, retaining explicit durations and attaching embedded annotations by source slot.
+ *
+ * A source carrying no KRC row is read as LRC, so a platform fallback keeps its container annotations.
+ * Placeholder slots carry no annotation, so they never keep a credit line in the stream.
+ * Kana supplies whole-word ruby; type 0 language tracks retain complete line romanization.
+ * Incomplete metadata remains available in unknowns, and source timing violations remain visible in diagnostics.
+ *
+ * @param input Decrypted plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKrc: (input: string | KrcParseInput) => ParseResult;
+
+/**
+ * Parses decoded KWRC with explicit word durations and structurally verified embedded translations.
+ *
+ * Missing or conflicting parameters and unsafe word calculations retain the complete row as line-level text.
+ * Plain LRC remains readable; offset is stored as metadata without changing source timestamps.
+ *
+ * @param input Decoded plaintext or an object containing its original text.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseKwrc: (input: string | KwrcParseInput) => ParseResult;
 
 /**
  * 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 +289,128 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+/**
+ * Integer tags use `offset[,duration]` in milliseconds relative to the line start.
+ * Clock tags are absolute and may append a duration in milliseconds, as in `<00:01.50,500>`.
+ * A missing or zero duration leaves the word end unspecified.
+ */
+export declare const parseWordTime: (body: string, lineStart: number) => {
+    start: number;
+    end: number | undefined;
+} | undefined;
+
+/**
+ * Parses native YRC or LRC fallback, keeping JSON display rows separate from annotation matching.
+ * Explicit line and word durations remain unchanged, including zero durations and source timing violations.
+ * JSON credit content becomes separate plain-text unknown entries sharing the source label and is omitted from lyric lines.
+ *
+ * @param input Plaintext tracks on the same timeline: yrc with ytlrc/yromalrc, or lrc with tlyric/romalrc.
+ * @param options Independent line and word tolerances, with optional local roman recovery.
+ *
+ * @returns Canonical lyrics and model diagnostics; no readable timed rows yields INVALID status.
+ */
+export declare const parseYrc: (input: string | YrcParseInput, options?: YrcParseOptions) => 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 JSON display text and splits the joined credit content at slash separators.
+ *
+ * @returns A readable display line and whether all source fields are represented, or null for other JSON.
+ */
+export declare const readJsonLine: (text: string) => JsonLine | null;
+
+/**
+ * Reads native KRC rows in source order and performs no other operation: no metadata mapping, annotation attachment, sorting, or normalization.
+ *
+ * Explicit line and word durations survive unchanged; whitespace splitting never reallocates segment time.
+ *
+ * @returns Original-order model lines and metadata tags awaiting interpretation.
+ */
+export declare const readKrc: (text: string) => KrcReadResult;
+
+/**
+ * Reads one LRC track in source order and performs no other operation: no metadata mapping, annotation attachment, sorting, or 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;
+
+/**
+ * Maps standard lyric metadata while preserving unmapped tags and unparseable durations in unknowns.
+ *
+ * @param tags Reader tags with lowercase keys and trimmed values.
+ *
+ * @returns Model metadata without interpreting platform-specific embedded annotations.
+ */
+export declare const readLrcMetaTags: (tags: LrcMetaTag[]) => Meta;
+
+/**
+ * Reads coverage markers and optional absolute token times without interpreting timing digits as coverage.
+ *
+ * @returns Complete ruby sources, or undefined when any source cannot be read.
+ */
+export declare const readRubyEntries: (value: string) => RubySource[] | undefined;
+
+/**
+ * One reading and the length of the source word it covers, in Unicode code points.
+ */
+export declare interface RubySource {
+    length: number;
+    ruby: runtime.WordAnnotationRuby;
+}
+
+/**
+ * Splits recognized tags from their following text while preserving literal content and empty tagged segments.
+ *
+ * @param pattern A global pattern whose first capture is the tag body.
+ * @param accepts Optional format-specific tag validation.
+ *
+ * @returns Source pieces in their original order, including an untagged prefix when present.
+ */
+export declare const scanWordTags: (content: string, pattern: RegExp, accepts?: (tag: string) => boolean) => WordPiece[];
+
+/**
+ * Untagged leading text is preserved; empty timed pieces retain explicit segment boundaries.
+ * Only recognized time tags split content; other angle-bracket text remains literal.
+ */
+export declare const splitWordTags: (content: string) => WordPiece[];
+
+export declare const TAG_PATTERN: RegExp;
+
 export declare interface TtmlGenerateOptions {
     /**
      * Defaults to the source TTML profile, or `amll` when the lyric came from another format.
@@ -156,4 +439,44 @@ export declare interface TtmlParseOptions {
 
 export declare type TtmlProfile = 'amll' | 'itunes';
 
+/**
+ * A recognized tag precedes its text; a missing tag identifies the literal prefix.
+ */
+export declare interface WordPiece {
+    text: string;
+    tag?: string;
+}
+
+declare interface YrcContent {
+    original: string;
+    translations?: string;
+    romans?: string;
+}
+
+export declare type YrcParseInput = YrcContent;
+
+export declare interface YrcParseOptions {
+    /**
+     * Extra timestamp drift allowed after exact and source-precision matching, in milliseconds.
+     * Tracks must share the original timeline; equal row counts never enable order matching.
+     *
+     * @default 0
+     */
+    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 matches retain the whole line romanization.
+     *
+     * @default 0
+     */
+    wordAnnotationTolerance?: number;
+    /**
+     * Recovers roman fragments from unique two-kana combination starts or equal-sized gaps between timing anchors.
+     * Recovered token times are clipped to their original word; untimed fragments inherit its range.
+     *
+     * @default false
+     */
+    wordAnnotationFallback?: boolean;
+}
+
 export { }