Text-to-speech (TTS)

Mayros dapat mengonversi balasan keluar menjadi audio menggunakan ElevenLabs, OpenAI, atau Edge TTS. Ini berfungsi di mana pun Mayros dapat mengirim audio; Telegram mendapatkan bubble voice-note bulat.

Layanan yang didukung

• ElevenLabs (provider utama atau fallback)
• OpenAI (provider utama atau fallback; juga digunakan untuk ringkasan)
• Edge TTS (provider utama atau fallback; menggunakan node-edge-tts, default ketika tidak ada API key)

Catatan Edge TTS

Edge TTS menggunakan layanan TTS neural online Microsoft Edge melalui library node-edge-tts. Ini adalah layanan yang dihosting (bukan lokal), menggunakan endpoint Microsoft, dan tidak memerlukan API key. node-edge-tts mengekspos opsi konfigurasi ucapan dan format output, tetapi tidak semua opsi didukung oleh layanan Edge.

Karena Edge TTS adalah layanan web publik tanpa SLA atau kuota yang dipublikasikan, perlakukan ini sebagai best-effort. Jika Anda memerlukan batas dan dukungan yang terjamin, gunakan OpenAI atau ElevenLabs. REST API Speech Microsoft mendokumentasikan batas audio 10 menit per permintaan; Edge TTS tidak mempublikasikan batas, jadi asumsikan batas yang sama atau lebih rendah.

Key opsional

Jika Anda ingin OpenAI atau ElevenLabs:

• ELEVENLABS_API_KEY (atau XI_API_KEY)
• OPENAI_API_KEY

Edge TTS tidak memerlukan API key. Jika tidak ada API key yang ditemukan, Mayros default ke Edge TTS (kecuali dinonaktifkan melalui messages.tts.edge.enabled=false).

Jika beberapa provider dikonfigurasi, provider yang dipilih digunakan terlebih dahulu dan yang lain adalah opsi fallback. Ringkasan otomatis menggunakan summaryModel yang dikonfigurasi (atau agents.defaults.model.primary), jadi provider itu juga harus diautentikasi jika Anda mengaktifkan ringkasan.

Link layanan

• Panduan OpenAI Text-to-Speech
• Referensi API Audio OpenAI
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• node-edge-tts
• Format output Microsoft Speech

Apakah diaktifkan secara default?

Tidak. Auto-TTS off secara default. Aktifkan di konfigurasi dengan messages.tts.auto atau per sesi dengan /tts always (alias: /tts on).

Edge TTS diaktifkan secara default setelah TTS on, dan digunakan secara otomatis ketika tidak ada API key OpenAI atau ElevenLabs yang tersedia.

Konfigurasi

Konfigurasi TTS berada di bawah messages.tts di mayros.json. Skema lengkap ada di Konfigurasi Gateway.

Konfigurasi minimal (aktifkan + provider)

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

OpenAI utama dengan fallback ElevenLabs

json5Copy
{
  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 utama (tanpa API key)

json5Copy
{
  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%",
      },
    },
  },
}

Nonaktifkan Edge TTS

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

Batas kustom + path preferensi

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

Hanya balas dengan audio setelah voice note masuk

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

Nonaktifkan ringkasan otomatis untuk balasan panjang

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

Kemudian jalankan:

/tts summary off

Catatan tentang field

• auto: mode auto-TTS (off, always, inbound, tagged).
  • inbound hanya mengirim audio setelah voice note masuk.
  • tagged hanya mengirim audio ketika balasan menyertakan tag [[tts]].
• enabled: toggle warisan (doctor memigrasikan ini ke auto).
• mode: "final" (default) atau "all" (termasuk balasan tool/blok).
• provider: "elevenlabs", "openai", atau "edge" (fallback otomatis).
• Jika provider tidak diset, Mayros lebih suka openai (jika key), lalu elevenlabs (jika key), jika tidak edge.
• summaryModel: model murah opsional untuk ringkasan otomatis; default ke agents.defaults.model.primary.
  • Menerima provider/model atau alias model yang dikonfigurasi.
• modelOverrides: izinkan model mengeluarkan direktif TTS (on secara default).
  • allowProvider default ke false (peralihan provider adalah opt-in).
