# Orca GSettings Schemas Reference

[TOC]

## Overview

Orca stores settings under `/org/gnome/orca/`.
- Profile-level settings: `/org/gnome/orca/<profile>/<schema-name>/`
- App-specific overrides: `/org/gnome/orca/<profile>/apps/<app>/<schema-name>/`
- Voice settings: `/org/gnome/orca/<profile>/voice-sets/<voice-set>/<voice-type>/`
- App-specific voice overrides: `/org/gnome/orca/<profile>/apps/<app>/voice-sets/<voice-set>/<voice-type>/`
- Voice settings (deprecated): `/org/gnome/orca/<profile>/voices/<voice-type>/`
- App-specific voice overrides (deprecated): `/org/gnome/orca/<profile>/apps/<app>/voices/<voice-type>/`

Path variables:
- `<profile>`: profile ID. `default` is the standard profile; users can add others, e.g. `italian`.
- `<schema-name>`: Orca schema name, e.g. `typing-echo`, `speech`, `braille`.
- `<app>`: app ID used for app-specific overrides.
- `<voice-set>`: voice set name. `primary` is the main set; language-specific sets use language codes.
- `<voice-type>`: voice type (`default`, `uppercase`, `hyperlink`, `system`).

When Orca reads a setting, it checks several layers from most specific to least specific:

- Scalars and enums: runtime override -> app override -> active profile -> `default` profile (if active profile is not `default`) -> schema default
- Dictionary settings (pronunciation entries, keybinding overrides): runtime override -> `default` profile entries (base) merged with active profile entries, then app-specific entries overlaid on top -> schema default. An empty list (`[]`) explicitly unbinds an inherited keybinding; an empty-string replacement removes an inherited pronunciation.

## Inspecting and Modifying Settings

You can read and write individual Orca settings with `dconf`.

- `dconf list /org/gnome/orca/`: list profiles
- `dconf read /org/gnome/orca/default/speech/enable`: read a single key
- `dconf write /org/gnome/orca/default/speech/enable false`: write a single key

`gsettings` also works but requires both the schema ID and path, since Orca uses relocatable schemas:

- `gsettings get org.gnome.Orca.Speech:/org/gnome/orca/default/speech/ enable`
- `gsettings set org.gnome.Orca.Speech:/org/gnome/orca/default/speech/ enable false`

## Monitoring Changes

`dconf watch` is path-based and can monitor any subtree. `gsettings monitor` is schema-based and shows key names instead of raw paths.

- `dconf watch /org/gnome/orca/`: all Orca changes
- `dconf watch /org/gnome/orca/default/speech/`: one schema path
- `gsettings monitor org.gnome.Orca.Speech:/org/gnome/orca/default/speech/`

## Migrating from JSON Settings

Orca v50 automatically migrated JSON settings from `~/.local/share/orca/` into dconf on first launch. Users upgrading from Orca v49 or earlier directly to v51 or later can use the standalone import tool:

```sh
python tools/gsettings_import_json.py import ~/.local/share/orca
```

Use `import --dry-run` to preview writes without changing anything. Use `--prefix <orca-prefix>` if schemas are installed in a non-default prefix.

## Transferring, Backing Up, and Restoring Settings

All Orca settings live in dconf under `/org/gnome/orca/`. You can dump them to a file, load them from a file, or reset them to defaults. These operations work for transferring settings between machines, creating backups, or starting fresh.

- Dump all settings to a file: `dconf dump /org/gnome/orca/ > orca-settings.ini`
- Load settings from a file: `dconf load /org/gnome/orca/ < orca-settings.ini`
- Reset all settings to defaults: `dconf reset -f /org/gnome/orca/`

Note: `dconf load` merges at the key level: it overwrites keys present in the ini file but leaves other existing keys untouched. To get an exact copy of the ini file (for example, when transferring settings from another machine), reset before loading: `dconf reset -f /org/gnome/orca/ && dconf load /org/gnome/orca/ < orca-settings.ini`

These operations also work at the profile level:

- Dump one profile: `dconf dump /org/gnome/orca/default/ > default-profile.ini`
- Load one profile: `dconf load /org/gnome/orca/default/ < default-profile.ini`
- Reset one profile to start fresh: `dconf reset -f /org/gnome/orca/default/`

