إنتقل إلى المحتوى الرئيسي

الصوت

الصوت هو إمكانية وسائط اختيارية. هو منفصل عن مسار مزود LLM الأساسي ويستخدم بيانات اعتماد متغيرات البيئة المباشرة فقط.

إذا كانت مزودات الصوت أو أدوات الصوت المحلية أو بيانات الاعتماد الحية غير متوفرة، يستمر تشغيل CLI والبوابة النصي الأساسي دون تغيير. الصوت لا يحظر بقية النظام.

ما يغطيه الصوت

الإمكانيةالوظيفة
TTSتحويل ردود العميل النصية إلى صوت.
STTتحويل صوت المستخدم إلى نص مكتوب.
Auto-TTSت vocalizing ردود البوابة اختياريًا لكل محادثة.
CLI push-to-talkتسجيل إدخال الميكروفون المحلي وإدخال النص في جلسة CLI الحالية.

نضج المزود في v0.1.0

TTS المستضاف — مستقر

المزودملاحظات
OpenAIمزود TTS مستضاف يتطلب مفتاح API. يستخدم محلل بيانات اعتماد OpenAI الصوتي المشترك.
ElevenLabsيستخدم xi-api-key وحودود النص الخاصة بالمزود.
MiniMaxيفك تشفير استجابات الصوت base64 JSON.
Geminiيرسل speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName.
xAIيستخدم نقطة النهاية الأصلية {baseUrl}/tts؛ غير متوافق مع OpenAI.
Edgeخيار الإعداد الموجّه الموصى به/الافتراضي. لا يتطلب مفتاح API؛ يُرسل نص التوليف إلى خدمة Microsoft Edge speech، لذلك فهو شبكي وليس TTS محليًا/offline. يُرجع MP3 (audio/mpeg).

STT المستضاف — مستقر

المزودملاحظات
OpenAIيستخدم محلل بيانات اعتماد OpenAI الصوتي المشترك.
Groqبحث مباشر عن مفتاح البيئة.
xAIيستخدم نقطة النهاية الأصلية {baseUrl}/stt؛ غير متوافق مع OpenAI.

STT المحلي — مستقر

المحركملاحظات
faster-whisperالافتراضي عند stt.provider: "local" في v0.1.0. يستخدم بيئة Python المُدارة من EstaCoda ما لم تُضبط Python مخصصة.
commandاختيار صريح عبر stt.local.engine: "command". يشغل قالب أمر مُعد؛ يفضل نص transcript من stdout.

مؤجل أو تجريبي

  • مزودا TTS المحليان/offline neutts و kittentts — غير مُنفذين في v0.1.0.
  • Mistral TTS/STT — قد توجد أشكال الإعدادات، لكن التنفيذ غير متاح.

لا تُعد مزودات مؤجلة للإنتاج.

الإعدادات

إعدادات الصوت موجودة في الملف الشخصي المحدد:

~/.estacoda/profiles/<profile-id>/config.json

مثال:

{
"tts": {
"enabled": true,
"provider": "openai",
"openai": {
"model": "gpt-4o-mini-tts",
"voice": "alloy",
"apiKeyEnv": "VOICE_TOOLS_OPENAI_KEY"
}
},
"stt": {
"enabled": true,
"provider": "openai",
"openai": {
"model": "gpt-4o-mini-transcribe",
"apiKeyEnv": "VOICE_TOOLS_OPENAI_KEY"
}
},
"voice": {
"autoTts": false,
"autoTtsMaxCharsPerReply": 1200,
"autoTtsMaxCharsPerHourPerChat": 5000
}
}

الحقول الأساسية:

الحقلالمعنى
tts.providerالقيم المنفذة: openai، elevenlabs، minimax، gemini، xai، edge.
tts.enabledعند false، يفشل TTS حتى لو كانت البيانات الاعتماد موجودة.
stt.providerالقيم المنفذة: openai، groq، xai، local.
stt.enabledعند false، يفشل STT قبل آثار النسخ.
voice.autoTtsالإعداد الافتراضي العام لـ auto-TTS في البوابة. الافتراضي false.
voice.autoTtsMaxCharsPerReplyحد اختياري لكل رد يُفحص قبل التوليف.
voice.autoTtsMaxCharsPerHourPerChatحد اختياري ساعيّ لكل منصة/محادثة.

