تحويل النص إلى كلام (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 أو حصة منشورة، تعامل معها على أنها أفضل جهد. إذا كنت بحاجة إلى حدود ودعم مضمونين، استخدم 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 (alias: /tts on).

Edge TTS ممكّن افتراضيًا بمجرد تشغيل TTS، ويُستخدم تلقائيًا عندما لا تكون مفاتيح OpenAI أو ElevenLabs API متاحة.

التكوين

يعيش تكوين TTS تحت messages.tts في mayros.json. المخطط الكامل في تكوين 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 (تشغيل افتراضيًا).
    • allowProvider يعود افتراضيًا إلى false (تبديل الموفر اختياري).
  • maxTextLength: حد صارم لإدخال TTS (أحرف). يفشل /tts audio إذا تم تجاوزه.
  • timeoutMs: مهلة الطلب (ms).
  • prefsPath: تجاوز مسار JSON للتفضيلات المحلية (الموفر/الحد/الملخص).
  • تعود قيم apiKey إلى متغيرات env (ELEVENLABS_API_KEY/XI_API_KEY، OPENAI_API_KEY).
  • elevenlabs.baseUrl: تجاوز عنوان URL الأساسي لواجهة برمجة تطبيقات 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: 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: عنوان URL للوكيل لطلبات Edge TTS.
  • edge.timeoutMs: تجاوز مهلة الطلب (ms).

التجاوزات المدفوعة بالنموذج (تشغيل افتراضي)

افتراضيًا، يمكن للنموذج أن يصدر توجيهات 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)
  • 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 (opus_48000_64 من ElevenLabs، opus من OpenAI).
    • 48kHz / 64kbps هو مقايضة جيدة للملاحظات الصوتية ومطلوب للفقاعة المستديرة.
  • قنوات أخرى: MP3 (mp3_44100_128 من ElevenLabs، mp3 من OpenAI).
    • 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؛ استخدم OpenAI/ElevenLabs إذا كنت بحاجة إلى ملاحظات صوتية Opus مضمونة.
    • إذا فشل تنسيق إخراج Edge المُكون، يعيد Mayros المحاولة باستخدام MP3.

تنسيقات OpenAI/ElevenLabs ثابتة؛ يتوقع Telegram Opus لتجربة مستخدم ملاحظة صوتية.

سلوك TTS التلقائي

عند التمكين، Mayros:

  • يتخطى TTS إذا كان الرد يحتوي بالفعل على وسائط أو توجيه MEDIA:.
  • يتخطى الردود القصيرة جدًا (< 10 أحرف).
  • يلخص الردود الطويلة عند التمكين باستخدام agents.defaults.model.primary (أو summaryModel).
  • يرفق الصوت الناتج بالرد.

إذا تجاوز الرد maxLength وتم إيقاف تشغيل الملخص (أو لا يوجد مفتاح API ل نموذج الملخص)، يتم تخطي الصوت ويتم إرسال الرد النصي العادي.

مخطط التدفق

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / MEDIA: / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

استخدام أمر الشرطة المائلة

هناك أمر واحد: /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، تتضمن الأداة [[audio_as_voice]] بحيث يرسل Telegram فقاعة صوتية.

Gateway RPC

طرق Gateway:

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