Text-to-speech (TTS)

Mayros pode converter respostas de saída em áudio usando ElevenLabs, OpenAI ou Edge TTS. Funciona em qualquer lugar onde o Mayros possa enviar áudio; Telegram recebe uma bolha redonda de nota de voz.

Serviços suportados

• ElevenLabs (provedor primário ou de fallback)
• OpenAI (provedor primário ou de fallback; também usado para resumos)
• Edge TTS (provedor primário ou de fallback; usa node-edge-tts, padrão quando não há chaves de API)

Notas do Edge TTS

Edge TTS usa o serviço TTS neural online do Microsoft Edge via biblioteca node-edge-tts. É um serviço hospedado (não local), usa endpoints da Microsoft e não requer uma chave de API. node-edge-tts expõe opções de configuração de fala e formatos de saída, mas nem todas as opções são suportadas pelo serviço Edge. citeturn2search0

Como Edge TTS é um serviço web público sem SLA ou cota publicados, trate-o como melhor esforço. Se você precisar de limites garantidos e suporte, use OpenAI ou ElevenLabs. A API REST de Fala da Microsoft documenta um limite de 10 minutos de áudio por solicitação; Edge TTS não publica limites, então assuma limites similares ou menores. citeturn0search3

Chaves opcionais

Se você quiser OpenAI ou ElevenLabs:

• ELEVENLABS_API_KEY (ou XI_API_KEY)
• OPENAI_API_KEY

Edge TTS não requer uma chave de API. Se nenhuma chave de API for encontrada, Mayros usa por padrão Edge TTS (a menos que desabilitado via messages.tts.edge.enabled=false).

Se múltiplos provedores estiverem configurados, o provedor selecionado é usado primeiro e os outros são opções de fallback. Auto-resumo usa o summaryModel configurado (ou agents.defaults.model.primary), então esse provedor também deve estar autenticado se você habilitar resumos.

Links de serviços

• Guia Text-to-Speech da OpenAI
• Referência da API de Áudio da OpenAI
• Text to Speech da ElevenLabs
• Autenticação da ElevenLabs
• node-edge-tts
• Formatos de saída de fala da Microsoft

Está habilitado por padrão?

Não. Auto-TTS está desativado por padrão. Habilite-o na configuração com messages.tts.auto ou por sessão com /tts always (alias: /tts on).

Edge TTS está habilitado por padrão uma vez que TTS esteja ativo, e é usado automaticamente quando nenhuma chave de API OpenAI ou ElevenLabs estiver disponível.

Configuração

A configuração de TTS fica em messages.tts em mayros.json. O schema completo está em Configuração do Gateway.

Configuração mínima (habilitar + provedor)

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

OpenAI primário com 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 primário (sem chave de 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%",
      },
    },
  },
}

Desabilitar Edge TTS

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

Limites personalizados + caminho de preferências

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

Responder apenas com áudio após uma nota de voz recebida

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

Desabilitar auto-resumo para respostas longas

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

Então execute:

/tts summary off

Notas sobre campos

• auto: modo auto-TTS (off, always, inbound, tagged).
  • inbound envia áudio apenas após uma nota de voz recebida.
  • tagged envia áudio apenas quando a resposta inclui tags [[tts]].
• enabled: alternância legada (doctor migra isso para auto).
• mode: "final" (padrão) ou "all" (inclui respostas de ferramenta/bloco).
• provider: "elevenlabs", "openai" ou "edge" (fallback é automático).
• Se provider não estiver definido, Mayros prefere openai (se houver chave), então elevenlabs (se houver chave), caso contrário edge.
• summaryModel: modelo barato opcional para auto-resumo; padrão é agents.defaults.model.primary.
  • Aceita provider/model ou um alias de modelo configurado.
• modelOverrides: permitir que o modelo emita diretivas TTS (ativado por padrão).
  • allowProvider padrão é false (troca de provedor é opt-in).