---

## Schemas

### `org.gnome.Orca.Braille` (schema-name: `braille`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `braille-progress-bar-updates` | `b` | `false` | Show progress bar updates in braille |
| `computer-braille-at-cursor` | `b` | `true` | Use computer braille at cursor position |
| `contracted-braille` | `b` | `false` | Enable contracted braille |
| `contraction-table` | `s` | `''` | Braille contraction table name |
| `display-ancestors` | `b` | `true` | Display ancestors of current object |
| `enabled` | `b` | `true` | Enable braille output |
| `end-of-line-indicator` | `b` | `true` | Show end-of-line indicator |
| `flash-message-duration` | `i` | `5000` | Flash message duration in milliseconds |
| `flash-messages` | `b` | `true` | Enable braille flash messages |
| `flash-messages-detailed` | `b` | `true` | Use detailed flash messages |
| `flash-messages-persistent` | `b` | `false` | Make flash messages persistent |
| `link-indicator` | `enum`<br>`BrailleIndicator` | `'dots78'` | Braille link indicator style (none, dot7, dot8, dots78) |
| `monitor-background` | `s` | `'#ffffff'` | Braille monitor background color |
| `monitor-cell-count` | `i` | `32` | Braille monitor cell count |
| `monitor-foreground` | `s` | `'#000000'` | Braille monitor foreground color |
| `monitor-show-dots` | `b` | `false` | Show Unicode braille dots in braille monitor |
| `present-mnemonics` | `b` | `true` | Present mnemonics on braille display |
| `progress-bar-braille-interval` | `i` | `10` | Progress bar braille update interval in seconds |
| `progress-bar-braille-verbosity` | `enum`<br>`ProgressBarVerbosity` | `'application'` | Progress bar braille verbosity (all, application, window) |
| `rolename-style` | `enum`<br>`VerbosityLevel` | `'verbose'` | Braille rolename style (brief, verbose) |
| `selector-indicator` | `enum`<br>`BrailleIndicator` | `'dots78'` | Braille selector indicator style (none, dot7, dot8, dots78) |
| `text-attributes-indicator` | `enum`<br>`BrailleIndicator` | `'none'` | Braille text attributes indicator style (none, dot7, dot8, dots78) |
| `verbosity-level` | `enum`<br>`VerbosityLevel` | `'verbose'` | Braille verbosity level (brief, verbose) |
| `word-wrap` | `b` | `false` | Enable braille word wrap |

---

### `org.gnome.Orca.CaretNavigation` (schema-name: `caret-navigation`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `enabled` | `b` | `true` | Enable caret navigation |
| `layout-mode` | `b` | `true` | Use document layout mode |
| `triggers-focus-mode` | `b` | `false` | Caret navigation triggers focus mode |

---

### `org.gnome.Orca.Chat` (schema-name: `chat`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `announce-buddy-typing` | `b` | `false` | Announce when buddies are typing |
| `message-verbosity` | `enum`<br>`ChatMessageVerbosity` | `'all'` | Chat message verbosity (all, all-if-focused, focused-channel, active-channel) |
| `room-histories` | `b` | `false` | Provide chat room specific message histories |
| `speak-room-name` | `b` | `false` | Speak chat room name |
| `speak-room-name-last` | `b` | `false` | Speak chat room name after message |

---

### `org.gnome.Orca.Document` (schema-name: `document`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `auto-sticky-focus-mode` | `b` | `true` | Auto-detect sticky focus mode for web apps |
| `find-results-minimum-length` | `i` | `4` | Minimum length for find results to be spoken |
| `find-results-verbosity` | `enum`<br>`FindResultsVerbosity` | `'all'` | Find results verbosity (none, if-line-changed, all) |
| `native-nav-triggers-focus-mode` | `b` | `true` | Native navigation triggers focus mode |
| `page-summary-on-load` | `b` | `true` | Present page summary when document loads |
| `say-all-on-load` | `b` | `true` | Perform say all when document loads |

---

### `org.gnome.Orca.Extensions` (schema-name: `extensions`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `approved-user-extensions` | `a{ss}` | `@a{ss} {}` | Approved user extensions (filename to SHA256 hash) |
| `disabled-extensions` | `as` | `@as []` | Extensions disabled by the user (by MODULE_NAME) |
| `settings` | `a{sv}` | `@a{sv} {}` | Settings for a user extension |

