@gondola-lyrics/kit 0.1.0 → 0.3.0

package/README.md

@@ -20,7 +20,7 @@ npm install @gondola-lyrics/kit
 > This package is ESM-only.
 > In your TS config, use `module: node20` / `module: nodenext` / `moduleResolution: bundler`.
 
-Parsing returns a `runtime.Lyric`, so the result is ready to validate and hand to a player without a second conversion step.
+Parsing returns a canonical `runtime.Lyric` together with the diagnostics it produced, so the result is ready to hand to a player without a second conversion step.
 
 ### Parse
 
@@ -28,14 +28,15 @@ Parsing returns a `runtime.Lyric`, so the result is ready to validate and hand t
 import { parse, parseLrc } from '@gondola-lyrics/kit'
 
 const content = `[00:01.00]Like the first time tangled by the fishing line`
-const lyric = parse(content)
+const parsed = parse(content)
 
-lyric?.format // => 'lrc'
-lyric?.lines[0]?.time?.start // => 1000
+parsed?.lyric.format // => 'lrc'
+parsed?.lyric.lines[0]?.time?.start // => 1000
+parsed?.diagnostics // => []
 
 // `parse` recognizes the format and returns `null` when it cannot.
 // `parseLrc` takes a known format and never returns `null`, so an unreadable source only carries `status: INVALID`.
