@gondola-lyrics/kit 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Diagnostic } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
 /**
@@ -5,12 +6,15 @@ 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;
 
 /**
  * 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.
@@ -19,6 +23,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;
@@ -59,21 +81,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) => ParseResult;
+
+/**
+ * A parsed lyric in canonical form, with every rule it breaks.
  */
-export declare const parseLrc: (input: string | LrcParseInput, options?: LrcParseOptions) => runtime.Lyric;
+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 { }

package/dist/index.js

@@ -1,3 +1,3 @@
-export { detectFormat, generate, generateLrc, parse, parseLrc } from "./formats.js";
+export { detectFormat, generate, generateLrc, generateTtml, parse, parseLrc, parseTtml } from "./formats.js";
 import "./parser.js";
 import "./generator.js";

package/dist/parser.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;
 
 declare interface LrcContent {
     original: string;
@@ -26,21 +27,46 @@ 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 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 { }

package/dist/parser.js

@@ -1 +1 @@
-export { detectFormat, parse, parseLrc } from "./formats.js";
+export { detectFormat, parse, parseLrc, parseTtml } from "./formats.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gondola-lyrics/kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Gondola lyrics toolkit",
   "keywords": [
     "gondola",