---
read_when:
    - การทำงานกับเส้นทางของ voice wake หรือ PTT
summary: โหมดคำปลุกด้วยเสียงและ push-to-talk รวมถึงรายละเอียดการกำหนดเส้นทางในแอป Mac
title: Voice Wake (macOS)
x-i18n:
    generated_at: "2026-04-23T05:45:25Z"
    model: gpt-5.4
    provider: openai
    source_hash: fed6524a2e1fad5373d34821c920b955a2b5a3fcd9c51cdb97cf4050536602a7
    source_path: platforms/mac/voicewake.md
    workflow: 15
---

# Voice Wake และ Push-to-Talk

## โหมด

- **โหมดคำปลุก** (ค่าเริ่มต้น): ตัวรู้จำ Speech ที่เปิดตลอดเวลาจะรอโทเค็นคำปลุก (`swabbleTriggerWords`) เมื่อจับคู่ได้ มันจะเริ่มการจับเสียง แสดง overlay พร้อมข้อความบางส่วน และส่งอัตโนมัติหลังความเงียบ
- **Push-to-talk (กด Right Option ค้าง)**: กดปุ่ม Right Option ค้างเพื่อเริ่มจับเสียงได้ทันที—ไม่ต้องมีคำปลุก Overlay จะปรากฏขณะกดค้าง; เมื่อปล่อยปุ่มจะเป็นการสรุปผลและส่งต่อหลังจากหน่วงสั้นๆ เพื่อให้คุณมีเวลาปรับแก้ข้อความ

## พฤติกรรมของรันไทม์ (คำปลุก)

- ตัวรู้จำ Speech อยู่ใน `VoiceWakeRuntime`
- trigger จะทำงานก็ต่อเมื่อมี **ช่วงหยุดที่มีนัยสำคัญ** ระหว่างคำปลุกกับคำถัดไป (ช่องว่างประมาณ 0.55 วินาที) overlay/เสียงเตือนอาจเริ่มขึ้นในช่วงหยุดนั้น แม้ก่อนที่คำสั่งจะเริ่ม
- หน้าต่างความเงียบ: 2.0 วินาทีเมื่อคำพูดไหลต่อเนื่อง, 5.0 วินาทีหากได้ยินเพียงคำปลุก
- หยุดแบบตายตัว: 120 วินาที เพื่อป้องกัน session ที่รันยาวเกินควบคุม
- debounce ระหว่าง sessions: 350ms
- overlay ถูกขับเคลื่อนผ่าน `VoiceWakeOverlayController` พร้อมการระบายสีแบบ committed/volatile
- หลังส่ง ตัวรู้จำจะเริ่มใหม่อย่างสะอาดเพื่อรอฟังคำปลุกครั้งถัดไป

## อินวาเรียนต์ของวงจรชีวิต

- หากเปิดใช้ Voice Wake และมีการให้สิทธิ์แล้ว ตัวรู้จำคำปลุกควรอยู่ในสถานะกำลังฟัง (ยกเว้นระหว่างการจับเสียงแบบ push-to-talk ที่ผู้ใช้เริ่มเองอย่างชัดเจน)
- การมองเห็นของ overlay (รวมถึงการปิดด้วยตนเองผ่านปุ่ม X) ต้องไม่ขัดขวางไม่ให้ตัวรู้จำกลับมาทำงานอีกครั้ง

## โหมดความล้มเหลวของ sticky overlay (ก่อนหน้า)

ก่อนหน้านี้ หาก overlay ค้างอยู่ในสถานะแสดงผลและคุณปิดมันด้วยตนเอง Voice Wake อาจดูเหมือน “ตาย” เพราะความพยายามรีสตาร์ตของรันไทม์อาจถูกบล็อกโดยการมองเห็นของ overlay และไม่มีการกำหนดรีสตาร์ตครั้งถัดไปไว้

การทำให้แข็งแกร่งขึ้น:

