@lp-labs/subtitle-timing
v1.0.0
Published
Subtitle cue shift, scale, split, clip, overlap and interval operations on millisecond times.
Readme
@lp-labs/subtitle-timing
Shifts, scales, splits, clips and de-overlaps subtitle cues expressed as integer millisecond intervals. It does not parse or write SRT/VTT. Catalog identity 489; standalone package version 1.0.0. No runtime, peer, or sibling dependencies. Node >=18, ESM and CommonJS with declarations.
Install
npm install @lp-labs/subtitle-timingQuickstart (runnable JavaScript)
import assert from 'node:assert/strict';
import {
mergeIntervals,
resolveOverlaps,
scaleCues,
shiftCues,
splitCue,
} from '@lp-labs/subtitle-timing';
const cues = [
{ id: 'a', startMs: 1000, endMs: 3000, text: 'Hello' },
{ id: 'b', startMs: 2500, endMs: 4000, text: 'World' },
];
assert.deepEqual(
shiftCues(cues, -1000, { negative: 'error' }).map((c) => c.startMs),
[0, 1500],
);
assert.deepEqual(
scaleCues(cues, 2).map((c) => c.endMs),
[6000, 8000],
);
assert.deepEqual(
resolveOverlaps(cues, 'trim-previous').map((c) => [c.startMs, c.endMs]),
[
[1000, 2500],
[2500, 4000],
],
);
assert.deepEqual(
splitCue(cues[0], [2000]).map((c) => c.id),
['a#1', 'a#2'],
);
assert.deepEqual(mergeIntervals(cues), [{ startMs: 1000, endMs: 4000 }]);Configuration and errors
A Cue is { id?: string, startMs, endMs, text } with integer milliseconds, startMs >= 0 and endMs > startMs (half-open intervals). All functions return new cue objects and never mutate input.
shiftCues(cues, deltaMs, { negative })andscaleCues(cues, factor, { anchorMs, rounding, negative })(timetbecomesanchor + (t - anchor) * factor, rounded withround(default),floororceil). Negative-time policy for a cue that would start before 0:error(default, RangeError),clip(start moves to 0; cues that end at or before 0 are removed) ordrop(any such cue is removed). A scaled cue that collapses to zero length is a RangeError.splitCue(cue, atMs, texts?): strictly increasing interior times; pieces keep the text unless one string per piece is given; ids becomeid#1,id#2...clipCues(cues, windowStartMs, windowEndMs, { rebase }): intersect with a window, optionally subtracting the window start.sortCues,findOverlaps(cues, { maxPairs })(positive-duration overlaps only, indices into the input, touching cues do not overlap),mergeIntervals(union; touching intervals merge) andresolveOverlaps(cues, 'trim-previous' | 'push-next').maxCues(default 100000) andmaxPairs(default 100000) are budgets.
Errors: TypeError for wrong container types, missing text/non-string ids or unknown policies; RangeError for non-integer or out-of-range times, results beyond safe integers, collapsed or invalid ranges and exceeded budgets.
Complete public declarations
Every runtime export and public type is shown below. This is the complete emitted declaration surface.
export interface Cue {
id?: string;
startMs: number;
endMs: number;
text: string;
}
export type NegativePolicy = 'error' | 'clip' | 'drop';
export type TimeRounding = 'round' | 'floor' | 'ceil';
export type OverlapPolicy = 'trim-previous' | 'push-next';
export interface ShiftOptions {
negative?: NegativePolicy;
}
export interface ScaleOptions extends ShiftOptions {
anchorMs?: number;
rounding?: TimeRounding;
}
export interface Interval {
startMs: number;
endMs: number;
}
export interface Overlap extends Interval {
first: number;
second: number;
}
export interface LimitOptions {
maxCues?: number;
}
export interface OverlapSearchOptions extends LimitOptions {
maxPairs?: number;
}
export interface ClipOptions extends LimitOptions {
rebase?: boolean;
}
export declare const DEFAULT_MAX_CUES = 100000;
export declare const DEFAULT_MAX_PAIRS = 100000;
export declare function shiftCues(
cues: readonly Cue[],
deltaMs: number,
options?: ShiftOptions,
): Cue[];
export declare function scaleCues(
cues: readonly Cue[],
factor: number,
options?: ScaleOptions,
): Cue[];
export declare function splitCue(
cue: Cue,
atMs: readonly number[],
texts?: readonly string[],
): Cue[];
export declare function clipCues(
cues: readonly Cue[],
windowStartMs: number,
windowEndMs: number,
options?: ClipOptions,
): Cue[];
export declare function sortCues(cues: readonly Cue[]): Cue[];
export declare function findOverlaps(
cues: readonly Cue[],
options?: OverlapSearchOptions,
): Overlap[];
export declare function resolveOverlaps(cues: readonly Cue[], overlapPolicy: OverlapPolicy): Cue[];
export declare function mergeIntervals(cues: readonly Cue[], options?: LimitOptions): Interval[];Performance, boundaries and limitations
Only times are manipulated: there is no SRT/VTT/ASS parsing or serialisation, no text re-wrapping, reading-speed or frame-rate logic. Splitting never guesses where text should break. resolveOverlaps sorts by start, end then original order and compares each cue only with the most recently kept cue: trim-previous shortens that cue (removing it if nothing remains) and push-next delays the new cue to its end (removing it if nothing remains), so some text time can be lost by design. Rounding is applied independently to start and end. Overlap discovery is O(n log n + pairs); every other operation is O(n log n) at most. Times are limited to safe integers.
Development
npm ci --offline
npm run build
npm run typecheck
npm test
npm run format:checkThe offline install requires the locked development dependencies already in the npm cache. Build emits separate ESM/CJS and declarations; type checks include bare-package .mts/.cts consumers with negative cases. Runtime tests import only the single-quoted standalone dist entry and also run against installed offline tarballs. No build artifacts or development dependencies are required at runtime.
Support
If this library is useful to you, consider supporting its maintenance with a donation via PayPal.
Author
Created by Libin Prasanth. Connect on LinkedIn for updates and discussion.
