Import & Export Vocabulary

You can move your custom vocabulary between devices and between platforms. HyperWhisper supports two formats. The format depends on the app that you use:

Format	macOS	Windows	iOS
`.hwbackup.json` (schemaVersion 2)	Export + Import	Export + Import	—
CSV	—	—	Export + Import

CSV format (iOS)

On iOS, the app exports and imports vocabulary as a plain CSV file. Each row is one entry:

phrase,replacement,caseSensitive

Column details:

Column	Required	Notes
`phrase`	Yes	The phrase that HyperWhisper recognizes. The app skips a row with an empty phrase.
`replacement`	Yes	The text that replaces the phrase in the transcript. The app skips a row with an empty replacement.
`caseSensitive`	No	`true` or `1` gives case-sensitive matching. Any other value gives `false`. If you omit this column, the value is `false`.

The parser obeys RFC 4180. A field that contains a comma, a quote, or a newline must have double-quotes around it. A literal double-quote inside a quoted field becomes "". The parser accepts LF, CR, and CRLF line endings. Example:

HyperWhisper,HyperWhisper,false
"Smith, John",John Smith,false
API,Application Programming Interface,true

Export CSV (iOS)

Open the Vocabulary screen

Go to Vocabulary in the app.

Open the actions menu

Tap the ⋯ button in the top-right corner.

Tap Export CSV

The app saves your vocabulary as a .csv file with the system share sheet.

Import CSV (iOS)

Open the Vocabulary screen

Go to Vocabulary in the app.

Open the actions menu

Tap the ⋯ button in the top-right corner.

Tap Import CSV

Pick a .csv file from Files. The app shows how many entries it imported and how many it skipped.

An import merges the file into your vocabulary. The app skips an entry when its word is already in your vocabulary. This match is case-insensitive. The app does not delete your existing entries.

`.hwbackup.json` format (macOS and Windows)

macOS and Windows share a universal .hwbackup.json format (schemaVersion: 2) for vocabulary-only exports. On macOS, a full export that also contains Settings, Modes, or API keys uses the older HyperWhisper-Backup-{date}.json format (schemaVersion 1). The macOS app also has a universal v2 export for full backups. An internal flag hides this export, and the app gives no UI control for the flag. Today, only a vocabulary-only macOS export is compatible with Windows. This is the vocabulary section of a .hwbackup.json file:

{
  "schemaVersion": 2,
  "exportDate": "2025-06-25T12:00:00Z",
  "appVersion": "2.4.0",
  "platform": "macos",
  "vocabulary": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "word": "HyperWhisper",
      "sortOrder": 0,
      "source": null
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "word": "kubernetes",
      "replacement": "Kubernetes",
      "sortOrder": 1,
      "source": null
    }
  ]
}

Vocabulary field reference:

Field	Type	Notes
`id`	UUID string	Unique identifier for the entry.
`word`	string	The phrase that HyperWhisper recognizes. On import, the app skips an entry when the word is empty or contains only whitespace.
`replacement`	string or null	The text that replaces the phrase in the transcript.
`sortOrder`	integer	The sort position of the entry.
`source`	string or null	Optional origin label.

On Windows, a .hwbackup.json export can contain settings, modes, and API keys with the vocabulary. On macOS today, only a vocabulary-only export uses this .hwbackup.json schemaVersion 2 format. That file has five top-level keys (schemaVersion, exportDate, appVersion, platform, vocabulary) and no settings, modes, or API keys sections. A macOS export that also contains Settings, Modes, or API keys uses the older schemaVersion 1 format above. An import of a .hwbackup.json file applies every section that the file contains — on Windows this can include settings, modes, and API keys along with vocabulary. On macOS, a vocabulary-only file (the only kind the app’s own export produces) imports only the vocabulary section, but a full file such as one created on Windows also applies its settings and modes when imported on macOS.

Export vocabulary (macOS)

Open Settings

Click the HyperWhisper menu bar icon and choose Settings.

Go to Backup

Select the Backup tab.

Select Vocabulary and export

Tick the Vocabulary section. To get a vocabulary-only file, deselect all other sections. Then click Export. Save the file. If Vocabulary is the only selected section, the app names the file HyperWhisper Vocabulary YYYY-MM-DD.hwbackup.json.

Import vocabulary (macOS)

Open Settings → Backup

Click the HyperWhisper menu bar icon. Choose Settings. Then select the Backup tab.

Choose a file

Click Import. Pick your .hwbackup.json file. The app then shows the number of vocabulary entries in the file.

Select Vocabulary and choose a conflict policy

Tick Vocabulary. Then pick what the app does with an entry whose word is already in your list:

Skip existing (default) — the app keeps your current entry.
Replace existing — the app writes the new replacement text into the matching entry.

Apply the import

Click Import. The app shows how many entries it imported and how many it skipped.

Export vocabulary (Windows)

Open Settings → Backup

Open HyperWhisper. Then go to Settings → Backup.

Select sections and export

Tick Vocabulary and each other section that you want in the file. Then click Export Backup…. Choose a location. The app saves the file as .hwbackup.json.

Import vocabulary (Windows)

Open Settings → Backup

Open HyperWhisper. Then go to Settings → Backup.

Choose a file

Click Choose File…. Pick your .hwbackup.json file. The app then shows which sections the file contains and the number of vocabulary entries.

Select Vocabulary and choose a conflict policy

Tick Vocabulary. Then pick what the app does with a word that is already in your list:

Keep my existing word (default) — the app keeps your current entry.
Replace with the imported word — the app writes the new replacement text, sort order, and source into the matching entry. The ID and the creation date do not change.

Apply the import

Click Import Selected. A dialog shows how many entries the app adds and how many conflicts it found. Confirm the dialog. The app then shows the final import summary.

Migrating vocabulary between macOS and Windows

Both platforms read and write the same .hwbackup.json vocabulary format. A move of your vocabulary from one platform to the other needs no conversion:

Export a vocabulary-only backup on the source platform (see above).
Import the .hwbackup.json file on the destination platform.

An import only adds. The app does not delete the existing entries on the destination platform. The app writes only the new words and the words that you chose to replace.

Case-sensitive matching is an iOS-only function. You set it with the caseSensitive CSV column above. Vocabulary entries on macOS and Windows have no case-sensitivity field. Matching on both platforms is case-insensitive. After a .hwbackup.json import, there is no case setting to change.

Getting Started

Plans & Billing

Transcription & Models

The Interface

Features

Settings

Privacy & Security

Developer & API

Troubleshooting

Windows

Import & Export Vocabulary

CSV format (iOS)

Export CSV (iOS)

Import CSV (iOS)

`.hwbackup.json` format (macOS and Windows)

Export vocabulary (macOS)

Import vocabulary (macOS)

Export vocabulary (Windows)

Import vocabulary (Windows)

Migrating vocabulary between macOS and Windows

​CSV format (iOS)

​Export CSV (iOS)

​Import CSV (iOS)

​.hwbackup.json format (macOS and Windows)

​Export vocabulary (macOS)

​Import vocabulary (macOS)

​Export vocabulary (Windows)

​Import vocabulary (Windows)

​Migrating vocabulary between macOS and Windows

CSV format (iOS)

Export CSV (iOS)

Import CSV (iOS)

`.hwbackup.json` format (macOS and Windows)

Export vocabulary (macOS)

Import vocabulary (macOS)

Export vocabulary (Windows)

Import vocabulary (Windows)

Migrating vocabulary between macOS and Windows