@gondola-lyrics/kit 0.2.0 → 0.3.0

package/dist/formats.d.ts

@@ -1,14 +1,12 @@
 import { Diagnostic } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
-export declare const AMLL_HINT_PATTERN: RegExp;
-
 /**
  * Recognition reads only the original text; the annotation tracks never decide the format.
  *
  * Unrecognized text returns `undefined`.
  */
-export declare const detectFormat: (input: unknown) => "lrc" | "ttml" | undefined;
+export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
 /**
  * A single readable time tag is enough for recognition; metadata alone is not.
@@ -24,14 +22,13 @@ export declare const detectLrc: (input: unknown) => boolean;
  */
 export declare const detectTtml: (input: unknown) => boolean;
 
-export declare const FORMAT = "ttml";
-
 /**
  * Generates text in the requested format, which need not match `lyric.format`.
  *
- * A format without a writer has no branch here, so adding one to `LyricFormat` makes this fail to compile.
+ * 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.
@@ -40,7 +37,23 @@ export declare const generate: (lyric: runtime.Lyric, target: LyricFormat, optio
  */
 export declare const generateLrc: (lyric: runtime.Lyric, options?: LrcGenerateOptions) => LrcGenerateResult;
 
-export declare const ITUNES_HINT_PATTERN: RegExp;
+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;
@@ -113,15 +126,28 @@ export declare interface ParseResult {
  * 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: string | TtmlContent, options?: TtmlParseOptions) => ParseResult;
+export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
-export declare const readTtmlContent: (input: unknown) => TtmlContent | null;
+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 const readTtmlProfile: (source: string) => TtmlProfile;
+export declare type TtmlGenerateResult = string;
 
-export declare interface TtmlContent {
-    original: 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. */