Text-to-speech (TTS)

Mayros può convertire le risposte in uscita in audio utilizzando ElevenLabs, OpenAI o Edge TTS. Funziona ovunque Mayros possa inviare audio; Telegram ottiene una bolla voice-note rotonda.

Servizi supportati

• ElevenLabs (provider primario o fallback)
• OpenAI (provider primario o fallback; usato anche per riepiloghi)
• Edge TTS (provider primario o fallback; usa node-edge-tts, predefinito quando nessuna chiave API)

Note Edge TTS

Edge TTS utilizza il servizio TTS neurale online di Microsoft Edge tramite la libreria node-edge-tts. È un servizio ospitato (non locale), usa gli endpoint di Microsoft, e non richiede una chiave API. node-edge-tts espone opzioni di configurazione speech e formati output, ma non tutte le opzioni sono supportate dal servizio Edge.

Poiché Edge TTS è un servizio web pubblico senza SLA pubblicato o quota, trattalo come best-effort. Se hai bisogno di limiti garantiti e supporto, usa OpenAI o ElevenLabs. L'API REST Speech di Microsoft documenta un limite audio di 10 minuti per richiesta; Edge TTS non pubblica limiti, quindi assumi limiti simili o inferiori.

Chiavi opzionali

Se vuoi OpenAI o ElevenLabs:

• ELEVENLABS_API_KEY (o XI_API_KEY)
• OPENAI_API_KEY

Edge TTS non richiede una chiave API. Se non vengono trovate chiavi API, Mayros usa per default Edge TTS (a meno che non sia disabilitato tramite messages.tts.edge.enabled=false).

Se sono configurati più provider, il provider selezionato viene usato prima e gli altri sono opzioni fallback. Il riepilogo automatico usa il summaryModel configurato (o agents.defaults.model.primary), quindi quel provider deve essere autenticato anche se abiliti i riepiloghi.

Link servizi

• Guida OpenAI Text-to-Speech
• Riferimento API Audio OpenAI
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• node-edge-tts
• Formati output Speech Microsoft

È abilitato per impostazione predefinita?

No. Il TTS automatico è disattivato per impostazione predefinita. Abilitalo nella configurazione con messages.tts.auto o per sessione con /tts always (alias: /tts on).

Edge TTS è abilitato per impostazione predefinita una volta che TTS è attivo, ed è usato automaticamente quando non sono disponibili chiavi API OpenAI o ElevenLabs.

Configurazione

La configurazione TTS risiede in messages.tts in mayros.json. Lo schema completo è in Configurazione Gateway.

Configurazione minima (abilita + provider)

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

OpenAI primario con 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 primario (nessuna chiave API)

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

Disabilita Edge TTS

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

Limiti personalizzati + percorso preferenze

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

Rispondi solo con audio dopo una voice note in arrivo

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

Disabilita riepilogo automatico per risposte lunghe

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

Poi esegui:

/tts summary off

Note sui campi

• auto: modalità TTS automatico (off, always, inbound, tagged).
  • inbound invia audio solo dopo una voice note in arrivo.
  • tagged invia audio solo quando la risposta include tag [[tts]].
• enabled: toggle legacy (doctor migra questo in auto).
• mode: "final" (predefinito) o "all" (include risposte strumento/blocco).
• provider: "elevenlabs", "openai", o "edge" (fallback è automatico).
• Se provider è non impostato, Mayros preferisce openai (se chiave), poi elevenlabs (se chiave), altrimenti edge.
• summaryModel: modello economico opzionale per riepilogo automatico; predefinito a agents.defaults.model.primary.
  • Accetta provider/model o un alias modello configurato.
• modelOverrides: permette al modello di emettere direttive TTS (attivo per default).
  • allowProvider predefinito a false (cambio provider è opt-in).
• maxTextLength: limite rigido per input TTS (caratteri). /tts audio fallisce se superato.
• timeoutMs: timeout richiesta (ms).
• prefsPath: override percorso JSON preferenze locali (provider/limite/riepilogo).
• I valori apiKey fallback a variabili env (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: override URL base API ElevenLabs.
• elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = normale)
• elevenlabs.applyTextNormalization: auto|on|off
• elevenlabs.languageCode: ISO 639-1 a 2 lettere (es. en, de)
• elevenlabs.seed: intero 0..4294967295 (determinismo best-effort)
• edge.enabled: permette uso Edge TTS (predefinito true; nessuna chiave API).
• edge.voice: nome voce neurale Edge (es. en-US-MichelleNeural).
• edge.lang: codice lingua (es. en-US).
• edge.outputFormat: formato output Edge (es. audio-24khz-48kbitrate-mono-mp3).
  • Vedi formati output Speech Microsoft per valori validi; non tutti i formati sono supportati da Edge.