---

### `org.gnome.Orca.FlatReview` (schema-name: `flat-review`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `display-updates` | `b` | `true` | Refresh braille for content changes at the flat review location |
| `focus-tracking` | `enum`<br>`FocusTracking` | `'auto'` | When flat review should follow the focus/caret location |
| `restricted` | `b` | `false` | Restrict flat review to current object |
| `speak-updates` | `b` | `false` | Speak content changes at the flat review location |

---

### `org.gnome.Orca.Keybindings` (schema-name: `keybindings`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `desktop-modifier-keys` | `as` | `['Insert', 'KP_Insert']` | Keys used as the Orca modifier for the desktop layout |
| `entries` | `a{saas}` | `@a{saas} {}` | User keybinding overrides |
| `keyboard-layout` | `enum`<br>`KeyboardLayout` | `'desktop'` | Keyboard layout (desktop, laptop) |
| `laptop-modifier-keys` | `as` | `['Caps_Lock', 'Shift_Lock']` | Keys used as the Orca modifier for the laptop layout |

---

### `org.gnome.Orca.LiveRegions` (schema-name: `live-regions`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `enabled` | `b` | `true` | Enable live region support |
| `present-from-inactive-tab` | `b` | `false` | Present live regions from inactive tabs |

---

### `org.gnome.Orca.MathPresentation` (schema-name: `math-presentation`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `auto-zoom-out` | `b` | `false` | Automatically exit 2D math structures when moving past the edge |
| `braille-code` | `s` | `'Nemeth'` | Math braille code |
| `braille-nav-highlight` | `enum`<br>`MathBrailleNavHighlight` | `'off'` | Braille navigation highlight style (off, first-char, end-points, all) |
| `copy-format` | `enum`<br>`MathCopyFormat` | `'mathml'` | Format for copying math content to clipboard |
| `language` | `s` | `'Auto'` | Math speech language (Auto uses system locale) |
| `nav-mode` | `enum`<br>`MathNavMode` | `'enhanced'` | Math navigation granularity (enhanced, simple, character) |
| `speech-style` | `s` | `'ClearSpeak'` | Math speech style |
| `verbosity` | `s` | `'Medium'` | Math speech verbosity |

---

### `org.gnome.Orca.MouseReview` (schema-name: `mouse-review`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `enabled` | `b` | `false` | Enable mouse review |
| `present-tooltips` | `b` | `false` | Present tooltips on mouse hover |

---

### `org.gnome.Orca.ProfileMetadata` (schema-name: `metadata`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `display-name` | `s` | `''` | Original display name (label) of the profile or app |
| `internal-name` | `s` | `''` | Original internal name (JSON dict key) of the profile |

---

### `org.gnome.Orca.Pronunciations` (schema-name: `pronunciations`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `entries` | `a{ss}` | `@a{ss} {}` | Pronunciation dictionary entries |

---

### `org.gnome.Orca.SayAll` (schema-name: `say-all`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `announce-article` | `b` | `true` | Announce articles |
| `announce-blockquote` | `b` | `true` | Announce blockquotes |
| `announce-code-block` | `b` | `true` | Announce code blocks |
| `announce-document` | `b` | `true` | Announce embedded documents |
| `announce-form` | `b` | `true` | Announce non-landmark forms |
| `announce-grouping` | `b` | `true` | Announce groupings |
| `announce-landmark` | `b` | `true` | Announce landmarks |
| `announce-list` | `b` | `true` | Announce lists |
| `announce-table` | `b` | `true` | Announce tables |
| `announce-tracked-changes` | `b` | `true` | Announce tracked changes |
| `only-speak-displayed-text` | `b` | `false` | Only speak displayed text |
| `rewind-and-fast-forward` | `b` | `false` | Enable rewind and fast forward in Say All |
| `structural-navigation` | `b` | `false` | Enable structural navigation in Say All |
| `style` | `enum`<br>`SayAllStyle` | `'sentence'` | Say All style (line, sentence) |
| `text-attribute-change-mode` | `enum`<br>`TextAttributeChangeMode` | `'off'` | When to speak text attribute changes during Say All |

