# التنبيه الصوتي والضغط للتحدث

# الأوضاع

• وضع كلمة التنبيه (افتراضي): ينتظر مُعرّف الكلام العامل دائمًا رموز التشغيل (swabbleTriggerWords). عند التطابق، يبدأ الالتقاط، ويعرض الطبقة المتراكبة مع النص الجزئي، ويرسل تلقائيًا بعد الصمت.
• الضغط للتحدث (الضغط المستمر على زر Option الأيمن): اضغط باستمرار على زر Option الأيمن لبدء الالتقاط فورًا، من دون الحاجة إلى مشغّل. تظهر الطبقة المتراكبة أثناء الضغط؛ ويؤدي الإفلات إلى الإنهاء وإعادة التوجيه بعد تأخير قصير حتى تتمكن من تعديل النص.

# سلوك وقت التشغيل (كلمة التنبيه)

• يعيش مُعرّف الكلام في VoiceWakeRuntime.
• لا يعمل المشغّل إلا عند وجود توقف ذي معنى بين كلمة التنبيه والكلمة التالية (فاصل يقارب 0.55 ثانية). يمكن أن تبدأ الطبقة المتراكبة/الرنين عند التوقف حتى قبل بدء الأمر.
• نوافذ الصمت: 2.0 ثانية عندما يكون الكلام متدفقًا، و5.0 ثوانٍ إذا لم يُسمع إلا المشغّل.
• إيقاف صارم: 120 ثانية لمنع الجلسات المنفلتة.
• منع الارتداد بين الجلسات: 350 مللي ثانية.
• تُدار الطبقة المتراكبة عبر VoiceWakeOverlayController مع تلوين ملتزم/متقلب.
• بعد الإرسال، يُعاد تشغيل المُعرّف بشكل نظيف للاستماع إلى المشغّل التالي.

# ثوابت دورة الحياة

• إذا كان التنبيه الصوتي مفعّلًا وكانت الأذونات ممنوحة، فيجب أن يكون مُعرّف كلمة التنبيه مستمعًا (إلا أثناء التقاط صريح بالضغط للتحدث).
• يجب ألا تمنع رؤية الطبقة المتراكبة (بما في ذلك الإغلاق اليدوي عبر زر X) المُعرّف من الاستئناف أبدًا.

# نمط فشل الطبقة المتراكبة المثبتة (سابقًا)

سابقًا، إذا علقت الطبقة المتراكبة وظلت ظاهرة ثم أغلقتها يدويًا، كان من الممكن أن يبدو التنبيه الصوتي "ميتًا" لأن محاولة إعادة التشغيل في وقت التشغيل قد تُحجب بسبب رؤية الطبقة المتراكبة ولا تُجدول أي إعادة تشغيل لاحقة.

التقوية:

• لم تعد إعادة تشغيل وقت تشغيل التنبيه تُحجب بسبب رؤية الطبقة المتراكبة.
• يؤدي اكتمال إغلاق الطبقة المتراكبة إلى تشغيل VoiceWakeRuntime.refresh(...) عبر VoiceSessionCoordinator، لذلك يستأنف الإغلاق اليدوي بزر X الاستماع دائمًا.

# تفاصيل الضغط للتحدث

• يستخدم اكتشاف مفتاح الاختصار مراقب .flagsChanged عامًّا من أجل Option الأيمن (keyCode 61 + .option). نحن نراقب الأحداث فقط (من دون ابتلاعها).
• يعيش مسار الالتقاط في VoicePushToTalk: يبدأ التعرّف على الكلام فورًا، ويبث الأجزاء الجزئية إلى الطبقة المتراكبة، ويستدعي VoiceWakeForwarder عند الإفلات.
• عند بدء الضغط للتحدث، نوقف وقت تشغيل كلمة التنبيه مؤقتًا لتجنب تنافس نقاط التقاط الصوت؛ ويُعاد تشغيله تلقائيًا بعد الإفلات.
• الأذونات: يتطلب الميكروفون + التعرّف على الكلام؛ ورؤية الأحداث تحتاج إلى موافقة إمكانية الوصول/مراقبة الإدخال.
• لوحات المفاتيح الخارجية: قد لا تعرض بعض اللوحات Option الأيمن كما هو متوقع، لذلك وفّر اختصارًا احتياطيًا إذا أبلغ المستخدمون عن حالات عدم التقاط.

# الإعدادات المرئية للمستخدم

• مفتاح تبديل التنبيه الصوتي: يفعّل وقت تشغيل كلمة التنبيه.
• اضغط باستمرار على Cmd+Fn للتحدث: يفعّل مراقب الضغط للتحدث. معطل على macOS < 26.
• منتقيات اللغة والميكروفون، ومقياس مستوى مباشر، وجدول كلمات التشغيل، والمختبِر (محلي فقط؛ لا يعيد التوجيه).
• يحتفظ منتقي الميكروفون بآخر تحديد إذا انقطع اتصال جهاز، ويعرض تلميحًا عن الانقطاع، ويعود مؤقتًا إلى الإعداد الافتراضي للنظام حتى يعود الجهاز.
• الأصوات: رنين عند اكتشاف المشغّل وعند الإرسال؛ الإعداد الافتراضي هو صوت نظام macOS "Glass". يمكنك اختيار أي ملف قابل للتحميل عبر NSSound (مثل MP3/WAV/AIFF) لكل حدث أو اختيار بلا صوت.

# سلوك إعادة التوجيه

• عند تفعيل التنبيه الصوتي، تُعاد توجيه النصوص المنسوخة إلى Gateway/الوكيل النشط (وضع المحلي مقابل البعيد نفسه الذي يستخدمه باقي تطبيق Mac).
• تُسلَّم الردود إلى آخر مزود رئيسي مستخدم (WhatsApp/Telegram/Discord/WebChat). إذا فشل التسليم، يُسجل الخطأ ويظل التشغيل مرئيًا عبر WebChat/سجلات الجلسة.

# حمولة إعادة التوجيه

• يضيف VoiceWakeForwarder.prefixedTranscript(_:) تلميح الجهاز قبل الإرسال. وهو مشترك بين مساري كلمة التنبيه والضغط للتحدث.

# التحقق السريع

• فعّل الضغط للتحدث، واضغط باستمرار على Cmd+Fn، وتحدث، ثم أفلت: يجب أن تعرض الطبقة المتراكبة الأجزاء الجزئية ثم ترسل.
• أثناء الضغط المستمر، يجب أن تبقى آذان شريط القوائم مكبرة (تستخدم triggerVoiceEars(ttl:nil))، ثم تصغر بعد الإفلات.

# ذو صلة

• التنبيه الصوتي
• الطبقة الصوتية المتراكبة
• تطبيق macOS