@gondola-lyrics/kit 0.2.0 → 0.3.0

package/dist/generator.d.ts

@@ -3,9 +3,10 @@ import { runtime } from '@gondola-lyrics/model';
 /**
  * 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.
@@ -14,6 +15,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;
@@ -46,4 +65,25 @@ export declare type LrcGenerateResult = LrcContent;
  */
 export declare type LyricFormat = 'lrc' | 'ttml';
 
+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 TtmlProfile = 'amll' | 'itunes';
+
 export { }

package/dist/generator.js

@@ -1 +1 @@
-export { generate, generateLrc } from "./formats.js";
+export { generate, generateLrc, generateTtml } from "./formats.js";

package/dist/index.d.ts

@@ -6,14 +6,15 @@ import { runtime } from '@gondola-lyrics/model';
  *
  * Unrecognized text returns `undefined`.
  */
-export declare const detectFormat: (input: unknown) => "lrc" | "ttml" | undefined;
+export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
 /**
  * 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.
@@ -22,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;
@@ -93,12 +112,29 @@ 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 interface TtmlContent {
-    original: string;
+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;

package/dist/index.js

@@ -1,3 +1,3 @@
-export { detectFormat, generate, generateLrc, parse, parseLrc, parseTtml } 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

@@ -6,7 +6,7 @@ import { runtime } from '@gondola-lyrics/model';
  *
  * Unrecognized text returns `undefined`.
  */
-export declare const detectFormat: (input: unknown) => "lrc" | "ttml" | undefined;
+export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
 declare interface LrcContent {
     original: string;
@@ -58,11 +58,9 @@ 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 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. */

package/package.json

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