Skip to content

TTS Plugins Reference

In a nutshell

This page holds the full technical entry for each TTS plugin in the roster: repository link, license notes, and a default configuration snippet where one exists. Start at TTS Plugins to pick a plugin, come here for the exact settings.

ovos-tts-server

ovos-tts-plugin-polly

ovos-tts-plugin-google-tx

Note

gTTS works by calling the same unofficial, undocumented endpoint used by the Google Translate web UI's "listen" feature. It is not a published, API-keyed Google Cloud Text-to-Speech API. Google can change or revoke access to this endpoint at any time.

Default Configuration

  "tts": {
    "module": "ovos-tts-plugin-google-tx",
    "ovos-tts-plugin-google-tx": {
        "tld": "com",
        "slow": false,
        "lang_check": false
    }
  }

tld only takes the configured value for languages outside the plugin's internal regional table. About 15 common locales (en-US, en-GB, fr-FR, pt-PT, es-ES, and others) always use that table's fixed TLD instead, no matter what tld is set to.

ovos-tts-plugin-edge-tts

ovos-tts-plugin-matxa-multispeaker-cat

Example Configuration

  "tts": {
    "module": "ovos-tts-plugin-matxa-multispeaker-cat",
    "ovos-tts-plugin-matxa-multispeaker-cat": {
      "voice": "valencia/gina"
    }
  }

ovos-tts-plugin-piper

  • GitHub: https://github.com/OpenVoiceOS/ovos-tts-plugin-piper

  • Description: Offline neural TTS using the Piper engine (ONNX voices). This is the default TTS on the raspOVOS hybrid and offline images. Warning: archived. phoonnx runs Piper ONNX voices (including the kusal voice) and is the maintained successor.

  • Config: set "module": "ovos-tts-plugin-piper" in the tts block. A "voice" key selects a specific Piper voice model, without it the plugin picks a voice for the configured language.

ovos-tts-plugin-marytts

url is required (the plugin refuses to load without it); only voice has a default (cmu-slt-hsmm). Point url at your own MaryTTS server:

"tts": {
    "module": "ovos-tts-plugin-marytts",
    "ovos-tts-plugin-marytts": {
      "url": "http://0.0.0.0:59125",
      "voice": "cmu-slt-hsmm"
    }
}

ovos-tts-plugin-espeakNG

ovos-tts-plugin-beepspeak

ovos-tts-plugin-cotovia

Example Configuration

  "tts": {
    "module": "ovos-tts-plugin-cotovia",
    "ovos-tts-plugin-cotovia": {
      "voice": "sabela"
    }
  }

Leaving voice unset (or "default") does not resolve to a fixed voice: the plugin lists whatever cotovia-voice-* packages are installed under data_path (/usr/share/cotovia/data unless overridden) and picks the first entry in directory order, which is not deterministic across installs. Cotovia's own docs call sabela the recommended default among its three voices (iago, sabela-large, sabela), so set voice explicitly if a stable choice matters.

ovos-tts-plugin-mimic

Default Configuration

  "tts": {
    "module": "ovos-tts-plugin-mimic",
    "ovos-tts-plugin-mimic": {
      "voice": "ap"
    }
  }

