transcribe

Transcribe

Generate SRT subtitle files + readable text from audio/video using ElevenLabs Scribe v2.

Quick Start

cd ~/.claude/skills/transcribe/scripts

# Basic transcription (generates both SRT + readable .md)
npx ts-node transcribe.ts -i /path/to/video.mp4 -o /path/to/output.srt

# Specify language
npx ts-node transcribe.ts -i /path/to/video.mp4 -o /path/to/output.srt -l he

# Only readable text (skip SRT)
npx ts-node transcribe.ts -i /path/to/meeting.m4a -o /path/to/output.srt --no-srt

Shorter timestamp intervals (every 2 minutes)

npx ts-node transcribe.ts -i /path/to/video.mp4 -o /path/to/output.srt --timestamp-interval 120

Disable speaker diarization

npx ts-node transcribe.ts -i /path/to/video.mp4 -o /path/to/output.srt --no-speakers

## Output Files

The script **always** generates:
1. `.srt` - Standard subtitle file (for embedding)
2. `.md` - Readable text with speakers + timestamps every ~5 min

Optional:
3. `_transcript.json` - Raw word-level data (with `--json`)

## Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--input` | `-i` | (required) | Input audio/video file |
| `--output` | `-o` | (required) | Output SRT file path |
| `--language` | `-l` | auto | Language code (en, he, ar, etc.) |
| `--max-words` | | 5 | Max words per subtitle entry |
| `--max-duration` | | 3.0 | Max seconds per subtitle entry |
| `--max-chars` | | 70 | Max characters per subtitle entry |
| `--timing-offset` | | 0.25 | Timing offset in seconds |
| `--json` | | false | Also output raw transcript JSON |
| `--no-srt` | | false | Skip SRT, only generate text |
| `--no-speakers` | | false | Disable speaker diarization |
| `--timestamp-interval` | | 300 | Seconds between timestamps in text (5 min) |

## Language Codes

- `en` - English
- `he` - Hebrew
- `ar` - Arabic
- `es` - Spanish
- `fr` - French
- `de` - German
- `ru` - Russian
- `zh` - Chinese
- `ja` - Japanese
- (or omit for auto-detection)

## Readable Text Format

The `.md` file includes:
- **Header** with filename, date, duration
- **Speaker labels** (דובר 1, דובר 2...) when diarization detects speaker changes
- **Timestamps** every ~5 minutes (configurable)
- **Paragraphs** broken naturally at sentence boundaries

Example:
```markdown
# תמלול: meeting.m4a
**תאריך:** 27.1.2026
**משך:** 45:32

---

**דובר 1:**
שלום לכולם, אני רוצה להתחיל את הפגישה...

**דובר 2:**
בסדר, בוא נדבר על הנושא הראשון...

**[5:00]**

**דובר 1:**
עכשיו נעבור לחלק השני...

Translation

If target language differs from audio language:

1. Transcribe first (get original language SRT)
2. Read the SRT, translate each entry preserving timestamps
3. Write translated SRT file

No API needed - translate directly.

Post-Transcription Refinement (Claude's Job)

After generating the raw SRT, always refine it semantically. The transcription API chunks by time intervals, not meaning - this creates awkward splits like:

1
00:00:00,500 --> 00:00:01,922
anything a human being can

2
00:00:02,002 --> 00:00:03,320
do, your Claude bot can

The word "do" belongs with the previous sentence! Always regroup by semantic meaning:

Refinement Rules

1. Complete sentences/clauses together - Never split subject from verb, verb from object
2. Move orphaned words - If a line starts with a word that completes the previous thought, merge it
3. Punctuation guides splits - Periods, question marks, exclamations are natural break points
4. Preserve parallel structure - Keep matching phrases together (e.g., "if X can do it, Y can do it")
5. Emphasis stays standalone - Repeated words for emphasis ("Anything. Anything!") get their own line
6. Action chains can split - Lists of actions can be separate lines if they're complete thoughts

Refinement Process

1. Read the raw SRT
2. Concatenate all text to see full content
3. Identify natural sentence/clause boundaries
4. Redistribute words into semantic groups
5. Adjust timestamps: line starts at first word's time, ends at last word's time + small buffer
6. Write refined SRT

Example Before/After

Before (raw):

1
00:00:00,500 --> 00:00:01,922
anything a human being can

2
00:00:02,002 --> 00:00:03,320
do, your Claude bot can

3
00:00:03,341 --> 00:00:06,282
do. Anything. Anything!

After (refined):

1
00:00:00,500 --> 00:00:02,100
anything a human being can do,

2
00:00:02,100 --> 00:00:03,500
your Claude bot can do.

3
00:00:03,600 --> 00:00:06,100
Anything. Anything!

Always apply this refinement after transcription. The user expects semantically coherent subtitles.

Environment

API key stored in scripts/.env:

ELEVENLABS_API_KEY=your_key_here