Text-to-speech (TTS)

Mayros ElevenLabs, OpenAI या Edge TTS का उपयोग करके outbound replies को audio में convert कर सकता है। यह कहीं भी काम करता है जहां Mayros audio भेज सकता है; Telegram को एक round voice-note bubble मिलता है।

समर्थित सेवाएं

  • ElevenLabs (primary या fallback provider)
  • OpenAI (primary या fallback provider; summaries के लिए भी उपयोग किया जाता है)
  • Edge TTS (primary या fallback provider; node-edge-tts का उपयोग करता है, कोई API keys नहीं होने पर डिफ़ॉल्ट)

Edge TTS नोट्स

Edge TTS node-edge-tts library के माध्यम से Microsoft Edge की online neural TTS service का उपयोग करता है। यह एक hosted service है (स्थानीय नहीं), Microsoft के endpoints का उपयोग करती है, और API key की आवश्यकता नहीं है। node-edge-tts speech configuration विकल्प और output formats को expose करता है, लेकिन सभी विकल्प Edge service द्वारा समर्थित नहीं हैं।

क्योंकि Edge TTS बिना published SLA या quota के एक public web service है, इसे best-effort के रूप में treat करें। यदि आपको guaranteed limits और support की आवश्यकता है, तो OpenAI या ElevenLabs का उपयोग करें। Microsoft की Speech REST API प्रति request 10‑मिनट की audio limit को document करती है; Edge TTS limits publish नहीं करता, इसलिए समान या कम limits मान लें।

वैकल्पिक keys

यदि आप OpenAI या ElevenLabs चाहते हैं:

  • ELEVENLABS_API_KEY (या XI_API_KEY)
  • OPENAI_API_KEY

Edge TTS को API key की आवश्यकता नहीं है। यदि कोई API keys नहीं मिलते, तो Mayros डिफ़ॉल्ट रूप से Edge TTS करता है (जब तक कि messages.tts.edge.enabled=false के माध्यम से अक्षम न हो)।

यदि कई providers कॉन्फ़िगर हैं, तो चयनित provider पहले उपयोग किया जाता है और अन्य fallback विकल्प हैं। Auto-summary कॉन्फ़िगर किए गए summaryModel (या agents.defaults.model.primary) का उपयोग करता है, इसलिए यदि आप summaries सक्षम करते हैं तो उस provider को भी प्रमाणित किया जाना चाहिए।

Service लिंक

क्या यह डिफ़ॉल्ट रूप से सक्षम है?

नहीं। Auto‑TTS डिफ़ॉल्ट रूप से बंद है। इसे कॉन्फ़िगरेशन में messages.tts.auto या /tts always (alias: /tts on) के साथ प्रति session सक्षम करें।

Edge TTS TTS on होने के बाद डिफ़ॉल्ट रूप से सक्षम है, और स्वचालित रूप से उपयोग किया जाता है जब कोई OpenAI या ElevenLabs API keys उपलब्ध नहीं होते।

कॉन्फ़िगरेशन

TTS कॉन्फ़िगरेशन mayros.json में messages.tts के तहत रहता है। पूर्ण schema Gateway configuration में है।

न्यूनतम कॉन्फ़िगरेशन (सक्षम + provider)

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

ElevenLabs fallback के साथ OpenAI primary

json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      openai: {
        apiKey: "openai_api_key",
        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,
        },
      },
    },
  },
}

Edge TTS primary (कोई API key नहीं)

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

Edge TTS अक्षम करें

json5
{
  messages: {
    tts: {
      edge: {
        enabled: false,
      },
    },
  },
}

Custom limits + prefs path

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

केवल inbound voice note के बाद audio reply

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

लंबे replies के लिए auto-summary अक्षम करें

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

फिर चलाएं:

/tts summary off

फ़ील्ड्स पर नोट्स

  • auto: auto‑TTS mode (off, always, inbound, tagged)।
    • inbound केवल inbound voice note के बाद audio भेजता है।
    • tagged केवल तब audio भेजता है जब reply में [[tts]] tags शामिल हों।
  • enabled: legacy toggle (doctor इसे auto में migrate करता है)।
  • mode: "final" (डिफ़ॉल्ट) या "all" (tool/block replies शामिल करता है)।
  • provider: "elevenlabs", "openai" या "edge" (fallback automatic है)।
  • यदि provider unset है, तो Mayros openai prefer करता है (यदि key), फिर elevenlabs (यदि key), अन्यथा edge।
  • summaryModel: auto-summary के लिए वैकल्पिक cheap model; agents.defaults.model.primary पर default करता है।
    • provider/model या configured model alias स्वीकार करता है।
  • modelOverrides: model को TTS directives emit करने दें (डिफ़ॉल्ट रूप से on)।
    • allowProvider false पर default करता है (provider switching opt-in है)।
  • maxTextLength: TTS input के लिए hard cap (chars)। exceed होने पर /tts audio fail होता है।
  • timeoutMs: request timeout (ms)।
  • prefsPath: local prefs JSON path override करें (provider/limit/summary)।
  • apiKey values env vars (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY) पर fall back करते हैं।
  • elevenlabs.baseUrl: ElevenLabs API base URL override करें।
  • 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 (जैसे en, de)
  • elevenlabs.seed: integer 0..4294967295 (best-effort determinism)
  • edge.enabled: Edge TTS उपयोग अनुमति दें (डिफ़ॉल्ट true; कोई API key नहीं)।
  • edge.voice: Edge neural voice name (जैसे en-US-MichelleNeural)।
  • edge.lang: language code (जैसे en-US)।
  • edge.outputFormat: Edge output format (जैसे audio-24khz-48kbitrate-mono-mp3)।
    • Valid values के लिए Microsoft Speech output formats देखें; सभी formats Edge द्वारा समर्थित नहीं हैं।
  • edge.rate / edge.pitch / edge.volume: percent strings (जैसे +10%, -5%)।
  • edge.saveSubtitles: audio file के साथ JSON subtitles लिखें।
  • edge.proxy: Edge TTS requests के लिए proxy URL।
  • edge.timeoutMs: request timeout override (ms)।

