Text-to-speech (TTS)

Mayros có thể chuyển đổi phản hồi đi thành âm thanh sử dụng ElevenLabs, OpenAI hoặc Edge TTS. Nó hoạt động ở bất kỳ nơi nào Mayros có thể gửi âm thanh; Telegram nhận bong bóng voice-note tròn.

Dịch vụ được hỗ trợ

• ElevenLabs (provider chính hoặc dự phòng)
• OpenAI (provider chính hoặc dự phòng; cũng được sử dụng cho tóm tắt)
• Edge TTS (provider chính hoặc dự phòng; sử dụng node-edge-tts, mặc định khi không có API key)

Lưu ý Edge TTS

Edge TTS sử dụng dịch vụ TTS neural trực tuyến của Microsoft Edge qua thư viện node-edge-tts. Đó là dịch vụ được lưu trữ (không local), sử dụng endpoint của Microsoft và không yêu cầu API key. node-edge-tts hiển thị tùy chọn cấu hình speech và định dạng output, nhưng không phải tất cả tùy chọn đều được hỗ trợ bởi dịch vụ Edge.

Vì Edge TTS là dịch vụ web công khai không có SLA hoặc quota được công bố, hãy coi nó là best-effort. Nếu bạn cần giới hạn và hỗ trợ được đảm bảo, sử dụng OpenAI hoặc ElevenLabs. Microsoft Speech REST API ghi lại giới hạn âm thanh 10 phút mỗi yêu cầu; Edge TTS không công bố giới hạn, vì vậy giả sử giới hạn tương tự hoặc thấp hơn.

Key tùy chọn

Nếu bạn muốn OpenAI hoặc ElevenLabs:

• ELEVENLABS_API_KEY (hoặc XI_API_KEY)
• OPENAI_API_KEY

Edge TTS không yêu cầu API key. Nếu không tìm thấy API key, Mayros mặc định về Edge TTS (trừ khi bị tắt qua messages.tts.edge.enabled=false).

Nếu nhiều provider được cấu hình, provider được chọn được sử dụng trước và các provider khác là tùy chọn dự phòng. Auto-summary sử dụng summaryModel được cấu hình (hoặc agents.defaults.model.primary), vì vậy provider đó cũng phải được xác thực nếu bạn bật tóm tắt.

Liên kết dịch vụ

• Hướng dẫn OpenAI Text-to-Speech
• Tham chiếu OpenAI Audio API
• ElevenLabs Text to Speech
• Xác thực ElevenLabs
• node-edge-tts
• Định dạng output Microsoft Speech

Nó có được bật theo mặc định không?

Không. Auto-TTS tắt theo mặc định. Bật nó trong cấu hình với messages.tts.auto hoặc mỗi phiên với /tts always (alias: /tts on).

Edge TTS được bật theo mặc định khi TTS được bật và được sử dụng tự động khi không có API key OpenAI hoặc ElevenLabs.

Cấu hình

Cấu hình TTS nằm dưới messages.tts trong mayros.json. Schema đầy đủ trong Cấu hình Gateway.

Cấu hình tối thiểu (bật + provider)

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

OpenAI chính với dự phòng 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 chính (không có 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%",
      },
    },
  },
}

Tắt Edge TTS

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

Giới hạn tùy chỉnh + đường dẫn prefs

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

Chỉ trả lời bằng âm thanh sau voice note đến

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

Tắt auto-summary cho phản hồi dài

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

Sau đó chạy:

/tts summary off

Lưu ý về trường

• auto: chế độ auto-TTS (off, always, inbound, tagged).
  • inbound chỉ gửi âm thanh sau voice note đến.
  • tagged chỉ gửi âm thanh khi phản hồi bao gồm thẻ [[tts]].
• enabled: toggle cũ (doctor di chuyển điều này sang auto).
• mode: "final" (mặc định) hoặc "all" (bao gồm phản hồi tool/block).
• provider: "elevenlabs", "openai" hoặc "edge" (dự phòng tự động).
• Nếu provider không được đặt, Mayros ưu tiên openai (nếu có key), sau đó elevenlabs (nếu có key), nếu không thì edge.
• summaryModel: model rẻ tùy chọn cho auto-summary; mặc định agents.defaults.model.primary.
  • Chấp nhận provider/model hoặc alias model được cấu hình.
• modelOverrides: cho phép model phát ra chỉ thị TTS (bật theo mặc định).
  • allowProvider mặc định false (chuyển provider là tùy chọn).
• maxTextLength: giới hạn cứng cho input TTS (ký tự). /tts audio thất bại nếu vượt quá.
• timeoutMs: timeout yêu cầu (ms).
• prefsPath: ghi đè đường dẫn JSON prefs local (provider/limit/summary).
• Giá trị apiKey quay về biến env (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY).
• elevenlabs.baseUrl: ghi đè base URL API ElevenLabs.
• elevenlabs.voiceSettings:
  • stability, similarityBoost, style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = bình thường)
• elevenlabs.applyTextNormalization: auto|on|off
• elevenlabs.languageCode: ISO 639-1 2 chữ cái (ví dụ: en, de)
• elevenlabs.seed: số nguyên 0..4294967295 (xác định best-effort)
• edge.enabled: cho phép sử dụng Edge TTS (mặc định true; không có API key).
• edge.voice: tên voice neural Edge (ví dụ: en-US-MichelleNeural).
• edge.lang: mã ngôn ngữ (ví dụ: en-US).
• edge.outputFormat: định dạng output Edge (ví dụ: audio-24khz-48kbitrate-mono-mp3).
  • Xem định dạng output Microsoft Speech cho giá trị hợp lệ; không phải tất cả định dạng đều được hỗ trợ bởi Edge.
