# subtitle-tools

**Repository Path**: mirrors_rjyo/subtitle-tools

## Basic Information

- **Project Name**: subtitle-tools
- **Description**: A collection of command-line tools for working with SRT subtitle files, with AI.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-14
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Subtitle Tools

A collection of command-line tools for working with SRT subtitle files.

## Features

- **Timing Adjustment**: Shift subtitle timing forward or backward
- **Translation**: Translate subtitles from one language to another using AI, with batching and context

## Installation

```bash
# Clone the repository
git clone https://github.com/rjyo/subtitle-tools.git
cd subtitle-tools

# Install dependencies
bun install
```

## Usage

### Subtitle Timing Adjustment

Adjust the timing of all subtitles in an SRT file by a specified amount of seconds.

```bash
bun adjust <srt-file> <time-adjustment>
```

#### Parameters:

- `<srt-file>`: Path to the SRT file
- `<time-adjustment>`: Time adjustment in seconds (positive or negative)
  - Use negative values to delay subtitles (e.g., `-0.5` for a 0.5-second delay)
  - Use positive values to advance subtitles (e.g., `0.5` to show subtitles 0.5 seconds earlier)

#### Examples:

```bash
# Delay subtitles by 2.5 seconds
bun adjust movie.srt -2.5

# Advance subtitles by 1 second
bun adjust movie.srt 1
```

#### Output:

The adjusted subtitles will be saved to a new file with `.adjusted.srt` appended to the original filename.

### Subtitle Translation

Translate subtitles from one language to another using AI.

```bash
bun translate <srt-file> <src,target>
```

#### Parameters:

- `<srt-file>`: Path to the SRT file
- `<src,target>`: Source and target language codes, separated by a comma (e.g., `en,ja` for English to Japanese)

#### Examples:

```bash
# Translate from English to Japanese
bun translate movie.srt en,ja

# Translate from Spanish to English
bun translate pelicula.srt es,en
```

#### API Key Setup:

Before using the translation feature, you need to set up an API key:

```bash
# For OpenAI (GPT-3.5/GPT-4)
export OPENAI_API_KEY=your_openai_api_key_here

# For Google (Gemini)
export GOOGLE_API_KEY=your_google_api_key_here
```

#### Output:

The translated subtitles will be saved to a new file with the target language code appended to the original filename (e.g., `movie.ja.srt`).

## Advanced Configuration

### Changing AI Models

You can modify the AI model used for translation by editing the `src/translate.ts` file:

```typescript
// For OpenAI
model: openai("gpt-4"); // Use GPT-4 instead of GPT-3.5-turbo

// For Google
model: google("gemini-1.5-pro"); // Use Gemini Pro instead of Flash
```

### Batch Size Adjustment

The translation script processes subtitles in batches for better context. You can adjust the batch size by modifying the `batchSize` variable in `src/translate.ts`.

## Troubleshooting

### Translation Issues

If the translation process freezes or fails:

1. Check your API key is correctly set
2. Try reducing the batch size in the script
3. Check the SRT file format is valid
4. Look for detailed error messages in the console output

### Timing Adjustment Issues

If the timing adjustment produces unexpected results:

1. Verify the SRT file format is valid
2. Check if any subtitles would have negative timing after adjustment
3. Ensure the time adjustment value is a valid number

## License

MIT

## Acknowledgements

- Uses [srt-parser-2](https://www.npmjs.com/package/srt-parser-2) for SRT parsing
- Uses [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) for AI integration