الإعداد الموجّه

يسألك Setup Editor وOnboarding Wizard عن اختيار مزود STT ومزود TTS. لا يطلبان أسماء النماذج أو أسماء مراجع متغيرات البيئة؛ توفر إعدادات التشغيل الافتراضية النماذج والأصوات وإعدادات المزود.

لمزودي Voice المستضافين، يجمع الإعداد مفتاح API الحقيقي عبر إدخال masked. تخزن خطوة review/apply مراجع متغيرات البيئة فقط في الإعدادات، وتكتب قيم الأسرار المحلية للملف الشخصي إلى .env الخاص بالملف الشخصي المحدد بعد التأكيد. لا تُخزن مفاتيح API الخام في الإعدادات، ولا تظهر في review manifests، ولا تُدرج في prompt context، ولا تُسجل أو تُعاد في الأخطاء.

المزودون بلا مفتاح هم STT local وTTS edge. لا يتطلب edge مفتاح API، لكنه ما زال ينفذ طلبًا شبكيًا إلى خدمة Microsoft Edge speech ويرسل نص التوليف إلى تلك الخدمة. المزودون المستضافون الذين يتطلبون مفتاحًا هم STT openai وgroq وxai؛ وTTS openai وelevenlabs وminimax وgemini وxai. المزودون المؤجلون هم STT mistral؛ وTTS mistral وneutts وkittentts.

يمكن للإعداد إعادة استخدام بيانات اعتماد موجودة عبر مراجع متغيرات البيئة مثل VOICE_TOOLS_OPENAI_KEY وOPENAI_API_KEY وGEMINI_API_KEY وGROQ_API_KEY وXAI_API_KEY، وعبر إعدادات/مسارات المزود المتوافقة الموجودة حيثما يكون ذلك مدعومًا. تبقى أعلام CLI المباشرة للمشغل مثل estacoda voice setup --tts-model و--stt-model و--tts-api-key-env و--stt-api-key-env و--tts-api-key و--stt-api-key متاحة للإعداد الصريح عبر السكربتات.

بيانات الاعتماد

تخزن إعدادات الصوت مراجع متغيرات بيئة مباشرة فقط. لا توجد مجمعات بيانات اعتماد أو وسطاء بوابة أو بدائل.

Edge TTS لا يستخدم مفتاح API. لكنه ما زال ينفذ طلبًا شبكيًا إلى خدمة Microsoft Edge speech ويرسل نص التوليف إلى تلك الخدمة.

ترتيب محلل بيانات اعتماد OpenAI الصوتي:

  1. config.openai.apiKeyEnv
  2. VOICE_TOOLS_OPENAI_KEY
  3. OPENAI_API_KEY، فقط عندما يكون المتغير المُعد هو الافتراضي VOICE_TOOLS_OPENAI_KEY

متغير بيئة مخصص مفقود لا يعود إلى OPENAI_API_KEY. لا يتم تسجيل المفاتيح المحلولة أو إرجاعها في الأخطاء.

ملاحظات خاصة بالمزود:

  • xAI TTS يستخدم voiceId، language، sampleRate، bitRate، baseUrl، apiKeyEnv، و speed الاختياري. لا يستخدم tts.xai.model.
  • xAI STT يستخدم baseUrl/base_url، apiKeyEnv/api_key_env، language الاختياري، format، diarize، keyterms، fillerWords، وتلميحات raw-audio. لا يستخدم stt.xai.model.
  • Gemini TTS يرسل speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName.
  • Edge TTS يستخدم tts.edge.voice و tts.edge.speed الاختياري و fallback من tts.speed. الصوت الافتراضي هو en-US-AriaNeural.

CLI push-to-talk

وضع صوت CLI محلي للملف الشخصي:

estacoda voice mode on # تفعيل إدخال push-to-talk
estacoda voice mode tts # تفعيل push-to-talk مع تشغيل TTS محلي على أفضل وجه
estacoda voice mode off # إلغاء التفعيل
estacoda voice mode status # عرض الوضع الحالي

