​

Text-to-speech (TTS)

​

Supported services

• ElevenLabs (primary or fallback provider)
• Microsoft (primary or fallback provider; current bundled implementation uses node-edge-tts, default when no API keys)
• OpenAI (primary or fallback provider; also used for summaries)

​

Microsoft speech notes

​

Optional keys

• ELEVENLABS_API_KEY (or XI_API_KEY)
• OPENAI_API_KEY

​

Service links

• OpenAI Text-to-Speech guide
• OpenAI Audio API reference
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• node-edge-tts
• Microsoft Speech output formats

​

Is it enabled by default?

​

Config

​

Minimal config (enable + provider)

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}

​

OpenAI primary with ElevenLabs fallback

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
    },
  },
}

​

Microsoft primary (no API key)

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      microsoft: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        rate: "+10%",
        pitch: "-5%",
      },
    },
  },
}

​

Disable Microsoft speech

{
  messages: {
    tts: {
      microsoft: {
        enabled: false,
      },
    },
  },
}

​

Custom limits + prefs path

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.pllan/settings/tts.json",
    },
  },
}

​

Only reply with audio after an inbound voice note

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

​

Disable auto-summary for long replies

{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

/tts summary off

​

Notes on fields

• auto: auto‑TTS mode (off, always, inbound, tagged).
  • inbound only sends audio after an inbound voice note.
  • tagged only sends audio when the reply includes [[tts]] tags.
• enabled: legacy toggle (doctor migrates this to auto).
• mode: "final" (default) or "all" (includes tool/block replies).
• provider: speech provider id such as "elevenlabs", "microsoft", or "openai" (fallback is automatic).
• If provider is unset, Pllan prefers openai (if key), then elevenlabs (if key), otherwise microsoft.
• Legacy provider: "edge" still works and is normalized to microsoft.
• summaryModel: optional cheap model for auto-summary; defaults to agents.defaults.model.primary.
  • Accepts provider/model or a configured model alias.
• modelOverrides: allow the model to emit TTS directives (on by default).
  • allowProvider defaults to false (provider switching is opt-in).
• maxTextLength: hard cap for TTS input (chars). /tts audio fails if exceeded.
• timeoutMs: request timeout (ms).
• prefsPath: override the local prefs JSON path (provider/limit/summary).
• apiKey values fall back to env vars (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: override ElevenLabs API base URL.
• openai.baseUrl: override the OpenAI TTS endpoint.
  • Resolution order: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • Non-default values are treated as OpenAI-compatible TTS endpoints, so custom model and voice names are accepted.
• elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = normal)
• elevenlabs.applyTextNormalization: auto|on|off
• elevenlabs.languageCode: 2-letter ISO 639-1 (e.g. en, de)
• elevenlabs.seed: integer 0..4294967295 (best-effort determinism)
• microsoft.enabled: allow Microsoft speech usage (default true; no API key).
• microsoft.voice: Microsoft neural voice name (e.g. en-US-MichelleNeural).
• microsoft.lang: language code (e.g. en-US).
• microsoft.outputFormat: Microsoft output format (e.g. audio-24khz-48kbitrate-mono-mp3).
  • See Microsoft Speech output formats for valid values; not all formats are supported by the bundled Edge-backed transport.
• microsoft.rate / microsoft.pitch / microsoft.volume: percent strings (e.g. +10%, -5%).
• microsoft.saveSubtitles: write JSON subtitles alongside the audio file.
• microsoft.proxy: proxy URL for Microsoft speech requests.
• microsoft.timeoutMs: request timeout override (ms).
• edge.*: legacy alias for the same Microsoft settings.

​

Model-driven overrides (default on)

Here you go.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

• provider (registered speech provider id, for example openai, elevenlabs, or microsoft; requires allowProvider: true)
• voice (OpenAI voice) or voiceId (ElevenLabs)
• model (OpenAI TTS model or ElevenLabs model id)
• stability, similarityBoost, style, speed, useSpeakerBoost
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: false,
      },
    },
  },
}

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: true,
        allowProvider: true,
        allowSeed: false,
      },
    },
  },
}

​

Per-user preferences

• enabled
• provider
• maxLength (summary threshold; default 1500 chars)
• summarize (default true)

​

Output formats (fixed)

• Telegram: Opus voice note (opus_48000_64 from ElevenLabs, opus from OpenAI).
  • 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble.
• Other channels: MP3 (mp3_44100_128 from ElevenLabs, mp3 from OpenAI).
  • 44.1kHz / 128kbps is the default balance for speech clarity.
• Microsoft: uses microsoft.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
  • The bundled transport accepts an outputFormat, but not all formats are available from the service.
  • Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus).
  • Telegram sendVoice accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need guaranteed Opus voice notes. citeturn1search1
  • If the configured Microsoft output format fails, Pllan retries with MP3.

​

Auto-TTS behavior

• skips TTS if the reply already contains media or a MEDIA: directive.
• skips very short replies (< 10 chars).
• summarizes long replies when enabled using agents.defaults.model.primary (or summaryModel).
• attaches the generated audio to the reply.

​

Flow diagram

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / MEDIA: / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

​

Slash command usage

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from Pllan

• Commands require an authorized sender (allowlist/owner rules still apply).
• commands.text or native command registration must be enabled.
• off|always|inbound|tagged are per‑session toggles (/tts on is an alias for /tts always).
• limit and summary are stored in local prefs, not the main config.
• /tts audio generates a one-off audio reply (does not toggle TTS on).

​

Agent tool

​

Gateway RPC

• tts.status
• tts.enable
• tts.disable
• tts.convert
• tts.setProvider
• tts.providers