@gondola-lyrics/kit 0.5.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,6 +22,20 @@ 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.
@@ -29,6 +57,13 @@ export declare const detectQrc: (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`.
  *
@@ -66,6 +101,38 @@ declare interface GenerateResults {
  */
 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;
@@ -132,9 +199,13 @@ export declare interface LrcParseOptions {
 
 export declare interface LrcReadOptions {
     /**
-     * Reports each line with its source precision before normalization can change its identity or order.
+     * 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) => void;
+    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 {
@@ -145,13 +216,41 @@ export declare interface LrcReadResult {
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc' | 'qrc' | '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 & QrcParseOptions & 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.
@@ -190,6 +289,28 @@ 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;
@@ -223,8 +344,23 @@ export declare interface QrcParseOptions {
 }
 
 /**
- * Reads one LRC track before normalization so consumers retain source order and timing slots.
- * The caller owns metadata mapping, annotation attachment, and final normalization.
+ * 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.
@@ -233,6 +369,48 @@ export declare interface QrcParseOptions {
  */
 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.
@@ -261,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 { }