Skip to main content

​
Terminal compatibility and keyboard behavior

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

​
Bundled macOS renderers

The macOS DMG installs one app with two built-in renderer choices:
  • SwiftTerm is the default and works on macOS 11 or later.
  • Ghostty is an opt-in GPU-accelerated renderer on macOS 13 or later. It supports Meiji Sampler’s full color output, Unicode glyphs, and kitty keyboard protocol.
Open Meiji Sampler > Settings… and choose a terminal renderer. Changing the renderer restarts Meiji Sampler, the choice is remembered, and both renderers are updated with Meiji Sampler.app. Neither bundled renderer passes an inherited NO_COLOR setting to the sampler engine, so Finder and command-line launches use the same full-color palette. If the sampler process exits unexpectedly, either renderer shows one error with the exit status when available and asks you to restart Meiji Sampler. The app does not restart a failed process automatically.

​
What works best

When you use the standalone command-line build, 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

  • 1 through 0 do not behave consistently
  • arrow keys or Esc feel inconsistent in modals
  • shortcuts work in one layout but not another
  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 only after you rule out terminal input issues

​
Next step

Go to Audio Setup.