jerry/buzz

mirror of https://github.com/block/buzz.git synced 2026-11-01 06:51:17 +00:00

Files

John Matthew Tennant efbc63daa2 feat(voice): use natural Pocket TTS segmentation (#3588 )

## Context

Pocket TTS decoder streaming begins playback while each model-valid
chunk is still being decoded. Segmentation should preserve a fast
first-sentence boundary, enforce the model's exact 50-token safety
limit, and use natural prosody boundaries for oversized sentences and
the remainder.

## Summary

Move Pocket TTS segmentation into the shared tokenizer-aware layer. A
fitting first sentence stays separate for low time-to-first-audio.
Oversized sentences use clause, word, then UTF-8 scalar fallback, while
later sentences pack into the largest natural unit of at most 50
prepared model tokens. Returned chunks are contiguous and reconstruct
the prepared prompt exactly.

## Changes

- Replace the shared word-only splitter with distinct playback and
model-safety policies using actual SentencePiece counts.
- Keep a fitting first sentence as the initial playback unit, then pack
later sentences into the largest natural model-valid units.
- Split oversized sentences at clause, word, then UTF-8 scalar
boundaries.
- Preserve punctuation, whitespace, Unicode, text order, and exact
reconstruction across chunks.
- Remove the Desktop 200-character splitter while preserving its
low-latency first-sentence behavior in the shared layer.
- Route Desktop playback directly through the shared splitter without
changing streaming, cancellation, queue, fade, or voice-switch behavior.
- Remove the unused Desktop sentence splitter and its tests.

## Related issue

None found.

## Testing

Parent versus child medians after one warmup and three measured runs:

| Response | Parent TTFA | Child TTFA | Delta | Parent RTF | Child RTF |
| --- | ---: | ---: | ---: | ---: | ---: |
| Short | 335.328 ms | 317.890 ms | -17.439 ms | 0.231865 | 0.220702 |
| Medium | 472.118 ms | 383.934 ms | -88.184 ms | 0.214413 | 0.188397 |
| Long | 922.557 ms | 682.583 ms | -239.974 ms | 0.186114 | 0.185482 |

In this measured run, preserving the first-sentence boundary improved
median TTFA for all three response lengths while the natural remainder
policy kept median RTF lower for all three.

Cancellation after callback 2 returned `Interrupted` in 0.0195 ms.
Boundary cancellation prevented chunk 2 from starting. Every final
callback matched returned PCM byte-for-byte, callback lengths were
monotonic, splitting was deterministic, and text reconstruction was
exact.

## Reviewer-reproducible examples

Run model-independent boundary properties:

```sh
cargo test --manifest-path crates/buzz-voice/Cargo.toml --lib natural_split
cargo test --manifest-path crates/buzz-voice/Cargo.toml --lib oversized
```

Run the cached-model cases:

```sh
BUZZ_POCKET_TEST_MODEL_DIR=/path/to/april-int8-bundle \
cargo test --manifest-path crates/buzz-voice/Cargo.toml --lib -- --ignored --nocapture
```

The 90-token Gary sentence reconstructs exactly as three natural chunks
of 32, 42, and 15 prepared tokens.

Automated transcription found complete expected endings in all six
clips, with no clipping, late onset, or meaningful DC offset. Manual
listening in the combined daily-driver build also completed
successfully.

## Screenshots

N/A, nonvisual audio behavior.

---------

Signed-off-by: John Tennant <jtennant@squareup.com>
Signed-off-by: Tyler Longwell <tlongwell@squareup.com>
Co-authored-by: npub1jmc9dt2lyvzu3h0kxlwxt5zg4fxp9476awyxw6gwxn72g6cw7exqs64whm <96f056ad5f2305c8ddf637dc65d048aa4c12d7daeb8867690e34fca46b0ef64c@buzz.block.builderlab.xyz>
Co-authored-by: Tyler Longwell <tlongwell@squareup.com>

2026-07-31 12:56:48 -04:00