IndexError: index 510 is out of bounds in _create_audio when phonemes are truncated to MAX_PHONEME_LENGTH

[matteofrassi]

Bug description

When input text produces phonemes that are truncated to MAX_PHONEME_LENGTH (510), _create_audio raises an IndexError at line 108:

voice = voice[len(tokens)]

The voice array has shape (510, ...) (valid indices 0–509), but len(tokens) can be exactly 510 after truncation, causing an out-of-bounds access.

Steps to reproduce

from kokoro_onnx import Kokoro

kokoro = Kokoro("kokoro-v1.0.onnx", "voices-v1.0.bin")

# Any text long enough to produce ≥510 phonemes triggers the bug
long_text = "L'intelligenza artificiale sta trasformando radicalmente il modo in cui le aziende operano e competono sul mercato globale. " * 10

samples, sr = kokoro.create(long_text, voice="if_sara", speed=1.0, lang="it")

Error

WARNING  [__init__.py:98] Phonemes are too long, truncating to 510 phonemes
Traceback (most recent call last):
  ...
  File "kokoro_onnx/__init__.py", line 201, in create
    audio_part, _ = self._create_audio(phonemes, voice, speed)
  File "kokoro_onnx/__init__.py", line 108, in _create_audio
    voice = voice[len(tokens)]
IndexError: index 510 is out of bounds for axis 0 with size 510

Root cause

In _create_audio (__init__.py):

1. Line 101 truncates phonemes to 510 characters: phonemes = phonemes[:MAX_PHONEME_LENGTH]
2. Line 103 tokenizes → len(tokens) can be exactly 510
3. Line 104 asserts len(tokens) <= MAX_PHONEME_LENGTH → passes (510 <= 510)
4. Line 108 indexes voice[len(tokens)] → voice[510] is out of bounds for an array of size 510

Suggested fix

Clamp the index to prevent out-of-bounds access:

- voice = voice[len(tokens)]
+ voice = voice[min(len(tokens), len(voice) - 1)]

Environment

• kokoro-onnx: 0.5.0
• Python: 3.12.12
• OS: macOS (Darwin 25.3.0)

[xPTM1219]

Confirming that the fix does work, thank you.

kokoro_onnx version is 0.5.0

There is an alternative here in the issue 115.

[thewh1teagle]

Feel free to create a new PR with claude code + minimal test! (with pytest) I will fix it soon otherwise

[matteofrassi]

PR submitted in #185. Includes the index clamping fix for the out-of-bounds access, plus a whitespace normalization improvement in normalize_text() to handle newlines and multiple spaces that were causing audio artifacts. Added pytest tests for both fixes.

[t-d-d]

The clamp in #185 stops the crash but leaves the truncation behaviour in place — anything past phoneme 510 is dropped (with the existing WARNING Phonemes are too long, truncating to 510 phonemes). The underlying bug is in _split_phonemes: it only breaks on [.,!?;], so any batch ≥ 510 chars without those marks (URLs, run-on text, espeak-ng's English-fallback IPA for kana/kanji/hanzi) reaches _create_audio over-length in the first place.

A complete fix needs the chunker to actually guarantee len(chunk) ≤ MAX_PHONEME_LENGTH so the truncate path never fires on valid input. We hit this in production and replaced _split_phonemes with a cascade — sentence punctuation → clause marks → whitespace → hard cut as a last resort — then greedy-pack the atoms globally so neighbours across split levels can share a chunk:

_SENTENCE_RE = re.compile(r"([.!?]+)")
_CLAUSE_RE = re.compile(r"([,;:]+)")
_WHITESPACE_RE = re.compile(r"(\s+)")

def _split_keep(text, pattern):
    parts = pattern.split(text)
    pieces = []
    for i in range(0, len(parts), 2):
        piece = parts[i] + (parts[i + 1] if i + 1 < len(parts) else "")
        if piece:
            pieces.append(piece)
    return pieces

def _greedy_pack(pieces, limit):
    result, current = [], ""
    for piece in pieces:
        if not current:
            current = piece
        elif len(current) + len(piece) <= limit:
            current += piece
        else:
            result.append(current)
            current = piece
    if current:
        result.append(current)
    return result

def _hard_cut(text, limit):
    return [text[i:i + limit] for i in range(0, len(text), limit)]

def _chunk_phonemes(phonemes, limit):
    if not phonemes:
        return []
    def atomise(text):
        if len(text) <= limit:
            return [text]
        for pattern in (_SENTENCE_RE, _CLAUSE_RE, _WHITESPACE_RE):
            pieces = _split_keep(text, pattern)
            if len(pieces) > 1:
                return [atom for piece in pieces for atom in atomise(piece)]
        return _hard_cut(text, limit)
    return _greedy_pack(atomise(phonemes), limit)

Happy to open a PR porting this into kokoro_onnx (with tests) if you'd take it. The clamp from #185 is still worth landing as belt-and-braces against future regressions, just shouldn't be the only line of defence.

[matteofrassi]

Thanks for the detailed write-up. Agreed the clamp in #185 is only a safety net and the real fix belongs in the chunker. Please go ahead with the PR; happy to review.

One thing worth covering in tests: _hard_cut slicing by character index can split inside multi-codepoint IPA sequences (combining diacritics, tie bars). Worth a grapheme-boundary check, or at least a test asserting no broken clusters on a stress input.

I'll keep #185 open as the belt-and-braces fallback; feel free to rebase on top once your chunker lands.

[RavSinghChandan]

Jumping in on what @t-d-d said above. The clamp in #185 does stop the crash, but there's still a problem underneath it.

If a chunk of text has no punctuation and is longer than 510 phonemes, _split_phonemes never breaks it up — so it hits the 510 limit and everything after that just gets dropped, quietly. I ran into this doing long-form TTS with kokoro.

I'd be happy to fix _split_phonemes so a too-long piece gets split at word boundaries instead of cut off, and add a small pytest for it. Should I open a separate PR for that (keeping it apart from the clamp in #185)?