/docs/
Overview
Talkie lets you talk to your Mac instead of typing. It runs locally and syncs across your devices without a Talkie cloud.
Philosophy
Three principles shape how Talkie is built. These aren't marketing words. They show up in how the app actually works.
Local-First
Your voice data never leaves your devices. All transcription happens on your Mac.
Privacy by Design
No cloud processing required. No accounts needed. Your data is yours.
Transparent
See exactly what's happening. No black boxes or hidden processes.
Design Principles
We figure anyone using this might want to poke at it. So you can see and change everything, with defaults good enough that you rarely have to.
Everything is a file
Your data lives in readable formats on disk. SQLite databases, JSON exports, audio files—all accessible and portable.
Small, focused data stores
Instead of one monolithic database, each component owns its data. Memos in one place, live dictations in another. Clear boundaries, easy to reason about.
Data stores exposed by default
We don't hide your data in opaque containers. Browse your recordings, query your databases, export anything. Your data, your access.
Well-defined lifecycles
Every recording flows through clear phases: capture → transcription → routing → storage. Each phase has hooks where you can plug in custom logic.
Protect the critical path
Recording and transcription are sacred. Nothing gets to block them: not sync, not workflows, not UI rendering. The happy path stays fast.
Smart defaults, full control
Talkie works out of the box. But when you want to change something (workflows, shortcuts, data locations, export formats), it's all configurable.
Local-First Design
"Local-first" means your data lives on your device first, always. The cloud is optional, not required. This has real implications:
- Works offline — Record, transcribe, and create memos without internet
- Instant startup — No waiting for cloud connections or sync
- You own your data — It's in readable formats on your disk
- No accounts required — Start using Talkie immediately
When you do enable sync (like iCloud), it's additive. The app works fine without it; sync just keeps your devices matched up.
Multi-Process Architecture
Unlike most apps that run as a single process, Talkie splits responsibilities across several smaller ones.
Why multiple processes?
- Fault isolation — If one component crashes, others keep running
- Security boundaries — Each process has only the permissions it needs
- Resource management — Heavy transcription work doesn't block the UI
- Independent updates — Components can evolve separately
How Components Communicate
The processes talk to each other using two main methods, each chosen for specific reasons.
XPC (Inter-Process Communication)
XPC is Apple's secure inter-process communication mechanism. It provides automatic process lifecycle management, type-safe messaging, and sandboxing support. All native macOS components use XPC.
HTTP (Local Server)
TalkieServer exposes HTTP endpoints that the iPhone app connects to. All traffic flows over Tailscale's encrypted WireGuard tunnel. Your devices sync directly, with no cloud in the middle.
Continue Reading
Ready to go deeper? The architecture docs explain each component in detail.
Detailed look at each component and how they work together