Xamathi/KeyXamathi/Docs

เอกสารประกอบ

รายละเอียดเทคนิค วิธีตั้งค่า และวิธีตรวจสอบแอปด้วยตัวเอง

ทำไมต้องขอ Accessibility?

macOS อนุญาตให้แอปดักจับและแก้ไข keystrokes ได้เฉพาะผ่านกลไก CGEventTap ซึ่งต้องการสิทธิ์ Accessibility

KeyXamathi ใช้สิทธิ์นี้เพื่อ:

  • ดักจับ keystrokes ที่เกิดขึ้นระหว่างระบบกำลังสลับ layout (ช่วง latency)
  • แก้ตัวอักษรที่หลุดภาษาก่อนส่งกลับระบบ
  • ตรวจจับสถานะ Caps Lock

สิ่งที่ไม่ได้ขอ

Input Monitoring — ไม่จำเป็น เพราะแอปใช้ .cghidEventTap (active tap ที่ต้องการ Accessibility) ไม่ใช่ .listenOnly tap (ที่ต้องการ Input Monitoring)

ตรวจสอบได้เองที่ System Settings → Privacy & Security → Input Monitoring — KeyXamathi ไม่อยู่ในรายการ

วิธีตั้งค่า

ขั้นตอนที่ 1: ติดตั้ง

เปิดไฟล์ .dmg แล้วลาก KeyXamathi ไปโฟลเดอร์ Applications ถ้า macOS แจ้งว่าแอปจากนักพัฒนาที่ไม่รู้จัก ให้คลิกขวาที่ไอคอนแอป → เลือก Open

ขั้นตอนที่ 2: ให้สิทธิ์ Accessibility

แอปจะแสดงหน้าต่างแนะนำพร้อมปุ่มพาไป System Settings โดยตรง

  1. เปิด System Settings → Privacy & Security → Accessibility
  2. คลิกปุ่มแม่กุญแจเพื่อปลดล็อก
  3. เปิดสวิตช์ข้าง KeyXamathi
การตั้งค่าระบบ (System Settings)
ความเป็นส่วนตัวและความปลอดภัย
♿️ การช่วยการเข้าถึง (Accessibility)

การช่วยการเข้าถึง (Accessibility)

อนุญาตให้แอปพลิเคชันด้านล่างควบคุมคอมพิวเตอร์ของคุณ

KeyXamathi
👉 เปิดสวิตช์นี้เพื่อให้แอปดักจับและแก้ตัวอักษรที่สลับภาษาไม่ทัน

ขั้นตอนที่ 3: เลือกปุ่มสลับภาษา

แอปมี 3 ตัวเลือก:

Option 1: Caps Lock ปกติ

ใช้ Caps Lock ตามที่ macOS ตั้งไว้ ไม่ remap อะไร ทำงานได้แต่ยังมี latency เล็กน้อยจากระบบ

Option 2: Caps Lock → F19 แนะนำ

ใช้ hidutil remap Caps Lock เป็นปุ่ม F19 ทุกคีย์บอร์ดที่ต่ออยู่ KeyXamathi จัดการสลับภาษาเองโดยตรงผ่าน TISSelectInputSource ตัดปัญหา latency ได้เกือบ 100%

Option 3: F19 เฉพาะคีย์บอร์ดนอก

remap เฉพาะคีย์บอร์ดภายนอก MacBook ยังใช้ Caps Lock ปกติ (ไฟ LED ทำงานตามปกติ)

🔍 ตรวจสอบ Privacy ด้วยตัวเอง

เราไม่อยากให้คุณเชื่อแค่เพราะเราบอก — นี่คือวิธีตรวจสอบด้วยตัวเองว่าแอปไม่ส่งข้อมูลออกไปไหนจริงๆ

1

Activity Monitor — ง่ายที่สุด

ความยาก: ⭐ ทำได้ทุกคน

  1. เปิด Activity Monitor (อยู่ใน Applications → Utilities)
  2. คลิกแท็บ Network
  3. หา KeyXamathi ในรายการ
  4. ดูที่คอลัมน์ Sent Bytes และ Rcvd Bytes
ผลที่คาดหวัง: Sent Bytes = 0 (หรือไม่มีแอปอยู่ในรายการเลย ถ้ายังไม่เปิด telemetry)
2

Little Snitch / LuLu — Firewall แอปเดียว

ความยาก: ⭐⭐ ต้องติดตั้งแอปเพิ่ม

  1. ติดตั้ง LuLu (ฟรี) หรือ Little Snitch
  2. ตั้ง rule Block สำหรับ KeyXamathi
  3. ใช้ KeyXamathi ตามปกติ
ผลที่คาดหวัง: แอปทำงานได้ 100% ปกติ ไม่มี popup แจ้งว่าพยายามเชื่อมต่อ (เพราะไม่มี connection ให้บล็อก)
3

Console.app — ดู log ระบบ

