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

npm install subchunk
# or
yarn add subchunk
# or
bun add subchunk

💻 Usage

subchunk is a pure function that processes ElevenLabs JSON directly. It has no file-system dependencies, making it perfect for both Node.js/Bun environments and the browser!

import { convertElevenlabsJsonToSubtitle } from "subchunk";

// 1. Pass the parsed JSON object directly
const elevenLabsData = {
  segments: [
    {
      text: "Hello world",
      words: [
        { text: "Hello", start: 0.1, end: 0.5, type: "word" },
        { text: "world", start: 0.5, end: 1.0, type: "word" }
      ]
    }
  ]
};

const srtOutput = convertElevenlabsJsonToSubtitle(elevenLabsData, {
  format: "srt",
  preset: "reels"
});

console.log(srtOutput);

// 2. Or pass a raw JSON string
const jsonString = JSON.stringify(elevenLabsData);

const vttOutput = convertElevenlabsJsonToSubtitle(jsonString, {
  format: "vtt",
  speaker: true,
  maxWords: 5,
  gap: 0.8
});

🔧 Options

🎯 Presets

📄 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 and returns the .srt or .vtt raw string

🎯 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