@gondola-lyrics/kit 0.4.0 → 0.5.0

package/dist/transforms.d.ts

@@ -1,5 +1,7 @@
 import { runtime } from '@gondola-lyrics/model';
 
+export declare const DEFAULT_CREDIT_NAME_SEPARATORS: readonly ["+", "：", "/"];
+
 /**
  * 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.
@@ -21,6 +23,32 @@ export declare interface DeriveWordEmphasisOptions {
     durationThreshold?: number;
 }
 
+/**
+ * Extracts colon-prefixed performers and carries them across nonempty normal lines, replacing their existing agent lists.
+ * Missing bindings enables legacy name inference; supplied bindings accept exact prefixes and reset propagation on unmatched prefixes.
+ * Removing prefixes preserves retained line and word times, but drops prefix-only lines with their attached content.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ *
+ * @throws {TypeError} If bindings reference an agent id absent from lyric.agents.
+ */
+export declare const extractAgents: (lyric: runtime.Lyric, options?: ExtractAgentsOptions) => runtime.Lyric;
+
+export declare interface ExtractAgentsOptions {
+    /**
+     * Maps complete, trimmed prefixes to existing agent ids, preserving array order for joint performers.
+     * Matching is case-sensitive and preserves internal whitespace; an empty object disables automatic inference.
+     * Omitting this option enables legacy name inference; explicit bindings override its clock exclusion.
+     */
+    bindings?: Readonly<Record<string, string | readonly string[]>>;
+    /**
+     * Removes matched prefixes and drops lines left with no sung text, including their attached content.
+     *
+     * @default true
+     */
+    removePrefixes?: boolean;
+}
+
 /**
  * Pulls bracketed background vocals out of the sung lines and attaches them to the line they accompany.
  *
@@ -53,6 +81,33 @@ export declare interface ExtractBackgroundLinesOptions {
     crossLine?: boolean;
 }
 
+/**
+ * Preserves source labels and name spelling while matching normalized credit labels in normal lead lines.
+ * Merges names by role and original label without inferring their language.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const extractCredits: (lyric: runtime.Lyric, options?: ExtractCreditsOptions) => runtime.Lyric;
+
+export declare interface ExtractCreditsOptions {
+    /**
+     * Removes extracted source lines unless they carry background vocals, line annotations, or word translations or romanizations.
+     * Ruby annotations alone do not prevent removal.
+     *
+     * Refreshes language usages and falls back to line timing when no word-level content remains.
+     *
+     * @default false
+     */
+    removeSourceLines?: boolean;
+    /**
+     * Splits names at literal separators and ignores empty strings; an empty list preserves the complete source name.
+     * Longer separators take precedence so overlapping delimiters remain predictable.
+     *
+     * @default DEFAULT_CREDIT_NAME_SEPARATORS
+     */
+    nameSeparators?: readonly string[];
+}
+
 export declare const INSERT_SPACES_RULES: InsertSpacesRule[];
 
 /**
@@ -157,6 +212,38 @@ export declare const InsertSpacesRules: {
     readonly TRIM_INSIDE_SYMBOLS: "trimInsideSymbols";
 };
 
+/**
+ * Categories the bundled filter rules identify, in rule order.
+ */
+export declare const NON_LYRIC_CATEGORIES: readonly string[];
+
+/**
+ * Removes normal lead lines matched by the shared notice rules and, when musicInfo is provided, first-line song information.
+ * The first non-empty normal line must have one literal " - " separator and a known title and artist on opposite sides; either order and extra text such as bracketed aliases are accepted.
+ * Drops attached annotations and backgrounds, refreshes language usages, and falls back to line timing when no word-level content remains.
+ *
+ * @returns The input when unchanged, or a new lyric sharing all unchanged nodes.
+ */
+export declare const removeNonLyricLines: (lyric: runtime.Lyric, options?: RemoveNonLyricLinesOptions) => runtime.Lyric;
+
+export declare interface RemoveNonLyricLinesOptions {
+    /**
+     * Removes lines identified under these categories; an empty list skips the shared rules.
+     * First-line music information is selected independently.
+     *
+     * @default NON_LYRIC_CATEGORIES
+     */
+    categories?: readonly string[];
+    /**
+     * Enables first-line music-information matching using these known titles and artists.
+     * Omitting this option, or leaving either list empty, skips the check; lyric metadata is not inferred.
+     */
+    musicInfo?: {
+        titles?: readonly string[];
+        artists?: readonly string[];
+    };
+}
+
 /**
  * Removes the brackets some sources wrap around background vocals.
  *