PocketSynth

PocketSynth is a Python synthesis engine for Pocket TTS ONNX bundles. It owns Pocket-specific text normalization, SentencePiece tokenization, model-limit chunking, voice-prompt preparation, and Pocket generation controls while delegating bundle assets and ONNX execution to OnnxVoice.

Document parsing, SSMD, written-to-spoken semantic preparation, logical voice binding, semantic pauses, markers, timeline composition, and final mastering are intentionally outside PocketSynth.

Install

Install PocketSynth with the OnnxVoice CPU runtime:

python -m pip install 'pocketsynth[cpu]'

The gpu extra selects OnnxVoice's GPU runtime. playback adds sounddevice for RenderedSegment.play().

Managed Kyutai prompt support uses the OnnxVoice 0.2.2 prompt catalog and cache API; the package dependency installs this minimum automatically.

Direct engine use

Use PocketRuntime for a reusable local or managed bundle session. Prepare a voice once and reuse it across independent requests:

from pocketsynth import PocketRuntime, SynthesisRequest

with PocketRuntime.from_pretrained("english_2026-04") as runtime:
    voice = runtime.prepare_voice("alba")
    result = runtime.synthesize(
        SynthesisRequest(
            id="line-001",
            text="Hello from Pocket.",
            language="en",
        ),
        voice=voice,
    )
    result.save_wav("example-artifacts/hello.wav")

PocketRuntime.synthesize() is strict and atomic. It encodes the complete request once, then either performs one inference or raises SynthesisInputTooLongError. It never splits text. config= accepts a validated GenerationConfig; synthesize_text() is a strict plain-text wrapper that prepares non-PreparedVoice inputs.

PocketRuntime.load(directory) opens a local bundle without catalog access or network activity. PocketRuntime.from_pretrained(bundle) resolves and opens a managed bundle through OnnxVoice.

Document-friendly splitting is available only from the explicit convenience module:

from pocketsynth.convenience import synthesize_to_wav

synthesize_to_wav(
    "Hello from Pocket.",
    "example-artifacts/hello-convenience.wav",
    bundle="english_2026-04",
    voice="alba",
    sentence_split="phrasplit",  # opt in to sentence segmentation
)

pocketsynth.convenience.synthesize_with_runtime() and pocketsynth.convenience.synthesize() return a RenderedSegment. pocketsynth.convenience.synthesize_to_wav() returns the destination Path after atomically writing the WAV. Convenience rendering may split at Pocket model limits. Sentence splitting defaults to "none"; pass sentence_split="phrasplit" to opt in. Convenience functions are not aliases for the strict runtime API and are not imported by pocketsynth.

Text and model chunks

Input text must already be speakable. PocketSynth does not parse documents, expand numbers or dates, or apply pronunciation directives. Strict synthesis neither segments sentences nor subdivides at the model token limit. Oversized requests fail with SynthesisInputTooLongError.

The explicit convenience layer can split text to fit model limits. Its optional Phrasplit mode segments sentences first, then Pocket model-limit chunks are rendered and joined in order. PocketRuntime.iter_chunks() exposes model-limit chunks for applications that explicitly want chunked rendering; it does not perform sentence segmentation.

from pocketsynth.convenience import synthesize_with_runtime
from pocketsynth import PocketRuntime

with PocketRuntime.from_pretrained("english_2026-04") as runtime:
    long_text = "Dr. Smith arrived early. Then he started the presentation."
    result = synthesize_with_runtime(runtime, long_text, voice="alba", sentence_split="phrasplit")

An explicit request language is a compatibility assertion against the active bundle. None uses the bundle language. PocketSynth does not switch bundles or route languages automatically.

Voices

Pocket bundles and voice conditioning are separate. prepare_voice() accepts bundle-declared predefined names, local PCM WAV paths, Path objects, in-memory (audio, sample_rate) tuples, existing PreparedVoice objects, and managed kyutai-tts-voices:<id> references. Reference WAVs support uncompressed PCM 8-, 16-, 24-, and 32-bit mono or multichannel audio; multichannel input is downmixed and audio is resampled to the bundle rate before OnnxVoice encodes it.

PreparedVoice can be reused for many requests on a compatible runtime. A reference voice's fingerprint identifies normalized audio and sample rate, while its metadata retains managed source provenance and license. OnnxVoice 0.2.2 owns Kyutai prompt discovery, pinned downloads, cache integrity, and offline behavior. PocketSynth does not download prompt assets itself. Predefined voice states remain separate assets and may require accepting upstream access terms and authenticating with Hugging Face.