ملف الحالة:

~/.estacoda/profiles/<profile-id>/cli-voice-mode.json

السلوك:

  • تسجيل إدخال الميكروفون المحلي بصيغة WAV أحادية 16 كيلوهرتز.
  • كتابة الصوت فقط في مساحة temp audio الخاصة بالملف الشخصي المحدد.
  • النسخ عبر مزود STT المُعد.
  • طباعة النص المكتوب.
  • إدخال النص غير الفارغ كدورة مستخدم تالية في جلسة CLI الحالية.
  • في وضع tts، التشغيل المحلي على أفضل وجه بعد توفر الرد.
  • أوامر التشغيل المدعومة: afplay، aplay، paplay، ffplay.
  • إذا لم يكن مشغل محلي متاحًا، يتم تخطي التشغيل بسلاسة.

كشف الميكروفون:

البيئةالسلوك
جلسة SSHيُبلغ بأن الميكروفون المحلي غير متاح؛ يقترح تسجيل محلي أو إدخال مسار.
Termuxيستخدم termux-microphone-record عند توفره.
WSL / PulseAudioيفحص pactl list sources.
Linux / macOS أصلييستخدم أوامر تسجيل مدعومة (sox، arec، rec) عند توفرها.

إضافات الصوت الأصلية لـ Node خارج النطاق.

Auto-TTS في البوابة

تُحلل أوامر /voice في البوابة بواسطة ChannelGateway، وليس بواسطة المحولات. تُعرض المحولات methods القدرات حيثما لزم.

حالة الصوت لكل محادثة محلية للملف الشخصي:

~/.estacoda/profiles/<profile-id>/gateway/voice-mode.json

الأوضاع:

الوضعالمعنى
offعدم auto-TTS ردود البوابة لهذه المحادثة.
voice_onlyauto-TTS فقط للردود على الرسائل الصوتية الواردة التي أنتجت نصًا.
allauto-TTS للردود النصية المؤهلة في هذه المحادثة.

الأوامر:

الأمرالسلوك
/voice onضبط المحادثة على voice_only.
/voice voiceبديل لـ voice_only.
/voice allضبط المحادثة على all.
/voice ttsبديل لـ all.
/voice offضبط المحادثة على off.
/voice statusالإبلاغ عن الوضع المحلول للمحادثة.
/voice channelDiscord فقط؛ ينضم إلى قناة الصوت الحالية للمتصل عند السماح.
/voice leaveDiscord فقط؛ يغادر قناة صوت Discord النشطة.

معالجة /voice في محادثات المجموعة تتبع مصادقة البوابة الحالية، ومنطق الذكر، وبوابة الاستجابة الحرة. المستخدمون غير المصرح لهم لا يمكنهم تغيير حالة الصوت لكل محادثة.

حقن النص المكتوب

يستخدم STT الناجح بالضبط:

[Voice message transcript]
{text}

بعد النسخ الناجح، تُزال مرفق الصوت الأصلي من سياق النموذج. فشل النسخ لا يحول ملف صوتي غير صالح إلى نص مرئي للنموذج.

كبت النصوص المكررة هو لكل (platform, chatId):

  • مخزن دائري لآخر 5 نصوص مُطابقة.
  • نافذة مقارنة مدتها 12 ثانية.
  • التطبيع يقلم، يحول لأحرف صغيرة، يضغط المسافات، ويحذف علامات الترقيم.
  • التطابقات الدقيقة للتجزئة/النص تُسقط.
  • نسبة التطابق القريب تُطبق فقط عندما يكون كلا النصين 16 حرفًا على الأقل.

سلوك Auto-TTS

