A TypeScript library for converting AssemblyAI transcripts to ASS subtitle files with multiple display strategies (full utterance, word-by-word, karaoke, word highlight) and natural sentence splitting
npm install sfl-subtitles-helperbash
npm install sfl-subtitles-helper
`
Quick Start
`typescript
import { SubtitlesHelper, SUBTITLE_STRATEGY } from 'sfl-subtitles-helper';
import { TranscriptSentence } from 'assemblyai';
// Your AssemblyAI transcript sentences
const sentences: TranscriptSentence[] = [/ ... /];
// Convert to ASS format
const assObject = SubtitlesHelper.transcriptToAssJSON(
sentences,
SUBTITLE_STRATEGY.FULL_UTTERANCE,
defaultStyle,
1920, // xRes
1080, // yRes
'My Video', // videoName (optional)
{ maxWords: 7 } // strategyOptions (optional)
);
// Convert to ASS string
const assString = SubtitlesHelper.stringify(assObject);
`
Subtitle Strategies
$3
Displays complete sentences as subtitles with natural break points.
`typescript
SubtitlesHelper.transcriptToAssJSON(
sentences,
SUBTITLE_STRATEGY.FULL_UTTERANCE,
styles,
1920,
1080,
undefined,
{ maxWords: 7 } // Splits at natural breaks (punctuation, pauses)
);
`
$3
Creates a subtitle event for each individual word.
`typescript
SubtitlesHelper.transcriptToAssJSON(
sentences,
SUBTITLE_STRATEGY.WORD_BY_WORD,
styles,
1920,
1080
);
`
$3
Applies karaoke-style timing effects to words as they're spoken.
`typescript
SubtitlesHelper.transcriptToAssJSON(
sentences,
SUBTITLE_STRATEGY.KARAOKE,
styles,
1920,
1080
);
`
$3
Highlights each word sequentially as it's spoken.
`typescript
SubtitlesHelper.transcriptToAssJSON(
sentences,
SUBTITLE_STRATEGY.WORD_HIGHLIGHT,
styles,
1920,
1080
);
`
Natural Sentence Splitting
The library intelligently splits long sentences at natural break points:
- Punctuation breaks: Periods, commas, semicolons, colons
- Timing gaps: Detects pauses between words (>200ms)
- Respects maxWords: Always honors the maximum word limit while preferring natural boundaries
`typescript
// Example: With maxWords: 7
// "Hello, world! This is a test sentence."
// Splits at: "Hello, world!" (2 words) and "This is a test sentence." (5 words)
// Instead of: "Hello, world! This is a" (7 words) and "test sentence." (2 words)
`
Bidirectional Text Support
Full support for RTL (Right-to-Left) languages like Hebrew and Arabic, with automatic text reordering and punctuation handling.
API Reference
$3
Converts AssemblyAI transcript sentences to an ASS JSON object.
Parameters:
- sentences: TranscriptSentence[] - Array of sentences from AssemblyAI
- strategyToPlay: SUBTITLE_STRATEGY - The subtitle display strategy
- styles: ISubtitleStyle | ISubtitleStyle[] - Subtitle style(s)
- xRes: number - Video horizontal resolution
- yRes: number - Video vertical resolution
- videoName?: string - Optional video name
- strategyOptions?: IStrategyOptions - Optional strategy configuration
- maxWords?: number - Maximum words per subtitle (default: 7)
Returns: ParsedASS object
$3
Converts an ASS object to ASS file format string.
Parameters:
- assObject: ParsedASS - The parsed ASS object
Returns: string - ASS file content
Strategy Options
$3
`typescript
interface IStrategyOptions {
maxWords?: number; // Maximum words per subtitle segment (default: 7)
}
`
The maxWords option controls how sentences are split:
- Splits at natural break points (punctuation, pauses) when possible
- Falls back to word-count splitting if no natural breaks found
- Always respects the maximum word limit
Dependencies
- assemblyai - For TranscriptSentence type
- ass-compiler - For ASS file format handling
- bidi-js - For bidirectional text processing
Development
`bash
Install dependencies
npm install
Build
npm run build
Test
npm test
Watch mode
npm run build:watch
``