Преобразование текста в речь (TTS)

Mayros может конвертировать исходящие ответы в аудио, используя ElevenLabs, OpenAI или Edge TTS. Это работает везде, где Mayros может отправлять аудио; Telegram получает круглый пузырь голосовой заметки.

Поддерживаемые сервисы

• ElevenLabs (основной или резервный провайдер)
• OpenAI (основной или резервный провайдер; также используется для резюме)
• Edge TTS (основной или резервный провайдер; использует node-edge-tts, по умолчанию когда нет API ключей)

Примечания Edge TTS

Edge TTS использует онлайн-сервис нейронного TTS Microsoft Edge через библиотеку node-edge-tts. Это размещенный сервис (не локальный), использует эндпоинты Microsoft и не требует API ключа. node-edge-tts предоставляет опции конфигурации речи и форматы вывода, но не все опции поддерживаются сервисом Edge.

Поскольку Edge TTS - это публичный веб-сервис без опубликованного SLA или квоты, относитесь к нему как к best-effort. Если вам нужны гарантированные лимиты и поддержка, используйте OpenAI или ElevenLabs. REST API Speech Microsoft документирует лимит аудио 10 минут на запрос; Edge TTS не публикует лимиты, поэтому предполагайте аналогичные или более низкие лимиты.

Опциональные ключи

Если хотите OpenAI или ElevenLabs:

• ELEVENLABS_API_KEY (или XI_API_KEY)
• OPENAI_API_KEY

Edge TTS не требует API ключ. Если API ключи не найдены, Mayros по умолчанию использует Edge TTS (если не отключено через messages.tts.edge.enabled=false).

Если настроено несколько провайдеров, выбранный провайдер используется первым, а остальные - резервные варианты. Авто-резюме использует настроенный summaryModel (или agents.defaults.model.primary), поэтому этот провайдер также должен быть аутентифицирован, если вы включаете резюме.

Ссылки на сервисы

• Руководство OpenAI по преобразованию текста в речь
• Справочник OpenAI Audio API
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• node-edge-tts
• Форматы вывода Microsoft Speech

Включено ли по умолчанию?

Нет. Авто-TTS выключен по умолчанию. Включите его в конфигурации с messages.tts.auto или для каждой сессии с /tts always (псевдоним: /tts on).

Edge TTS включен по умолчанию после включения TTS и используется автоматически, когда недоступны API ключи OpenAI или ElevenLabs.

Конфигурация

Конфигурация TTS находится в messages.tts в mayros.json. Полная схема в Конфигурации Gateway.

Минимальная конфигурация (включение + провайдер)

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

OpenAI основной с 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 основной (без 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%",
      },
    },
  },
}

Отключение Edge TTS

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

Пользовательские лимиты + путь к настройкам

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

Только ответ аудио после входящей голосовой заметки

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

Отключение авто-резюме для длинных ответов

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

Затем запустите:

/tts summary off

Примечания к полям

• auto: режим авто-TTS (off, always, inbound, tagged).
  • inbound отправляет аудио только после входящей голосовой заметки.
  • tagged отправляет аудио только когда ответ включает теги [[tts]].
• enabled: устаревший переключатель (doctor мигрирует это в auto).
• mode: "final" (по умолчанию) или "all" (включает ответы инструментов/блоков).
• provider: "elevenlabs", "openai" или "edge" (резервный автоматический).
• Если provider не установлен, Mayros предпочитает openai (если ключ), затем elevenlabs (если ключ), иначе edge.
• summaryModel: опциональная дешевая модель для авто-резюме; по умолчанию agents.defaults.model.primary.
  • Принимает provider/model или настроенный псевдоним модели.
• modelOverrides: позволить модели генерировать директивы TTS (по умолчанию включено).
  • allowProvider по умолчанию false (переключение провайдера - opt-in).
• maxTextLength: жесткий лимит для ввода TTS (символы). /tts audio падает при превышении.
• timeoutMs: таймаут запроса (мс).
• prefsPath: переопределить путь к локальному JSON настроек (провайдер/лимит/резюме).
• Значения apiKey откатываются к переменным окружения (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: переопределить базовый URL API ElevenLabs.
• elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = нормально)
• elevenlabs.applyTextNormalization: auto|on|off
• elevenlabs.languageCode: 2-буквенный ISO 639-1 (например, en, de)
• elevenlabs.seed: целое число 0..4294967295 (детерминизм best-effort)
• edge.enabled: разрешить использование Edge TTS (по умолчанию true; без API ключа).
• edge.voice: имя нейронного голоса Edge (например, en-US-MichelleNeural).
• edge.lang: код языка (например, en-US).
• edge.outputFormat: формат вывода Edge (например, audio-24khz-48kbitrate-mono-mp3).
  • См. форматы вывода Microsoft Speech для допустимых значений; не все форматы поддерживаются Edge.
