عن المشروع

## نظرة عامة على المشروع تطبيق AirPods Voice 输入法 هو تطبيق أصلي لشريط قائمة macOS، يتحكم في الإدخال الصوتي عبر إيماءة النقرة الواحدة في AirPods: نقرة واحدة تبدأ التسجيل، ونقرة أخرى توقف التسجيل وتؤكد النص وترسله تلقائيًا، دون الحاجة إلى لمس لوحة المفاتيح طوال العملية. الإصدار الرسمي الحالي هو 1.0. ## الميزات الرئيسية - نقرة واحدة على AirPods تبدأ الإدخال الصوتي، ونقرة أخرى توقفه وترسله تلقائيًا. - يدعم الاستخدام المتواصل لعدة جولات، مع العودة إلى حالة الخمول القابلة لإعادة التشغيل بعد كل جولة. - متوافق مع الميكروفون المدمج وميكروفون AirPods، دون الحاجة إلى تعديل إعدادات التطبيق. - يحاكي افتراضيًا الضغط المطول على `Fn`، ويمكن تهيئته أيضًا إلى Control أو Option أو Command أو Shift أو F1–F12. - يوفر شريط القائمة ونافذة التحكم حالة التشغيل، بالإضافة إلى البدء والإيقاف وتعليمات الاستخدام والخروج. - يعرض نافذة التحكم في كل مرة يُفتح فيها التطبيق، ويستمر بعد إغلاقها في شريط القائمة. - يؤدي إدخال لوحة المفاتيح الفعلية إلى إيقاف تلقائي لمفتاح الصوت غير المنتهي، مما يمنع مفاتيح التعديل من التأثير على الطرفية أو برامج المهام. - لا يشغل Dock، ولا يعتمد على برامج أتمتة تابعة لجهات خارجية مثل BetterTouchTool. - يدعم Apple Silicon وIntel Mac، ويتطلب macOS 13 كحد أدنى. ## متطلبات الاستخدام يجب ضبط اختصار الإدخال الصوتي في أسلوب الإدخال الصوتي الخاص بالمستخدم على «الضغط المطول على Fn». يوضح README أن الإصدار 1.0 اجتاز فحص قبول متعدد الجولات باستخدام AirPods فعلية مع أسلوب إدخال Doubao، وتحتاج أساليب الإدخال الأخرى إلى دعم سلوك «اضغط مع الاستمرار على الاختصار للتسجيل، وحرره للإنهاء». أثناء تشغيل التطبيق، يتولى نقرة التشغيل/الإيقاف المؤقت الواحدة في AirPods، لذلك لا يمكن استخدام النقرة للتحكم في الموسيقى في ذلك الوقت؛ وتعود عناصر التحكم في الوسائط بعد إيقاف التطبيق أو الخروج منه. ## التثبيت والصلاحيات نزّل حزمة PKG من GitHub Releases وثبّتها إلى `/Applications/AirPods Voice 输入法.app`. سيقوم المثبّت تلقائيًا بإيقاف الإصدارات التجريبية القديمة وإزالتها، مما يمنع إصدارين من تولي AirPods في الوقت نفسه. الحزمة الحالية موقعة بتوقيع ad-hoc، وإذا منعها macOS يمكن النقر بزر الماوس الأيمن في Finder واختيار «فتح». يجب أن يحصل التطبيق على صلاحية Accessibility في macOS ليتمكن من محاكاة الضغط المطول على مفتاح الصوت وإرسال مفتاح Return. الكيان المصرّح له هو التطبيق نفسه؛ لا حاجة لمنح صلاحية للطرفية أو أدوات التطوير، ولا حاجة إلى الوصول الكامل إلى القرص. لا يجمع التطبيق نفسه صوت الميكروفون؛ إذ تُدار صلاحية الميكروفون بواسطة أسلوب الإدخال الصوتي الذي يختاره المستخدم. ## طريقة العمل (وفق وصف README) يحتفظ التطبيق عبر `MPRemoteCommandCenter` بجلسة Now Playing لاستقبال نقرات AirPods، ولا يقبل إلا أحداث الوسائط الواردة من `com.apple.bluetoothd` أو `com.apple.cloudpaird`؛ أما المصادر الأخرى مثل مفتاح التشغيل في لوحة المفاتيح فلا تبدأ الصوت. بعد دخول ميكروفون AirPods في وضع صوت المكالمة، يُبلغ `bluetoothd` عن النقرة الثانية بوصفها Software Mute، ويعاملها التطبيق كإشارة إيقاف وإرسال فقط داخل جلسة صوتية بدأها هو نفسه. تعمل مراقبة IOHID كقناة احتياطية، ويُزيل تكرار العملية الفعلية نفسها عبر نافذة مدتها 350ms. ترسل النقرة الأولى تفعيل Fn مرة واحدة عبر `IOHIDPostEvent`؛ وتنهي النقرة الثانية جلسة التسجيل ثم ترسل مفتاحي Return بالتتابع، يؤكد الأول النص المركّب من أسلوب الإدخال، ويرسل الثاني الرسالة. لمنع مفاتيح التعديل العامة من التأثير على التطبيقات الحساسة للاختصارات، يضيف الإصدار 1.0 ثلاث طبقات حماية: تنظيف Fn المتبقي تاريخيًا عند بدء التشغيل؛ عند اكتشاف إدخال من لوحة المفاتيح الفعلية أثناء الصوت، تُزال أولاً مفاتيح تعديل الصوت ويُنهى الصوت فورًا؛ عند خروج التطبيق بشكل غير طبيعي، يحرر daemon مستقل مفتاح Fn. عند الإيقاف العادي، أو تبديل التطبيق الأمامي، أو انتهاء مهلة الأمان البالغة 5 دقائق، أو الخروج من التطبيق، يتم تحرير المفتاح فقط دون إرسال عرضي. ## الإعداد والسجلات ملف الإعداد الافتراضي هو `config/voice-key` ومحتواه `fn`، ويمكن تغييره إلى control أو option أو command أو shift أو f1–f12، ويلزم إعادة تشغيل السكربت بعد التعديل. يمكن أيضًا تحديده مؤقتًا عبر متغير بيئة أثناء تشغيل الكود المصدري. توجد السجلات في `/tmp/airpods-voice-input-method/` ضمن app.log وapp.stdout.log وapp.stderr.log، ويمكن استخدام `pgrep -fl airpods-voice-input-method` للتحقق من العملية، و`./scripts/stop.sh` للإيقاف الآمن وتحرير مفتاح الصوت. ## البناء والاختبار يوفر `scripts/build.sh` لبناء تطبيق Universal، و`scripts/package-release.sh` لإنشاء PKG، مع دعم تحديد شهادة Developer ID. تغطي سكربتات الاختبار أربع جولات من التفاعل الصوتي، واستهلاك Fn، وأمان لوحة المفاتيح، والاسترداد بعد التعطل، وسيناريوهات الانحدار الأخرى، بالإضافة إلى `tests/hitl-two-cycle.sh` للفحص البشري باستخدام AirPods فعلية. ## الترخيص يستخدم الكود المصدري ترخيص PolyForm Noncommercial 1.0.0، وهو ترخيص source-available وليس ترخيص مفتوح المصدر وفق تعريف OSI؛ يُسمح بالتعلم الشخصي والبحث والاستخدام غير التجاري، ويتطلب الاستخدام التجاري الحصول على إذن منفصل.