Texto a voz (TTS)

Mayros puede convertir respuestas salientes en audio usando ElevenLabs, OpenAI o Edge TTS. Funciona en cualquier lugar donde Mayros pueda enviar audio; Telegram obtiene una burbuja de nota de voz redonda.

Servicios soportados

  • ElevenLabs (proveedor primario o fallback)
  • OpenAI (proveedor primario o fallback; también usado para resúmenes)
  • Edge TTS (proveedor primario o fallback; usa node-edge-tts, predeterminado cuando no hay claves API)

Notas sobre Edge TTS

Edge TTS usa el servicio de TTS neuronal en línea de Microsoft Edge a través de la biblioteca node-edge-tts. Es un servicio alojado (no local), usa los endpoints de Microsoft y no requiere una clave API. node-edge-tts expone opciones de configuración de voz y formatos de salida, pero no todas las opciones son soportadas por el servicio Edge.

Debido a que Edge TTS es un servicio web público sin un SLA o cuota publicada, trátalo como mejor esfuerzo. Si necesitas límites garantizados y soporte, usa OpenAI o ElevenLabs. La API REST de Speech de Microsoft documenta un límite de audio de 10 minutos por solicitud; Edge TTS no publica límites, así que asume límites similares o menores.

Claves opcionales

Si quieres OpenAI o ElevenLabs:

  • ELEVENLABS_API_KEY (o XI_API_KEY)
  • OPENAI_API_KEY

Edge TTS no requiere una clave API. Si no se encuentran claves API, Mayros usa Edge TTS por defecto (a menos que se deshabilite vía messages.tts.edge.enabled=false).

Si múltiples proveedores están configurados, el proveedor seleccionado se usa primero y los demás son opciones de fallback. El auto-resumen usa el summaryModel configurado (o agents.defaults.model.primary), así que ese proveedor también debe estar autenticado si habilitas resúmenes.

Enlaces de servicios

¿Está habilitado por defecto?

No. Auto‑TTS está desactivado por defecto. Habilítalo en la configuración con messages.tts.auto o por sesión con /tts always (alias: /tts on).

Edge TTS está habilitado por defecto una vez que TTS está activado, y se usa automáticamente cuando no hay claves API de OpenAI o ElevenLabs disponibles.

Configuración

La configuración de TTS vive bajo messages.tts en mayros.json. El esquema completo está en Configuración del Gateway.

Configuración mínima (habilitar + proveedor)

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

OpenAI primario con ElevenLabs fallback

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 primario (sin clave API)

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

Deshabilitar Edge TTS

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

Límites personalizados + ruta de preferencias

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

Solo responder con audio después de una nota de voz entrante

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

Deshabilitar auto-resumen para respuestas largas

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

Luego ejecuta:

/tts summary off

Notas sobre campos

  • auto: modo auto‑TTS (off, always, inbound, tagged).
    • inbound solo envía audio después de una nota de voz entrante.
    • tagged solo envía audio cuando la respuesta incluye etiquetas [[tts]].
  • enabled: toggle legacy (doctor migra esto a auto).
  • mode: "final" (predeterminado) o "all" (incluye respuestas de herramienta/bloque).
  • provider: "elevenlabs", "openai", o "edge" (el fallback es automático).
  • Si provider no está establecido, Mayros prefiere openai (si hay clave), luego elevenlabs (si hay clave), de lo contrario edge.
  • summaryModel: modelo económico opcional para auto-resumen; predeterminado a agents.defaults.model.primary.
    • Acepta provider/model o un alias de modelo configurado.
  • modelOverrides: permite al modelo emitir directivas TTS (activado por defecto).
    • allowProvider predeterminado a false (cambio de proveedor es opt-in).
  • maxTextLength: límite máximo para entrada TTS (caracteres). /tts audio falla si se excede.
  • timeoutMs: timeout de solicitud (ms).
  • prefsPath: anula la ruta JSON de preferencias locales (proveedor/límite/resumen).
  • Los valores apiKey vuelven a variables de entorno (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
  • elevenlabs.baseUrl: anula la URL base de la API de 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 de 2 letras (p.ej. en, de)
  • elevenlabs.seed: entero 0..4294967295 (determinismo de mejor esfuerzo)
  • edge.enabled: permite uso de Edge TTS (predeterminado true; sin clave API).
  • edge.voice: nombre de voz neural de Edge (p.ej. en-US-MichelleNeural).
  • edge.lang: código de idioma (p.ej. en-US).
  • edge.outputFormat: formato de salida de Edge (p.ej. audio-24khz-48kbitrate-mono-mp3).
    • Consulta formatos de salida de Microsoft Speech para valores válidos; no todos los formatos son soportados por Edge.
  • edge.rate / edge.pitch / edge.volume: cadenas de porcentaje (p.ej. +10%, -5%).
  • edge.saveSubtitles: escribe subtítulos JSON junto al archivo de audio.
  • edge.proxy: URL de proxy para solicitudes Edge TTS.
  • edge.timeoutMs: anulación de timeout de solicitud (ms).

Anulaciones impulsadas por modelo (predeterminado activado)

Por defecto, el modelo puede emitir directivas TTS para una sola respuesta. Cuando messages.tts.auto es tagged, estas directivas son requeridas para activar audio.

Cuando está habilitado, el modelo puede emitir directivas [[tts:...]] para anular la voz para una sola respuesta, más un bloque opcional [[tts:text]]...[[/tts:text]] para proporcionar etiquetas expresivas (risa, señales de canto, etc) que solo deben aparecer en el audio.

Las directivas provider=... se ignoran a menos que modelOverrides.allowProvider: true.

Ejemplo de payload de respuesta:

Aquí tienes.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ríe) Lee la canción una vez más.[[/tts:text]]

