Eve library

Transcript Management API

Guide

Revision 1

On this page

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#

  1. Transcript Types
  2. CRUD Operations
  3. Locale Management
  4. Status Management
  5. Format Conversion
  6. Word-Level Timestamps
  7. Transcript Search
  8. Segment Utilities
  9. Error Codes
  10. 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

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');
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',
});


Questions?#

  • Technical Support: api-support@lilith.app
  • Documentation: GitHub Issues