> ## Documentation Index
> Fetch the complete documentation index at: https://docs.responsivevoice.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Chunking

## Overview

ResponsiveVoice automatically splits long text into smaller chunks for optimal playback. This ensures reliable speech synthesis even with large amounts of text.

## Why Chunking?

- **API Limits**: TTS services have character limits per request
- **Memory**: Smaller audio buffers are more efficient
- **Responsiveness**: Speech starts faster with smaller chunks
- **Reliability**: Reduces chance of timeouts and errors

## Automatic Chunking

Chunking happens automatically when you call `speak()`:

```typescript
// This long text is automatically split into chunks
responsiveVoice.speak(
  `
  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
`,
  'UK English Female',
);
```

## Chunk Boundaries

Within the character limit, text is split at the latest (rightmost) natural boundary, preferring higher-priority delimiters first:

1. **Sentence endings** (`.` `?` `!`)
2. **Major separators** (`;` `:`)
3. **Clause separators** (`,`)
4. **Word boundaries** (spaces)
5. **CJK character boundaries** (between ideographs, when no earlier boundary fits)

> [!TIP]
> The chunker never splits in the middle of a word, and skips `.`/`,` inside numbers like `3.14` or `1,000`.

## Default Limits

| Setting            | Value     | Description                            |
| ------------------ | --------- | -------------------------------------- |
| Default chunk size | 100 chars | Characters per chunk when not set      |
| Min chunk size     | 50 chars  | Lower bound (smaller values clamp up)  |
| Max chunk size     | 300 chars | Upper bound (larger values clamp down) |
| Sentence priority  | High      | Prefers sentence boundaries            |

## Custom Configuration

The chunk character limit is a page-wide setting. Set it globally:

**Browser bundle (CDN)**

```html
<script src="https://cdn.responsivevoice.org/sdk/latest/responsivevoice.js"></script>
<script>
  // At startup
  responsiveVoice.init({ characterLimit: 150 }); // clamped to 50–300

  // Or at runtime
  responsiveVoice.setCharacterLimit(150);
  responsiveVoice.getCharacterLimit(); // 150
</script>
```

**npm (ESM)**

```typescript
import { getResponsiveVoice } from '@responsivevoice/core';

// At startup
const rv = await getResponsiveVoice({ characterLimit: 150 }); // clamped to 50–300

// Or at runtime
rv.setCharacterLimit(150);
rv.getCharacterLimit(); // 150
```

> [!NOTE]
> Examples below use the browser bundle's global `responsiveVoice`. With the npm package, call the same methods on the instance returned by `getResponsiveVoice()`.

## Seamless Playback

Chunks are queued and played sequentially without gaps:

```typescript
responsiveVoice.speak(longArticle, 'UK English Female', {
  onstart: () => console.log('Started reading article'),
  onend: () => console.log('Finished reading article'),
  // onend fires once when ALL chunks complete
});
```

## Manual Chunking

For complete control, split the text yourself with `chunkText()`. Each chunk is `{ text, index, total, isLast }`:

```typescript
const chunks = responsiveVoice.chunkText(article, { characterLimit: 200 });

for (const chunk of chunks) {
  await new Promise<void>((resolve) =>
    responsiveVoice.speak(chunk.text, 'UK English Female', { onend: resolve }),
  );
}
```

`chunkText` is also importable standalone from `@responsivevoice/text`.

## Progress with Chunks

Track progress across chunks:

```typescript
const chunks = responsiveVoice.chunkText(longText, { characterLimit: 200 });
let currentChunk = 0;

function speakNextChunk() {
  if (currentChunk >= chunks.length) {
    console.log('Complete!');
    return;
  }

  const chunk = chunks[currentChunk];
  const progress = ((chunk.index + 1) / chunk.total) * 100;
  console.log(`Progress: ${progress.toFixed(0)}%`);

  responsiveVoice.speak(chunk.text, 'UK English Female', {
    onend: () => {
      currentChunk++;
      speakNextChunk();
    },
  });
}

speakNextChunk();
```

## Special Characters

The chunker is aware of:

- **Numbers**: won't split on `.` or `,` inside a number (`3.14`, `1,000`)
- **Grouping pairs**: prefers not to split inside quotes, parentheses, or brackets

```typescript
// Numbers stay intact
responsiveVoice.speak('The price is $19.99 per month.', voice);

// Quoted text is kept together
responsiveVoice.speak('She said "Hello there, friend!" and waved.', voice);
```

## SSML

ResponsiveVoice takes **plain text**, not SSML — no current browser implements the Web Speech API's SSML, so it isn't supported. Shape delivery with the `rate`, `pitch`, and `volume` parameters plus punctuation. See the [FAQ](/guides/faq/#does-responsivevoice-support-ssml).

## Performance Tips

1. **Pre-chunk large texts** for better control
2. **Keep `characterLimit` within range** (50–300; default 100)
3. **Avoid very small chunks** (causes choppy playback)
4. **Consider caching** for repeated content