Managed references are resolved and cached by OnnxVoice, so no WAV download step is needed:

from pocketsynth import PocketRuntime

with PocketRuntime.from_pretrained("english_2026-04") as runtime:
    voice = runtime.prepare_voice("kyutai-tts-voices:alba-mackenna/casual")
    result = runtime.synthesize_text("Hello from a managed Kyutai voice.", voice=voice)
    result.save_wav("example-artifacts/kyutai-casual.wav")

Discover prompts without downloading their audio with runtime.list_voice_prompts() or pocketsynth voices list. The CLI supports --dataset, --variant, --license, and --offline filters.

To inspect dependencies, providers, bundle metadata, and voice format:

pocketsynth check --bundle english_2026-04 --voice alba
pocketsynth check --bundle-dir ./onnx/english_2026-04 --voice reference.wav

CLI

Managed bundle:

pocketsynth synthesize \
  --bundle english_2026-04 \
  --voice alba \
  --output example-artifacts/hello.wav \
  "Hello from Pocket."

Managed Kyutai reference:

pocketsynth synthesize \
  --bundle english_2026-04 \
  --voice kyutai-tts-voices:alba-mackenna/casual \
  --output example-artifacts/kyutai-casual.wav \
  "Hello from PocketSynth."

After the bundle and prompt are cached, pass --offline to use them without network access. List available catalog prompts without downloading WAVs:

pocketsynth voices list --dataset alba-mackenna

Local bundle:

pocketsynth synthesize \
  --bundle-dir ./onnx/english_2026-04 \
  --voice reference.wav \
  --output example-artifacts/hello-local.wav \
  "Hello from Pocket."

The synthesize CLI is a convenience renderer. Sentence splitting defaults to none, which still permits Pocket model-limit chunking. Pass --sentence-split phrasplit to opt into Phrasplit's lightweight regex sentence segmentation. Other inference controls include --temperature, --lsd-steps, --max-frames, and --frames-after-eos. Asset controls include --cache-dir, --offline, --refresh-catalog, and --force-download for managed bundles.

Orchestrated use

An application that renders documents resolves document meaning and concrete engine inputs before calling PocketSynth:

source document / SSMD
    -> application orchestration and document planning
    -> prepared speakable text + concrete bundle + PreparedVoice
    -> PocketRuntime
    -> SynthesisResult
    -> application composition and output policy

PocketSynth does not import or require the neighboring document-planning or audio-composition packages. Callers own semantic pauses, markers, logical voice roles, external audio, timeline placement, and final mastering.

Breaking boundary change

PocketSynth's engine API is strict and atomic: PocketRuntime.synthesize() accepts one SynthesisRequest and never splits it. synthesize_text() is the strict plain-text wrapper. Document and model-limit splitting lives in the explicit pocketsynth.convenience module and the CLI. Convenience imports are not loaded by importing pocketsynth.

The strict API returns finite mono float32 audio with request and runtime metadata, but no chunk collection. Applications that deliberately need model-limit chunks can use PocketRuntime.iter_chunks() or the explicit convenience layer. Document pauses, markers, role routing, and final timelines remain application responsibilities.

Migration from 0.1

Examples and checks

See examples/README.md. The runner does not start managed downloads unless requested:

python examples/run_all.py --list
python examples/run_all.py --local-only
python examples/run_all.py --include-network
python examples/run_all.py --include-network --offline

examples/kyutai_voice.py uses a managed catalog reference and needs no local WAV or POCKETSYNTH_EXAMPLE_VOICE. Set POCKETSYNTH_EXAMPLE_VOICE for local reference-WAV examples and POCKETSYNTH_EXAMPLE_BUNDLE_DIR for local bundles. examples/clone_all_kyutai_voices.py discovers and renders all cataloged WAV prompts; see the examples guide for filters and dry-run usage.

Run project checks with:

python -m pytest
python -m ruff check pocketsynth tests examples
python -m mypy --config-file pyproject.toml pocketsynth
python -m compileall -q pocketsynth tests examples

Real model tests are environment-gated. Set POCKETSYNTH_TEST_BUNDLE_DIR and POCKETSYNTH_TEST_VOICE_WAV to run the local integration tests. To opt into one pinned Kyutai prompt download and synthesis followed by offline cache reuse, set POCKETSYNTH_TEST_MANAGED_PROMPT=1; the test uses english_2026-04 unless POCKETSYNTH_TEST_BUNDLE overrides it. It does not synthesize the full catalog. Managed tests may require network access and accepted upstream voice-asset terms.