Two more keys default unset: binary (path to the mimic executable; unset autodetects via XDG premium-mimic paths, then mimic on PATH) and duration_stretch (unset applies no stretch; when set, passed through as mimic's --setf duration_stretch=<value>).

ovos-tts-plugin-SAM

ovos-tts-plugin-azure

Default Configuration

Never commit a real api_key

Treat this like any other credential: keep the real value out of version control and shared config files. Use a local, untracked config or an environment-backed secret store instead of hard-coding it in mycroft.conf.

"tts": {
    "module": "ovos-tts-plugin-azure",
    "ovos-tts-plugin-azure": {
        "api_key": "insert_your_key_here",
        "voice": "en-US-JennyNeural",  // optional, this is already the default
        "region": "westus" // optional, if your region is westus
    }
}

ovos-tts-plugin-ahotts

Required Configuration

  "tts": {
    "module": "ovos-tts-plugin-ahotts",
    "ovos-tts-plugin-ahotts": {
        "lang": "eu"
    }
  }

lang has no default here: it must be es or eu, and the plugin raises a ValueError on any other configured language.

ovos-tts-server-plugin

Talks to a public community server by default

The host below points at a best-effort, publicly-run community server, not a private or guaranteed-available endpoint. Point it at your own self-hosted server (see tts-server) if you need privacy or reliability.

  "tts": {
    "module": "ovos-tts-plugin-server",
    "ovos-tts-plugin-server": {
        "host": "https://tts.smartgic.io/piper",
        "v2": true,
        "verify_ssl": true,
        "tts_timeout": 5
     }
 }

When host is omitted (the true default), the plugin shuffles the public community server list (tts.openvoiceos.pt and tts.smartgic.io/piper) and tries them in order. Either way these are public community-run servers, not addresses on your network. See tts-server to self-host, or pick a fully offline voice from the table on the TTS Plugins page.

Community servers are best-effort demos

The public OVOS servers exist for easy onboarding and demos only. They are best-effort, not optimized, carry no uptime guarantees, and may vanish at any time. OVOS will be slow and unreliable if you rely on them. The official recommendation is to self-host — or skip servers entirely: fully offline plugins exist for everything.

ovos-tts-plugin-coqui

Example Configuration

  "tts": {
    "module": "ovos-tts-plugin-coqui",
    "ovos-tts-plugin-coqui": {}
  }

There is no single hardcoded default model. Leaving model unset resolves one from an internal LANG2MODEL table keyed by lang, and raises ValueError at load if the configured language has no entry and no model is set explicitly — pass model directly for a language the table doesn't cover.

ovos-tts-plugin-pico

ovos-tts-plugin-phoonnx

  • GitHub: TigreGotico/phoonnx

  • Description: OVOS's own multilingual, ONNX-based neural TTS engine, distributed as part of the phoonnx package. Registering the plugin only requires pip install phoonnx. Model files are fetched and cached automatically the first time a voice is used.

Example Configuration

  "tts": {
    "module": "ovos-tts-plugin-phoonnx",
    "ovos-tts-plugin-phoonnx": {
      "voice": "OpenVoiceOS/phoonnx_pt-PT_miro_tugaphone"
    }
  }

If "voice" is omitted, the plugin picks the first bundled model that supports the configured language.

Per-language default voices

A configured voice pins one voice regardless of request language. For multilingual serving (1.86.0a1+), the lang2voice config map, e.g. {"pt-br": "...", "gl": "..."}, and PHOONNX_DEFAULT_VOICE_<LANG> env vars resolve the default voice per request language. Keys are BCP-47 tags, full tag tried before primary subtag, and resolution is table-major: the whole lang2voice table wins outright for any language it names before env vars are consulted at all. Spellings are normalized on both sides (gl-ES/gl, pt-br/pt_BR agree). An entry naming a nonexistent voice logs the mistake and falls back to the voice index's own default rather than refusing to serve the language.

Bounding the voice cache

Loaded voice models stay resident in an in-process cache. Two settings bound it, and they are not equivalent:

Key Bounds by Default
max_loaded_bytes Total size in memory, LRU-evicted. Accepts a plain byte count or a human size like "3GB", "512MB", "1.5GiB" (KB/MB/GB/TB are powers of 1000, KiB/MiB/GiB/TiB powers of 1024). unset (no budget)
max_loaded_voices Count of resident voices, LRU-evicted. unset (no limit)
load_wait_timeout Seconds a load waits for resident memory to free up before proceeding anyway. 300

max_loaded_voices is the older setting and a poor bound on this catalog: a Piper voice is around 60 MB while an omnivoice voice is around 2.2 GB, roughly a 40x spread, so a count that is safe for small voices is fatal for large ones. max_loaded_bytes bounds by the actual resident size instead, and is the one to reach for on a mixed catalog. (Mirrors max_loaded_mb on the linguonnx plugins.)

  "tts": {
    "module": "ovos-tts-plugin-phoonnx",
    "ovos-tts-plugin-phoonnx": {
      "voice": "OpenVoiceOS/phoonnx_pt-PT_miro_tugaphone",
      "pinned_voices": ["OpenVoiceOS/phoonnx_pt-PT_miro_tugaphone"],
      "max_loaded_bytes": "3GB"
    }
  }

pinned_voices (a string or a list) names voices that are loaded at startup and never evicted. The two caps treat pins differently. If more voices are pinned than max_loaded_voices allows, that count limit is raised to fit them (logged as an error so the mismatch isn't silent). The max_loaded_bytes size budget is never raised: a pin that fits individually still loads even when resident usage then exceeds the budget (again logged, not fatal). A failed pin never stops the service from starting.

This refusal applies to any voice load, not only pins: any voice whose own known on-disk size alone exceeds the whole max_loaded_bytes budget is refused with VoiceExceedsMemoryBudget and never becomes resident — loading it would be a guaranteed OOM kill, not a degraded path. A voice that fits on its own but not beside what is currently resident instead waits for room: up to load_wait_timeout seconds (default 300) for another load to finish or a leased voice to be released, after which it loads anyway and logs a warning that memory use will exceed the budget. A voice not yet downloaded can't be measured and is treated as needing the whole budget, so it always loads alone.

Size the budget for the actual peak, not just the steady state: peak resident memory is the cached models plus whatever is loading in flight at that moment, and a request that arrives mid-load can tip a box over even when the cache's own ceiling looks safe.

Read next: TTS Plugins Related: Writing a TTS Plugin · TTS Server · SSML