subchunk

Convert ElevenLabs transcript JSON into clean, readable subtitles (.srt / .vtt).

🚨 Problem

ElevenLabs provides SRT exports, but they often look like this:

1
00:00:00,000 --> 00:00:05,000
This is a very long subtitle line that contains too many words and is hard to read quickly.

❌ Issues:

• Subtitles are too long
• Poor readability
• Weak alignment with speech timing
• Not optimized for modern content (Reels, Shorts, YouTube)

✅ Solution

ElevenLabs JSON includes word-level timestamps — this tool uses that to generate high-quality subtitles:

✔ Short, readable chunks ✔ Pause-aware timing ✔ Smart sentence splitting ✔ Multi-line subtitles (2 lines max) ✔ Speaker labels (optional) ✔ .srt and .vtt support

✨ Example Output

1
00:00:00,460 --> 00:00:01,160
Three minutes.

2
00:00:01,200 --> 00:00:02,400
That’s all it takes
to get started.

⚙️ Features

• 🎯 Smart chunking (punctuation + pauses + word limits)

• 🧠 Human-friendly subtitle splitting

• 🪶 Lightweight & fast (Bun-powered)

• 🎬 Presets for different content styles:

  • reels (short captions)
  • youtube
  • podcast

• 🗣 Speaker labels support

• 📄 Multiple formats (.srt, .vtt)

• 🛡 Robust error handling

📦 Installation

Run instantly

bunx subchunk input.json -o output.srt

Install globally

bun install -g subchunk

🚀 Usage

subchunk <input.json> [options]

🔧 Options

💻 Programmatic Usage

You can also import subchunk as a library in your Node.js or Bun projects. It includes first-class TypeScript support.

import { convertElevenlabsJsonToSubtitle } from "subchunk";

// 1. Pass a file path and get the string result
const srtOutput = await convertElevenlabsJsonToSubtitle("input.json", {
  format: "srt",
  preset: "reels"
});

// 2. Or pass the JSON object directly
const vttOutput = await convertElevenlabsJsonToSubtitle(myJsonObject, {
  format: "vtt",
  speaker: true
});

// 3. Write directly to a file by specifying 'output'
await convertElevenlabsJsonToSubtitle("input.json", {
  output: "output.srt",
  maxWords: 5,
  gap: 0.5
});

🎯 Presets

Example:

subchunk input.json --preset reels

📄 Input Format (ElevenLabs JSON)

{
  "segments": [
    {
      "text": "Three minutes.",
      "words": [
        {
          "text": "Three",
          "start": 0.46,
          "end": 0.66,
          "type": "word"
        }
      ]
    }
  ]
}

🧠 How It Works

1. Extracts words from segments[].words[]

2. Detects:

   • sentence endings (. ? !)
   • pauses in speech
   • word limits

3. Groups words into natural subtitle chunks

4. Formats into .srt or .vtt

🧪 Examples

# basic
subchunk input.json

# reels (short captions)
subchunk input.json --preset reels

# include speaker labels
subchunk input.json --speaker

# VTT format
subchunk input.json --format vtt

# custom tuning
subchunk input.json --maxWords 6 --gap 0.5

🎯 Why This Matters

Good subtitles are critical for:

• Viewer retention 📈
• Accessibility ♿
• Mobile-first content 📱

This tool helps you generate modern, readable captions instead of outdated long blocks.

📄 License

MIT