Subtitle Service Guidelines

Purpose

Establish patterns for subtitle processing services in Gemini-Subtitle-Pro, covering parsing, generation, translation, and the AI pipeline.

When to Use This Skill

Automatically activates when working on:

• SRT/ASS/VTT parsing and generation
• Translation pipeline
• Glossary management
• Speaker identification
• Gemini API integration for refinement
• Transcription workflow

Quick Start

Subtitle Processing Checklist

• [ ] Parser: Use appropriate parser for format (SRT, ASS, VTT)
• [ ] Types: Use SubtitleEntry interface consistently
• [ ] Validation: Validate timestamps and text content
• [ ] Error Handling: Handle parsing errors gracefully
• [ ] i18n: Support multiple languages in output

Architecture Overview

Pipeline Flow

Audio/Video Input
    ↓
Transcription (Whisper)
    ↓
Segmentation (VAD)
    ↓
Glossary Extraction
    ↓
Speaker Identification
    ↓
Translation/Refinement (Gemini)
    ↓
Subtitle Output (SRT/ASS/VTT)

Key Services

Core Data Types

SubtitleEntry

interface SubtitleEntry {
  index: number;
  startTime: number; // milliseconds
  endTime: number; // milliseconds
  text: string;
  translatedText?: string;
  speaker?: string;
}

Timestamp Utilities

// Parse SRT timestamp: "00:01:23,456" → 83456
function parseSrtTimestamp(timestamp: string): number;

// Format to SRT: 83456 → "00:01:23,456"
function formatSrtTimestamp(ms: number): string;

// Parse ASS timestamp: "0:01:23.45" → 83450
function parseAssTimestamp(timestamp: string): number;

Parsing Patterns

SRT Parser

export function parseSrt(content: string): SubtitleEntry[] {
  const blocks = content.trim().split(/\n\n+/);

  return blocks.map((block, index) => {
    const lines = block.split('\n');
    const timestampLine = lines[1];
    const [start, end] = timestampLine.split(' --> ');

    return {
      index,
      startTime: parseSrtTimestamp(start),
      endTime: parseSrtTimestamp(end),
      text: lines.slice(2).join('\n'),
    };
  });
}

Format Detection

export function detectSubtitleFormat(content: string): 'srt' | 'ass' | 'vtt' {
  if (content.startsWith('WEBVTT')) return 'vtt';
  if (content.includes('[Script Info]')) return 'ass';
  return 'srt';
}

Translation Pipeline

Concurrency Model

// Dual semaphores for resource management
const transcriptionSemaphore = new Semaphore(
  isLocal ? 1 : 5 // Local: 1, Cloud: 5
);

const refinementSemaphore = new Semaphore(5); // Gemini Flash

// Process chunks in parallel
await mapInParallel(chunks, async (chunk) => {
  await transcriptionSemaphore.acquire();
  try {
    const transcription = await transcribe(chunk);
    // ...
  } finally {
    transcriptionSemaphore.release();
  }
});

Resource Files

For detailed guidelines, see the resources directory:

• parsing-patterns.md - Subtitle format parsing
• pipeline-guide.md - Translation pipeline patterns
• gemini-integration.md - Gemini API usage