Capture and translate any text on your Mac in two shortcuts.
Selected text with ⌥ D. Anything on screen with ⌥ Q and local OCR.
Important
TextFlow v0.1 is a developer preview. It is ready to build from source, but there is no signed and notarized public binary yet. See Project status before installing.
Copy and translate works until the text lives in an image, video, remote desktop, error dialog, or an app that refuses selection. TextFlow gives both cases the same small, keyboard-first pipeline:
| Shortcut | Capture path | Result |
|---|---|---|
| ⌥ D | Accessibility first, clipboard fallback second | Translate the selected text |
| ⌥ Q | Screen selection → ScreenCaptureKit → Apple Vision | OCR locally, then translate the recognized text |
Both paths open one floating panel where the source stays editable and the source or translation can be copied or spoken aloud.
- Two shortcuts, one flow. No main window to find and no context switching.
- Local OCR. Screenshots stay in memory and text recognition runs through Apple Vision.
- Bring your own model. Configure custom URLs, models, headers, timeouts, streaming, OpenAI Responses, or Chat Completions.
- Flexible speech. Use an OpenAI-compatible speech endpoint, Alibaba Cloud Model Studio Qwen3-TTS over native HTTP, or explicitly fall back to macOS system voices.
- Privacy by design. Keys live in Keychain; logs are redacted; there is no history, account, telemetry, or cloud sync.
- Native and lean. Swift 6, SwiftUI + AppKit, Apple frameworks, and zero third-party runtime dependencies.
- Cancellation-safe. A new capture replaces the previous session and cancels in-flight OCR, network, and audio work.
flowchart LR
A["⌥D Selected text"] --> C["Unified text session"]
B["⌥Q Screen region"] --> D["ScreenCaptureKit + Vision OCR"]
D --> C
C --> E["Your translation provider"]
E --> F["Floating editable panel"]
F --> G["Copy or speech"]
TextFlow is intentionally a text-capture pipeline, not a general AI assistant. It does not include chat, translation history, clipboard history, accounts, telemetry, or cloud sync.
| Data | Where it goes |
|---|---|
| OCR screenshot | Memory only; processed locally with Apple Vision; not uploaded or written to disk |
| Selected or recognized text | Sent only to the translation provider you configure |
| Text sent for network speech | Sent only to the speech provider you configure |
| API keys and secret headers | macOS Keychain |
| Diagnostics | Redacted metadata such as provider name, timing, status code, and categorized errors |
| History | Not stored—no translation, clipboard, screenshot, or audio history |
Remote endpoints must use HTTPS. Plain HTTP is accepted only for explicit localhost or 127.0.0.1 development endpoints. TLS verification is never disabled.
- macOS 15.0 or later
- Xcode 26 with Swift 6
- XcodeGen
The current reference build is tested on an Apple Silicon M2 Mac running macOS 26.5.2. Other supported Mac configurations still need broader community testing.
git clone https://github.com/BA7IEE/TextFlow.git
cd TextFlow
brew install xcodegen
./scripts/install-local.shThe install script builds a Release app, creates a local development signing identity, installs to ~/Applications/TextFlow.app, and preserves the identity across upgrades so macOS permissions remain stable. It does not require a paid Apple Developer Program membership.
For a build without local installation:
./scripts/build-debug.sh
./scripts/build-release.sh- Open Settings → Permissions & Privacy and grant Accessibility and Screen Recording separately.
- Add a translation profile, save its API key to Keychain, and run Test Connection.
- Optionally add a speech profile. The local macOS voice remains available as an explicit fallback.
- Select text and press ⌥ D, or press ⌥ Q and drag over any text on screen.
If selected-text capture fails, TextFlow offers a Start OCR action but never starts screen capture automatically.
Translation profiles support:
- OpenAI Responses and Chat Completions protocols
- Base URL + path or a complete endpoint
- Bearer auth, custom secret headers, or no authentication
- Automatic, enabled, or disabled streaming
- Streaming SSE and non-streaming JSON responses
Speech profiles support OpenAI-compatible /v1/audio/speech endpoints with custom URL, model, headers, output format, and independent Chinese/English voice, instructions, and 0.25×–4.00× speed control. A dedicated Alibaba Cloud Model Studio HTTP adapter supports qwen3-tts-flash and qwen3-tts-instruct-flash; it downloads the short-lived audio result over HTTPS without forwarding API credentials. Other “OpenAI-compatible” implementations still vary, so please open a compatibility report when a provider needs a dedicated adapter.
Never place a real API key in source files, Markdown, test fixtures, .env files committed to Git, or issue screenshots.
xcodebuild \
-project TextFlow.xcodeproj \
-scheme TextFlow \
-configuration Debug \
-derivedDataPath DerivedData \
CODE_SIGNING_ALLOWED=NO \
testThe suite covers URL safety, arbitrary SSE fragmentation, provider decoding and error mapping, Keychain persistence, secret redaction, clipboard restoration, OCR ordering, multi-display coordinates, panel lifecycle, cancellation, speech limits, and permission separation.
A reviewable PopClip extension and its packaged build live in Extensions/PopClip. It triggers TextFlow's default ⌥ D shortcut and reuses TextFlow's existing capture, Keychain, provider, and privacy paths; it does not store text or make its own network requests.
TextFlow v0.1 implements the core local workflow and is currently distributed as source:
- Menu bar app and configurable global shortcuts
- Accessibility capture with clipboard-preserving fallback
- Multi-display screen selection and local Vision OCR
- Responses and Chat Completions translation providers
- Network and local system speech
- Keychain secrets, redacted diagnostics, and cancellation
- Unit and mock-provider integration tests
- Signed and notarized downloadable release
- Short product demo and real-world compatibility gallery
- Broader macOS hardware, display, keyboard-layout, and app coverage
- User-interface localization beyond the current Simplified Chinese UI
The product scope deliberately excludes chat, histories, bulk OCR, full-document translation, accounts, and sync. Those are not hidden roadmap items.
- Complex multi-column layouts, tables, vertical text, low-resolution images, and stylized fonts may produce imperfect OCR order or accuracy.
- Secure input fields and some applications may expose neither Accessibility text nor a copyable selection.
- A screen selection is limited to the display where the drag starts.
- Some third-party providers advertise OpenAI compatibility but differ in request, stream, or response details.
- Local development signing does not provide the frictionless install experience of a notarized Developer ID build.
Focused bug fixes, provider compatibility improvements, accessibility work, tests, and clear documentation are welcome. Please read CONTRIBUTING.md before opening a pull request. Product changes must preserve the small text-capture mission and the privacy boundaries above.
For security-sensitive reports, follow SECURITY.md instead of opening a public issue.
The frozen v0.1 contracts are available in the product requirements, technical design, and acceptance tests.
TextFlow is released under the MIT License.
If TextFlow makes any screen translatable without breaking your flow, consider giving the project a ⭐.