Model-driven overrides (डिफ़ॉल्ट on)

डिफ़ॉल्ट रूप से, model एक single reply के लिए TTS directives emit कर सकता है। जब messages.tts.auto tagged है, तो audio trigger करने के लिए ये directives आवश्यक हैं।

जब enabled हो, model एक single reply के लिए voice override करने के लिए [[tts:...]] directives emit कर सकता है, साथ ही expressive tags (laughter, singing cues, आदि) प्रदान करने के लिए एक वैकल्पिक [[tts:text]]...[[/tts:text]] block जो केवल audio में दिखाई देना चाहिए।

provider=... directives ignore किए जाते हैं जब तक modelOverrides.allowProvider: true न हो।

उदाहरण reply payload:

Here you go.

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

उपलब्ध directive keys (जब enabled):

  • provider (openai | elevenlabs | edge, allowProvider: true आवश्यक)
  • voice (OpenAI voice) या voiceId (ElevenLabs)
  • model (OpenAI TTS model या ElevenLabs model id)
  • stability, similarityBoost, style, speed, useSpeakerBoost
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed

सभी model overrides अक्षम करें:

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

वैकल्पिक allowlist (अन्य knobs configurable रखते हुए provider switching सक्षम करें):

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

Per-user preferences

Slash commands prefsPath (default: ~/.mayros/settings/tts.json, MAYROS_TTS_PREFS या messages.tts.prefsPath से override करें) में local overrides लिखते हैं।

संग्रहीत फ़ील्ड्स:

  • enabled
  • provider
  • maxLength (summary threshold; डिफ़ॉल्ट 1500 chars)
  • summarize (डिफ़ॉल्ट true)

ये उस host के लिए messages.tts.* को override करते हैं।

Output formats (fixed)

  • Telegram: Opus voice note (opus_48000_64 ElevenLabs से, opus OpenAI से)।
    • 48kHz / 64kbps एक अच्छा voice-note tradeoff है और round bubble के लिए आवश्यक है।
  • अन्य channels: MP3 (mp3_44100_128 ElevenLabs से, mp3 OpenAI से)।
    • 44.1kHz / 128kbps speech clarity के लिए डिफ़ॉल्ट balance है।
  • Edge TTS: edge.outputFormat (डिफ़ॉल्ट audio-24khz-48kbitrate-mono-mp3) का उपयोग करता है।
    • node-edge-tts एक outputFormat स्वीकार करता है, लेकिन सभी formats Edge service से उपलब्ध नहीं हैं।
    • Output format values Microsoft Speech output formats (Ogg/WebM Opus सहित) का पालन करते हैं।
    • Telegram sendVoice OGG/MP3/M4A स्वीकार करता है; guaranteed Opus voice notes के लिए OpenAI/ElevenLabs का उपयोग करें।
    • यदि configured Edge output format fail होता है, तो Mayros MP3 के साथ retry करता है।

OpenAI/ElevenLabs formats fixed हैं; Telegram voice-note UX के लिए Opus expect करता है।

Auto-TTS व्यवहार

जब सक्षम हो, तो Mayros:

  • TTS skip करता है यदि reply में पहले से media या MEDIA: directive है।
  • बहुत छोटे replies (< 10 chars) skip करता है।
  • सक्षम होने पर agents.defaults.model.primary (या summaryModel) का उपयोग करके लंबे replies summarize करता है।
  • जेनरेट की गई audio को reply में attach करता है।

यदि reply maxLength से अधिक है और summary बंद है (या summary model के लिए कोई API key नहीं), तो audio skip है और सामान्य text 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 उपयोग

एक single command है: /tts। Enablement विवरण के लिए Slash commands देखें।

Discord नोट: /tts एक built-in Discord command है, इसलिए Mayros /voice को native command के रूप में वहां register करता है। Text /tts ... अभी भी काम करता है।

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

नोट्स:

  • Commands को एक authorized sender की आवश्यकता है (allowlist/owner नियम अभी भी लागू होते हैं)।
  • commands.text या native command registration सक्षम होना चाहिए।
  • off|always|inbound|tagged प्रति‑session toggles हैं (/tts on /tts always के लिए alias है)।
  • limit और summary local prefs में संग्रहीत हैं, मुख्य कॉन्फ़िगरेशन में नहीं।
  • /tts audio एक one-off audio reply जेनरेट करता है (TTS on नहीं करता)।

Agent tool

tts tool text को speech में convert करता है और एक MEDIA: path लौटाता है। जब result Telegram-compatible है, तो tool [[audio_as_voice]] शामिल करता है ताकि Telegram एक voice bubble भेजे।

Gateway RPC

Gateway methods:

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