Spum Voice¶

Spum CLI 0.2.4 adds native, local speech commands. Download the released packs once; inference then reads local files without Python or a remote inference API. This initial release exposes English recognition and three English synthesis voices.

Get the models¶

spum models catalog
spum models download whisper-base-en
spum models download kokoro-en-v1-int8
spum models verify whisper-base-en
spum models verify kokoro-en-v1-int8

The packages are hosted in the Spum Hugging Face repository. Archive checksums are compiled into the release catalog. File checksums, upstream licences and provenance are included in each archive. Model downloads are explicit; inference never silently downloads a model.

Transcribe a recording¶

spum transcribe recording.wav --model whisper-base-en --output transcript.txt
spum transcribe interview.m4a --model whisper-base-en --json --output transcript.json
spum transcribe recording.mp3 --language en --threads 4 --quiet

Common formats supported by the Mac's audio decoder, including WAV, AIFF, M4A and MP3, are converted locally to mono 16 kHz. The command reads a file; it does not activate the microphone. Inputs are limited to two hours. A transcript output path must not be the same file as the input recording.

Option	Default	Meaning
`--model`, `-m`	`whisper-base-en`	Released model ID or a compatible local pack directory
`--language`	`en`	English is the supported language of the released pack
`--threads`, `-t`	`4`	CPU worker count, 1 to 64
`--chunk-seconds`	`25`	Recognition window, 1 to 29 seconds
`--format`	`text`	`text`, `json`, `srt` or `vtt`
`--json`	Flag	Alias for JSON output; conflicts with a different explicit format
`--output`, `-o`	stdout	Save the completed transcript; replaces existing content
`--models-dir`	`~/.spum/models`	Speech model directory
`--quiet`	Flag	Suppress timing summaries; errors remain visible

Long recordings are processed in windows, preferring a quiet boundary near the end of each window when one is present. Recognition at a boundary can still differ from a continuous utterance. Silent windows produce no transcript rather than inviting a model to invent speech.

JSON output¶

JSON includes the text, language, segment array, input duration, model-load time, inference time, total time and real-time factor. The real-time factor is inference seconds divided by audio seconds; model loading is reported separately.

Captions¶

spum transcribe recording.wav --format srt --output captions.srt
spum transcribe recording.wav --format vtt --output captions.vtt

These captions use recognition-window timing. They are not word-aligned or speaker-diarized subtitles. Inspect and refine their timing before production use.

Generate speech¶

spum speak --text "The scanner is ready." --voice af_heart --output speech.wav
spum speak --text-file announcement.txt --voice af_alloy --speed 1.1 --output announcement.wav --json
spum speak --model kokoro-en-v1-int8 --list-voices

Synthesis produces mono, 24 kHz WAV audio. The checked voices are af_heart, af_alloy and am_adam. Voice IDs are model presets, not a facility for cloning an uploaded person's voice.

Option	Default	Meaning
`--model`, `-m`	`kokoro-en-v1-int8`	Released model ID or local pack directory
`--text`, `-p`	Text	Direct text input
`--text-file`	File	UTF-8 text input, up to 1 MiB; choose text or text-file
`--output`, `-o`	Required	WAV output path ending in `.wav`; replaces existing content
`--voice`	`af_heart`	Voice ID from the selected pack
`--list-voices`	Flag	List the voice IDs; supports `--json`
`--speed`	`1.0`	Speed factor, 0.5 to 2.0; larger values are faster
`--threads`, `-t`	`4`	CPU workers, 1 to 64
`--lexicon`	Extra file	Additional or overriding English pronunciations
`--models-dir`	`~/.spum/models`	Speech model directory
`--json`	Flag	Structured output path, duration and timing fields on stdout
`--quiet`	Flag	Suppress timing summaries

--json describes the WAV output; it does not embed its audio bytes. No sound is played automatically. Open the WAV in a player or pass it to an application of your choice.

Pronunciation and numbers¶

The English pack combines openly licensed Misaki and CMUdict pronunciation data. Spum validates dictionary coverage before synthesis. An unknown word causes a clear error instead of being silently skipped.

To add an entry, create a UTF-8 dictionary with a word, ||, and model-supported phonemes separated by spaces. For example, the package's Spum pronunciation is:

spum || s p ˈ ʌ m

spum speak --text "Spum is ready." --lexicon pronunciations.txt --output speech.wav

The extra dictionary is applied after the bundled dictionary, so it can override an entry. It must use the Kokoro model's phoneme alphabet; arbitrary English spellings in the phoneme column are not valid pronunciations.

Digits are read individually, and % becomes “percent.” Write a number out in words when you want a particular reading. This release does not interpret medical units, dates, abbreviations or multilingual text semantically. Review critical spoken content before use.

Use a different model directory¶

spum models download whisper-base-en --models-dir /path/to/speech-models
spum transcribe recording.wav --models-dir /path/to/speech-models --json

A model ID resolves under the selected directory. An explicit pack directory can also be passed directly to --model.

What was tested¶

The published functional-check record covers three reference recordings, including an 8 kHz input, and three synthesized phrases. The normalized recognition comparison counted three differences across 77 reference words. The synthesis checks verified finite, non-silent 24 kHz audio and recovered all words in an ASR roundtrip for those three phrases.

These are small integration checks, not a general ASR benchmark or a perceptual listening study. A synthesis-to-recognition roundtrip is not independent proof of voice quality. Noise, accents, names, unfamiliar terminology and chunk boundaries can affect results. Nothing here establishes clinical transcription accuracy.

The published CLI checks also cover M4A, MP3, stereo resampling, silence, malformed options, unknown pronunciations, checksum failure and input-file preservation. There are no audio HTTP endpoints or speech controls in the desktop app in this release.

Upstream comparisons¶

Measured Spum Voice comparisons include Maya on an H200, Kokoro on the Mac CPU and a classical eSpeak NG reference. The page includes parameters, audio, automatic-transcription checks and blind listening controls. It reports deployment differences explicitly; no faster-Maya-kernel or superior-naturalness claim is made.

The released speak command uses the native Kokoro pack. Maya speech in the Reasoning example runs in a separately configured DGX worker; it is not an additional native speak backend in this release.