-parseLrc('no timestamps here').status // => LyricStatus.INVALID
+parseLrc('no timestamps here').lyric.status // => LyricStatus.INVALID
 
 // LRC keeps translations and romanizations in separate files, attached here by timestamp.
 const annotated = parseLrc({
@@ -47,8 +48,8 @@ const annotated = parseLrc({
 [00:03.00]tanguru do bai za rain`,
 })
 
-annotated.lines[0]?.annotation?.translations[0].text // => '就像第一次'
-annotated.lines[0]?.annotation?.romans[0].text // => 'raiku za fasuto taimu'
+annotated.lyric.lines[0]?.annotation?.translations[0].text // => '就像第一次'
+annotated.lyric.lines[0]?.annotation?.romans[0].text // => 'raiku za fasuto taimu'
 
 // An exact timestamp match is assigned before any fuzzy one, and rows matching no line are dropped.
 // A drifting track attaches within a tolerance, where the nearest unclaimed line wins.
@@ -59,10 +60,12 @@ const drifted = {
 [00:03.20]被渔线缠住那样`,
 }
 
-parseLrc(drifted).lines[0]?.annotation // => undefined
-parseLrc(drifted, { annotationTolerance: 500 }).lines[0]?.annotation?.translations[0].text // => '就像第一次'
+parseLrc(drifted).lyric.lines[0]?.annotation // => undefined
+parseLrc(drifted, { annotationTolerance: 500 }).lyric.lines[0]?.annotation?.translations[0].text // => '就像第一次'
 ```
 
+Every parser canonicalizes its lyric and validates the result before returning, so `lyric` is already in canonical order and `diagnostics` is exactly what `@gondola-lyrics/model` reports for it.
+
 ### Generate
 
 `generate` takes the target format explicitly, so a lyric parsed from one format can be written out as another.
@@ -70,7 +73,7 @@ parseLrc(drifted, { annotationTolerance: 500 }).lines[0]?.annotation?.translatio
 ```ts
 import { generate, parseLrc } from '@gondola-lyrics/kit'
 
-const lyric = parseLrc('[00:01.00]Like the first time')
+const { lyric } = parseLrc('[00:01.00]Like the first time')
 
 // Separate tracks come back as separate fields, so the result parses again unchanged.
 const { original, translations, romans } = generate(lyric, 'lrc')
@@ -93,14 +96,15 @@ Detection reads only the original text. It answers whether the source is recogni
 
 ### Validation
 
-The kit does not report diagnostics of its own. Parsing keeps the source as written, and `@gondola-lyrics/model` decides what is valid.
+The kit does not invent diagnostics. It canonicalizes the lyric and hands back exactly what `@gondola-lyrics/model` reports for it.
 
 ```ts
-import { canonicalizeLyric, validateLyric } from '@gondola-lyrics/model/runtime'
+const { lyric, diagnostics } = parseLrc(source)
 
-const lyric = parseLrc(source)
+// The same list, computed by the kit on the way out.
+import { validateLyric } from '@gondola-lyrics/model/runtime'
 
-validateLyric(canonicalizeLyric(lyric)) // => []
+validateLyric(lyric) // deep-equals `diagnostics`
 ```
 
 ### Entries

package/dist/formats.d.ts

@@ -1,3 +1,4 @@
+import { Diagnostic } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
 /**
@@ -5,7 +6,7 @@ import { runtime } from '@gondola-lyrics/model';
  *
  * Unrecognized text returns `undefined`.
  */
-export declare const detectFormat: (input: unknown) => "lrc" | undefined;
+export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
 /**
  * A single readable time tag is enough for recognition; metadata alone is not.
@@ -13,10 +14,21 @@ export declare const detectFormat: (input: unknown) => "lrc" | undefined;
  */
 export declare const detectLrc: (input: unknown) => boolean;
 
+/**
+ * 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.
+ */
+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.
+ * An unknown target returns `null`.
  */
-export declare const generate: (lyric: runtime.Lyric, target: LyricFormat, options?: LrcGenerateOptions) => LrcGenerateResult;
+export declare const generate: <Target extends LyricFormat>(lyric: runtime.Lyric, target: Target, options?: GenerateOptions[Target]) => GenerateResults[Target] | null;
 
 /**
  * Generates the LRC text plus the annotations a single file cannot hold.
@@ -25,6 +37,24 @@ export declare const generate: (lyric: runtime.Lyric, target: LyricFormat, optio
  */
 export declare const generateLrc: (lyric: runtime.Lyric, options?: LrcGenerateOptions) => LrcGenerateResult;
 
+declare interface GenerateOptions {
+    lrc: LrcGenerateOptions;
+    ttml: TtmlGenerateOptions;
+}
+
+declare interface GenerateResults {
+    lrc: LrcGenerateResult;
+    ttml: TtmlGenerateResult;
+}
+
+/**
+ * Generates one TTML document, retaining the source profile unless explicitly overridden.
+ *
+ * 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.
+ */
+export declare const generateTtml: (lyric: runtime.Lyric, options?: TtmlGenerateOptions) => TtmlGenerateResult;
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -65,21 +95,65 @@ export declare interface LrcParseOptions {
 /**
  * Values match the lowercase format names stored in `Lyric.format`.
  */
-export declare type LyricFormat = 'lrc';
+export declare type LyricFormat = 'lrc' | '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.
  */
-export declare const parse: (input: unknown, options?: LrcParseOptions) => runtime.Lyric | null;
+export declare const parse: (input: unknown, options?: LrcParseOptions & TtmlParseOptions) => ParseResult | null;
 
 /**
  * Source order, empty timed lines, and missing word times are preserved for model validation.
  *
  * 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.
  */
-export declare const parseLrc: (input: string | LrcParseInput, options?: LrcParseOptions) => runtime.Lyric;
+export declare const parseLrc: (input: string | LrcParseInput, options?: LrcParseOptions) => ParseResult;
+
+/**
+ * A parsed lyric in canonical form, with every rule it breaks.
+ */
+export declare interface ParseResult {
+    lyric: runtime.Lyric;
+    diagnostics: Diagnostic[];
+}
+
+/**
+ * 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.
+ */
+export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
+
+export declare interface TtmlGenerateOptions {
+    /**
+     * Defaults to the source TTML profile, or `amll` when the lyric came from another format.
+     */
+    profile?: TtmlProfile;
+    /**
+     * Indent document structure; defaults to `false`.
+     * Lyric content stays flush to keep formatting whitespace out of the words.
+     */
+    indent?: boolean;
+    /**
+     * Emit song metadata; defaults to `true`.
+     * Agents and annotation tracks are retained because the body references them.
+     */
+    includeMeta?: boolean;
+}
+
+export declare type TtmlGenerateResult = string;
+
+export declare type TtmlParseInput = string;
+
+export declare interface TtmlParseOptions {
+    /** Language tag the lyric declares; the document's own `xml:lang` wins when it states one. */
+    language?: string;
+}
+
+export declare type TtmlProfile = 'amll' | 'itunes';
 
 export { }