• edge.rate / edge.pitch / edge.volume: stringhe percentuale (es. +10%, -5%).
• edge.saveSubtitles: scrivi sottotitoli JSON accanto al file audio.
• edge.proxy: URL proxy per richieste Edge TTS.
• edge.timeoutMs: override timeout richiesta (ms).

Override guidati da modello (predefinito attivo)

Per impostazione predefinita, il modello può emettere direttive TTS per una singola risposta. Quando messages.tts.auto è tagged, queste direttive sono richieste per attivare l'audio.

Quando abilitato, il modello può emettere direttive [[tts:...]] per sovrascrivere la voce per una singola risposta, più un blocco opzionale [[tts:text]]...[[/tts:text]] per fornire tag espressivi (risata, cue canto, ecc.) che dovrebbero apparire solo nell'audio.

Le direttive provider=... sono ignorate a meno che modelOverrides.allowProvider: true.

Esempio payload risposta:

Ecco qui.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ride) Leggi la canzone ancora una volta.[[/tts:text]]

Chiavi direttiva disponibili (quando abilitate):

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

Disabilita tutti gli override modello:

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

Allowlist opzionale (abilita cambio provider mantenendo altre manopole configurabili):

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

Preferenze per utente

I comandi slash scrivono override locali in prefsPath (predefinito: ~/.mayros/settings/tts.json, override con MAYROS_TTS_PREFS o messages.tts.prefsPath).

Campi memorizzati:

• enabled
• provider
• maxLength (soglia riepilogo; default 1500 caratteri)
• summarize (default true)

Questi sovrascrivono messages.tts.* per quell'host.

Formati output (fissi)

• Telegram: Voice note Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48kHz / 64kbps è un buon compromesso voice-note e richiesto per la bolla rotonda.
• Altri canali: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44.1kHz / 128kbps è il bilanciamento default per chiarezza speech.
• Edge TTS: usa edge.outputFormat (default audio-24khz-48kbitrate-mono-mp3).
  • node-edge-tts accetta un outputFormat, ma non tutti i formati sono disponibili dal servizio Edge.
  • I valori formato output seguono i formati output Speech Microsoft (incluso Ogg/WebM Opus).
  • Telegram sendVoice accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se hai bisogno di voice note Opus garantite.
  • Se il formato output Edge configurato fallisce, Mayros riprova con MP3.

I formati OpenAI/ElevenLabs sono fissi; Telegram si aspetta Opus per UX voice-note.

Comportamento TTS automatico

Quando abilitato, Mayros:

• salta TTS se la risposta contiene già media o una direttiva MEDIA:.
• salta risposte molto brevi (< 10 caratteri).
• riassume risposte lunghe quando abilitato usando agents.defaults.model.primary (o summaryModel).
• allega l'audio generato alla risposta.

Se la risposta supera maxLength e il riepilogo è disattivato (o nessuna chiave API per il modello riepilogo), l'audio viene saltato e viene inviata la normale risposta testo.

Diagramma flusso

Risposta -> TTS abilitato?
  no  -> invia testo
  yes -> ha media / MEDIA: / breve?
          yes -> invia testo
          no  -> lunghezza > limite?
                   no  -> TTS -> allega audio
                   yes -> riepilogo abilitato?
                            no  -> invia testo
                            yes -> riassumi (summaryModel o agents.defaults.model.primary)
                                      -> TTS -> allega audio

Uso comando slash

C'è un singolo comando: /tts. Vedi Comandi slash per dettagli abilitazione.

Nota Discord: /tts è un comando Discord integrato, quindi Mayros registra /voice come comando nativo lì. Il testo /tts ... funziona ancora.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Ciao da Mayros

Note:

• I comandi richiedono un mittente autorizzato (regole allowlist/owner si applicano ancora).
• commands.text o registrazione comando nativo deve essere abilitata.
• off|always|inbound|tagged sono toggle per sessione (/tts on è un alias per /tts always).
• limit e summary sono memorizzati nelle preferenze locali, non nella configurazione principale.
• /tts audio genera una risposta audio una tantum (non attiva TTS).

Strumento agente

Lo strumento tts converte testo in speech e restituisce un percorso MEDIA:. Quando il risultato è compatibile con Telegram, lo strumento include [[audio_as_voice]] così Telegram invia una bolla voce.

RPC Gateway

Metodi Gateway:

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