# Transcript Management API

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](#transcript-types)
2. [CRUD Operations](#crud-operations)
3. [Locale Management](#locale-management)
4. [Status Management](#status-management)
5. [Format Conversion](#format-conversion)
6. [Word-Level Timestamps](#word-level-timestamps)
7. [Transcript Search](#transcript-search)
8. [Segment Utilities](#segment-utilities)
9. [Error Codes](#error-codes)
10. [SDK Integration](#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](./asset-api.md) - Media asset management
- [Audio Processing](./audio-processing.md) - Audio transcoding and processing
- [Video Processing](./video-processing.md) - Video transcoding and packaging
- [Streaming API](./streaming-api.md) - Real-time streaming

---

## Questions?

- **Technical Support**: api-support@lilith.app
- **Documentation**: [GitHub Issues](https://github.com/lilith/platform/issues)
