---
read_when:
    - تنظیم رفتار لایهٔ رویی صوتی
summary: چرخهٔ حیات لایهٔ رویی صوتی هنگام تداخل واژهٔ بیدارباش و فشار برای صحبت
title: هم‌پوشانی صوتی
x-i18n:
    generated_at: "2026-05-06T09:31:08Z"
    model: gpt-5.5
    provider: openai
    source_hash: 5b30f50512e557bd5a50f0e4e8b7955a847b3b554694347d56638581fcda9514
    source_path: platforms/mac/voice-overlay.md
    workflow: 16
---

# چرخهٔ عمر هم‌پوشان صوتی (macOS)

مخاطب: مشارکت‌کنندگان برنامهٔ macOS. هدف: قابل پیش‌بینی نگه داشتن هم‌پوشان صوتی وقتی واژهٔ بیدارباش و فشار برای صحبت هم‌پوشانی دارند.

## هدف فعلی

- اگر هم‌پوشان از طریق واژهٔ بیدارباش از قبل نمایان باشد و کاربر کلید میانبر را فشار دهد، نشست کلید میانبر به‌جای بازنشانی متن موجود، آن را _می‌پذیرد_. هم‌پوشان تا زمانی که کلید میانبر نگه داشته شده است باقی می‌ماند. وقتی کاربر رها می‌کند: اگر متن برش‌خورده‌ای وجود داشته باشد ارسال شود، وگرنه بسته شود.
- واژهٔ بیدارباش به‌تنهایی همچنان هنگام سکوت به‌طور خودکار ارسال می‌کند؛ فشار برای صحبت بلافاصله هنگام رها کردن ارسال می‌کند.

## پیاده‌سازی‌شده (۹ دسامبر ۲۰۲۵)

- نشست‌های هم‌پوشان اکنون برای هر ضبط (واژهٔ بیدارباش یا فشار برای صحبت) یک توکن دارند. به‌روزرسانی‌های جزئی/نهایی/ارسال/بستن/سطح وقتی توکن مطابقت نداشته باشد کنار گذاشته می‌شوند و از callbackهای کهنه جلوگیری می‌شود.
- فشار برای صحبت هر متن نمایان هم‌پوشان را به‌عنوان پیشوند می‌پذیرد (بنابراین فشار دادن کلید میانبر وقتی هم‌پوشان بیدارباش باز است، متن را نگه می‌دارد و گفتار جدید را به آن اضافه می‌کند). پیش از بازگشت به متن فعلی، تا ۱٫۵ ثانیه برای transcript نهایی منتظر می‌ماند.
- ثبت گزارش chime/هم‌پوشان با سطح `info` در دسته‌های `voicewake.overlay`، `voicewake.ptt` و `voicewake.chime` منتشر می‌شود (شروع نشست، جزئی، نهایی، ارسال، بستن، دلیل chime).

## گام‌های بعدی

1. **VoiceSessionCoordinator (اکتور)**
   - در هر زمان دقیقاً مالک یک `VoiceSession` است.
   - API (مبتنی بر توکن): `beginWakeCapture`، `beginPushToTalk`، `updatePartial`، `endCapture`، `cancel`، `applyCooldown`.
   - callbackهایی را که توکن‌های کهنه دارند کنار می‌گذارد (از باز کردن دوبارهٔ هم‌پوشان توسط تشخیص‌دهنده‌های قدیمی جلوگیری می‌کند).
2. **VoiceSession (مدل)**
   - فیلدها: `token`، `source` (wakeWord|pushToTalk)، متن ثبت‌شده/موقت، پرچم‌های chime، تایمرها (ارسال خودکار، بی‌کاری)، `overlayMode` (display|editing|sending)، مهلت cooldown.
3. **اتصال هم‌پوشان**
   - `VoiceSessionPublisher` (`ObservableObject`) نشست فعال را در SwiftUI بازتاب می‌دهد.
   - `VoiceWakeOverlayView` فقط از طریق publisher رندر می‌شود؛ هرگز singletonهای سراسری را مستقیم تغییر نمی‌دهد.
   - کنش‌های کاربر در هم‌پوشان (`sendNow`، `dismiss`، `edit`) با توکن نشست به coordinator برمی‌گردند.
4. **مسیر ارسال یکپارچه**
   - در `endCapture`: اگر متن برش‌خورده خالی باشد → بستن؛ وگرنه `performSend(session:)` (chime ارسال را یک بار پخش می‌کند، ارسال می‌کند، می‌بندد).
   - فشار برای صحبت: بدون تأخیر؛ واژهٔ بیدارباش: تأخیر اختیاری برای ارسال خودکار.
   - پس از پایان فشار برای صحبت، یک cooldown کوتاه روی runtime بیدارباش اعمال کنید تا واژهٔ بیدارباش بلافاصله دوباره فعال نشود.
5. **ثبت گزارش**
   - coordinator گزارش‌های `.info` را در subsystem `ai.openclaw` و دسته‌های `voicewake.overlay` و `voicewake.chime` منتشر می‌کند.
   - رویدادهای کلیدی: `session_started`، `adopted_by_push_to_talk`، `partial`، `finalized`، `send`، `dismiss`، `cancel`، `cooldown`.

## فهرست بررسی اشکال‌زدایی

- هنگام بازتولید هم‌پوشان گیرکرده، گزارش‌ها را استریم کنید:

  ```bash
  sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact
  ```

- بررسی کنید فقط یک توکن نشست فعال وجود داشته باشد؛ callbackهای کهنه باید توسط coordinator کنار گذاشته شوند.
- مطمئن شوید رها کردن فشار برای صحبت همیشه `endCapture` را با توکن فعال فراخوانی می‌کند؛ اگر متن خالی باشد، انتظار `dismiss` بدون chime یا ارسال را داشته باشید.

## گام‌های مهاجرت (پیشنهادی)

1. `VoiceSessionCoordinator`، `VoiceSession` و `VoiceSessionPublisher` را اضافه کنید.
2. `VoiceWakeRuntime` را بازآرایی کنید تا به‌جای دست زدن مستقیم به `VoiceWakeOverlayController`، نشست‌ها را ایجاد/به‌روزرسانی/پایان دهد.
3. `VoicePushToTalk` را بازآرایی کنید تا نشست‌های موجود را بپذیرد و هنگام رها کردن `endCapture` را فراخوانی کند؛ cooldown مربوط به runtime را اعمال کنید.
4. `VoiceWakeOverlayController` را به publisher وصل کنید؛ فراخوانی‌های مستقیم از runtime/PTT را حذف کنید.
5. آزمون‌های یکپارچه‌سازی برای پذیرش نشست، cooldown و بستن متن خالی اضافه کنید.

## مرتبط

- [برنامهٔ macOS](/fa/platforms/macos)
- [بیدارباش صوتی (macOS)](/fa/platforms/mac/voicewake)
- [حالت گفتگو](/fa/nodes/talk)