• edge.rate / edge.pitch / edge.volume: chuỗi phần trăm (ví dụ: +10%, -5%).
• edge.saveSubtitles: viết phụ đề JSON cạnh file âm thanh.
• edge.proxy: URL proxy cho yêu cầu Edge TTS.
• edge.timeoutMs: ghi đè timeout yêu cầu (ms).

Ghi đè điều khiển model (mặc định bật)

Theo mặc định, model có thể phát ra chỉ thị TTS cho một phản hồi đơn. Khi messages.tts.auto là tagged, các chỉ thị này bắt buộc để kích hoạt âm thanh.

Khi được bật, model có thể phát ra chỉ thị [[tts:...]] để ghi đè voice cho một phản hồi đơn, cộng block [[tts:text]]...[[/tts:text]] tùy chọn để cung cấp thẻ biểu cảm (tiếng cười, gợi ý hát, v.v.) chỉ nên xuất hiện trong âm thanh.

Chỉ thị provider=... bị bỏ qua trừ khi modelOverrides.allowProvider: true.

Ví dụ payload phản hồi:

Đây rồi.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](cười) Đọc bài hát một lần nữa.[[/tts:text]]

Key chỉ thị có sẵn (khi được bật):

• provider (openai | elevenlabs | edge, yêu cầu allowProvider: true)
• voice (voice OpenAI) hoặc voiceId (ElevenLabs)
• model (model TTS OpenAI hoặc id model ElevenLabs)
• stability, similarityBoost, style, speed, useSpeakerBoost
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

Tắt tất cả ghi đè model:

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

Allowlist tùy chọn (bật chuyển provider trong khi giữ các nút khác có thể cấu hình):

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

Tùy chọn mỗi người dùng

Lệnh slash ghi ghi đè local vào prefsPath (mặc định: ~/.mayros/settings/tts.json, ghi đè với MAYROS_TTS_PREFS hoặc messages.tts.prefsPath).

Trường được lưu trữ:

• enabled
• provider
• maxLength (ngưỡng tóm tắt; mặc định 1500 ký tự)
• summarize (mặc định true)

Những thứ này ghi đè messages.tts.* cho host đó.

Định dạng output (cố định)

• Telegram: Voice note Opus (opus_48000_64 từ ElevenLabs, opus từ OpenAI).
  • 48kHz / 64kbps là sự cân bằng tốt cho voice-note và bắt buộc cho bong bóng tròn.
• Kênh khác: MP3 (mp3_44100_128 từ ElevenLabs, mp3 từ OpenAI).
  • 44.1kHz / 128kbps là sự cân bằng mặc định cho độ rõ giọng nói.
• Edge TTS: sử dụng edge.outputFormat (mặc định audio-24khz-48kbitrate-mono-mp3).
  • node-edge-tts chấp nhận outputFormat, nhưng không phải tất cả định dạng đều có sẵn từ dịch vụ Edge.
  • Giá trị định dạng output theo định dạng output Microsoft Speech (bao gồm Ogg/WebM Opus).
  • Telegram sendVoice chấp nhận OGG/MP3/M4A; sử dụng OpenAI/ElevenLabs nếu bạn cần voice note Opus được đảm bảo.
  • Nếu định dạng output Edge được cấu hình thất bại, Mayros thử lại với MP3.

Định dạng OpenAI/ElevenLabs cố định; Telegram mong đợi Opus cho UX voice-note.

Hành vi Auto-TTS

Khi được bật, Mayros:

• bỏ qua TTS nếu phản hồi đã chứa media hoặc chỉ thị MEDIA:.
• bỏ qua phản hồi rất ngắn (< 10 ký tự).
• tóm tắt phản hồi dài khi được bật sử dụng agents.defaults.model.primary (hoặc summaryModel).
• đính kèm âm thanh được tạo vào phản hồi.

Nếu phản hồi vượt quá maxLength và tóm tắt tắt (hoặc không có API key cho model tóm tắt), âm thanh bị bỏ qua và phản hồi text bình thường được gửi.

Sơ đồ luồng

Phản hồi -> TTS được bật?
  không  -> gửi text
  có -> có media / MEDIA: / ngắn?
          có -> gửi text
          không  -> độ dài > giới hạn?
                   không  -> TTS -> đính kèm âm thanh
                   có -> tóm tắt được bật?
                            không  -> gửi text
                            có -> tóm tắt (summaryModel hoặc agents.defaults.model.primary)
                                      -> TTS -> đính kèm âm thanh

Sử dụng lệnh slash

Có một lệnh duy nhất: /tts. Xem Lệnh slash để biết chi tiết kích hoạt.

Lưu ý Discord: /tts là lệnh Discord tích hợp, vì vậy Mayros đăng ký /voice như lệnh native ở đó. Text /tts ... vẫn hoạt động.

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Xin chào từ Mayros

Lưu ý:

• Lệnh yêu cầu người gửi được ủy quyền (quy tắc allowlist/owner vẫn áp dụng).
• commands.text hoặc đăng ký lệnh native phải được bật.
• off|always|inbound|tagged là toggle mỗi phiên (/tts on là alias cho /tts always).
• limit và summary được lưu trữ trong prefs local, không phải cấu hình chính.
• /tts audio tạo phản hồi âm thanh một lần (không bật TTS).

Công cụ agent

Công cụ tts chuyển đổi text thành speech và trả về đường dẫn MEDIA:. Khi kết quả tương thích Telegram, công cụ bao gồm [[audio_as_voice]] để Telegram gửi bong bóng voice.

Gateway RPC

Phương thức Gateway:

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