Tidytalk user guide
Everything Tidytalk can do, from your first dictation to local AI models and troubleshooting.
Updated 2026-11-05
Install and set up
Tidytalk needs macOS 26 or later on a Mac with Apple silicon.
- Download the latest
Tidytalk-x.y.z.dmgfrom GitHub Releases, open it, and drag Tidytalk into the Applications folder. - Open Tidytalk. It's signed with an Apple Developer ID and notarized by Apple, so macOS only asks once whether to open an app downloaded from the internet. Click Open.
- Follow the setup guide that opens:
- Allow Microphone so Tidytalk can record.
- Allow Accessibility so it can detect the shortcut and paste text at your cursor.
- Set Up AI: pick Ollama, LM Studio, Cloud, or Apple Intelligence and enter an OpenAI-compatible endpoint, API key, and model. DeepSeek is the default. You can skip this and get the raw transcript instead.
- Download Speech Model: about 240 MB, once. After that, recognition works offline.
Tidytalk lives in the menu bar. It only appears in the Dock while its setup guide or main window is open. The menu bar menu has only actions: start live captions, start meeting notes, transcribe a file or link, and your last 3 results.
The main window has four pages: Home (what you dictated today, the three features, and recent results), Transcribe (transcribe a file or link), Library (dictation, meeting notes, and transcriptions in one list you can filter and search), and Vocabulary. Settings are at the bottom left (⌘,), in three groups, with each option in exactly one place: Features (Dictation, Live Captions, Meetings), Shared (Shortcuts, AI Service, Speech Model), and System (General, Privacy & Data, About).
Hold to talk
- Put your cursor in any text field.
- Hold Option + Command and speak. A glass indicator appears at the bottom of the screen and moves with your voice.
- Let go. After a moment, the tidied text appears at your cursor.
- Recording starts after you hold the keys for about 0.4 seconds, so ordinary shortcuts such as Option + Command + a letter don't trigger it.
- Press another key, click the mouse, or press Esc while holding to cancel.
- One recording can be up to about 2 minutes. Recordings shorter than half a second are ignored.
- Change the shortcut in Settings › Dictation. You can choose Control, Option, Command, Fn (🌐), Right Option, or Right Command. If you choose Fn, set "Press 🌐 key to" to "Do Nothing" in System Settings › Keyboard, or macOS opens emoji or Dictation at the same time.
- Live text appears under the indicator while you speak. It's only a preview: the final result is recognized and tidied after you let go.
- If there's nowhere to type, for example the focus is on the desktop or a web page, the result is copied to the clipboard instead of pasted.
- Your clipboard is restored after pasting, including images, files, and rich text.
Hands-free recording
Double-tap the shortcut to start recording without holding the keys, which is handy for longer thoughts. Press the shortcut once more to finish, or Esc to cancel. Typing and clicking don't interrupt a hands-free recording. When you talk for a long time, Tidytalk recognizes what you've already said while you keep talking, so the text is ready soon after you finish. You can turn this off in Settings › Dictation.
Rewrite selected text
Select some text, hold Right Option, and say how to change it, such as "make it more formal", "shorten this to one sentence", or "translate to English". When you let go, the selection is replaced with the rewrite.
- This needs an AI service. The selected text and your instruction are sent to it.
- If nothing is selected, Tidytalk asks you to select text first. If the rewrite fails, your text isn't changed.
- Change or turn off the rewrite shortcut in Settings › Dictation.
Control from other apps
Tidytalk responds to tidytalk:// links, so you can start dictation from Raycast, Shortcuts, Karabiner, or a Stream Deck:
| Link | What it does |
|---|---|
tidytalk://toggle | Start dictation, like double-tapping the shortcut; open it again to finish |
tidytalk://start / tidytalk://stop | Only start, or only finish |
tidytalk://cancel | Cancel the current recording |
tidytalk://captions | Turn live captions on or off; also captions/start and captions/stop |
In Terminal or a script, use open -g tidytalk://toggle so focus stays where you're typing. If opening a link brings Tidytalk to the front, it hands focus back to the app you were in, so the text still lands at your cursor.
Speech models
SenseVoice is the default: small (about 240 MB), fast, and great with mixed Chinese and English. In Settings › Speech Model you can switch to another model. All of them run on your Mac.
- Qwen3-ASR (about 1 GB): the most accurate, with 30 languages and 22 Chinese dialects, and it recognizes names and terms from your vocabulary. About 4 seconds for 20 seconds of speech.
- Fun-ASR-Nano (about 1 GB): Chinese, English, and Japanese, nearly as accurate as Qwen3-ASR and a bit faster.
- Whisper Turbo (about 1 GB): about 99 languages, good for less common ones. It drops characters in Chinese.
- Apple Speech: built into macOS, nothing to download. It recognizes your system language and is weaker on mixed Chinese and English.
Click the download button and keep working: the current model is used until the download finishes. Dictation, live captions, and file transcription all use the model you choose.
Live captions
Tidytalk can caption whatever your Mac is playing, such as a video, a lecture, or a video call. It records only the computer's audio, never the microphone, and recognizes it on your Mac.
- Turn it on or off: press ⌃⌥C (Control + Option + C), or choose Start Live Captions on Home or in the menu bar menu. The first time, macOS asks to allow Tidytalk to record system audio. While listening, the menu bar icon shows an orange dot. Turning captions off clears the audio and text from memory.
- The caption bar: one sentence per line, with earlier sentences dimmed. Drag it anywhere and it remembers the spot. It hides after 10 seconds of silence and comes back when there's sound. Hover over it for translate, pause, and close buttons; close stops listening. Clicking a sentence does nothing, so you can drag freely. Choose a dark or glass style and a text size in Settings › Live Captions.
- What it listens to: all audio except Tidytalk's own sounds, or a single app you pick in Settings › Live Captions.
- Translation: turn on Translate Captions in Settings › Live Captions and sentences are translated with the service in Settings › AI Service and shown under the original. Sentences already in the target language are left alone. With "Translate as You Listen" on (the default), the sentence being spoken is translated too and updates as it goes, then the final translation replaces it; turn it off to translate only finished sentences and make fewer AI calls. With Ollama, LM Studio, or Apple Intelligence, nothing goes online; with a cloud service, caption text is sent to it.
- Paste what was just said: while listening, put your cursor in a text field and press ⌃⌥V. Tidytalk tidies the latest passage (since the last pause of more than 2 seconds, up to 30 seconds) with your dictation settings and pastes it. You can also hover over a sentence in the captions and click Paste to paste from there onward. ⌃⌥V only works while captions are on; the rest of the time other apps can use it.
For a step-by-step walkthrough, see Live translated captions for videos and meetings.
Meeting recording
Press ⌃⌥M (Control + Option + M), or choose Start Meeting Notes on Home or in the menu bar menu. While recording, the bottom of the main window sidebar shows the timer and a stop button. Tidytalk records your microphone and your Mac's audio (the people on the other end) at the same time. Press it again to stop.
- During the meeting: each sentence appears as a draft as soon as it's spoken, with "Me" and "Others" in two colors. Dictation keeps working. Meeting recording and live captions can't run at the same time.
- After the meeting: Tidytalk tells speakers apart and transcribes again on your Mac (about 5 minutes for an hour). The other side is split into Speaker 1, 2, 3, which you can rename. Moments when several people talk at once are marked, and that text is transcribed from the mixed audio. If the split looks wrong, set how many people were on the other side and run it again.
- Without headphones: your microphone also picks up the other side from your speakers. Tidytalk turns on the system's echo cancellation and removes your lines that match theirs at the same moment.
- AI summary: key points, decisions, to-dos, and open questions. With Ollama, LM Studio, or Apple Intelligence the text stays on your Mac; with a cloud service the meeting text is sent to that service.
- Where it's stored: text and recordings stay on your Mac (
~/Library/Application Support/Tidytalk/Meetings), about 30 MB per hour. Delete a meeting, or just its recording, at any time. - Telling speakers apart needs a one-time download of about 29 MB. Without it, Tidytalk only separates "Me" and "Others". Needs microphone and system audio recording permission.
Transcribe files and links
On the Transcribe page of the main window, drop in a file or paste a video link. You can also choose "Transcribe File or Link…" in the menu bar menu, or press ⌘O for a file and ⌘L for a link. Results are listed on the Transcribe page and in the Library:
- Files: drop an audio or video file (MP3, M4A, WAV, MP4, MOV and more, up to 3 hours) onto the Transcribe page, or click the folder icon to choose one. Tidytalk remembers where the file is and doesn't copy it.
- Links: paste a video link (YouTube, Bilibili, and more). The first time, Tidytalk downloads the open-source tool yt-dlp (about 35 MB) from its official GitHub release, checks it against the checksum published there, and updates it every two weeks. Only the audio and cover image are downloaded. They stay on your Mac and can be deleted anytime. Use only content you have the right to use.
- Every transcription is saved in the Library. Open it to play the audio, fix a line, copy everything, or export plain text (.txt), subtitles (.srt), or Markdown. Downloaded audio can be saved elsewhere, or deleted while keeping the text.
- It uses the speech model from Settings › Speech Model and runs on your Mac.
How tidying works
Tidying only removes and corrects. It doesn't change what you said:
- Filler words such as "um", "uh", and "like" (and 嗯、那个、就是说 in Chinese) are removed.
- Repeated words and slips are removed. When you correct yourself, only the corrected version is kept.
- Punctuation is added, and long speech is split into sentences.
- It never summarizes or adds content. English words and technical terms inside Chinese speech are kept as they are.
- Text that sounds like a command, such as "write me an email", is tidied into text, not carried out.
| You say | You get |
|---|---|
| Um so I wanted to ask, like, what's the uh rate limit for this API | I wanted to ask what the rate limit for this API is. |
| Let's move the launch to Wednesday, no wait, Thursday | Let's move the launch to Thursday. |
Turn off "Tidy up text" in Settings › Dictation to paste the raw transcript. Tidytalk then works fully offline. If the AI service is slow, unreachable, or returns something unexpected, Tidytalk pastes the raw transcript and tells you.
Cleanup strength and mode
Both are in Settings › Dictation › Tidy up text.
| Strength | What it does |
|---|---|
| Light | Only adds punctuation and removes fillers like "um" and "uh". Everything else stays as you said it. |
| Standard (default) | Removes fillers and slips, and adds punctuation. |
| Thorough | Also tightens wordy or repetitive phrasing, without changing the meaning. |
| Mode | What it does |
|---|---|
| Standard (default) | Removes fillers, fixes slips, and adds punctuation, keeping your meaning. |
| Chat (casual) | Keeps a casual tone and sentence-final particles. Good for messages. |
| Email (formal) | Uses formal, complete sentences. Good for email and documents. |
| Code (keep terms) | Keeps terms, commands, file names, and symbols exactly as they are and leaves punctuation alone. Good for technical writing. |
Output language
By default the output is in the language you spoke. Choose another output language and the text is translated as it's tidied, so you can speak Chinese and paste an English email. Tidytalk can translate into English, Simplified Chinese, Traditional Chinese, Japanese, Korean, French, German, and Spanish.
- Change it in Settings › Dictation › Tidy up text.
- Translation and tidying happen in one request, so it's about as fast as tidying alone. Your vocabulary and mode still apply.
- Translation needs "Tidy up text" turned on. If the request fails, the original text is pasted.
See Dictate and translate for examples.
Local AI models
Tidytalk talks to AI services with the OpenAI-compatible protocol, so it also works with models running on your Mac. Then your text never leaves the computer.
- Install Ollama and download a model, for example
ollama pull qwen2.5:7b. Or download and load a model in LM Studio and start its local server. - At the top of Settings › AI Service, choose Ollama or LM Studio, confirm the model name, and save. To go back to DeepSeek, OpenAI, or another online service, choose Cloud. Local models don't need an API key, and the timeout is raised to 60 seconds.
- Click the purple network icon to test the connection.
Reasoning models such as Qwen3 or DeepSeek-R1 work too: Tidytalk asks the service to skip thinking and removes any thinking that still comes back. Results depend on the model size. Small models follow "tidy, don't answer" and custom rules less reliably than cloud models, so a model around 7B or larger is recommended. See Private and offline dictation for details.
Apple Intelligence
On a Mac that supports Apple Intelligence, choose Apple Intelligence in Settings › AI Service to tidy and translate with the model built into macOS. No API key is needed, and your text never leaves your Mac. Turn on Apple Intelligence in System Settings first; if this Mac doesn't support it or it's off, the option is dimmed and says why.
Vocabulary
All of these are on the Vocabulary page of the main window.
Common words
List names, products, and terms you use, one per line. These are the words speech recognition gets wrong most often. With Qwen3-ASR as the speech model, they're recognized correctly from the start. They're also added to the AI prompt so similar-sounding mistakes are corrected to your spelling, which requires "Tidy up text". Even with tidying off, close matches are fixed on your Mac: different capitalization or spacing ("github" → "GitHub", "chat gpt" → "ChatGPT"), a letter off in a long word ("Kubernetis" → "Kubernetes"), and Chinese words of three or more characters that sound the same ("张三峰" → "张三丰"). Words inside links, email addresses, and file paths aren't touched.
Replacements
Always replace one spelling with another, for example "cloud" with "Claude". English matching ignores case and only matches whole words. Replacements run on your Mac, even with tidying off. From "Recent Results" in the menu bar menu, choose a result and "Add to Vocabulary…" to add a misheard word directly.
Words you correct
If you change a word in the same text field after pasting, such as "cloud" to "Claude", Tidytalk lists it under "Words you changed" on the Vocabulary page. Nothing is added until you click ✓. It only compares within about a minute and a half of pasting and saves nothing. Turn it off with "Suggest vocabulary" in Settings › Dictation.
Snippets
Say only a phrase such as "my email" to insert a full email address or a canned reply. The snippet is used only when the whole recording is that phrase, never when it appears inside a sentence.
Custom rules
Write your own rules, one per line, such as "Write amounts as digits" or "Write the product name as Tidytalk". Tidying and voice rewrite follow them. Rules only affect how things are written; they never make the AI add content. Up to 20 rules.
Not sure which to use? See how to make dictation get names and terms right.
Chinese–English spacing
Tidytalk adds spaces between Chinese and English or numbers, uses full-width punctuation after Chinese, and converts full-width letters and digits to half-width. Decimal points, file names, and URLs aren't affected. This runs on your Mac and can be turned off in Settings › General.
Dictation history
Each dictation and voice rewrite (the clean text and the raw transcript) is saved on this Mac for 30 days by default. Only you can read it, nothing is uploaded, and Tidytalk doesn't record which app you pasted into. Everything is in the Library, where you can search, copy, re-tidy, or delete it; your last 3 results are also under "Recent Results" in the menu bar menu, where you can paste one again. In Settings › Privacy & Data you can change how long it's kept, clear it all, or turn off "Save dictation history" to keep it in memory only until you quit.
Supported languages
You don't choose a language before speaking. Tidytalk detects it automatically. With the default SenseVoice model, it supports:
- Mandarin Chinese, including English words and technical terms mixed in
- English
- Japanese
- Korean
- Cantonese (written in Simplified Chinese, keeping Cantonese wording)
For other spoken languages, switch the speech model in Settings › Speech Model: Qwen3-ASR covers 30 languages and 22 Chinese dialects, such as Sichuanese, Northeastern, Wu, and Minnan, and Whisper Turbo covers about 99 languages. You can also speak one language and set the output language to write in another. The interface is available in English and Simplified Chinese and follows your system language.
Mixing Chinese and English? See how to dictate mixed Chinese and English.
Troubleshooting
| What happens | Why, and what to do |
|---|---|
| "Cleanup failed, pasted original" | The AI service was unreachable, timed out, or returned something unusual. Check your network and click the purple network icon in Settings › AI Service to test the connection. |
| "Didn't hear anything" | Nothing was recognized. Check the microphone in Settings › Dictation. |
| The shortcut does nothing | Accessibility access is missing. Allow it in Settings › General › Permissions. |
| macOS says it can't verify the developer | Versions before 0.4.2 weren't notarized. Download the latest version, which is notarized and opens after one confirmation. |
Accessibility still shows as not allowed
If Tidytalk is turned on in System Settings but still shows as not allowed, the list probably has an entry from an older version. In System Settings › Privacy & Security › Accessibility, select Tidytalk, click "−" to remove it, then click "Allow" in Tidytalk to add it again. Or run:
tccutil reset Accessibility app.tidytalk.Tidytalk
All settings are stored in ~/.tidytalk.json, which you can edit directly. Your API key is kept in the macOS Keychain instead of that file. See the configuration reference.
Uninstall
Dragging Tidytalk to the Trash removes only the app. The speech model, settings, and permission records stay on your Mac. To remove everything, quit Tidytalk (turn off "Open at login" first if you enabled it), move the app to the Trash, and run:
rm -rf ~/Library/Application\ Support/Tidytalk
rm -f ~/.tidytalk.json
security delete-generic-password -s app.tidytalk.Tidytalk -a ai.api_key
rm -rf ~/Library/Caches/app.tidytalk.Tidytalk ~/Library/HTTPStorages/app.tidytalk.Tidytalk
defaults delete app.tidytalk.Tidytalk
tccutil reset All app.tidytalk.Tidytalk
These remove the speech models (SenseVoice is about 240 MB, other models about 1 GB each), the speaker model, yt-dlp, your meetings, transcriptions, and dictation history, your settings, your API key in the Keychain, network caches, preferences, and microphone, accessibility, and system audio recording permissions. Keep ~/.tidytalk.json if you plan to reinstall and want your settings back.