This document provides comprehensive documentation for the Lilith Media Service Transcript Management API, including storage, search, format conversion, and word-level timing operations.
Overview#
The Transcript Management API provides:
- Transcript Storage: CRUD operations for transcripts with locale support
- Word-Level Timestamps: Precise word timing with speaker diarization
- Full-Text Search: Segment and word search with fuzzy matching
- Format Conversion: SRT, VTT, and plain text import/export
- Timing Utilities: Segment merging, splitting, and timestamp manipulation
Table of Contents#
- Transcript Types
- CRUD Operations
- Locale Management
- Status Management
- Format Conversion
- Word-Level Timestamps
- Transcript Search
- Segment Utilities
- Error Codes
- SDK Integration
Transcript Types#
Transcript Entity#
typescript
interface Transcript {
id: string;
assetId: string;
locale: string; // e.g., 'en', 'es', 'ja'
isPrimary: boolean; // Primary transcript for asset
type: TranscriptType;
plainText: string | null; // Full transcript as plain text
timedText: TimedTextSegment[]; // Timed segments
vtt: string | null; // WebVTT format
srt: string | null; // SubRip format
wordTimings: WordTiming[]; // Word-level timestamps
hasSpeakers: boolean; // Has speaker diarization
speakers: SpeakerInfo[]; // Speaker metadata
speakerSegments: TimedTextSegment[]; // Speaker-attributed segments
confidenceScore: number | null; // 0-1 transcription confidence
wordCount: number | null;
segmentCount: number | null;
transcriptionService: string | null; // e.g., 'whisper', 'deepgram'
modelVersion: string | null;
processingParams: Record<string, unknown>;
processingTimeMs: number | null;
status: TranscriptStatus;
errorMessage: string | null;
isReviewed: boolean;
reviewedBy: string | null;
reviewedAt: Date | null;
createdAt: Date;
updatedAt: Date;
}
Transcript Type#
typescript
type TranscriptType =
| 'auto_generated' // Machine-generated (ASR)
| 'professional' // Human transcription service
| 'user_provided' // Uploaded by user
| 'edited'; // Edited/corrected transcript
Transcript Status#
typescript
type TranscriptStatus =
| 'pending' // Awaiting processing
| 'processing' // Currently being transcribed
| 'ready' // Available for use
| 'failed' // Transcription failed
| 'archived'; // Archived/deprecated
Timed Text Segment#
typescript
interface TimedTextSegment {
id: string;
startTime: number; // Milliseconds
endTime: number; // Milliseconds
text: string;
speakerId?: string; // For speaker diarization
confidence?: number; // 0-1 segment confidence
}
Word Timing#
typescript
interface WordTiming {
word: string;
startTime: number; // Milliseconds
endTime: number; // Milliseconds
confidence?: number; // 0-1 word confidence
speakerId?: string;
}
Speaker Info#
typescript
interface SpeakerInfo {
id: string; // Unique speaker identifier
name?: string; // Display name
label?: string; // Label (e.g., "Speaker 1")
}
CRUD Operations#
Create Transcript#
typescript
interface CreateTranscriptInput {
assetId: string; // Required
locale?: string; // Default: 'en'
isPrimary?: boolean; // Default: false
type?: TranscriptType; // Default: 'auto_generated'
plainText?: string | null;
timedText?: TimedTextSegment[];
vtt?: string | null;
srt?: string | null;
wordTimings?: WordTiming[];
hasSpeakers?: boolean;
speakers?: SpeakerInfo[];
speakerSegments?: TimedTextSegment[];
confidenceScore?: number | null;
wordCount?: number | null;
segmentCount?: number | null;
transcriptionService?: string | null;
modelVersion?: string | null;
processingParams?: Record<string, unknown>;
processingTimeMs?: number | null;
status?: TranscriptStatus; // Default: 'pending'
}
Example:
typescript
const transcript = await transcriptRepository.create({
assetId: 'asset_123',
locale: 'en',
isPrimary: true,
type: 'auto_generated',
transcriptionService: 'whisper',
modelVersion: 'large-v3',
status: 'pending',
});
Get Transcript by ID#
typescript
const transcript = await transcriptRepository.findById('transcript_456');
Get Transcripts by Asset#
typescript
// Get all transcripts for an asset (sorted by primary first, then locale)
const transcripts = await transcriptRepository.findByAssetId('asset_123');
Get Transcript by Asset and Locale#
typescript
const transcript = await transcriptRepository.findByAssetIdAndLocale(
'asset_123',
'en'
);
Update Transcript#
typescript
interface UpdateTranscriptInput {
isPrimary?: boolean;
plainText?: string | null;
timedText?: TimedTextSegment[];
vtt?: string | null;
srt?: string | null;
wordTimings?: WordTiming[];
hasSpeakers?: boolean;
speakers?: SpeakerInfo[];
speakerSegments?: TimedTextSegment[];
confidenceScore?: number | null;
wordCount?: number | null;
segmentCount?: number | null;
status?: TranscriptStatus;
errorMessage?: string | null;
isReviewed?: boolean;
reviewedBy?: string | null;
reviewedAt?: Date | null;
}
Example:
typescript
const updated = await transcriptRepository.update('transcript_456', {
timedText: segments,
wordTimings: words,
status: 'ready',
confidenceScore: 0.95,
});
Delete Transcript#
typescript
const deleted = await transcriptRepository.delete('transcript_456');
// Returns: boolean
Delete All Transcripts for Asset#
typescript
const count = await transcriptRepository.deleteByAssetId('asset_123');
// Returns: number of deleted transcripts
List Transcripts with Pagination#
typescript
const result = await transcriptRepository.list({
page: 1,
limit: 20,
});
// Returns:
interface PaginatedResult<Transcript> {
data: Transcript[];
total: number;
page: number;
limit: number;
totalPages: number;
hasMore: boolean;
}
Locale Management#
Get Primary Transcript#
typescript
const primary = await transcriptRepository.getPrimaryTranscript('asset_123');
Set Primary Transcript#
typescript
// Atomically sets one transcript as primary, clears flag on others
await transcriptRepository.setPrimaryTranscript('asset_123', 'transcript_456');
Get Available Locales#
typescript
const locales = await transcriptRepository.getAvailableLocales('asset_123');
// Returns: ['en', 'es', 'ja'] (only 'ready' transcripts)
Status Management#
Update Status#
typescript
const transcript = await transcriptRepository.updateStatus(
'transcript_456',
'processing'
);
Mark Ready#
typescript
const transcript = await transcriptRepository.markReady('transcript_456');
Mark Failed#
typescript
const transcript = await transcriptRepository.markFailed(
'transcript_456',
'Transcription service timeout'
);
Mark Reviewed#
typescript
const transcript = await transcriptRepository.markReviewed(
'transcript_456',
'user_789' // Reviewer user ID
);
// Sets isReviewed=true, reviewedBy, reviewedAt
Format Conversion#
Timestamp Utilities#
typescript
import {
msToTimestamp,
timestampToMs,
formatDuration,
} from '@lilith/media/transcripts';
// Convert milliseconds to timestamp
msToTimestamp(65500, 'srt'); // "00:01:05,500"
msToTimestamp(65500, 'vtt'); // "00:01:05.500"
// Parse timestamp to milliseconds
timestampToMs('00:01:05,500'); // 65500 (SRT format)
timestampToMs('00:01:05.500'); // 65500 (VTT format)
timestampToMs('01:05.500'); // 65500 (VTT short format)
// Format duration for display
formatDuration(65500); // "1:05"
formatDuration(3665500); // "1:01:05"
SRT Generation#
typescript
import { generateSRT } from '@lilith/media/transcripts';
const srt = generateSRT(segments);
/* Output:
1
00:00:00,000 --> 00:00:03,500
Welcome to the meditation session.
2
00:00:04,000 --> 00:00:07,200
Find a comfortable position.
*/
SRT Parsing#
typescript
import { parseSRT } from '@lilith/media/transcripts';
const segments = parseSRT(srtContent);
// Returns: TimedTextSegment[]
VTT Generation#
typescript
import { generateVTT, VTTOptions } from '@lilith/media/transcripts';
const options: VTTOptions = {
includeHeader: true, // Default: true
includeSequenceNumbers: false, // Default: false
includePosition: false, // Default: false
};
const vtt = generateVTT(segments, options);
/* Output:
WEBVTT
00:00:00.000 --> 00:00:03.500
Welcome to the meditation session.
00:00:04.000 --> 00:00:07.200
Find a comfortable position.
*/
VTT Parsing#
typescript
import { parseVTT } from '@lilith/media/transcripts';
const segments = parseVTT(vttContent);
// Returns: TimedTextSegment[]
Format Conversion#
typescript
import { convertSRTtoVTT, convertVTTtoSRT } from '@lilith/media/transcripts';
const vtt = convertSRTtoVTT(srtContent);
const srt = convertVTTtoSRT(vttContent);
Export Transcript#
typescript
import { exportTranscript, SubtitleFormat } from '@lilith/media/transcripts';
type SubtitleFormat = 'srt' | 'vtt' | 'txt';
const output = exportTranscript(segments, 'vtt');
Import with Auto-Detection#
typescript
import { importTranscript } from '@lilith/media/transcripts';
const result = importTranscript(content);
// Returns: { segments: TimedTextSegment[], detectedFormat: SubtitleFormat }
// Detects format automatically:
// - Starts with "WEBVTT" -> vtt
// - Matches SRT pattern (number + timestamp) -> srt
// - Otherwise -> txt (plain text)
Word-Level Timestamps#
Estimate Word Timings#
Generate word-level timestamps from segment-level timing:
typescript
import { estimateWordTimings } from '@lilith/media/transcripts';
const segment: TimedTextSegment = {
id: 'seg-1',
startTime: 0,
endTime: 3000,
text: 'Welcome to the session',
};
const wordTimings = estimateWordTimings(segment, 0.9);
// Returns: WordTiming[] with proportionally distributed times
// Each word gets: confidence ~= 0.9 with slight variance
Convert Word Timings to Segments#
typescript
import { wordTimingsToSegments } from '@lilith/media/transcripts';
const segments = wordTimingsToSegments(wordTimings, {
maxGapMs: 500, // Break on gaps > 500ms
maxSegmentDurationMs: 8000, // Max segment length 8s
maxWordsPerSegment: 20, // Max 20 words per segment
});
// Returns: TimedTextSegment[]
Get Word at Time#
typescript
import { getWordAtTime } from '@lilith/media/transcripts';
const word = getWordAtTime(wordTimings, 1500);
// Returns: WordTiming | null
Get Words in Range#
typescript
import { getWordsInRange } from '@lilith/media/transcripts';
const words = getWordsInRange(wordTimings, 0, 3000);
// Returns: WordTiming[] overlapping the range
Transcript Search#
Search Options#
typescript
interface SearchOptions {
caseSensitive?: boolean; // Default: false
wholeWord?: boolean; // Default: false
fuzzy?: boolean; // Default: false
fuzzyThreshold?: number; // Default: 0.7 (70% similarity)
maxResults?: number; // Default: 100
speakerId?: string; // Filter by speaker
timeRangeStart?: number; // Filter by time range (ms)
timeRangeEnd?: number;
includeContext?: boolean; // Default: true
contextLength?: number; // Default: 50 characters
}
Search Segments#
typescript
import { searchSegments, SearchResult } from '@lilith/media/transcripts';
interface SearchResult {
segmentId: string;
segmentIndex: number;
startTime: number;
endTime: number;
text: string;
matchedText: string;
matchPosition: number;
matchLength: number;
speakerId?: string;
score: number;
context?: {
before: string;
after: string;
};
}
const results = searchSegments(segments, 'meditation', {
caseSensitive: false,
includeContext: true,
});
Search Words#
typescript
import { searchWords, WordSearchResult } from '@lilith/media/transcripts';
interface WordSearchResult {
wordIndex: number;
word: string;
startTime: number;
endTime: number;
confidence?: number;
speakerId?: string;
score: number;
}
// Single word search
const results = searchWords(wordTimings, 'breath', {
wholeWord: true,
});
// Phrase search (automatically detected)
const phraseResults = searchWords(wordTimings, 'take a deep breath');
Fuzzy Search#
typescript
const results = searchSegments(segments, 'meditaton', {
fuzzy: true,
fuzzyThreshold: 0.7, // 70% similarity required
});
// Finds "meditation" despite typo
Search and Highlight#
typescript
import {
searchAndHighlight,
HighlightedSegment,
} from '@lilith/media/transcripts';
interface HighlightedSegment {
segment: TimedTextSegment;
highlightedText: string; // HTML with <mark> tags
matchCount: number;
}
const highlighted = searchAndHighlight(
segments,
'meditation',
'mark', // HTML tag for highlighting
{ caseSensitive: false }
);
// Example output:
// highlightedText: "Welcome to the <mark>meditation</mark> session."
Search Jump Points#
Get time-based navigation points for search results:
typescript
import { getSearchJumpPoints, JumpPoint } from '@lilith/media/transcripts';
interface JumpPoint {
time: number; // Milliseconds
formattedTime: string; // "1:05"
text: string; // Matched text
speakerId?: string;
}
const jumpPoints = getSearchJumpPoints(searchResults, 20);
// Returns up to 20 unique time points for navigation
Search Index#
For repeated searches, build an index for better performance:
typescript
import {
buildSearchIndex,
searchWithIndex,
SearchIndex,
} from '@lilith/media/transcripts';
// Build index once
const index: SearchIndex = buildSearchIndex(segments);
// Use index for multiple searches
const results1 = searchWithIndex(index, 'meditation');
const results2 = searchWithIndex(index, 'breathing', { fuzzy: true });
String Similarity#
Calculate Levenshtein-based similarity:
typescript
import { calculateSimilarity } from '@lilith/media/transcripts';
const similarity = calculateSimilarity('meditation', 'meditaton');
// Returns: 0.9 (90% similar)
Segment Utilities#
Get Segment at Time#
typescript
import { getSegmentAtTime } from '@lilith/media/transcripts';
const segment = getSegmentAtTime(segments, 5000);
// Returns segment containing time 5000ms, or null
Get Segments in Range#
typescript
import { getSegmentsInRange } from '@lilith/media/transcripts';
const rangeSegments = getSegmentsInRange(segments, 0, 30000);
// Returns all segments overlapping 0-30s range
Merge Segments#
Combine adjacent or overlapping segments:
typescript
import { mergeSegments } from '@lilith/media/transcripts';
const merged = mergeSegments(segments, 100);
// Merges segments with gaps <= 100ms and same speaker
Split Long Segments#
typescript
import { splitLongSegments } from '@lilith/media/transcripts';
const split = splitLongSegments(segments, 10000, 100);
// Splits segments > 10s or > 100 characters at sentence boundaries
Shift Timestamps#
typescript
import { shiftTimestamps } from '@lilith/media/transcripts';
// Shift all timestamps by offset
const shifted = shiftTimestamps(segments, 5000); // Add 5 seconds
const earlier = shiftTimestamps(segments, -2000); // Subtract 2 seconds
Scale Timestamps#
For speed adjustments:
typescript
import { scaleTimestamps } from '@lilith/media/transcripts';
// 2x speed (halve timestamps)
const faster = scaleTimestamps(segments, 0.5);
// 0.5x speed (double timestamps)
const slower = scaleTimestamps(segments, 2.0);
Get Transcript Statistics#
typescript
import { getTranscriptStats, TranscriptStats } from '@lilith/media/transcripts';
interface TranscriptStats {
totalDurationMs: number;
segmentCount: number;
wordCount: number;
characterCount: number;
averageSegmentDurationMs: number;
wordsPerMinute: number;
speakerCount: number;
speakers: string[];
}
const stats = getTranscriptStats(segments);
Convert to Plain Text#
typescript
import { segmentsToPlainText } from '@lilith/media/transcripts';
const text = segmentsToPlainText(segments, '\n');
// Joins all segment text with specified separator
Error Codes#
| Code | Description |
|---|---|
TRANSCRIPT_NOT_FOUND |
Transcript with ID not found |
ASSET_NOT_FOUND |
Asset ID does not exist |
INVALID_LOCALE |
Invalid locale code |
INVALID_FORMAT |
Invalid transcript format (SRT/VTT) |
PARSE_ERROR |
Failed to parse transcript content |
TIMESTAMP_ERROR |
Invalid timestamp format |
PROCESSING_FAILED |
Transcription processing failed |
SERVICE_UNAVAILABLE |
Transcription service unavailable |
SDK Integration#
TypeScript/JavaScript#
typescript
import { LilithClient } from '@lilith/sdk';
const client = new LilithClient({
apiKey: process.env.LILITH_API_KEY,
});
// Create transcript
const transcript = await client.media.transcripts.create({
assetId: 'asset_123',
locale: 'en',
type: 'auto_generated',
});
// Get transcript
const fetched = await client.media.transcripts.get('transcript_456');
// Get transcripts for asset
const transcripts = await client.media.transcripts.listByAsset('asset_123');
// Update transcript content
await client.media.transcripts.update('transcript_456', {
timedText: segments,
status: 'ready',
});
// Export transcript
const vtt = await client.media.transcripts.export('transcript_456', 'vtt');
const srt = await client.media.transcripts.export('transcript_456', 'srt');
// Search transcript
const results = await client.media.transcripts.search(
'transcript_456',
'meditation',
{
fuzzy: true,
includeContext: true,
}
);
// Get available locales
const locales = await client.media.transcripts.getLocales('asset_123');
// Set primary transcript
await client.media.transcripts.setPrimary('asset_123', 'transcript_456');
// Import transcript
const imported = await client.media.transcripts.import({
assetId: 'asset_123',
content: vttContent,
locale: 'es',
});
// Delete transcript
await client.media.transcripts.delete('transcript_456');
Transcript Processing Pipeline#
typescript
import { LilithClient } from '@lilith/sdk';
import {
parseVTT,
estimateWordTimings,
getTranscriptStats,
} from '@lilith/media/transcripts';
// Process uploaded VTT file
const segments = parseVTT(vttContent);
// Generate word-level timestamps
const wordTimings = segments.flatMap((segment) =>
estimateWordTimings(segment, 0.9)
);
// Calculate statistics
const stats = getTranscriptStats(segments);
// Create transcript with full data
const transcript = await client.media.transcripts.create({
assetId: 'asset_123',
locale: 'en',
isPrimary: true,
type: 'user_provided',
timedText: segments,
wordTimings,
vtt: vttContent,
wordCount: stats.wordCount,
segmentCount: stats.segmentCount,
status: 'ready',
});
Related Documentation#
- Asset API - Media asset management
- Audio Processing - Audio transcoding and processing
- Video Processing - Video transcoding and packaging
- Streaming API - Real-time streaming
Questions?#
- Technical Support: api-support@lilith.app
- Documentation: GitHub Issues