@gondola-lyrics/kit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 folltoshe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# Gondola Lyric Kit For Node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Gondola lyrics toolkit: parses and generates lyric.
+
+## Installation
+
+```bash
+npm install @gondola-lyrics/kit
+```
+
+## Supports
+
+| Format | Parse | Generate | Annotation tracks | Notes                                                                |
+| ------ | ----- | -------- | ----------------- | -------------------------------------------------------------------- |
+| LRC    | ✅    | ✅       | ✅                | Line and enhanced word timing, metadata, translations, romanizations |
+
+## Usage
+
+> [!IMPORTANT]
+> This package is ESM-only.
+> In your TS config, use `module: node20` / `module: nodenext` / `moduleResolution: bundler`.
+
+Parsing returns a canonical `runtime.Lyric` together with the diagnostics it produced, so the result is ready to hand to a player without a second conversion step.
+
+### Parse
+
+```ts
+import { parse, parseLrc } from '@gondola-lyrics/kit'
+
+const content = `[00:01.00]Like the first time tangled by the fishing line`
+const parsed = parse(content)
+
+parsed?.lyric.format // => 'lrc'
+parsed?.lyric.lines[0]?.time?.start // => 1000
+parsed?.diagnostics // => []
+
+// `parse` recognizes the format and returns `null` when it cannot.
+// `parseLrc` takes a known format and never returns `null`, so an unreadable source only carries `status: INVALID`.
+parseLrc('no timestamps here').lyric.status // => LyricStatus.INVALID
+
+// LRC keeps translations and romanizations in separate files, attached here by timestamp.
+const annotated = parseLrc({
+  original: `[00:01.00]Like the first time
+[00:03.00]tangled by the line`,
+  translations: `[00:01.00]就像第一次
+[00:03.00]被渔线缠住那样`,
+  romans: `[00:01.00]raiku za fasuto taimu
+[00:03.00]tanguru do bai za rain`,
+})
+
+annotated.lyric.lines[0]?.annotation?.translations[0].text // => '就像第一次'
+annotated.lyric.lines[0]?.annotation?.romans[0].text // => 'raiku za fasuto taimu'
+
+// An exact timestamp match is assigned before any fuzzy one, and rows matching no line are dropped.
+// A drifting track attaches within a tolerance, where the nearest unclaimed line wins.
+const drifted = {
+  original: `[00:01.00]Like the first time
+[00:03.00]tangled by the line`,
+  translations: `[00:01.30]就像第一次
+[00:03.20]被渔线缠住那样`,
+}
+
+parseLrc(drifted).lyric.lines[0]?.annotation // => undefined
+parseLrc(drifted, { annotationTolerance: 500 }).lyric.lines[0]?.annotation?.translations[0].text // => '就像第一次'
+```
+
+Every parser canonicalizes its lyric and validates the result before returning, so `lyric` is already in canonical order and `diagnostics` is exactly what `@gondola-lyrics/model` reports for it.
+
+### Generate
+
+`generate` takes the target format explicitly, so a lyric parsed from one format can be written out as another.
+
+```ts
+import { generate, parseLrc } from '@gondola-lyrics/kit'
+
+const { lyric } = parseLrc('[00:01.00]Like the first time')
+
+// Separate tracks come back as separate fields, so the result parses again unchanged.
+const { original, translations, romans } = generate(lyric, 'lrc')
+
+parseLrc(generate(lyric, 'lrc')) // round-trips
+```
+
+`generateLrc` is the same thing without the dispatch step.
+
+### Detect
+
+```ts
+import { detectFormat } from '@gondola-lyrics/kit'
+
+detectFormat('[00:01.00]Like the first time') // => 'lrc'
+detectFormat('plain text without timestamps') // => undefined
+```
+
+Detection reads only the original text. It answers whether the source is recognizable, not whether it is valid: a recognized source can still parse into an `INVALID` lyric.
+
+### Validation
+
+The kit does not invent diagnostics. It canonicalizes the lyric and hands back exactly what `@gondola-lyrics/model` reports for it.
+
+```ts
+const { lyric, diagnostics } = parseLrc(source)
+
+// The same list, computed by the kit on the way out.
+import { validateLyric } from '@gondola-lyrics/model/runtime'
+
+validateLyric(lyric) // deep-equals `diagnostics`
+```
+
+### Entries
+
+| Import                          | Contains   |
+| ------------------------------- | ---------- |
+| `@gondola-lyrics/kit`           | Everything |
+| `@gondola-lyrics/kit/parser`    | Parsing    |
+| `@gondola-lyrics/kit/generator` | Generation |
+
+## Commands
+
+**Build**
+
+```bash
+npm run build
+```
+
+**Check**
+
+```bash
+npm run check
+npm run format
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/formats.d.ts

@@ -0,0 +1,133 @@
+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;
+
+/**
+ * A single readable time tag is enough for recognition; metadata alone is not.
+ * This is a format probe, not a validity check, so an input of another shape is simply not LRC.
+ */
+export declare const detectLrc: (input: unknown) => boolean;
+
+/**
+ * Recognition needs a profile hint, since plain TTML says nothing about which profile wrote it.
+ *
+ * A bare `tt` root also counts, which is what a hand-written document has.
+ * This is a format probe, not a validity check, so an input of another shape is simply not TTML.
+ */
+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.
+ */
+export declare const generate: (lyric: runtime.Lyric, target: LyricFormat, options?: LrcGenerateOptions) => LrcGenerateResult;
+
+/**
+ * Generates the LRC text plus the annotations a single file cannot hold.
+ *
+ * Word tags appear only for a word-timed lyric when `wordTiming` is not `none`; otherwise every line stays whole.
+ */
+export declare const generateLrc: (lyric: runtime.Lyric, options?: LrcGenerateOptions) => LrcGenerateResult;
+
+export declare const ITUNES_HINT_PATTERN: RegExp;
+
+declare interface LrcContent {
+    original: string;
+    translations?: string;
+    romans?: string;
+}
+
+export declare interface LrcGenerateOptions {
+    /**
+     * Word-level timestamp style; defaults to `angle`.
+     *
+     * `angle` is the enhanced LRC form and round-trips through this parser.
+     *
+     * `bracket` matches line timestamps, so this parser reads it as new lines rather than words.
+     */
+    wordTiming?: 'angle' | 'bracket' | 'none';
+    /** Clock format for every timestamp; defaults to `mm:ss.SSS`. */
+    timeFormat?: string;
+    /** Emit the metadata header; defaults to `true`. */
+    includeMeta?: boolean;
+    /** Append the word duration to its tag, as in `<00:01.00,500>`. */
+    includeWordEnd?: boolean;
+    /** Emit instrumental lines as a timestamp with no text; defaults to `true`. */
+    includeInstrumental?: boolean;
+}
+
+export declare type LrcGenerateResult = LrcContent;
+
+export declare type LrcParseInput = LrcContent;
+
+export declare interface LrcParseOptions {
+    /**
+     * How far an annotation's timestamp may sit from a line's start, in milliseconds.
+     * Defaults to `0`, which requires an exact match.
+     */
+    annotationTolerance?: number;
+}
+
+/**
+ * Values match the lowercase format names stored in `Lyric.format`.
+ */
+export declare type LyricFormat = 'lrc' | 'ttml';
+
+/**
+ * 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 & 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; 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 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: string | TtmlContent, options?: TtmlParseOptions) => ParseResult;
+
+export declare const readTtmlContent: (input: unknown) => TtmlContent | null;
+
+export declare const readTtmlProfile: (source: string) => TtmlProfile;
+
+export declare interface TtmlContent {
+    original: 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 { }