Isimud

isimud is the text-to-speech counterpart tomuninn, which turns speech into text for agents.

cargo build --release --bin isimud ./target/release/isimud --version

mkdir -p ~/.config/isimud cp configs/config.sample.toml ~/.config/isimud/config.toml

--headless Run only the MCP server -h, --help Print help -V, --version Print the version

If you setISIMUD_AUTH_TOKENor[server].auth_token, add this request header:

The server only binds to loopback IP addresses.127.0.0.1and::1are accepted; hostnames such aslocalhostand non-loopback addresses such as0.0.0.0are rejected at startup.

When auth is configured, requests without the exact bearer token return HTTP401.

{ "text": "Build finished.", "voice": "default", "rate": 1.0 }

The call returns immediately by default:

{ "job_id": "00000000-0000-0000-0000-000000000000", "queue_depth": 0 }

Setwaittotruewhen the MCP caller should block until the utterance completes, fails, is cancelled, or reaches[tts].wait_timeout_secs:

{ "text": "Deployment complete.", "wait": true }

Withwait=true, the response includesoutcome:

{ "job_id": "00000000-0000-0000-0000-000000000000", "queue_depth": 0, "outcome": "completed" }

Named voices are the public voice contract for agents. Thevoiceargument toisimud.speakand[tts].default_voicemust match a[voices.<name>]key.

[tts] providers = ["apple", "openai", "google"] default_voice = "default" rate = 1.0 max_queue_depth = 64 wait_timeout_secs = 0 [voices.default] provider = "apple" voice = "Samantha" [voices.narrator] provider = "openai" voice = "onyx" [voices.googler] provider = "google" voice = "en-US-Neural2-C" language = "en-US"

Important:default_voiceis a voice name, not a provider name. To make OpenAI the default, setdefault_voice = "narrator"or create another[voices.<name>]block whoseprovider = "openai".

Optional per-voice fields arelanguage,rate,pitch, andvolume. A requestrateoverrides the voicerate, which overrides[tts].rate; voicevolumedefaults to1.0.

Provider availability follows[tts].providers. If the requested voice's provider is unavailable, isimud selects the first available fallback provider and drops the provider-specific voice ID for that fallback utterance. If no provider is available, the job fails and emits afailedevent.

OpenAI and Google send a rate/speed value only when the resolved rate is within0.25..=4.0. Google sends pitch only when the resolved pitch is within-20..=20.

OpenAI built-in voice IDs exposed byisimud.list_voices:

alloy ash ballad cedar coral echo fable marin nova onyx sage shimmer verse

Google voice listing is intentionally best-effort and currently returns an empty provider catalog; configured named Google voices still work.

Seeconfigs/config.sample.tomlfor the full sample.

{ "queue_depth": 64, "capacity": 64 }

enqueued started finished failed stopped degraded

The active job does not count toward[tts].max_queue_depth. That setting only limits jobs waiting behind the active utterance.

Saving the config file hot-reloads the speech engine and tray palette. Valid changes update voices, provider credentials, speaking rates, queue settings, and tray colors without a restart. Invalid edits are logged and the previous config stays active.

Server bind settings ([server].host,[server].port,[server].path, and auth) and LaunchAgent autostart sync are applied at startup. Restart isimud after changing those settings.

The macOS tray icon is gray while idle and pulses green while speaking. If the speech worker exits unexpectedly or a job panics,isimud.statusreportsdegraded: trueand adegradedevent is broadcast.

The packaged app registers theisimud://URL scheme. Use it to enqueue speech from macOS links or automation:

isimud://speak/Hello%20world isimud://speak?text=Hello%20world&voice=narrator&rate=1.25

The path text takes precedence over thetextquery parameter when both are present. The URL scheme is available when running the packaged.appthat includes theCFBundleURLTypesentry.

In menu bar mode, a left click on the tray icon tries to run the optionalfortunecommand and speak its output. Iffortuneis not installed or returns no text, the click is ignored and a warning is logged.

Set[app].autostart = trueto sync a per-user LaunchAgent at~/Library/LaunchAgents/com.bnomei.isimud.plist. The LaunchAgent uses the current executable path and setsISIMUD_CONFIGto the resolved config path.

When running the packaged.app, prefer macOS Login Items if you want app-style launch behavior.

TARGET=aarch64-apple-darwin scripts/build-release.sh

Build a macOS app bundle and zip archive from an existing release binary:

TARGET=aarch64-apple-darwin scripts/package-macos-app.sh

If you built the default host target withcargo build --release --bin isimud, runscripts/package-macos-app.shwithoutTARGET.

Create a tarball release archive from a built target:

VERSION=$(scripts/resolve-version.sh) TARGET=aarch64-apple-darwin scripts/package-release.sh

cargo test cargo fmt --all -- --check cargo clippy --all-targets --all-features -- -D warnings

This repository also includesprekhooks:

- macOS is the only supported platform.
- The MCP server supports streamable HTTP only; there is no stdio transport.
- The server binds only to loopback addresses.
- Applesayhonorsratebut does not applyvolumeorpitch.
- OpenAI and Google request timeouts are left to the HTTP client and provider/network behavior.[tts].wait_timeout_secsonly limits how long an MCPwait=truecall waits for the job outcome; it does not cancel synthesis.
- isimud validates thattextis non-empty, but it does not enforce a fixed character, byte, token, or provider response-size limit.
- Cloud-provider audio is decoded and played in memory, so very long utterances can increase memory use and playback latency.

- Configuration loading and defaults:src/config.rs
- MCP tools and notification fan-out:src/mcp.rs
- HTTP server and loopback/auth enforcement:src/server.rs
- Named voice resolution:src/voices.rs
- Speech queue and worker:src/worker.rs
- Provider registry and fallback:src/providers/mod.rs
- macOS tray behavior:src/runtime_tray.rs
- URL scheme parsing:src/url_scheme.rs
- macOS app bundle template:packaging/macos/Info.plist.template

Free local MCP server for Apple Mail, Calendar, and Reminders on macOS.