Claves de directiva disponibles (cuando está habilitado):

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

Deshabilitar todas las anulaciones de modelo:

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

Lista de permitidos opcional (habilitar cambio de proveedor mientras mantiene otras perillas configurables):

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

Preferencias por usuario

Los comandos slash escriben anulaciones locales en prefsPath (predeterminado: ~/.mayros/settings/tts.json, anular con MAYROS_TTS_PREFS o messages.tts.prefsPath).

Campos almacenados:

  • enabled
  • provider
  • maxLength (umbral de resumen; predeterminado 1500 caracteres)
  • summarize (predeterminado true)

Estos anulan messages.tts.* para ese host.

Formatos de salida (fijos)

  • Telegram: Nota de voz Opus (opus_48000_64 de ElevenLabs, opus de OpenAI).
    • 48kHz / 64kbps es un buen compromiso de nota de voz y requerido para la burbuja redonda.
  • Otros canales: MP3 (mp3_44100_128 de ElevenLabs, mp3 de OpenAI).
    • 44.1kHz / 128kbps es el balance predeterminado para claridad de voz.
  • Edge TTS: usa edge.outputFormat (predeterminado audio-24khz-48kbitrate-mono-mp3).
    • node-edge-tts acepta un outputFormat, pero no todos los formatos están disponibles desde el servicio Edge.
    • Los valores de formato de salida siguen los formatos de salida de Microsoft Speech (incluyendo Ogg/WebM Opus).
    • Telegram sendVoice acepta OGG/MP3/M4A; usa OpenAI/ElevenLabs si necesitas notas de voz Opus garantizadas.
    • Si el formato de salida Edge configurado falla, Mayros reintenta con MP3.

Los formatos OpenAI/ElevenLabs son fijos; Telegram espera Opus para UX de nota de voz.

Comportamiento de Auto-TTS

Cuando está habilitado, Mayros:

  • omite TTS si la respuesta ya contiene medios o una directiva MEDIA:.
  • omite respuestas muy cortas (< 10 caracteres).
  • resume respuestas largas cuando está habilitado usando agents.defaults.model.primary (o summaryModel).
  • adjunta el audio generado a la respuesta.

Si la respuesta excede maxLength y el resumen está desactivado (o no hay clave API para el modelo de resumen), el audio se omite y se envía la respuesta de texto normal.

Diagrama de flujo

Respuesta -> ¿TTS habilitado?
  no  -> enviar texto
  sí -> ¿tiene medios / MEDIA: / corta?
          sí -> enviar texto
          no  -> ¿longitud > límite?
                   no  -> TTS -> adjuntar audio
                   sí -> ¿resumen habilitado?
                            no  -> enviar texto
                            sí -> resumir (summaryModel o agents.defaults.model.primary)
                                      -> TTS -> adjuntar audio

Uso de comando slash

Hay un solo comando: /tts. Consulta Comandos slash para detalles de habilitación.

Nota de Discord: /tts es un comando incorporado de Discord, así que Mayros registra /voice como el comando nativo allí. Texto /tts ... aún funciona.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hola desde Mayros

Notas:

  • Los comandos requieren un remitente autorizado (las reglas de lista de permitidos/propietario aún aplican).
  • commands.text o registro de comando nativo debe estar habilitado.
  • off|always|inbound|tagged son toggles por sesión (/tts on es un alias para /tts always).
  • limit y summary se almacenan en preferencias locales, no en la configuración principal.
  • /tts audio genera una respuesta de audio única (no activa TTS).

Herramienta de agente

La herramienta tts convierte texto a voz y devuelve una ruta MEDIA:. Cuando el resultado es compatible con Telegram, la herramienta incluye [[audio_as_voice]] para que Telegram envíe una burbuja de voz.

RPC del Gateway

Métodos del Gateway:

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