@gondola-lyrics/kit 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,27 @@
 import { Diagnostic } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
+/**
+ * Derives emphasis for normal words in lead and background vocals using complete, valid word ranges.
+ * The stored word duration must strictly exceed durationThreshold; metadata offset and duration have no effect.
+ *
+ * Source emphasis, including an explicit false, is preserved; derived emphasis is cleared when a word no longer qualifies.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ *
+ * @throws {RangeError} If durationThreshold is not a non-negative safe integer in milliseconds.
+ */
+export declare const deriveWordEmphasis: (lyric: runtime.Lyric, options?: DeriveWordEmphasisOptions) => runtime.Lyric;
+
+export declare interface DeriveWordEmphasisOptions {
+    /**
+     * Word duration must strictly exceed this threshold, expressed as a non-negative safe integer in milliseconds.
+     *
+     * @default 3000
+     */
+    durationThreshold?: number;
+}
+
 /**
  * Recognition reads only the original text; the annotation tracks never decide the format.
  *
@@ -8,6 +29,38 @@ import { runtime } from '@gondola-lyrics/model';
  */
 export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
+/**
+ * Pulls bracketed background vocals out of the sung lines and attaches them to the line they accompany.
+ *
+ * A line holding nothing but brackets becomes a background of the line before it and is removed.
+ * A bracket opened on one line and closed on a later one joins the line before the opening, and both source lines go.
+ * Text outside brackets stays on its line, and a line left with none keeps its place.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const extractBackgroundLines: (lyric: runtime.Lyric, options?: ExtractBackgroundLinesOptions) => runtime.Lyric;
+
+export declare interface ExtractBackgroundLinesOptions {
+    /**
+     * Turn a line holding nothing but brackets into a background line of the line before it.
+     *
+     * @default true
+     */
+    fullLine?: boolean;
+    /**
+     * Pull the bracketed runs inside a line out into background lines of that same line.
+     *
+     * @default true
+     */
+    inLine?: boolean;
+    /**
+     * Join a bracket opened on one line and closed on a later one, attaching it to the line before them.
+     *
+     * @default true
+     */
+    crossLine?: boolean;
+}
+
 /**
  * Generates text in the requested format, which need not match `lyric.format`.
  *
@@ -41,6 +94,108 @@ declare interface GenerateResults {
  */
 export declare const generateTtml: (lyric: runtime.Lyric, options?: TtmlGenerateOptions) => TtmlGenerateResult;
 