• edge.rate / edge.pitch / edge.volume: процентные строки (например, +10%, -5%).
• edge.saveSubtitles: записать субтитры JSON рядом с аудиофайлом.
• edge.proxy: URL прокси для запросов Edge TTS.
• edge.timeoutMs: переопределение таймаута запроса (мс).

Переопределения, управляемые моделью (по умолчанию включено)

По умолчанию модель может генерировать директивы TTS для одного ответа. Когда messages.tts.auto - это tagged, эти директивы необходимы для запуска аудио.

Когда включено, модель может генерировать директивы [[tts:...]] для переопределения голоса для одного ответа, плюс опциональный блок [[tts:text]]...[[/tts:text]] для предоставления выразительных тегов (смех, пение и т.д.), которые должны появляться только в аудио.

Директивы provider=... игнорируются, если не modelOverrides.allowProvider: true.

Пример полезной нагрузки ответа:

Вот вам.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](смеется) Прочитайте песню еще раз.[[/tts:text]]

Доступные ключи директив (когда включено):

• provider (openai | elevenlabs | edge, требуется allowProvider: true)
• voice (голос OpenAI) или voiceId (ElevenLabs)
• model (модель TTS OpenAI или id модели ElevenLabs)
• stability, similarityBoost, style, speed, useSpeakerBoost
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Отключить все переопределения модели:

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

Опциональный список разрешенных (включить переключение провайдера, сохраняя другие настройки конфигурируемыми):

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

Настройки для каждого пользователя

Slash команды записывают локальные переопределения в prefsPath (по умолчанию: ~/.mayros/settings/tts.json, переопределить с MAYROS_TTS_PREFS или messages.tts.prefsPath).

Сохраненные поля:

• enabled
• provider
• maxLength (порог резюме; по умолчанию 1500 символов)
• summarize (по умолчанию true)

Они переопределяют messages.tts.* для этого хоста.

Форматы вывода (фиксированные)

• Telegram: Opus голосовая заметка (opus_48000_64 из ElevenLabs, opus из OpenAI).
  • 48кГц / 64кбит/с - это хороший компромисс для голосовой заметки и требуется для круглого пузыря.
• Другие каналы: MP3 (mp3_44100_128 из ElevenLabs, mp3 из OpenAI).
  • 44.1кГц / 128кбит/с - это баланс по умолчанию для четкости речи.
• Edge TTS: использует edge.outputFormat (по умолчанию audio-24khz-48kbitrate-mono-mp3).
  • node-edge-tts принимает outputFormat, но не все форматы доступны из сервиса Edge.
  • Значения формата вывода следуют форматам вывода Microsoft Speech (включая Ogg/WebM Opus).
  • Telegram sendVoice принимает OGG/MP3/M4A; используйте OpenAI/ElevenLabs, если нужны гарантированные голосовые заметки Opus.
  • Если настроенный формат вывода Edge падает, Mayros повторяет с MP3.

Форматы OpenAI/ElevenLabs фиксированы; Telegram ожидает Opus для UX голосовых заметок.

Поведение авто-TTS

Когда включено, Mayros:

• пропускает TTS, если ответ уже содержит медиа или директиву MEDIA:.
• пропускает очень короткие ответы (< 10 символов).
• резюмирует длинные ответы, когда включено, используя agents.defaults.model.primary (или summaryModel).
• прикрепляет сгенерированное аудио к ответу.

Если ответ превышает maxLength и резюме выключено (или нет API ключа для модели резюме), аудио пропускается и отправляется нормальный текстовый ответ.

Диаграмма потока

Ответ -> TTS включен?
  нет -> отправить текст
  да  -> есть медиа / MEDIA: / короткий?
          да  -> отправить текст
          нет -> длина > лимит?
                   нет -> TTS -> прикрепить аудио
                   да  -> резюме включено?
                            нет -> отправить текст
                            да  -> резюмировать (summaryModel или agents.defaults.model.primary)
                                      -> TTS -> прикрепить аудио

Использование Slash команды

Есть одна команда: /tts. См. Slash команды для деталей включения.

Примечание Discord: /tts - это встроенная команда Discord, поэтому Mayros регистрирует /voice как нативную команду там. Текстовый /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

Примечания:

• Команды требуют авторизованного отправителя (правила allowlist/owner по-прежнему применяются).
• commands.text или регистрация нативных команд должны быть включены.
• off|always|inbound|tagged - это переключатели для каждой сессии (/tts on - это псевдоним для /tts always).
• limit и summary сохраняются в локальных настройках, не в основной конфигурации.
• /tts audio генерирует разовый аудио ответ (не переключает TTS).

Инструмент агента

Инструмент tts преобразует текст в речь и возвращает путь MEDIA:. Когда результат совместим с Telegram, инструмент включает [[audio_as_voice]], чтобы Telegram отправлял голосовой пузырь.

Gateway RPC

Методы Gateway:

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