@spark-apps/video-kit

Pure, dependency-free logic shared by the Spark video tools: VidLet (local MCP server), ViralCat (Vercel app) and QuickPeek (local CLI).

What this is, and what it deliberately is not

This package holds the logic where the three apps disagreeing would be a bug: a title that grades A in one tool and B in another, a domain pronounced two different ways, audio mastered to two different loudness targets.

It is not a video engine. The apps keep their own ffmpeg pipelines, because they genuinely need different things: one sidechain-ducks, one time-gates the music volume, one does not duck at all; one runs on a 16-core desktop with no time limit, one inside a serverless function. Merging those would produce a package that three apps have to negotiate over, which costs more than the duplication it removes.

Every export is pure. No filesystem, no network, no process spawning, no environment reads. That is what makes it safe to import from a serverless function, a CLI and a browser bundle alike, and it is the line that stops this package growing into an engine.

Modules

| Module | Contents | |---|---| | title | YouTube title virality scoring, 0-100 with a letter grade | | spoken | Written text to TTS-pronounceable text (URLs, emails, TLDs) | | voices | Edge TTS voice tables and language resolution | | ass | ASS subtitle format: timing, colour, layout maths, word packing | | hashtags | Tag blacklist, normalisation, view-count formatting | | segments | Time-span merge and inversion | | ffmpeg | Loudness constants and the scale/crop/pad idiom | | paths | Windows to WSL path conversion |

Two decisions worth knowing about

Two voice tables ship, not one. MULTILINGUAL_VOICES covers 14 languages with the newer Multilingual neural voices (en-US); WIDE_VOICES covers 68 languages with standard voices (en-GB). They disagree on en, fr, de and zh. Those are preferences, not quality rankings, so each app picks rather than one being silently promoted.

Two word packers ship, not one. chunkWordsToLines packs to a measured character budget (what a Short needs, so a URL never splits); chunkWordsByCount packs a fixed number of words per cue. Switching a tool from one to the other re-flows every caption it has ever produced, so that is a deliberate change, not a side effect of sharing code.

Install

npm install @spark-apps/video-kit

Ships dual ESM + CJS with types for both. CJS is not optional: QuickPeek's CLI bundle is CommonJS on moduleResolution: NodeNext.

Develop

npm test