+/**
+ * Inserts derived instrumental lines into uncovered gaps on the stored timeline, starting at zero.
+ * Existing lines and background vocals occupy their full ranges; an unknown end blocks later gaps.
+ *
+ * An outro requires an explicit endTime; metadata duration and offset do not affect insertion.
+ *
+ * @returns The input when unchanged, or a new lyric and lines array sharing existing nodes.
+ */
+export declare const insertInstrumentalLines: (lyric: runtime.Lyric, options?: InsertInstrumentalLinesOptions) => runtime.Lyric;
+
+export declare interface InsertInstrumentalLinesOptions {
+    /**
+     * Minimum gap duration in milliseconds, including an outro.
+     *
+     * @default 10000
+     */
+    minDuration?: number;
+    /**
+     * Minimum gap duration before the first vocal in milliseconds.
+     *
+     * @default 5000
+     */
+    minIntroDuration?: number;
+    /**
+     * Outro boundary in milliseconds, measured on the same timeline as line ranges.
+     * An omitted boundary leaves the outro unknown.
+     */
+    endTime?: number;
+}
+
+/**
+ * Inserts the spaces a source left out, so CJK text set against Latin letters, digits or punctuation reads evenly.
+ *
+ * A word-level line keeps every word's time and annotation: an inserted space becomes its own space word,
+ * and a word the rules split yields one word per character, all sharing the original range.
+ * A plain-text line and the annotation tracks are rewritten as whole strings.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const insertSpacesInLines: (lyric: runtime.Lyric, options?: InsertSpacesOptions) => runtime.Lyric;
+
+export declare interface InsertSpacesOptions {
+    /**
+     * Rules to apply; omitting the list applies all of them.
+     */
+    rules?: InsertSpacesRule[];
+    /**
+     * Rewrite the translation and romanization tracks too.
+     *
+     * @default true
+     */
+    annotations?: boolean;
+}
+
+export declare type InsertSpacesRule = (typeof InsertSpacesRules)[keyof typeof InsertSpacesRules];
+
+/**
+ * Groups of characters a source may write without a space where one belongs.
+ */
+export declare const InsertSpacesRules: {
+    /**
+     * A CJK character touching a Latin letter, as in `ABC中文`.
+     */
+    readonly CJK_ENGLISH: "cjkEnglish";
+    /**
+     * A CJK character touching a digit, as in `2026年`.
+     */
+    readonly CJK_NUMBER: "cjkNumber";
+    /**
+     * A comma, semicolon, exclamation mark, question mark or colon touching a character, as in `a,b`; a clock time or thousands separator such as `10:30` stays as written.
+     */
+    readonly PUNCTUATION: "punctuation";
+    /**
+     * A quotation mark touching a neighbouring character.
+     */
+    readonly QUOTE: "quote";
+    /**
+     * A bracket touching the character outside it.
+     */
+    readonly BRACKET_OUTSIDE: "bracketOutside";
+    /**
+     * A plus, equals or ampersand touching a character, as in `a+b`; a compound operator such as `a+=b` stays as written.
+     */
+    readonly MATH_OPERATOR: "mathOperator";
+    /**
+     * A hyphen touching a CJK character, as in `中-文`; a compound word such as `well-known` stays as written.
+     */
+    readonly HYPHEN: "hyphen";
+    /**
+     * A slash touching a character, as in `and/or`; a fraction such as `1/2` stays as written.
+     */
+    readonly SLASH: "slash";
+    /**
+     * Runs of two or more spaces, collapsed to one.
+     */
+    readonly COMPRESS_SPACES: "compressSpaces";
+    /**
+     * Spaces just inside a bracket or quotation mark, removed.
+     */
+    readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
+};
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -90,7 +245,7 @@ export declare type LyricFormat = 'lrc' | 'ttml';
 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.
+ * Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
  *
  * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
  *
@@ -114,6 +269,16 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+/**
+ * Removes the brackets some sources wrap around background vocals.
+ *
+ * One layer is removed from each edge of every background line, leaving a nested pair as `(x)`.
+ * A line left with no content is dropped, since a background line must carry something.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const stripBackgroundBrackets: (lyric: runtime.Lyric) => runtime.Lyric;
+
 export declare interface TtmlGenerateOptions {
     /**
      * Defaults to the source TTML profile, or `amll` when the lyric came from another format.

package/dist/index.js

@@ -1,3 +1,5 @@
-export { detectFormat, generate, generateLrc, generateTtml, parse, parseLrc, parseTtml } from "./formats.js";
+import { detectFormat, generate, generateLrc, generateTtml, parse, parseLrc, parseTtml } from "./formats.js";
+import { InsertSpacesRules, deriveWordEmphasis, extractBackgroundLines, insertInstrumentalLines, insertSpacesInLines, stripBackgroundBrackets } from "./transforms.js";
 import "./parser.js";
 import "./generator.js";
+export { InsertSpacesRules, deriveWordEmphasis, detectFormat, extractBackgroundLines, generate, generateLrc, generateTtml, insertInstrumentalLines, insertSpacesInLines, parse, parseLrc, parseTtml, stripBackgroundBrackets };

package/dist/parser.d.ts

@@ -1,6 +1,27 @@
 import { Diagnostic } from '@gondola-lyrics/model/runtime';
 import { runtime } from '@gondola-lyrics/model';
 
+/**
+ * Derives emphasis for normal words in lead and background vocals using complete, valid word ranges.
+ * The stored word duration must strictly exceed durationThreshold; metadata offset and duration have no effect.
+ *
+ * Source emphasis, including an explicit false, is preserved; derived emphasis is cleared when a word no longer qualifies.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ *
+ * @throws {RangeError} If durationThreshold is not a non-negative safe integer in milliseconds.
+ */
+export declare const deriveWordEmphasis: (lyric: runtime.Lyric, options?: DeriveWordEmphasisOptions) => runtime.Lyric;
+
+export declare interface DeriveWordEmphasisOptions {
+    /**
+     * Word duration must strictly exceed this threshold, expressed as a non-negative safe integer in milliseconds.
+     *
+     * @default 3000
+     */
+    durationThreshold?: number;
+}
+
 /**
  * Recognition reads only the original text; the annotation tracks never decide the format.
  *
@@ -8,6 +29,140 @@ import { runtime } from '@gondola-lyrics/model';
  */
 export declare const detectFormat: (input: unknown) => LyricFormat | undefined;
 