Auto-TTS في البوابة اختياري والنص أولًا:

  • voice.autoTts افتراضيًا false.
  • إذا لم يكن هناك تجاوز لكل محادثة، فإن voice.autoTts: true يعيّن voice_only، وليس all.
  • توصيل النص يبقى أساسيًا.
  • Auto-TTS هو أفضل جهد وفتح للفشل إلى النص.
  • فشل المزود أو التوصيل يسجل تحذيرات آمنة ويترك النص سليمًا.
  • في Telegram، يفعّل /voice on الردود المنطوقة فقط بعد الرسائل الصوتية الواردة، ويجعل /voice all الردود النصية المؤهلة منطوقة أيضًا، ويعطل /voice off الردود المنطوقة، ويعرض /voice status الوضع المحلول.
  • مع /voice on، تتبع رسالة Telegram الصوتية الواردة هذا المسار: Telegram voice message -> STT transcript -> agent text response -> configured TTS provider -> Telegram voice/audio reply.

Auto-TTS يتخطى:

  • الوضع off
  • voice_only عندما كانت الرسالة الواردة ليست رسالة صوتية مكتوبة
  • نص الرد فارغ أو مسافة فقط
  • ردود الأخطاء، بما في ذلك Error:
  • ردود أوامر البوابة مثل /voice status
  • الدورات حيث أنتج العميل أداة TTS/صوت أو استدعى voice.speak
  • الردود التي تحتوي بالفعل على مخرج صوتي
  • تجاوز حدود المزود
  • تجاوز voice.autoTtsMaxCharsPerReply
  • تجاوز voice.autoTtsMaxCharsPerHourPerChat
  • فشل جاهزية المزود

وسائط Auto-TTS مؤقتة. تُكتب الملفات في مساحة temp audio الخاصة بالملف الشخصي، تُسلَّم ككائنات Artifact مع metadata.deliveryHint: "voice" و metadata.ephemeral: true، وتُحذف في كتلة finally على أفضل وجه بعد نجاح أو فشل التوصيل. لا تُحفظ في durable artifact history، ولا تدخل في prompt context، ولا تصبح model-visible attachments أو artifacts طويلة الأجل عادية.

يحاول Telegram تسليم Auto-TTS كـ voice bubble أصلي. يُرجع Edge ملف MP3 (audio/mpeg)، لذلك يتطلب توصيل voice bubble عادةً تحويل ffmpeg إلى OGG/Opus. مع ffmpeg، يحصل Telegram على voice bubble أصلي؛ وبدون ffmpeg، يتلقى Telegram ملفًا صوتيًا عاديًا بدلًا من ذلك.

نص MEDIA:/path الصادر عن النموذج بشكل عشوائي ليس إشارة auto-TTS.

faster-whisper محلي STT

يعمل faster-whisper المحلي عبر عامل Python JSONL طويل الأجل مملوك من قبل بيئة التشغيل لكل runtime/profile. في v0.1.0، يعني stt.provider: "local" مسار faster-whisper المُدار افتراضياً.

المسارات المُدارة:

~/.estacoda/python-env
~/.estacoda/cache/huggingface

~/.estacoda/python-env هي بيئة venv المُدارة. ~/.estacoda/cache/huggingface هي ذاكرة تخزين النموذج الافتراضية. ذاكرة النموذج لا تعيش داخل venv.

شكل الإعدادات:

{
"stt": {
"provider": "local",
"local": {
"engine": "faster-whisper",
"model": "base",
"pythonBinary": "/optional/custom/python",
"fasterWhisper": {
"enabled": true,
"model": "base",
"device": "auto",
"computeType": "default",
"hfHome": "/optional/model-cache",
"allowModelDownload": true,
"gatewayAllowModelDownload": true,
"queueDepth": 1,
"timeoutMs": 300000
}
}
}
}

وضع الأوامر:

{
"stt": {
"provider": "local",
"local": {
"engine": "command",
"command": "/path/to/transcriber {input}"
}
}
}

stt.local.engine: "command" هو الحاكم ولا يستخدم faster-whisper المُدار.

إعداد البيئة المُدارة

estacoda voice setup --stt-provider local

عند عدم توفير Python مخصصة، يقوم الإعداد بما يلي:

  1. يفحص ~/.estacoda/python-env
  2. ينشئه أو يصلحه عندما يكون مفقوداً أو تالفاً
  3. يثبّت بالضبط faster-whisper==1.2.1
  4. يتحقق من import faster_whisper
  5. يكتب إعداد STT المحلي فقط بعد نجاح الإعداد

