텍스트 음성 변환 (TTS)

Mayros는 ElevenLabs, OpenAI 또는 Edge TTS를 사용하여 아웃바운드 응답을 오디오로 변환할 수 있습니다. Mayros가 오디오를 보낼 수 있는 모든 곳에서 작동합니다. Telegram은 둥근 음성 메모 버블을 받습니다.

지원되는 서비스

  • ElevenLabs (기본 또는 폴백 공급자)
  • OpenAI (기본 또는 폴백 공급자; 요약에도 사용)
  • Edge TTS (기본 또는 폴백 공급자; node-edge-tts 사용, API 키가 없을 때 기본값)

Edge TTS 참고 사항

Edge TTS는 node-edge-tts 라이브러리를 통해 Microsoft Edge의 온라인 신경 TTS 서비스를 사용합니다. 호스팅 서비스(로컬이 아님)이고 Microsoft의 엔드포인트를 사용하며 API 키가 필요하지 않습니다. node-edge-tts는 음성 구성 옵션 및 출력 형식을 노출하지만 모든 옵션이 Edge 서비스에서 지원되는 것은 아닙니다.

Edge TTS는 게시된 SLA 또는 할당량 없이 공개 웹 서비스이므로 최선의 노력으로 취급하세요. 보장된 한도 및 지원이 필요한 경우 OpenAI 또는 ElevenLabs를 사용하세요. Microsoft의 Speech REST API는 요청당 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)을 사용하므로 요약을 활성화하는 경우 해당 공급자도 인증되어야 합니다.

서비스 링크

기본적으로 활성화되어 있나요?

아니요. 자동 TTS는 기본적으로 꺼져 있습니다. 구성에서 messages.tts.auto로 활성화하거나 /tts always (별칭: /tts on)로 세션당 활성화하세요.

Edge TTS는 TTS가 켜져 있으면 기본적으로 활성화되어 OpenAI 또는 ElevenLabs API 키를 사용할 수 없을 때 자동으로 사용됩니다.

구성

TTS 구성은 mayros.json의 messages.tts 아래에 있습니다. 전체 스키마는 Gateway 구성에 있습니다.

최소 구성 (활성화 + 공급자)

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

OpenAI 기본, ElevenLabs 폴백

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

Edge TTS 비활성화

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

사용자 정의 한도 + 선호도 경로

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

인바운드 음성 메모 후에만 오디오로 응답

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

긴 응답에 대한 자동 요약 비활성화