+/**
+ * Pulls bracketed background vocals out of the sung lines and attaches them to the line they accompany.
+ *
+ * A line holding nothing but brackets becomes a background of the line before it and is removed.
+ * A bracket opened on one line and closed on a later one joins the line before the opening, and both source lines go.
+ * Text outside brackets stays on its line, and a line left with none keeps its place.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const extractBackgroundLines: (lyric: runtime.Lyric, options?: ExtractBackgroundLinesOptions) => runtime.Lyric;
+
+export declare interface ExtractBackgroundLinesOptions {
+    /**
+     * Turn a line holding nothing but brackets into a background line of the line before it.
+     *
+     * @default true
+     */
+    fullLine?: boolean;
+    /**
+     * Pull the bracketed runs inside a line out into background lines of that same line.
+     *
+     * @default true
+     */
+    inLine?: boolean;
+    /**
+     * Join a bracket opened on one line and closed on a later one, attaching it to the line before them.
+     *
+     * @default true
+     */
+    crossLine?: boolean;
+}
+
+/**
+ * Inserts derived instrumental lines into uncovered gaps on the stored timeline, starting at zero.
+ * Existing lines and background vocals occupy their full ranges; an unknown end blocks later gaps.
+ *
+ * An outro requires an explicit endTime; metadata duration and offset do not affect insertion.
+ *
+ * @returns The input when unchanged, or a new lyric and lines array sharing existing nodes.
+ */
+export declare const insertInstrumentalLines: (lyric: runtime.Lyric, options?: InsertInstrumentalLinesOptions) => runtime.Lyric;
+
+export declare interface InsertInstrumentalLinesOptions {
+    /**
+     * Minimum gap duration in milliseconds, including an outro.
+     *
+     * @default 10000
+     */
+    minDuration?: number;
+    /**
+     * Minimum gap duration before the first vocal in milliseconds.
+     *
+     * @default 5000
+     */
+    minIntroDuration?: number;
+    /**
+     * Outro boundary in milliseconds, measured on the same timeline as line ranges.
+     * An omitted boundary leaves the outro unknown.
+     */
+    endTime?: number;
+}
+
+/**
+ * Inserts the spaces a source left out, so CJK text set against Latin letters, digits or punctuation reads evenly.
+ *
+ * A word-level line keeps every word's time and annotation: an inserted space becomes its own space word,
+ * and a word the rules split yields one word per character, all sharing the original range.
+ * A plain-text line and the annotation tracks are rewritten as whole strings.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const insertSpacesInLines: (lyric: runtime.Lyric, options?: InsertSpacesOptions) => runtime.Lyric;
+
+export declare interface InsertSpacesOptions {
+    /**
+     * Rules to apply; omitting the list applies all of them.
+     */
+    rules?: InsertSpacesRule[];
+    /**
+     * Rewrite the translation and romanization tracks too.
+     *
+     * @default true
+     */
+    annotations?: boolean;
+}
+
+export declare type InsertSpacesRule = (typeof InsertSpacesRules)[keyof typeof InsertSpacesRules];
+
+/**
+ * Groups of characters a source may write without a space where one belongs.
+ */
+export declare const InsertSpacesRules: {
+    /**
+     * A CJK character touching a Latin letter, as in `ABC中文`.
+     */
+    readonly CJK_ENGLISH: "cjkEnglish";
+    /**
+     * A CJK character touching a digit, as in `2026年`.
+     */
+    readonly CJK_NUMBER: "cjkNumber";
+    /**
+     * A comma, semicolon, exclamation mark, question mark or colon touching a character, as in `a,b`; a clock time or thousands separator such as `10:30` stays as written.
+     */
+    readonly PUNCTUATION: "punctuation";
+    /**
+     * A quotation mark touching a neighbouring character.
+     */
+    readonly QUOTE: "quote";
+    /**
+     * A bracket touching the character outside it.
+     */
+    readonly BRACKET_OUTSIDE: "bracketOutside";
+    /**
+     * A plus, equals or ampersand touching a character, as in `a+b`; a compound operator such as `a+=b` stays as written.
+     */
+    readonly MATH_OPERATOR: "mathOperator";
+    /**
+     * A hyphen touching a CJK character, as in `中-文`; a compound word such as `well-known` stays as written.
+     */
+    readonly HYPHEN: "hyphen";
+    /**
+     * A slash touching a character, as in `and/or`; a fraction such as `1/2` stays as written.
+     */
+    readonly SLASH: "slash";
+    /**
+     * Runs of two or more spaces, collapsed to one.
+     */
+    readonly COMPRESS_SPACES: "compressSpaces";
+    /**
+     * Spaces just inside a bracket or quotation mark, removed.
+     */
+    readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
+};
+
 declare interface LrcContent {
     original: string;
     translations?: string;
@@ -36,7 +191,7 @@ export declare type LyricFormat = 'lrc' | 'ttml';
 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.
+ * Empty timed rows become instrumental lines; source order and missing word times remain for model validation.
  *
  * Annotation tracks are read as lines too and attached by timestamp, and rows that match no line are dropped.
  *
@@ -60,6 +215,16 @@ export declare interface ParseResult {
  */
 export declare const parseTtml: (input: TtmlParseInput, options?: TtmlParseOptions) => ParseResult;
 
+/**
+ * Removes the brackets some sources wrap around background vocals.
+ *
+ * One layer is removed from each edge of every background line, leaving a nested pair as `(x)`.
+ * A line left with no content is dropped, since a background line must carry something.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const stripBackgroundBrackets: (lyric: runtime.Lyric) => runtime.Lyric;
+
 export declare type TtmlParseInput = string;
 
 export declare interface TtmlParseOptions {

package/dist/parser.js

@@ -1 +1,3 @@
-export { detectFormat, parse, parseLrc, parseTtml } from "./formats.js";
+import { detectFormat, parse, parseLrc, parseTtml } from "./formats.js";
+import { InsertSpacesRules, deriveWordEmphasis, extractBackgroundLines, insertInstrumentalLines, insertSpacesInLines, stripBackgroundBrackets } from "./transforms.js";
+export { InsertSpacesRules, deriveWordEmphasis, detectFormat, extractBackgroundLines, insertInstrumentalLines, insertSpacesInLines, parse, parseLrc, parseTtml, stripBackgroundBrackets };

package/dist/transforms.d.ts

@@ -1 +1,170 @@
-export {}
+import { runtime } from '@gondola-lyrics/model';
+
+/**
+ * Derives emphasis for normal words in lead and background vocals using complete, valid word ranges.
+ * The stored word duration must strictly exceed durationThreshold; metadata offset and duration have no effect.
+ *
+ * Source emphasis, including an explicit false, is preserved; derived emphasis is cleared when a word no longer qualifies.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ *
+ * @throws {RangeError} If durationThreshold is not a non-negative safe integer in milliseconds.
+ */
+export declare const deriveWordEmphasis: (lyric: runtime.Lyric, options?: DeriveWordEmphasisOptions) => runtime.Lyric;
+
+export declare interface DeriveWordEmphasisOptions {
+    /**
+     * Word duration must strictly exceed this threshold, expressed as a non-negative safe integer in milliseconds.
+     *
+     * @default 3000
+     */
+    durationThreshold?: number;
+}
+
+/**
+ * Pulls bracketed background vocals out of the sung lines and attaches them to the line they accompany.
+ *
+ * A line holding nothing but brackets becomes a background of the line before it and is removed.
+ * A bracket opened on one line and closed on a later one joins the line before the opening, and both source lines go.
+ * Text outside brackets stays on its line, and a line left with none keeps its place.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const extractBackgroundLines: (lyric: runtime.Lyric, options?: ExtractBackgroundLinesOptions) => runtime.Lyric;
+
+export declare interface ExtractBackgroundLinesOptions {
+    /**
+     * Turn a line holding nothing but brackets into a background line of the line before it.
+     *
+     * @default true
+     */
+    fullLine?: boolean;
+    /**
+     * Pull the bracketed runs inside a line out into background lines of that same line.
+     *
+     * @default true
+     */
+    inLine?: boolean;
+    /**
+     * Join a bracket opened on one line and closed on a later one, attaching it to the line before them.
+     *
+     * @default true
+     */
+    crossLine?: boolean;
+}
+
+export declare const INSERT_SPACES_RULES: InsertSpacesRule[];
+
+/**
+ * Inserts derived instrumental lines into uncovered gaps on the stored timeline, starting at zero.
+ * Existing lines and background vocals occupy their full ranges; an unknown end blocks later gaps.
+ *
+ * An outro requires an explicit endTime; metadata duration and offset do not affect insertion.
+ *
+ * @returns The input when unchanged, or a new lyric and lines array sharing existing nodes.
+ */
+export declare const insertInstrumentalLines: (lyric: runtime.Lyric, options?: InsertInstrumentalLinesOptions) => runtime.Lyric;
+
+export declare interface InsertInstrumentalLinesOptions {
+    /**
+     * Minimum gap duration in milliseconds, including an outro.
+     *
+     * @default 10000
+     */
+    minDuration?: number;
+    /**
+     * Minimum gap duration before the first vocal in milliseconds.
+     *
+     * @default 5000
+     */
+    minIntroDuration?: number;
+    /**
+     * Outro boundary in milliseconds, measured on the same timeline as line ranges.
+     * An omitted boundary leaves the outro unknown.
+     */
+    endTime?: number;
+}
+
+/**
+ * Inserts the spaces a source left out, so CJK text set against Latin letters, digits or punctuation reads evenly.
+ *
+ * A word-level line keeps every word's time and annotation: an inserted space becomes its own space word,
+ * and a word the rules split yields one word per character, all sharing the original range.
+ * A plain-text line and the annotation tracks are rewritten as whole strings.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const insertSpacesInLines: (lyric: runtime.Lyric, options?: InsertSpacesOptions) => runtime.Lyric;
+
+export declare interface InsertSpacesOptions {
+    /**
+     * Rules to apply; omitting the list applies all of them.
+     */
+    rules?: InsertSpacesRule[];
+    /**
+     * Rewrite the translation and romanization tracks too.
+     *
+     * @default true
+     */
+    annotations?: boolean;
+}
+
+export declare type InsertSpacesRule = (typeof InsertSpacesRules)[keyof typeof InsertSpacesRules];
+
+/**
+ * Groups of characters a source may write without a space where one belongs.
+ */
+export declare const InsertSpacesRules: {
+    /**
+     * A CJK character touching a Latin letter, as in `ABC中文`.
+     */
+    readonly CJK_ENGLISH: "cjkEnglish";
+    /**
+     * A CJK character touching a digit, as in `2026年`.
+     */
+    readonly CJK_NUMBER: "cjkNumber";
+    /**
+     * A comma, semicolon, exclamation mark, question mark or colon touching a character, as in `a,b`; a clock time or thousands separator such as `10:30` stays as written.
+     */
+    readonly PUNCTUATION: "punctuation";
+    /**
+     * A quotation mark touching a neighbouring character.
+     */
+    readonly QUOTE: "quote";
+    /**
+     * A bracket touching the character outside it.
+     */
+    readonly BRACKET_OUTSIDE: "bracketOutside";
+    /**
+     * A plus, equals or ampersand touching a character, as in `a+b`; a compound operator such as `a+=b` stays as written.
+     */
+    readonly MATH_OPERATOR: "mathOperator";
+    /**
+     * A hyphen touching a CJK character, as in `中-文`; a compound word such as `well-known` stays as written.
+     */
+    readonly HYPHEN: "hyphen";
+    /**
+     * A slash touching a character, as in `and/or`; a fraction such as `1/2` stays as written.
+     */
+    readonly SLASH: "slash";
+    /**
+     * Runs of two or more spaces, collapsed to one.
+     */
+    readonly COMPRESS_SPACES: "compressSpaces";
+    /**
+     * Spaces just inside a bracket or quotation mark, removed.
+     */
+    readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
+};
+
+/**
+ * Removes the brackets some sources wrap around background vocals.
+ *
+ * One layer is removed from each edge of every background line, leaving a nested pair as `(x)`.
+ * A line left with no content is dropped, since a background line must carry something.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const stripBackgroundBrackets: (lyric: runtime.Lyric) => runtime.Lyric;
+
+export { }