• maxTextLength: limite rígido para entrada TTS (caracteres). /tts audio falha se excedido.
• timeoutMs: timeout de solicitação (ms).
• prefsPath: substituir o caminho JSON de preferências locais (provedor/limite/resumo).
• Valores de apiKey retornam a variáveis de ambiente (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: substituir URL base da 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 de 2 letras (ex: en, de)
• elevenlabs.seed: inteiro 0..4294967295 (determinismo de melhor esforço)
• edge.enabled: permitir uso de Edge TTS (padrão true; sem chave de API).
• edge.voice: nome da voz neural Edge (ex: en-US-MichelleNeural).
• edge.lang: código de idioma (ex: en-US).
• edge.outputFormat: formato de saída Edge (ex: audio-24khz-48kbitrate-mono-mp3).
  • Consulte formatos de saída de fala da Microsoft para valores válidos; nem todos os formatos são suportados pelo Edge.
• edge.rate / edge.pitch / edge.volume: strings de porcentagem (ex: +10%, -5%).
• edge.saveSubtitles: escrever legendas JSON ao lado do arquivo de áudio.
• edge.proxy: URL de proxy para solicitações Edge TTS.
• edge.timeoutMs: substituição de timeout de solicitação (ms).

Substituições orientadas por modelo (padrão ativado)

Por padrão, o modelo pode emitir diretivas TTS para uma única resposta. Quando messages.tts.auto é tagged, essas diretivas são necessárias para acionar áudio.

Quando habilitado, o modelo pode emitir diretivas [[tts:...]] para substituir a voz para uma única resposta, mais um bloco opcional [[tts:text]]...[[/tts:text]] para fornecer tags expressivas (risadas, dicas de canto, etc) que devem aparecer apenas no áudio.

Diretivas provider=... são ignoradas a menos que modelOverrides.allowProvider: true.

Exemplo de payload de resposta:

Aqui está.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](ri) Leia a música mais uma vez.[[/tts:text]]

Chaves de diretiva disponíveis (quando habilitado):

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

Desabilitar todas as substituições de modelo:

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

Lista de permissões opcional (habilitar troca de provedor enquanto mantém outros controles configuráveis):

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

Preferências por usuário

Comandos slash escrevem substituições locais em prefsPath (padrão: ~/.mayros/settings/tts.json, substituir com MAYROS_TTS_PREFS ou messages.tts.prefsPath).

Campos armazenados:

• enabled
• provider
• maxLength (limite de resumo; padrão 1500 caracteres)
• summarize (padrão true)

Estes substituem messages.tts.* para esse host.

Formatos de saída (fixos)

• Telegram: nota de voz Opus (opus_48000_64 da ElevenLabs, opus da OpenAI).
  • 48kHz / 64kbps é um bom compromisso para nota de voz e necessário para a bolha redonda.
• Outros canais: MP3 (mp3_44100_128 da ElevenLabs, mp3 da OpenAI).
  • 44.1kHz / 128kbps é o equilíbrio padrão para clareza de fala.
• Edge TTS: usa edge.outputFormat (padrão audio-24khz-48kbitrate-mono-mp3).
  • node-edge-tts aceita um outputFormat, mas nem todos os formatos estão disponíveis do serviço Edge. citeturn2search0
  • Valores de formato de saída seguem formatos de saída de fala da Microsoft (incluindo Ogg/WebM Opus). citeturn1search0
  • sendVoice do Telegram aceita OGG/MP3/M4A; use OpenAI/ElevenLabs se precisar de notas de voz Opus garantidas. citeturn1search1
  • Se o formato de saída Edge configurado falhar, Mayros tenta novamente com MP3.

Formatos OpenAI/ElevenLabs são fixos; Telegram espera Opus para UX de nota de voz.

Comportamento de Auto-TTS

Quando habilitado, Mayros:

• pula TTS se a resposta já contém mídia ou uma diretiva MEDIA:.
• pula respostas muito curtas (< 10 caracteres).
• resume respostas longas quando habilitado usando agents.defaults.model.primary (ou summaryModel).
• anexa o áudio gerado à resposta.

Se a resposta exceder maxLength e o resumo estiver desligado (ou sem chave de API para o modelo de resumo), o áudio é pulado e a resposta de texto normal é enviada.

Diagrama de fluxo

Resposta -> TTS habilitado?
  não  -> enviar texto
  sim -> tem mídia / MEDIA: / curta?
          sim -> enviar texto
          não  -> comprimento > limite?
                   não  -> TTS -> anexar áudio
                   sim -> resumo habilitado?
                            não  -> enviar texto
                            sim -> resumir (summaryModel ou agents.defaults.model.primary)
                                      -> TTS -> anexar áudio

Uso de comando slash

Há um único comando: /tts. Consulte Comandos slash para detalhes de habilitação.

Nota do Discord: /tts é um comando integrado do Discord, então Mayros registra /voice como o comando nativo lá. Texto /tts ... ainda funciona.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Olá do Mayros

Observações:

• Comandos requerem um remetente autorizado (regras de lista de permissões/proprietário ainda se aplicam).
• commands.text ou registro de comando nativo deve estar habilitado.
• off|always|inbound|tagged são alternâncias por sessão (/tts on é um alias para /tts always).
• limit e summary são armazenados em preferências locais, não na configuração principal.
• /tts audio gera uma resposta de áudio única (não alterna TTS).

Ferramenta de agente

A ferramenta tts converte texto em fala e retorna um caminho MEDIA:. Quando o resultado é compatível com Telegram, a ferramenta inclui [[audio_as_voice]] para que Telegram envie uma bolha de voz.

RPC do Gateway

Métodos do Gateway:

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