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.

  1. Download the latest Tidytalk-x.y.z.dmg from GitHub Releases, open it, and drag Tidytalk into the Applications folder.
  2. 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.
  3. 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

  1. Put your cursor in any text field.
  2. Hold Option + Command and speak. A glass indicator appears at the bottom of the screen and moves with your voice.
  3. Let go. After a moment, the tidied text appears at your cursor.

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.

Control from other apps

Tidytalk responds to tidytalk:// links, so you can start dictation from Raycast, Shortcuts, Karabiner, or a Stream Deck:

LinkWhat it does
tidytalk://toggleStart dictation, like double-tapping the shortcut; open it again to finish
tidytalk://start / tidytalk://stopOnly start, or only finish
tidytalk://cancelCancel the current recording
tidytalk://captionsTurn 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.

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.

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.

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:

How tidying works

Tidying only removes and corrects. It doesn't change what you said:

You sayYou get
Um so I wanted to ask, like, what's the uh rate limit for this APII wanted to ask what the rate limit for this API is.
Let's move the launch to Wednesday, no wait, ThursdayLet'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.

StrengthWhat it does
LightOnly 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.
ThoroughAlso tightens wordy or repetitive phrasing, without changing the meaning.
ModeWhat 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.

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.

  1. 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.
  2. 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.
  3. 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:

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 happensWhy, 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 nothingAccessibility access is missing. Allow it in Settings › General › Permissions.
macOS says it can't verify the developerVersions 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.