json5
{
  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 지시문을 내보낼 수 있도록 허용 (기본적으로 on).
    • allowProvider는 기본적으로 false입니다 (공급자 전환은 옵트인).
  • maxTextLength: TTS 입력에 대한 하드 캡 (문자). 초과하면 /tts audio가 실패합니다.
  • timeoutMs: 요청 시간 초과 (ms).
  • prefsPath: 로컬 선호도 JSON 경로 재정의 (공급자/한도/요약).
  • apiKey 값은 환경 변수 (ELEVENLABS_API_KEY/XI_API_KEY, OPENAI_API_KEY)로 폴백됩니다.
  • elevenlabs.baseUrl: ElevenLabs API 기본 URL 재정의.
  • 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 (최선의 노력 결정론)
  • 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: Edge TTS 요청을 위한 프록시 URL.
  • edge.timeoutMs: 요청 시간 초과 재정의 (ms).

모델 기반 재정의 (기본적으로 on)

기본적으로 모델은 단일 응답에 대해 TTS 지시문을 내보낼 수 있습니다. messages.tts.auto가 tagged일 때 이러한 지시문은 오디오를 트리거하는 데 필요합니다.

활성화된 경우 모델은 단일 응답에 대한 음성을 재정의하기 위해 [[tts:...]] 지시문을 내보낼 수 있으며 오디오에만 나타나야 하는 표현 태그 (웃음, 노래 큐 등)를 제공하기 위해 선택적 [[tts:text]]...[[/tts:text]] 블록을 내보낼 수 있습니다.

provider=... 지시문은 modelOverrides.allowProvider: true가 아니면 무시됩니다.

응답 페이로드 예시:

Here you go.

[[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

사용 가능한 지시문 키 (활성화된 경우):

  • provider (openai | elevenlabs | edge, allowProvider: true 필요)
  • voice (OpenAI 음성) 또는 voiceId (ElevenLabs)
  • model (OpenAI TTS 모델 또는 ElevenLabs 모델 ID)
  • stability, similarityBoost, style, speed, useSpeakerBoost
  • applyTextNormalization (auto|on|off)
  • languageCode (ISO 639-1)
  • seed

모든 모델 재정의 비활성화:

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

선택적 허용 목록 (다른 손잡이를 구성 가능하게 유지하면서 공급자 전환 활성화):

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

사용자별 선호도

슬래시 명령은 prefsPath (기본값: ~/.mayros/settings/tts.json, MAYROS_TTS_PREFS 또는 messages.tts.prefsPath로 재정의)에 로컬 재정의를 작성합니다.

저장된 필드:

  • enabled
  • provider
  • maxLength (요약 임계값; 기본값 1500자)
  • summarize (기본값 true)

이는 해당 호스트에 대해 messages.tts.*를 재정의합니다.

출력 형식 (고정)

  • Telegram: Opus 음성 메모 (ElevenLabs에서 opus_48000_64, OpenAI에서 opus).
    • 48kHz / 64kbps는 좋은 음성 메모 절충안이며 둥근 버블에 필요합니다.
  • 기타 채널: MP3 (ElevenLabs에서 mp3_44100_128, OpenAI에서 mp3).
    • 44.1kHz / 128kbps는 음성 명확도에 대한 기본 균형입니다.
  • Edge TTS: edge.outputFormat 사용 (기본값 audio-24khz-48kbitrate-mono-mp3).
    • node-edge-tts는 outputFormat을 허용하지만 모든 형식이 Edge 서비스에서 사용 가능한 것은 아닙니다.
    • 출력 형식 값은 Microsoft Speech 출력 형식 (Ogg/WebM Opus 포함)을 따릅니다.
    • Telegram sendVoice는 OGG/MP3/M4A를 허용합니다. 보장된 Opus 음성 메모가 필요한 경우 OpenAI/ElevenLabs를 사용하세요.
    • 구성된 Edge 출력 형식이 실패하면 Mayros는 MP3로 재시도합니다.

OpenAI/ElevenLabs 형식은 고정되어 있습니다. Telegram은 음성 메모 UX를 위해 Opus를 예상합니다.

자동 TTS 동작

활성화된 경우 Mayros는:

  • 응답에 이미 미디어 또는 MEDIA: 지시문이 포함된 경우 TTS를 건너뜁니다.
  • 매우 짧은 응답 (< 10자)을 건너뜁니다.
  • 활성화된 경우 agents.defaults.model.primary (또는 summaryModel)를 사용하여 긴 응답을 요약합니다.
  • 생성된 오디오를 응답에 첨부합니다.

응답이 maxLength를 초과하고 요약이 꺼져 있는 경우 (또는 요약 모델에 대한 API 키가 없는 경우) 오디오가 건너뛰어지고 일반 텍스트 응답이 전송됩니다.

흐름 다이어그램

응답 -> TTS 활성화?
  아니요  -> 텍스트 전송
  예 -> 미디어 / MEDIA: / 짧음?
          예 -> 텍스트 전송
          아니요  -> 길이 > 한도?
                   아니요  -> TTS -> 오디오 첨부
                   예 -> 요약 활성화?
                            아니요  -> 텍스트 전송
                            예 -> 요약 (summaryModel 또는 agents.defaults.model.primary)
                                      -> TTS -> 오디오 첨부

슬래시 명령 사용

단일 명령이 있습니다: /tts. 활성화 세부 정보는 슬래시 명령을 참조하세요.

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

참고 사항:

  • 명령에는 승인된 발신자가 필요합니다 (허용 목록/소유자 규칙이 여전히 적용됨).
  • commands.text 또는 네이티브 명령 등록이 활성화되어야 합니다.
  • off|always|inbound|tagged는 세션당 토글입니다 (/tts on은 /tts always의 별칭).
  • limit 및 summary는 로컬 선호도에 저장되며 메인 구성에는 저장되지 않습니다.
  • /tts audio는 일회성 오디오 응답을 생성합니다 (TTS를 켜지 않음).

에이전트 도구

tts 도구는 텍스트를 음성으로 변환하고 MEDIA: 경로를 반환합니다. 결과가 Telegram 호환인 경우 도구에는 Telegram이 음성 버블을 보내도록 [[audio_as_voice]]가 포함됩니다.

Gateway RPC

Gateway 메서드:

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