---

### `org.gnome.Orca.SleepMode` (schema-name: `sleep-mode`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `apps` | `as` | `@as []` | Applications that automatically use sleep mode |

---

### `org.gnome.Orca.Sound` (schema-name: `sound`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `beep-progress-bar-updates` | `b` | `false` | Beep progress bar updates |
| `enabled` | `b` | `true` | Enable sound output |
| `progress-bar-beep-interval` | `i` | `0` | Progress bar beep interval in seconds |
| `progress-bar-beep-verbosity` | `enum`<br>`ProgressBarVerbosity` | `'application'` | Progress bar beep verbosity (all, application, window) |
| `volume` | `d` | `0.5` | Sound volume (0.0-1.0) |

---

### `org.gnome.Orca.Speech` (schema-name: `speech`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `always-announce-selected-range-in-spreadsheet` | `b` | `false` | Always announce selected range in spreadsheets |
| `announce-article` | `b` | `true` | Announce articles |
| `announce-blockquote` | `b` | `true` | Announce blockquotes |
| `announce-cell-coordinates` | `b` | `true` | Announce cell coordinates |
| `announce-cell-headers` | `b` | `true` | Announce cell headers |
| `announce-cell-span` | `b` | `true` | Announce cell span |
| `announce-code-block` | `b` | `true` | Announce code blocks |
| `announce-document` | `b` | `true` | Announce embedded documents |
| `announce-form` | `b` | `true` | Announce forms |
| `announce-grouping` | `b` | `true` | Announce groupings/panels |
| `announce-landmark` | `b` | `true` | Announce landmarks |
| `announce-list` | `b` | `true` | Announce lists |
| `announce-spreadsheet-cell-coordinates` | `b` | `true` | Announce spreadsheet cell coordinates |
| `announce-table` | `b` | `true` | Announce tables |
| `announce-tracked-changes` | `b` | `true` | Announce tracked changes |
| `auto-language-switching` | `b` | `true` | Automatically switch voice based on document content language |
| `auto-language-switching-ui` | `b` | `false` | Automatically switch voice based on UI element language |
| `capitalization-style` | `enum`<br>`CapitalizationStyle` | `'none'` | Capitalization style (none, spell, icon) |
| `enable` | `b` | `true` | Enable speech output |
| `insert-pauses-between-utterances` | `b` | `true` | Insert pauses between utterances |
| `messages-are-detailed` | `b` | `true` | Use detailed informative messages |
| `monitor-background` | `s` | `'#000000'` | Speech monitor background color |
| `monitor-font-size` | `i` | `14` | Speech monitor font size |
| `monitor-foreground` | `s` | `'#ffffff'` | Speech monitor foreground color |
| `only-speak-displayed-text` | `b` | `false` | Only speak displayed text |
| `only-switch-configured-languages` | `b` | `false` | Only switch languages that have a configured voice set |
| `progress-bar-speech-interval` | `i` | `10` | Progress bar speech update interval in seconds |
| `progress-bar-speech-verbosity` | `enum`<br>`ProgressBarVerbosity` | `'application'` | Progress bar speech verbosity (all, application, window) |
| `punctuation-level` | `enum`<br>`PunctuationStyle` | `'most'` | Punctuation verbosity level (none, some, most, all) |
| `repeated-character-limit` | `i` | `4` | Threshold for repeated character compression |
| `speak-blank-lines` | `b` | `true` | Speak blank lines |
| `speak-description` | `b` | `true` | Speak object descriptions |
| `speak-indentation` | `b` | `false` | Speak indentation |
| `speak-indentation-only-if-changed` | `b` | `false` | Speak indentation only if changed |
| `speak-misspelled-indicator` | `b` | `true` | Speak misspelled word indicator |
| `speak-numbers-as-digits` | `b` | `false` | Speak numbers as individual digits |
| `speak-position-in-set` | `b` | `false` | Speak position in set |
| `speak-progress-bar-updates` | `b` | `true` | Speak progress bar updates |
| `speak-row-in-document-table` | `b` | `true` | Speak full row in document tables |
| `speak-row-in-gui-table` | `b` | `true` | Speak full row in GUI tables |
| `speak-row-in-spreadsheet` | `b` | `false` | Speak full row in spreadsheets |
| `speak-text-attribute-changes` | `enum`<br>`TextAttributeChangeMode` | `'off'` | When to speak text attribute changes during navigation |
| `speak-tutorial-messages` | `b` | `true` | Speak tutorial messages |
| `speak-widget-mnemonic` | `b` | `true` | Speak widget mnemonics |
| `speech-server` | `s` | `''` | Speech server name |
| `speech-server-factory` | `s` | `'speechdispatcherfactory'` | Speech server factory module |
| `synthesizer` | `s` | `''` | Speech synthesizer |
| `use-color-names` | `b` | `true` | Use color names instead of values |
| `use-pronunciation-dictionary` | `b` | `true` | Apply user pronunciation dictionary |
| `verbosity-level` | `enum`<br>`VerbosityLevel` | `'verbose'` | Speech verbosity level (brief, verbose) |

