subcraft 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,228 @@
+/**
+ * Core normalized representation of a single subtitle cue.
+ * Timestamps are strictly stored in integer milliseconds.
+ */
+interface SubtitleCue {
+    /** Unique sequential identifier (e.g. "1", "2") */
+    id: string;
+    /** Start time in integer milliseconds */
+    start: number;
+    /** End time in integer milliseconds */
+    end: number;
+    /** Raw subtitle text content (may contain newlines) */
+    text: string;
+    /** Optional WebVTT cue placement/styling settings (e.g., "align:middle line:90%") */
+    settings?: string;
+}
+/**
+ * Calculates the duration of a cue in milliseconds.
+ * Derived helper function to keep the core data model minimal and immutable.
+ */
+declare const getCueDuration: (cue: SubtitleCue) => number;
+/** Supported subtitle file formats */
+type TimecodeFormat = 'srt' | 'vtt';
+/**
+ * Detailed error reported when a cue block fails parsing syntax rules.
+ */
+interface ParseError {
+    index?: number;
+    rawBlock: string;
+    message: string;
+}
+/**
+ * Resilient parser result returning successfully parsed cues
+ * alongside any syntax errors encountered without throwing.
+ */
+interface ParseResult {
+    cues: SubtitleCue[];
+    errors: ParseError[];
+}
+/** Severity levels for lint diagnostics */
+type LintSeverity = 'error' | 'warning';
+/** Quality rules enforced by the linter */
+type LintRule = 'out-of-order' | 'overlap' | 'zero-or-negative-duration' | 'min-duration' | 'max-duration' | 'max-cpl' | 'max-cps';
+/**
+ * Diagnostic report produced when a cue violates a quality rule.
+ */
+interface LintDiagnostic {
+    cueId: string;
+    rule: LintRule;
+    severity: LintSeverity;
+    message: string;
+    expected?: number | string;
+    actual?: number | string;
+}
+/**
+ * Configuration options for locale-aware subtitle validation.
+ */
+interface LintProfile {
+    name: string;
+    locale?: string;
+    maxCps: number;
+    maxCpl: number;
+    minDurationMs: number;
+    maxDurationMs: number;
+    includeSpaces?: boolean;
+}
+
+/**
+ * Converts a formatted timecode string into integer milliseconds.
+ *
+ * Supported formats:
+ * - "01:23:45,678" (SRT standard)
+ * - "01:23:45.678" (WebVTT standard)
+ * - "23:45.678"    (WebVTT short form without hours)
+ *
+ * @throws {Error} if timecode format is invalid
+ */
+declare function timecodeToMs(timecode: string): number;
+/**
+ * Converts integer milliseconds into a standard formatted timecode string.
+ *
+ * @param ms - Non-negative integer milliseconds (negative values clamped to 0)
+ * @param format - 'srt' (uses comma delimiter) or 'vtt' (uses dot delimiter)
+ *
+ * @example
+ * msToTimecode(83456, 'srt') // "00:01:23,456"
+ * msToTimecode(83456, 'vtt') // "00:01:23.456"
+ */
+declare function msToTimecode(ms: number, format?: TimecodeFormat): string;
+/**
+ * Linearly shifts timecodes by a constant millisecond offset.
+ * Used to correct audio-sync delay or advance.
+ * Clamps negative results to 0.
+ *
+ * @param cues - Array of SubtitleCue objects
+ * @param offsetMs - Offset in milliseconds (positive advances, negative delays)
+ * @returns A new immutable array of shifted cues
+ */
+declare function shiftTimecodes(cues: readonly SubtitleCue[], offsetMs: number): SubtitleCue[];
+/**
+ * Scales all cue timecodes by a multiplicative ratio.
+ * Used for frame-rate drift compensation between video standards.
+ * All results are strictly rounded to integer milliseconds with Math.round.
+ *
+ * Direction definition:
+ * targetTimestamp = Math.round(sourceTimestamp * ratio)
+ *
+ * @example
+ * // 24 fps to 25 fps (PAL speed-up): video is ~4% faster, timecodes compress
+ * const palCues = retime(filmCues, 24 / 25); // ratio = 0.96
+ *
+ * @example
+ * // 25 fps to 24 fps (Slow-down): video is ~4% slower, timecodes stretch
+ * const filmCues = retime(palCues, 25 / 24); // ratio = 1.04167
+ *
+ * @param cues - Array of SubtitleCue objects
+ * @param ratio - Positive scaling multiplier (e.g., 24/25 or 25/24)
+ * @returns A new immutable array of retimed cues
+ */
+declare function retime(cues: readonly SubtitleCue[], ratio: number): SubtitleCue[];
+
+/**
+ * Parses raw SRT subtitle text into structured SubtitleCue objects.
+ * Resilient parser that collects syntax errors without throwing unhandled exceptions.
+ *
+ * Handles:
+ * - UTF-8 Byte Order Marks (BOM `\uFEFF`)
+ * - Windows (CRLF), Unix (LF), and legacy Mac (CR) line endings
+ * - Optional or missing cue numeric index headers
+ * - Multi-line subtitle texts
+ * - Trailing and irregular blank lines
+ *
+ * @param rawText - Raw SRT file content as a string
+ * @returns {ParseResult} Object containing successfully parsed cues and any block errors
+ */
+declare function parseSRT(rawText: string): ParseResult;
+
+/**
+ * Serializes an array of SubtitleCue objects into standard SRT file format.
+ *
+ * Output format:
+ * 1
+ * 00:00:20,000 --> 00:00:24,000
+ * Subtitle text
+ *
+ * @param cues - Array of SubtitleCue objects to format
+ * @returns Standard formatted SRT string
+ */
+declare function stringifySRT(cues: readonly SubtitleCue[]): string;
+
+interface StringifyVTTOptions {
+    /** Optional custom header line after WEBVTT (e.g. "WEBVTT - Commentary Track") */
+    header?: string;
+    /** Whether to output cue numeric ID headers (default: false for standard clean WebVTT) */
+    includeIds?: boolean;
+}
+/**
+ * Parses raw WebVTT (.vtt) subtitle text into structured SubtitleCue objects.
+ *
+ * Handles:
+ * - UTF-8 Byte Order Marks (BOM \uFEFF)
+ * - WEBVTT header and metadata blocks
+ * - NOTE comment blocks (skipped automatically)
+ * - Dot-separated milliseconds (00:01:20.500) and comma-separated fallback
+ * - Short timecodes without hours (MM:SS.mmm)
+ * - Cue placement/styling settings (e.g. align:middle line:90%)
+ * - Optional cue identifiers
+ *
+ * @param rawText - Raw WebVTT file content as a string
+ * @returns {ParseResult} Successfully parsed cues and any block errors
+ */
+declare function parseVTT(rawText: string): ParseResult;
+/**
+ * Serializes an array of SubtitleCue objects into standard WebVTT (.vtt) file format.
+ *
+ * @param cues - Array of SubtitleCue objects to format
+ * @param options - Formatting options (header title, inclusion of cue IDs)
+ * @returns Formatted WebVTT string
+ */
+declare function stringifyVTT(cues: readonly SubtitleCue[], options?: StringifyVTTOptions): string;
+/**
+ * Converts raw SRT subtitle text directly into a valid WebVTT (.vtt) string.
+ *
+ * @param srtText - Raw SubRip (.srt) text content
+ * @param options - WebVTT formatting options
+ * @returns Formatted WebVTT string
+ */
+declare function srtToVTT(srtText: string, options?: StringifyVTTOptions): string;
+/**
+ * Converts raw WebVTT subtitle text directly into a standard SRT (.srt) string.
+ *
+ * @param vttText - Raw WebVTT (.vtt) text content
+ * @returns Standard SubRip (.srt) string
+ */
+declare function vttToSRT(vttText: string): string;
+
+/** Default quality profiles for subtitle verification */
+declare const DEFAULT_PROFILES: Record<string, LintProfile>;
+/**
+ * Strips HTML formatting tags from subtitle text before measuring character limits.
+ * Handles <i>, <b>, <u>, <font color="...">, etc.
+ */
+declare function stripFormattingTags(text: string): string;
+/**
+ * Counts user-perceived grapheme clusters using native ECMAScript Intl.Segmenter.
+ * Accurately measures multi-byte conjuncts and vowel modifiers in Indic scripts (Kannada, Hindi),
+ * as well as emojis and complex Unicode characters without UTF-16 code unit inflation.
+ */
+declare function countGraphemes(text: string, locale?: string): number;
+/**
+ * Inspects an array of SubtitleCues against timing, structural, and reading speed rules.
+ *
+ * Rules verified:
+ * - out-of-order: Cues not in ascending chronological order
+ * - zero-or-negative-duration: Cues where end <= start
+ * - overlap: Cues overlapping chronologically with preceding cues
+ * - min-duration: Cues flashing too fast for comprehension (< 800ms)
+ * - max-duration: Cues remaining on screen too long (> 7000ms)
+ * - max-cpl: Any line exceeding characters-per-line limit
+ * - max-cps: Reading speed exceeding characters-per-second limit
+ *
+ * @param cues - Array of SubtitleCue objects to inspect
+ * @param customProfile - Optional custom thresholds or language profile
+ * @returns Array of LintDiagnostic reports
+ */
+declare function lintCues(cues: readonly SubtitleCue[], customProfile?: Partial<LintProfile>): LintDiagnostic[];
+
+export { DEFAULT_PROFILES, type LintDiagnostic, type LintProfile, type LintRule, type LintSeverity, type ParseError, type ParseResult, type StringifyVTTOptions, type SubtitleCue, type TimecodeFormat, countGraphemes, getCueDuration, lintCues, msToTimecode, parseSRT, parseVTT, retime, shiftTimecodes, srtToVTT, stringifySRT, stringifyVTT, stripFormattingTags, timecodeToMs, vttToSRT };

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Core normalized representation of a single subtitle cue.
+ * Timestamps are strictly stored in integer milliseconds.
+ */
+interface SubtitleCue {
+    /** Unique sequential identifier (e.g. "1", "2") */
+    id: string;
+    /** Start time in integer milliseconds */
+    start: number;
+    /** End time in integer milliseconds */
+    end: number;
+    /** Raw subtitle text content (may contain newlines) */
+    text: string;
+    /** Optional WebVTT cue placement/styling settings (e.g., "align:middle line:90%") */
+    settings?: string;
+}
+/**
+ * Calculates the duration of a cue in milliseconds.
+ * Derived helper function to keep the core data model minimal and immutable.
+ */
+declare const getCueDuration: (cue: SubtitleCue) => number;
+/** Supported subtitle file formats */
+type TimecodeFormat = 'srt' | 'vtt';
+/**
+ * Detailed error reported when a cue block fails parsing syntax rules.
+ */
+interface ParseError {
+    index?: number;
+    rawBlock: string;
+    message: string;
+}
+/**
+ * Resilient parser result returning successfully parsed cues
+ * alongside any syntax errors encountered without throwing.
+ */
+interface ParseResult {
+    cues: SubtitleCue[];
+    errors: ParseError[];
+}
+/** Severity levels for lint diagnostics */
+type LintSeverity = 'error' | 'warning';
+/** Quality rules enforced by the linter */
+type LintRule = 'out-of-order' | 'overlap' | 'zero-or-negative-duration' | 'min-duration' | 'max-duration' | 'max-cpl' | 'max-cps';
+/**
+ * Diagnostic report produced when a cue violates a quality rule.
+ */
+interface LintDiagnostic {
+    cueId: string;
+    rule: LintRule;
+    severity: LintSeverity;
+    message: string;
+    expected?: number | string;
+    actual?: number | string;
+}
+/**
+ * Configuration options for locale-aware subtitle validation.
+ */
+interface LintProfile {
+    name: string;
+    locale?: string;
+    maxCps: number;
+    maxCpl: number;
+    minDurationMs: number;
+    maxDurationMs: number;
+    includeSpaces?: boolean;
+}
+
+/**
+ * Converts a formatted timecode string into integer milliseconds.
+ *
+ * Supported formats:
+ * - "01:23:45,678" (SRT standard)
+ * - "01:23:45.678" (WebVTT standard)
+ * - "23:45.678"    (WebVTT short form without hours)
+ *
+ * @throws {Error} if timecode format is invalid
+ */
+declare function timecodeToMs(timecode: string): number;
+/**
+ * Converts integer milliseconds into a standard formatted timecode string.
+ *
+ * @param ms - Non-negative integer milliseconds (negative values clamped to 0)
+ * @param format - 'srt' (uses comma delimiter) or 'vtt' (uses dot delimiter)
+ *
+ * @example
+ * msToTimecode(83456, 'srt') // "00:01:23,456"
+ * msToTimecode(83456, 'vtt') // "00:01:23.456"
+ */
+declare function msToTimecode(ms: number, format?: TimecodeFormat): string;
+/**
+ * Linearly shifts timecodes by a constant millisecond offset.
+ * Used to correct audio-sync delay or advance.
+ * Clamps negative results to 0.
+ *
+ * @param cues - Array of SubtitleCue objects
+ * @param offsetMs - Offset in milliseconds (positive advances, negative delays)
+ * @returns A new immutable array of shifted cues
+ */
+declare function shiftTimecodes(cues: readonly SubtitleCue[], offsetMs: number): SubtitleCue[];
+/**
+ * Scales all cue timecodes by a multiplicative ratio.
+ * Used for frame-rate drift compensation between video standards.
+ * All results are strictly rounded to integer milliseconds with Math.round.
+ *
+ * Direction definition:
+ * targetTimestamp = Math.round(sourceTimestamp * ratio)
+ *
+ * @example
+ * // 24 fps to 25 fps (PAL speed-up): video is ~4% faster, timecodes compress
+ * const palCues = retime(filmCues, 24 / 25); // ratio = 0.96
+ *
+ * @example
+ * // 25 fps to 24 fps (Slow-down): video is ~4% slower, timecodes stretch
+ * const filmCues = retime(palCues, 25 / 24); // ratio = 1.04167
+ *
+ * @param cues - Array of SubtitleCue objects
+ * @param ratio - Positive scaling multiplier (e.g., 24/25 or 25/24)
+ * @returns A new immutable array of retimed cues
+ */
+declare function retime(cues: readonly SubtitleCue[], ratio: number): SubtitleCue[];
+
+/**
+ * Parses raw SRT subtitle text into structured SubtitleCue objects.
+ * Resilient parser that collects syntax errors without throwing unhandled exceptions.
+ *
+ * Handles:
+ * - UTF-8 Byte Order Marks (BOM `\uFEFF`)
+ * - Windows (CRLF), Unix (LF), and legacy Mac (CR) line endings
+ * - Optional or missing cue numeric index headers
+ * - Multi-line subtitle texts
+ * - Trailing and irregular blank lines
+ *
+ * @param rawText - Raw SRT file content as a string
+ * @returns {ParseResult} Object containing successfully parsed cues and any block errors
+ */
+declare function parseSRT(rawText: string): ParseResult;
+
+/**
+ * Serializes an array of SubtitleCue objects into standard SRT file format.
+ *
+ * Output format:
+ * 1
+ * 00:00:20,000 --> 00:00:24,000
+ * Subtitle text
+ *
+ * @param cues - Array of SubtitleCue objects to format
+ * @returns Standard formatted SRT string
+ */
+declare function stringifySRT(cues: readonly SubtitleCue[]): string;
+
+interface StringifyVTTOptions {
+    /** Optional custom header line after WEBVTT (e.g. "WEBVTT - Commentary Track") */
+    header?: string;
+    /** Whether to output cue numeric ID headers (default: false for standard clean WebVTT) */
+    includeIds?: boolean;
+}
+/**
+ * Parses raw WebVTT (.vtt) subtitle text into structured SubtitleCue objects.
+ *
+ * Handles:
+ * - UTF-8 Byte Order Marks (BOM \uFEFF)
+ * - WEBVTT header and metadata blocks
+ * - NOTE comment blocks (skipped automatically)
+ * - Dot-separated milliseconds (00:01:20.500) and comma-separated fallback
+ * - Short timecodes without hours (MM:SS.mmm)
+ * - Cue placement/styling settings (e.g. align:middle line:90%)
+ * - Optional cue identifiers
+ *
+ * @param rawText - Raw WebVTT file content as a string
+ * @returns {ParseResult} Successfully parsed cues and any block errors
+ */
+declare function parseVTT(rawText: string): ParseResult;
+/**
+ * Serializes an array of SubtitleCue objects into standard WebVTT (.vtt) file format.
+ *
+ * @param cues - Array of SubtitleCue objects to format
+ * @param options - Formatting options (header title, inclusion of cue IDs)
+ * @returns Formatted WebVTT string
+ */
+declare function stringifyVTT(cues: readonly SubtitleCue[], options?: StringifyVTTOptions): string;
+/**
+ * Converts raw SRT subtitle text directly into a valid WebVTT (.vtt) string.
+ *
+ * @param srtText - Raw SubRip (.srt) text content
+ * @param options - WebVTT formatting options
+ * @returns Formatted WebVTT string
+ */
+declare function srtToVTT(srtText: string, options?: StringifyVTTOptions): string;
+/**
+ * Converts raw WebVTT subtitle text directly into a standard SRT (.srt) string.
+ *
+ * @param vttText - Raw WebVTT (.vtt) text content
+ * @returns Standard SubRip (.srt) string
+ */
+declare function vttToSRT(vttText: string): string;
+
+/** Default quality profiles for subtitle verification */
+declare const DEFAULT_PROFILES: Record<string, LintProfile>;
+/**
+ * Strips HTML formatting tags from subtitle text before measuring character limits.
+ * Handles <i>, <b>, <u>, <font color="...">, etc.
+ */
+declare function stripFormattingTags(text: string): string;
+/**
+ * Counts user-perceived grapheme clusters using native ECMAScript Intl.Segmenter.
+ * Accurately measures multi-byte conjuncts and vowel modifiers in Indic scripts (Kannada, Hindi),
+ * as well as emojis and complex Unicode characters without UTF-16 code unit inflation.
+ */
+declare function countGraphemes(text: string, locale?: string): number;
+/**
+ * Inspects an array of SubtitleCues against timing, structural, and reading speed rules.
+ *
+ * Rules verified:
+ * - out-of-order: Cues not in ascending chronological order
+ * - zero-or-negative-duration: Cues where end <= start
+ * - overlap: Cues overlapping chronologically with preceding cues
+ * - min-duration: Cues flashing too fast for comprehension (< 800ms)
+ * - max-duration: Cues remaining on screen too long (> 7000ms)
+ * - max-cpl: Any line exceeding characters-per-line limit
+ * - max-cps: Reading speed exceeding characters-per-second limit
+ *
+ * @param cues - Array of SubtitleCue objects to inspect
+ * @param customProfile - Optional custom thresholds or language profile
+ * @returns Array of LintDiagnostic reports
+ */
+declare function lintCues(cues: readonly SubtitleCue[], customProfile?: Partial<LintProfile>): LintDiagnostic[];
+
+export { DEFAULT_PROFILES, type LintDiagnostic, type LintProfile, type LintRule, type LintSeverity, type ParseError, type ParseResult, type StringifyVTTOptions, type SubtitleCue, type TimecodeFormat, countGraphemes, getCueDuration, lintCues, msToTimecode, parseSRT, parseVTT, retime, shiftTimecodes, srtToVTT, stringifySRT, stringifyVTT, stripFormattingTags, timecodeToMs, vttToSRT };