ความยาก: ⭐⭐ ต้องอ่าน log

  1. เปิด Console (อยู่ใน Applications → Utilities)
  2. พิมพ์ KeyXamathi ในช่องค้นหา
  3. ดู log ที่ปรากฏ ตรวจว่าไม่มี network-related entries
ผลที่คาดหวัง: log ที่เห็นเป็นแค่ event tap, layout switch, key processing — ไม่มี URL, ไม่มี HTTP request
4

Wireshark / tcpdump — จับ packet จริง

ความยาก: ⭐⭐⭐ สำหรับ technical users

เปิด Terminal แล้วรัน:

sudo tcpdump -i any -n host 0.0.0.0/0 and proc KeyXamathi

หรือใช้ Wireshark filter by process

ผลที่คาดหวัง: ไม่มี packet ใดๆ — ไม่มี DNS query, ไม่มี TCP handshake, ไม่มีอะไรทั้งนั้น
5

ปิดอินเทอร์เน็ตทั้งเครื่อง — เรียบง่ายที่สุด

ความยาก: ⭐ ทำได้ทุกคน

  1. ปิด Wi-Fi (หรือถอดสาย Ethernet)
  2. ใช้ KeyXamathi ตามปกติ
ผลที่คาดหวัง: แอปทำงานได้ทุกอย่าง 100% เหมือนมีเน็ต — เพราะไม่ต้องการเน็ตตั้งแต่แรก

รายละเอียดเทคนิค

สถาปัตยกรรม

  • CGEventTap (.cghidEventTap, active tap) — ดักจับ key events ก่อนระบบจัดการ
  • TISSelectInputSource (Carbon API) — สั่งสลับภาษาโดยตรง ไม่ผ่าน shortcut
  • hidutil property --set — remap Caps Lock → F19 ระดับ HID
  • IOHIDManager — enumerate คีย์บอร์ดที่ต่ออยู่ (สำหรับ Option 3: remap เฉพาะคีย์บอร์ดนอก)
  • LaunchAgent — persist remap ข้าม reboot

Flow การทำงาน

  1. ผู้ใช้กด Caps Lock (หรือ F19 หลัง remap)
  2. Event Tap จับ key event
  3. KeyXamathi สั่ง TISSelectInputSource สลับภาษาทันที
  4. ระหว่างรอระบบสลับจริง keystrokes ที่มาระหว่างนี้ถูกคิวไว้
  5. เมื่อสลับเสร็จ ปล่อย queued keystrokes ออกมาเป็นภาษาที่ถูกต้อง

Fallback

ถ้า TISSelectInputSource ล้มเหลว (หายากมาก) แอปจะ fallback ไปใช้ "Select next source in input menu" ซึ่งเป็นกลไกของ macOS เอง — ไม่มี latency แฝงเหมือน Control+Space

FAQ เทคนิค

Event Tap กับ Input Monitoring ต่างกันยังไง?

Event Tap (CGEventTap) ใช้ Accessibility permission — สามารถดักจับและแก้ไข key events ได้ (active tap)

Input Monitoring ใช้สำหรับ .listenOnly tap — แค่ฟังอย่างเดียว ไม่สามารถแก้ไข events ได้

KeyXamathi ต้องการแก้ไข keystrokes (เปลี่ยนตัวอักษรที่หลุดภาษา) จึงใช้ active tap + Accessibility ไม่ใช่ listen-only + Input Monitoring

hidutil remap คืออะไร?

hidutil เป็นเครื่องมือของ macOS เอง (ไม่ใช่ third-party) สำหรับ remap ปุ่มในระดับ HID (Human Interface Device) — เปลี่ยน keycode ก่อนที่ระบบจะเห็น

KeyXamathi ใช้ hidutil property --set เพื่อ remap Caps Lock (keycode 57) เป็น F19 (keycode 80) ทำให้ macOS ไม่จัดการ Caps Lock toggle เอง ปล่อยให้ KeyXamathi สั่งสลับภาษาโดยตรง

LaunchAgent ทำอะไร?

LaunchAgent เป็นกลไกของ macOS สำหรับรันคำสั่งตอนเปิดเครื่อง KeyXamathi ใช้เพื่อ:

  • ตั้ง hidutil remap ใหม่ทุกครั้งที่ login (เพราะ remap หายตอน reboot)
  • เปิดแอปอัตโนมัติ (ถ้าผู้ใช้เปิดตัวเลือกนี้ไว้)

ไฟล์อยู่ที่ ~/Library/LaunchAgents/ — ลบได้ทุกเมื่อ

ถ้าเปิด Option 3 แล้วเสียบคีย์บอร์ดใหม่ ต้องทำอะไรไหม?

ต้องปิดแล้วเปิดโหมดใหม่ (หรือรีสตาร์ทแอป) เพื่อให้แอปจับอุปกรณ์ใหม่ — ยังไม่มี auto-detect คีย์บอร์ดที่เสียบเพิ่มระหว่างใช้งาน