---

name: subtitle-service description: Subtitle parsing, generation, and translation service guidelines for Gemini-Subtitle-Pro. Use when working with SRT/ASS/VTT parsing, subtitle generation, translation pipeline, glossary management, speaker identification, and Gemini API integration. Covers the complete transcription → translation workflow.

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

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

Key Services

---

Core Data Types

SubtitleEntry

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

Timestamp Utilities

Copy// 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

Copyexport 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

Copyexport 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

Copy// 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