> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sampler.meiji.industries/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal Compatibility And Keyboard Behavior

> Use a terminal and keyboard setup that matches Meiji Sampler's shortcut-heavy workflow.

# Terminal compatibility and keyboard behavior

Meiji Sampler is designed around physical key presses, fast navigation, and dense shortcut use. Your terminal matters.

## What works best

The best experience comes from terminals that support the kitty keyboard protocol:

* built-in macOS Terminal app (macOS Tahoe 26 and later — earlier versions do not support the kitty keyboard protocol)
* iTerm2
* Kitty
* Alacritty
* WezTerm
* Ghostty

These terminals report physical key positions more reliably, which helps combinations like `Shift+number` behave across layouts such as QWERTZ and AZERTY.

## Why this matters

Meiji Sampler depends on:

* single-key actions
* modifier-heavy shortcuts
* predictable number-row behavior
* responsive key repeat and release

If your terminal misreports keys, the app can feel broken even when the sampler itself is working correctly.

## Signs your terminal is a bad fit

* `Shift+1` through `Shift+0` do not behave consistently
* arrow keys or `Esc` feel inconsistent in modals
* shortcuts work in one layout but not another

## Recommended setup

1. Start with one of the recommended terminals.
2. Use a normal desktop keyboard layout with no OS-level key remaps at first.
3. Verify core shortcuts:
   * `Tab` to switch between `Create` and `Settings`
   * `Space` to trigger playback
   * `?` to open help
4. Only add custom remaps after the default key flow works.

## Vim-style navigation and terminal protocol

Meiji Sampler supports `h`/`j`/`k`/`l` as alternatives to arrow keys. How your terminal reports shifted letter keys depends on its keyboard protocol:

* **Kitty-protocol terminals** (iTerm2, Kitty, WezTerm, Ghostty, Alacritty, and macOS Terminal on Tahoe 26+) send `Shift+lowercase`, which Meiji Sampler handles correctly.
* **Legacy terminals** (macOS Terminal prior to Tahoe 26) send uppercase letters, which also works.

Both styles are supported. If a shifted vim key does not behave as expected, try a recommended terminal from the list above.

## If shortcuts misbehave

* try a different supported terminal first
* disable OS-level remapping tools temporarily
* confirm the problem is not isolated to one keyboard layout
* review [Audio And Playback Problems](/troubleshooting/audio-and-playback) only after you rule out terminal input issues

## Next step

Go to [Audio Setup](/start-here/audio-setup).