يعرض الإعداد رسائل تقدم منتقاة، وليس سجلات pip الخام. لا تثبت EstaCoda حزم مستخدم عشوائية في البيئة المُدارة. يُستخدم Python النظام فقط لإنشاء venv؛ لا تُعدّل EstaCoda Python النظام أو conda envs أو project venvs أو poetry envs أو uv envs. تُحصر ذاكرة pip المؤقتة أثناء الإعداد المُدار تحت حالة EstaCoda.

Python مخصص:

estacoda voice setup --stt-provider local --python-binary /path/to/python

هذا يتخطى فحص/إنشاء البيئة المُدارة ويخزن المسار المخصص. المشغل يملك بيئة Python هذه، بما في ذلك تثبيت faster-whisper.

إعداد TTS فقط يبقى TTS فقط:

estacoda voice setup --tts-provider openai

لا يغيّر إعداد STT ولا يلمس بيئة Python المُدارة.

سلوك التشغيل

  • يحل runtime مسار stt.local.pythonBinary المُعد أولاً، وإلا يستخدم مسار venv المُدار تحت ~/.estacoda/python-env.
  • يضبط runtime قيم HF_HOME / TRANSFORMERS_CACHE دائمة تحت ~/.estacoda/cache/huggingface.
  • عندما يكون STT المحلي عبر faster-whisper مضبوطاً دون pythonBinary مخصص، ينشئ runtime بيئة Python المُدارة أو يصلحها عند أول عملية نسخ.
  • يثبّت إعداد runtime المُدار حزمة faster-whisper المثبّتة فقط داخل ~/.estacoda/python-env؛ ولا يغيّر system Python أو venvs المملوكة للمشغل.
  • فشل إعداد Python المُدار لا يمنع بدء runtime أو البوابة؛ يصبح نسخ faster-whisper المحلي فقط غير متاح إلى أن تُصلح البيئة.
  • قد يضيف أمر voice doctor لاحقاً فحص/إصلاح هذا المسار.

سلوك تشغيلي:

  • النموذج الافتراضي هو base. الإعدادات المدعومة: tiny، small، medium، large-v1، large-v2، large-v3.
  • بروتوكول العامل يتضمن protocolVersion: 1.
  • النماذج مخبأة حسب (model, device, computeType).
  • فشل CUDA/الجهاز يعيد المحاولة مرة واحدة بـ device: "cpu" و computeType: "int8" عبر نفس العامل.
  • خروج العامل غير المتوقع يُعيد التشغيل مرة واحدة، ثم يُعلّم faster-whisper غير متاح للـ runtime الحالي.
  • runtime.dispose() يُوقف العامل.
  • المهلة الافتراضية 300 ثانية.
  • عمق الطابور الافتراضي 1 ما لم يُعدل.
  • تجاوز الطابور يفشل سريعًا.
  • ترث تنزيلات النموذج الأولى عبر البوابة allowModelDownload. لأن allowModelDownload افتراضياً true، قد تُنزّل أول رسالة صوتية عبر البوابة ملفات النموذج المضبوط.
  • اضبط gatewayAllowModelDownload: false فقط عندما يجب أن تستخدم رسائل البوابة الصوتية نماذج مخزّنة مسبقًا.
  • يسمح faster-whisper المحلي غير المُطلق من البوابة بتنزيل النماذج افتراضياً.
  • يُمرَّر hfHome إلى العامل عند ضبطه. وإلا تضبط EstaCoda HF_HOME افتراضياً إلى ~/.estacoda/cache/huggingface وتحافظ على TRANSFORMERS_CACHE الموجود إذا ضبطته بيئة العملية مسبقاً.

ملف العامل مُعبَّأ في:

workers/faster-whisper/faster-whisper-worker.py

أنماط الفشل

