PHTV (Precision Hybrid Typing Vietnamese) là bộ gõ tiếng Việt nhanh và riêng tư cho macOS 14+. Ứng dụng chạy như một menu bar app native bằng Swift/SwiftUI, bắt phím bằng CGEvent tap và xử lý tiếng Việt trực tiếp trên máy.
Tự động cập nhật - Nhận phiên bản mới ngay khi ra mắt với Sparkle framework. Không cần tải lại thủ công.
# Cài đặt bằng Homebrew
brew install --cask phtv
# Mở ứng dụng
open /Applications/PHTV.appQuan trọng: Trước khi sử dụng, bạn nên tắt các tính năng tự động sửa lỗi của macOS (Correct spelling, Capitalize words, inline predictive text,...) trong System Settings > Keyboard > Edit Input Sources để tránh xung đột. Xem hướng dẫn chi tiết.
Sau khi cài:
- Mở PHTV và cấp đúng một quyền theo phiên bản hệ điều hành: Device Control and Data Access trên macOS 27 trở lên, hoặc Trợ năng trên macOS cũ hơn.
- Click icon En trên menu bar, chọn Vi để bật tiếng Việt.
- Nhấn Control + Shift để chuyển đổi Việt/Anh (có thể tùy chỉnh trong Settings).
- Bắt đầu gõ.
PHTV chỉ cần đúng một quyền của macOS để hoạt động:
| Phiên bản macOS | Quyền cần cấp | Dùng để làm gì |
|---|---|---|
| macOS 27 trở lên | Device Control and Data Access | Cho phép PHTV nhận phím và đưa chữ đã xử lý vào ứng dụng đang dùng. |
| macOS 26 trở xuống | Trợ năng | Cho phép PHTV nhận phím và đưa chữ đã xử lý vào ứng dụng đang dùng. |
Các kiểm tra Accessibility/AX và event tap là trạng thái vận hành nội bộ, không phải quyền bổ sung mà người dùng phải cấp.
Engine xử lý dữ liệu gõ offline trên máy và không gửi nội dung bạn gõ trong ứng dụng khác ra máy chủ. Sparkle cần mạng để cập nhật; GIF/Sticker chỉ kết nối Klipy khi người dùng mở hoặc tìm nội dung. Xem đầy đủ tại Quyền riêng tư. Nếu trạng thái quyền chưa cập nhật, PHTV sẽ hướng dẫn mở đúng mục trong System Settings cho phiên bản macOS đang dùng.
- Engine offline - Telex/VNI, macro và từ điển chạy trực tiếp trên máy; tính năng mạng tùy chọn được công khai rõ
- Telex, VNI, Simple Telex - Đầy đủ các phương pháp gõ phổ biến
- Nhiều bảng mã - Unicode, TCVN3 (ABC), VNI Windows, Unicode tổ hợp, CP1258
- Native macOS - Giao diện SwiftUI hiện đại, hỗ trợ Dark Mode
- Kiểm tra chính tả - Tự động phát hiện từ sai chính tả
- Chính tả hiện đại - Hỗ trợ quy tắc "oà, uý" thay vì "òa, úy"
- Gõ tắt nhanh (Quick Telex) - cc→ch, gg→gi, kk→kh, nn→ng, qq→qu, pp→ph, tt→th
- Phụ âm đầu/cuối nhanh - f→ph, j→gi, w→qu (đầu) và g→ng, h→nh, k→ch (cuối)
- Tự động viết hoa - Viết hoa chữ cái đầu câu sau dấu chấm
- Tự động khôi phục từ - Mặc định chỉ tiếng Anh; tùy chọn “Không phải tiếng Việt” khôi phục tên riêng/thuật ngữ tại ranh giới từ. Picker và công tắc ở cùng dòng trong Bộ gõ, không khôi phục từ Việt đang gõ dở.
- Vietnamese consonant detection - Logic thông minh phân biệt từ tiếng Việt có dấu và từ tiếng Anh (VD: "đi" vs "did", "fix" vs "fi")
- Gõ tắt thông minh - Định nghĩa từ viết tắt tùy ý (VD: "btw" → "by the way")
- Text Snippets - Gõ tắt động với ngày, giờ, clipboard, random, counter
- Tự động viết hoa macro - "Btw" → "By the way", "BTW" → "BY THE WAY"
- Hoạt động ở cả 2 chế độ - Macro hoạt động cả khi gõ tiếng Việt và tiếng Anh
- Import/Export - Nhập xuất macro/danh mục, giữ nguyên snippet động, ID và metadata. Xem phạm vi sao lưu.
- Danh mục - Tổ chức macro theo nhóm với icon và màu sắc
- Lưu nội dung đã sao chép - Tự động lưu văn bản, ảnh, đường dẫn file vào lịch sử
- Dán nhanh bằng phím tắt - Mặc định ⌃V (Control + V), tuỳ chỉnh trong Settings
- Tìm kiếm - Tìm nhanh trong danh sách nội dung đã sao chép
- Giao diện Liquid Glass - Đồng bộ với PHTV Picker, hỗ trợ kéo di chuyển
- Tuỳ chỉnh - Giới hạn số mục lưu (10–100), mặc định tắt
- Giao diện Liquid Glass - Thiết kế hiện đại theo chuẩn Apple với hiệu ứng glass morphism
- 1,463 Emoji từ Unicode v17.0 - Đầy đủ emoji mới nhất với categories và tìm kiếm
- GIF không giới hạn - Tích hợp Klipy API với hàng ngàn GIF miễn phí
- Tìm kiếm thông minh - Tìm Emoji/GIF theo từ khóa tiếng Việt và tiếng Anh
- Auto-paste - Click là gửi ngay, không cần Cmd+V
- Multi-format support - Hoạt động với iMessage, Zalo, Messenger Web và các app khác
- Auto cleanup - Dọn file GIF/Sticker tạm sau khi dùng, kèm cơ chế dọn cache dự phòng
- Ad-supported - Miễn phí hoàn toàn nhờ quảng cáo từ Klipy
- Minh bạch dữ liệu - Từ khóa GIF/Sticker và sự kiện quảng cáo được gửi tới Klipy chỉ khi dùng khu nội dung trực tuyến
- Hotkey tiện lợi - Cmd+E (tùy chỉnh được) để mở nhanh
- Keyboard Layout Compatibility - Hỗ trợ Dvorak, Colemak và các bố cục bàn phím đặc biệt
- Claude Code Support - Tự nhận diện session Claude Code trong Terminal/IDE và áp timing profile ổn định hơn, không cần patch riêng
- Safe Mode - Tự động khôi phục khi Accessibility API gặp lỗi
- Tiếng Anh theo ứng dụng - Chọn Tự chuyển hoặc Khóa tiếng Anh riêng cho từng ứng dụng
- Send Key Step-by-Step - Gửi từng phím riêng lẻ cho ứng dụng tương thích kém
- Nhớ bảng mã theo ứng dụng - Tự động chuyển bảng mã phù hợp cho từng app
- Phím chuyển ngôn ngữ tùy chỉnh - Control, Option, Command, Shift hoặc tổ hợp
- Tạm tắt tiếng Việt - Giữ phím để tạm thời gõ tiếng Anh
- Khôi phục ký tự gốc - Nhấn ESC để hoàn tác dấu (VD: "việt" → "viejet")
- Ghi nhớ chế độ theo ứng dụng - Khôi phục chế độ Việt/Anh đã dùng gần nhất trong từng ứng dụng
- Tự động chuyển về English - Khi dùng bàn phím Nhật, Trung, Hàn, A Rập, Thái, Hindi...
- Khôi phục tự động - Chuyển lại bàn phím Latin sẽ khôi phục chế độ tiếng Việt
- Hỗ trợ đa dạng - Japanese, Chinese, Korean, Arabic, Hebrew, Thai, Greek, Cyrillic, v.v.
- Khởi động cùng macOS - Tùy chọn chạy khi đăng nhập
- Hot Reload - Thay đổi cài đặt không cần khởi động lại
- Tự động cập nhật (Sparkle) - Kiểm tra và cập nhật phiên bản mới tự động từ GitHub với EdDSA signing bảo mật
- Import/Export cài đặt - Sao lưu cài đặt, macro, quy tắc ứng dụng và dữ liệu Clipboard, gồm ảnh/file đã cache; kiểm tra và hoàn tác khi nhập lỗi. Xem Nhập/xuất và sao lưu.
- Menu bar icon - Hiển thị trạng thái Vi/En trên thanh menu
- Trạng thái quyền rõ ràng - Hiển thị đúng một quyền theo phiên bản macOS và chỉ báo readiness của bộ gõ riêng biệt
- Báo lỗi thông minh - Tự động thu thập log debug, thống kê lỗi, gửi qua GitHub/Email
Ảnh minh họa được chụp ở các phiên bản trước; bố cục và tên mục có thể khác bản hiện tại. Bảng cài đặt và hướng dẫn bên dưới mô tả giao diện trong mã nguồn hiện tại.
Menu Bar |
PHTV Picker (Emoji & GIF) |
Lịch sử Clipboard |
Bộ gõ |
Phím tắt |
PHTV đã có trong Homebrew Cask chính thức, không cần thêm tap riêng.
brew install --cask phtvTự động cập nhật: Sau khi cài, PHTV sẽ tự động kiểm tra và thông báo khi có phiên bản mới. Không cần
brew upgradethủ công.
Cập nhật thủ công qua Homebrew (nếu muốn):
brew upgrade --cask --greedy phtvGỡ cài đặt:
# Gỡ ứng dụng
brew uninstall --cask phtv
# Gỡ sạch (bao gồm cả settings)
brew uninstall --zap --cask phtv# Tải từ website
open https://phamhungtien.com/PHTV/
# Hoặc từ GitHub Releases
open https://github.com/PhamHungTien/PHTV/releases/latestgit clone https://github.com/PhamHungTien/PHTV.git
cd PHTV/Apps/macOS
open PHTV.xcodeproj
# Build với Cmd+B, chạy với Cmd+RProject hiện chỉ có app chính PHTV và test target PHEngineTests; không còn target InputMethodKit riêng. Khi chạy bản tự build, hãy cấp đúng một quyền cho bundle vừa build: Device Control and Data Access trên macOS 27 trở lên, hoặc Trợ năng trên macOS cũ hơn.
Xem chi tiết kiến trúc: docs/ARCHITECTURE.md
PHTV sử dụng GitHub Actions để tự động build, sign, và release:
- ✅ Full XCTest + coverage trên runner macOS với Xcode stable
- ✅ Static analysis + Thread Sanitizer theo lịch và khi chạy thủ công
- ✅ Release verify gate trước khi dùng self-hosted runner để đóng gói
- ✅ Code signing với Developer ID Application certificate
- ✅ Tạo DMG với Applications shortcut
- ✅ Sparkle signing cho auto-update bảo mật
- ✅ Auto-update Homebrew formula và appcast.xml
- ✅ Auto-increment build number cho mỗi release
Xem chi tiết tại .github/workflows/README.md
| Phím tắt | Chức năng |
|---|---|
| Control + Shift | Chuyển Việt/Anh (tùy chỉnh được) |
| ESC | Khôi phục ký tự gốc (hoàn tác dấu) |
| Giữ Option | Tạm tắt tiếng Việt (tùy chỉnh được) |
| Control + V | Mở Lịch sử Clipboard (tùy chỉnh được, mặc định tắt) |
Click biểu tượng Vi (Việt) / En (Anh) trên menu bar:
- Chuyển đổi phương pháp gõ (Telex/VNI/Simple Telex)
- Thay đổi bảng mã (Unicode/TCVN3/VNI Windows/Unicode Compound)
- Bật/tắt kiểm tra chính tả, gõ tắt
- Mở Settings để cấu hình chi tiết
| Tab | Nội dung |
|---|---|
| Bộ gõ | Phương pháp gõ, bảng mã, chính tả, Quick Telex, phụ âm nhanh |
| Phím tắt | Phím chuyển ngôn ngữ, khôi phục ký tự gốc và tạm tắt tiếng Việt |
| Gõ tắt | Quản lý macro, text snippets, import/export, tự động viết hoa |
| Ứng dụng | Ghi nhớ chế độ theo ứng dụng, Luôn dùng tiếng Anh, Send Key Step-by-Step, Keyboard Layout, Safe Mode |
| PHTV Picker | Emoji/GIF/Sticker và phím tắt mở bảng chọn |
| Clipboard | Lịch sử, mục đã lưu, giới hạn lưu trữ và phím tắt Clipboard |
| Lau bàn phím | Khóa nhập liệu tạm thời để vệ sinh bàn phím |
| Hệ thống | Khởi động cùng macOS, cập nhật, giao diện, nhập/xuất cấu hình và gỡ ứng dụng |
| Báo lỗi | Gửi báo cáo lỗi qua GitHub hoặc Email với crash logs và debug info |
| Thông tin | Phiên bản, giấy phép, ủng hộ phát triển |
| Thành phần | Yêu cầu |
|---|---|
| macOS | 14.0+ (Sonoma trở lên) |
| Kiến trúc | DMG riêng cho Intel và Apple Silicon |
| Xcode | Phiên bản mới nhất (nếu build từ source) |
| Quyền | Đúng một quyền: Device Control and Data Access (macOS 27+) hoặc Trợ năng (macOS cũ hơn) |
Lưu ý: PHTV hỗ trợ cả Intel và Apple Silicon (M1/M2/M3/M4/...). Workflow phát hành tạo đúng DMG theo kiến trúc để giảm dung lượng tải.
- Swift 6.0 + SwiftUI - Ứng dụng và toàn bộ local tooling đều viết bằng Swift
- CGEvent API - Event interception và xử lý bàn phím
- Accessibility API - Tương tác với ô nhập liệu và hỗ trợ các app đặc biệt
- TCC monitoring - Theo dõi, nhận diện và phục hồi trạng thái quyền macOS
- NSUserDefaults - Lưu trữ cấu hình local
- Sparkle 2.8.1 - Framework auto-update với EdDSA signing
- GitHub Actions - CI/CD tự động build và release
- Homebrew Cask - Package manager cho macOS
- DMG - Disk image riêng theo kiến trúc với Applications symlink
- Cài đặt - Hướng dẫn cài đặt chi tiết
- FAQ - Các câu hỏi thường gặp
- Nhập/xuất và sao lưu - Dữ liệu được hỗ trợ, khác biệt giữa hai luồng và giới hạn hiện tại
- Quyền riêng tư - Dữ liệu local, kết nối mạng và cách xóa dữ liệu
- GitHub Actions Workflows - CI/CD, auto-update, và release automation
- Scripts - Local build/test, dictionary và release metadata tools
- Engine Regression Tests - Chạy
scripts/dev.swift engine-test; cấu hìnhTestingcô lập dữ liệu kiểm thử khỏi ứng dụng thật - Kiến trúc - Thiết kế hệ thống và cấu trúc mã nguồn
- Kiểm thử - Full suite, sanitizer và Definition of Done
- Phát hành - Changelog, signing, Sparkle và rollback
- Ma trận tương thích - Ứng dụng, cấu hình và bằng chứng kiểm thử
- Bảo trì kỹ thuật - Quality gates và ngân sách nợ kỹ thuật
- Third-Party Notices - Dependency, dịch vụ và nguồn dữ liệu
- Contributing - Hướng dẫn đóng góp
- Security - Chính sách bảo mật
Mọi đóng góp đều được chào đón! Xem CONTRIBUTING.md để biết cách thức.
Các cách đóng góp:
- Báo lỗi
- Đề xuất tính năng
- Gửi Pull Request
- Cải thiện tài liệu
- Email: [email protected]
- GitHub: Issues | Discussions
- Website: phamhungtien.com/PHTV
- Facebook: PHTVInput
- LinkedIn: Phạm Hùng Tiến
PHTV được phát hành dưới giấy phép GNU AGPL v3.0.