---

### `org.gnome.Orca.Spellcheck` (schema-name: `spellcheck`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `present-context` | `b` | `true` | Present context/surrounding sentence |
| `spell-error` | `b` | `true` | Spell misspelled word |
| `spell-suggestion` | `b` | `true` | Spell suggested correction |

---

### `org.gnome.Orca.StructuralNavigation` (schema-name: `structural-navigation`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `enabled` | `b` | `true` | Enable structural navigation |
| `large-object-text-length` | `i` | `75` | Minimum text length for large objects |
| `skip-unlabeled-images` | `b` | `false` | Skip unlabeled images during navigation |
| `triggers-focus-mode` | `b` | `false` | Structural navigation triggers focus mode |
| `wraps` | `b` | `true` | Wrap when reaching top/bottom |

---

### `org.gnome.Orca.SystemInformation` (schema-name: `system-information`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `date-format` | `s` | `'%x'` | Date format string |
| `time-format` | `s` | `'%X'` | Time format string |

---

### `org.gnome.Orca.TableNavigation` (schema-name: `table-navigation`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `enabled` | `b` | `true` | Enable table navigation |
| `skip-blank-cells` | `b` | `false` | Skip blank cells during navigation |

---

### `org.gnome.Orca.TextAttributes` (schema-name: `text-attributes`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `attributes-to-braille` | `as` | `@as []` | Text attributes to mark in braille |
| `attributes-to-speak` | `as` | `@as []` | Text attributes to speak |

---

### `org.gnome.Orca.TypingEcho` (schema-name: `typing-echo`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `action-keys` | `b` | `true` | Echo action keys |
| `alphabetic-keys` | `b` | `true` | Echo alphabetic keys |
| `character-echo` | `b` | `false` | Echo inserted characters |
| `diacritical-keys` | `b` | `false` | Echo diacritical keys |
| `function-keys` | `b` | `true` | Echo function keys |
| `key-echo` | `b` | `true` | Enable key echo |
| `modifier-keys` | `b` | `true` | Echo modifier keys |
| `navigation-keys` | `b` | `false` | Echo navigation keys |
| `numeric-keys` | `b` | `true` | Echo numeric keys |
| `punctuation-keys` | `b` | `true` | Echo punctuation keys |
| `sentence-echo` | `b` | `false` | Echo completed sentences |
| `space` | `b` | `true` | Echo space key |
| `word-echo` | `b` | `false` | Echo completed words |

---

### `org.gnome.Orca.Voice` (schema-name: `voice`)

| Key | Type | Default | Summary |
| --- | --- | --- | --- |
| `established` | `b` | `false` | Whether this voice type has been user-customized |
| `family-dialect` | `s` | `''` | Voice family dialect |
| `family-gender` | `s` | `''` | Voice family gender |
| `family-lang` | `s` | `''` | Voice family language |
| `family-name` | `s` | `''` | Voice family name |
| `family-variant` | `s` | `''` | Voice family variant |
| `pitch` | `d` | `5.0` | Speech pitch (0.0-10.0) |
| `pitch-range` | `d` | `5.0` | Speech inflection / pitch range (0.0-10.0) |
| `rate` | `i` | `50` | Speech rate (0-100) |
| `volume` | `d` | `10.0` | Speech volume (0.0-10.0) |

---