العرضالسبب المحتملالاستعادة
missing keyمتغير البيئة المُشار إليه من المزود غير موجود.أضفه إلى .env الخاص بالملف الشخصي أو بيئة الخدمة.
disabledtts.enabled أو stt.enabled هي false.فعّل المزود في إعدادات الملف الشخصي إذا كان مقصودًا.
not implementedمزود مؤجل مُحدد (مثل Mistral).اختر مزودًا منفذًا.
python package missingفشل استيراد faster-whisper.شغّل estacoda voice setup --stt-provider local، أو أصلح ~/.estacoda/python-env. عند استخدام --python-binary، أصلح بيئة Python المملوكة للمشغل.
venv support missingيبلغ Python عن نقص ensurepip أو دعم venv.ثبّت حزمة venv الخاصة بالنظام، مثل sudo apt install python3.13-venv أو sudo apt install python3-venv، ثم أعد محاولة إعداد STT المحلي.
download requiredالنموذج المحدد غير مخبأ والتنزيلات ممنوعة.خزّن النموذج مسبقًا أو اسمح بالتنزيل صراحةً.
queue fullتجاوز عمق طابور faster-whisper.انتظر، أو زِد عمق الطابور، أو قلل الطلبات المتزامنة.
timeoutتجاوز طلب STT المهلة.تحقق من أداء النموذج/الجهاز وإعدادات المهلة.
المزود غير متاحخطأ شبكة أو 5xx من المزود.تحقق من الاتصال وحالة المزود.
تجاوز حد auto-TTS في البوابةتجاوز الحد لكل رد أو ساعة.انتظر النافذة الساعية أو ارفع الحد.
تبعية صوت مفقودةffmpeg مفقود لتطبيع التنسيق.ثبّت ffmpeg؛ العملية تتدهور بسلاسة بدونه.

مواقع الحالة والملفات المؤقتة والتخزين المؤقت

المسارالغرض
~/.estacoda/profiles/<profile-id>/temp/audio/تسجيلات CLI، ملفات auto-TTS المؤقتة، تحويلات Telegram، استقبال Discord.
~/.estacoda/profiles/<profile-id>/audio-cache/ذاكرة التخزين المؤقت للصوت ومساحة عمل إخراج الأمر المحلي.
~/.estacoda/profiles/<profile-id>/channel-media/مرفقات القنوات التي تم تنزيلها عبر البوابة.
~/.estacoda/profiles/<profile-id>/gateway/logs/voice-stt-preprocess.jsonlأحداث تدقيق معالجة STT المسبقة في البوابة.
~/.estacoda/python-envبيئة Python الافتراضية المُدارة لـ STT المحلي عبر faster-whisper.
~/.estacoda/cache/huggingfaceذاكرة تخزين النموذج الافتراضية لـ faster-whisper / Hugging Face. منفصلة عن venv.
~/.estacoda/cache/pipذاكرة pip المؤقتة أثناء تثبيت البيئة المُدارة.
hfHome أو متغير بيئة Hugging Face cacheتجاوز اختياري لذاكرة نماذج faster-whisper.

لا تسجل أحداث التدقيق المسارات الخاصة الكاملة. تستخدم تجزئات مسارات مستقرة وبيانات وصفية آمنة للمرفقات.

حدود الأمان

تجري معالجة STT المسبقة في البوابة قبل إرسال المزود، أو بدء العامل، أو ffmpeg، أو STT المستضاف، أو التنزيلات، أو الكتابات المؤقتة:

  1. توحيد attachment.localPath ?? attachment.path ضمن جذور الوسائط/الصوت المسموح بها.
  2. التحقق من نوع الملف والحجم باستخدام التحقق من صوت الإدخال.
  3. فحص جاهزية STT و stt.enabled !== false.
  4. تطبيق سياسة تنزيل faster-whisper قبل أي تنزيل نموذج أولي تُطلقه البوابة. ترث تنزيلات البوابة allowModelDownload، وهو افتراضياً true؛ ويمنعها gatewayAllowModelDownload: false صراحةً.

الجذور المسموح بها هي وسائط القنوات المحلية للملف الشخصي، وذاكرة تخزين الصوت المؤقتة، وجذور temp audio المستخدمة في مسارات استقبال قنوات الصوت.

صفحات ذات صلة

  • البوابة — بيئة تشغيل البوابة، وسياسات الانشغال، وإدارة الخدمة
  • القنوات — إعداد القنوات والنضج
  • الأدوات — توفر الأدوات وفئات المخاطر