- การรีสตาร์ตรันไทม์ของ wake จะไม่ถูกบล็อกด้วยการมองเห็นของ overlay อีกต่อไป
- เมื่อการปิด overlay เสร็จสมบูรณ์ จะกระตุ้น `VoiceWakeRuntime.refresh(...)` ผ่าน `VoiceSessionCoordinator` ดังนั้นการกด X เพื่อปิดด้วยตนเองจะทำให้กลับไปฟังต่อเสมอ

## รายละเอียดเฉพาะของ push-to-talk

- การตรวจจับ hotkey ใช้ตัวเฝ้าดู `.flagsChanged` แบบโกลบอลสำหรับ **Right Option** (`keyCode 61` + `.option`) เราเพียงสังเกต events (ไม่กลืน event)
- ไปป์ไลน์การจับเสียงอยู่ใน `VoicePushToTalk`: เริ่ม Speech ทันที, สตรีม partials ไปยัง overlay และเรียก `VoiceWakeForwarder` เมื่อปล่อยปุ่ม
- เมื่อเริ่ม push-to-talk เราจะ pause รันไทม์คำปลุกเพื่อหลีกเลี่ยง audio taps ที่แย่งกัน; มันจะเริ่มใหม่อัตโนมัติหลังปล่อยปุ่ม
- Permissions: ต้องใช้ทั้ง Microphone + Speech; การมองเห็น events ต้องได้รับการอนุมัติ Accessibility/Input Monitoring
- คีย์บอร์ดภายนอก: บางรุ่นอาจไม่แสดง Right Option ตามที่คาดไว้—ควรมีคีย์ลัดสำรองหากผู้ใช้รายงานว่าจับไม่ติด

## การตั้งค่าที่ผู้ใช้มองเห็น

- สวิตช์ **Voice Wake**: เปิดใช้รันไทม์คำปลุก
- **Hold Cmd+Fn to talk**: เปิดใช้ตัวเฝ้าดู push-to-talk ปิดใช้งานบน macOS < 26
- ตัวเลือกภาษาและไมค์, มิเตอร์ระดับเสียงแบบสด, ตารางคำปลุก, ตัวทดสอบ (เฉพาะในเครื่อง; ไม่ส่งต่อ)
- ตัวเลือกไมค์จะคงการเลือกครั้งล่าสุดไว้หากอุปกรณ์ถูกตัดการเชื่อมต่อ, แสดงคำใบ้ว่า disconnected และ fallback ชั่วคราวไปยังค่าเริ่มต้นของระบบจนกว่าอุปกรณ์จะกลับมา
- **Sounds**: มีเสียงเตือนเมื่อพบคำปลุกและเมื่อส่ง; ค่าเริ่มต้นคือเสียงระบบ macOS “Glass” คุณสามารถเลือกไฟล์ใดก็ได้ที่ `NSSound` โหลดได้ (เช่น MP3/WAV/AIFF) สำหรับแต่ละเหตุการณ์ หรือเลือก **No Sound**

## พฤติกรรมการส่งต่อ

- เมื่อเปิดใช้ Voice Wake ทรานสคริปต์จะถูกส่งต่อไปยัง gateway/agent ที่กำลังใช้งาน (ใช้โหมด local หรือ remote เดียวกับส่วนอื่นของแอป Mac)
- การตอบกลับจะถูกส่งไปยัง **main provider ที่ใช้งานล่าสุด** (WhatsApp/Telegram/Discord/WebChat) หากการส่งล้มเหลว ข้อผิดพลาดจะถูกบันทึกล็อก และยังคงมองเห็นการรันนั้นได้ผ่าน WebChat/session logs

## เพย์โหลดการส่งต่อ

- `VoiceWakeForwarder.prefixedTranscript(_:)` จะเติม machine hint นำหน้าก่อนส่ง ใช้ร่วมกันระหว่างเส้นทางคำปลุกและ push-to-talk

## การตรวจสอบแบบรวดเร็ว

- เปิดใช้ push-to-talk แล้วกด Cmd+Fn ค้าง พูด แล้วปล่อย: overlay ควรแสดง partials แล้วจึงส่ง
- ระหว่างกดค้าง หูบน menu-bar ควรยังขยายอยู่ (ใช้ `triggerVoiceEars(ttl:nil)`); จากนั้นจะยุบลงหลังปล่อยปุ่ม