• maxTextLength: batas keras untuk input TTS (karakter). /tts audio gagal jika terlampaui.
• timeoutMs: timeout permintaan (ms).
• prefsPath: ganti path JSON preferensi lokal (provider/limit/summary).
• Nilai apiKey fallback ke var env (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: ganti base URL API ElevenLabs.
• 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: ISO 639-1 2 huruf (misalnya en, de)
• elevenlabs.seed: integer 0..4294967295 (determinisme best-effort)
• edge.enabled: izinkan penggunaan Edge TTS (default true; tidak ada API key).
• edge.voice: nama voice neural Edge (misalnya en-US-MichelleNeural).
• edge.lang: kode bahasa (misalnya en-US).
• edge.outputFormat: format output Edge (misalnya audio-24khz-48kbitrate-mono-mp3).
  • Lihat format output Microsoft Speech untuk nilai yang valid; tidak semua format didukung oleh Edge.
• edge.rate / edge.pitch / edge.volume: string persen (misalnya +10%, -5%).
• edge.saveSubtitles: tulis subtitle JSON di samping file audio.
• edge.proxy: URL proxy untuk permintaan Edge TTS.
• edge.timeoutMs: override timeout permintaan (ms).

Override yang didorong model (default on)

Secara default, model dapat mengeluarkan direktif TTS untuk satu balasan. Ketika messages.tts.auto adalah tagged, direktif ini diperlukan untuk memicu audio.

Ketika diaktifkan, model dapat mengeluarkan direktif [[tts:...]] untuk mengganti voice untuk satu balasan, plus blok [[tts:text]]...[[/tts:text]] opsional untuk menyediakan tag ekspresif (tawa, isyarat menyanyi, dll.) yang hanya muncul di audio.

Direktif provider=... diabaikan kecuali modelOverrides.allowProvider: true.

Contoh payload balasan:

Here you go.

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

Key direktif yang tersedia (ketika diaktifkan):

• provider (openai | elevenlabs | edge, memerlukan allowProvider: true)
• voice (voice OpenAI) atau voiceId (ElevenLabs)
• model (model TTS OpenAI atau id model ElevenLabs)
• stability, similarityBoost, style, speed, useSpeakerBoost
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Nonaktifkan semua override model:

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

Allowlist opsional (aktifkan peralihan provider sambil menjaga tombol lain dapat dikonfigurasi):

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

Preferensi per-pengguna

Slash command menulis override lokal ke prefsPath (default: ~/.mayros/settings/tts.json, ganti dengan MAYROS_TTS_PREFS atau messages.tts.prefsPath).

Field yang disimpan:

• enabled
• provider
• maxLength (threshold ringkasan; default 1500 karakter)
• summarize (default true)

Ini mengganti messages.tts.* untuk host itu.

Format output (tetap)

• Telegram: Voice note Opus (opus_48000_64 dari ElevenLabs, opus dari OpenAI).
  • 48kHz / 64kbps adalah tradeoff voice-note yang baik dan diperlukan untuk bubble bulat.
• Channel lain: MP3 (mp3_44100_128 dari ElevenLabs, mp3 dari OpenAI).
  • 44.1kHz / 128kbps adalah keseimbangan default untuk kejelasan ucapan.
• Edge TTS: menggunakan edge.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
  • node-edge-tts menerima outputFormat, tetapi tidak semua format tersedia dari layanan Edge.
  • Nilai format output mengikuti format output Microsoft Speech (termasuk Ogg/WebM Opus).
  • sendVoice Telegram menerima OGG/MP3/M4A; gunakan OpenAI/ElevenLabs jika Anda memerlukan voice note Opus yang terjamin.
  • Jika format output Edge yang dikonfigurasi gagal, Mayros mencoba ulang dengan MP3.

Format OpenAI/ElevenLabs tetap; Telegram mengharapkan Opus untuk UX voice-note.

Perilaku auto-TTS

Ketika diaktifkan, Mayros:

• melewati TTS jika balasan sudah berisi media atau direktif MEDIA:.
• melewati balasan yang sangat pendek (< 10 karakter).
• meringkas balasan panjang ketika diaktifkan menggunakan agents.defaults.model.primary (atau summaryModel).
• melampirkan audio yang dihasilkan ke balasan.

Jika balasan melebihi maxLength dan ringkasan off (atau tidak ada API key untuk model ringkasan), audio dilewati dan balasan teks normal dikirim.

Diagram alur

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

Penggunaan slash command

Ada satu command: /tts. Lihat Slash command untuk detail pengaktifan.

Catatan Discord: /tts adalah command Discord bawaan, jadi Mayros mendaftarkan /voice sebagai command native di sana. Teks /tts ... masih berfungsi.

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

Catatan:

• Command memerlukan pengirim yang diotorisasi (aturan allowlist/owner masih berlaku).
• commands.text atau pendaftaran command native harus diaktifkan.
• off|always|inbound|tagged adalah toggle per-sesi (/tts on adalah alias untuk /tts always).
• limit dan summary disimpan di preferensi lokal, bukan konfigurasi utama.
• /tts audio menghasilkan balasan audio satu kali (tidak mengaktifkan TTS).

Tool agen

Tool tts mengonversi teks ke ucapan dan mengembalikan path MEDIA:. Ketika hasilnya kompatibel dengan Telegram, tool menyertakan [[audio_as_voice]] sehingga Telegram mengirim bubble voice.

RPC Gateway

Metode gateway:

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