​

Upgrade and migration notes

This page highlights the upgrades most likely to affect existing users.

​

Vim-style navigation key remaps

The addition of h/j/k/l as arrow key alternatives required remapping several shortcuts that previously used those bare keys: If you have muscle memory for any of these shortcuts, update your habits to the shifted or new key. Arrow keys continue to work exactly as before — the vim keys are purely additive alternatives. Both kitty-protocol terminals (which send Shift+lowercase) and legacy terminals (which send uppercase) are supported. Trim view movement semantics changed: Previously, bare h was fine (small-step) movement and Shift+H was coarse. Now bare h/l are coarse (matching the arrow keys) and Shift+H/Shift+L are fine. If you relied on h for precision trimming, use Shift+H instead.

​

PerformFX A/B audition shortcuts

PerformFX now has additive A/B audition controls for comparing the current built-in lane against official permissive CLAP candidates:

• [SHIFT+A] selects lane A: current PerformFX
• [SHIFT+B] selects lane B: permissive CLAP candidate
• [SHIFT+N] starts notes
• [SHIFT+S] exports local feedback JSON

The existing unshifted [B] bank toggle is unchanged. Shifted [B] is the new CLAP-candidate lane selector.

​

PerformFX fixed slots and FX Params

The Perform tab now uses ten fixed slots per bank. [1] through [9] and [0] trigger those slots directly, even when FX Library focus is elsewhere. [ENTER] now opens FX Params for the focused slot or FX Library preset. The old [E] shortcut is removed. Use [DELETE] or [BACKSPACE] on a focused assigned slot to clear it after confirmation. Legacy PerformFX bank arrays are migrated into fixed slots by order when they used letter keys, while numeric legacy keys still map to their matching fixed slots.

​

Tempo moved out of Project in Settings

The project tempo editor lives in its own Tempo category in the Settings sidebar instead of being a row inside Project. Open it with Settings → Tempo. The behavior is unchanged — type a value, nudge with arrows (hold Shift for fine adjustment), tap Space for tap tempo, apply with Enter, reset with R or Delete while editing. The page still requires at least one recorded loop to establish a timing source. Before the first loop, pressing [R] now opens First Loop Setup instead of arming immediately. The default Fixed mode applies a fixed 1 BAR first-loop Length, auto-stops at that bar boundary, sets 90.00 BPM, initializes Quantize from Settings with OFF as the default, enables a 4 BEATS count-in, and uses a REC + PLAY click. Highlight Tempo to type a BPM directly, or press [SPACE] anywhere in the dialog to tap tempo with an audible click, return to Fixed mode, and focus Tempo. Pressing [ENTER] during a Fixed take can end recording early, but the loop remains the configured fixed Length and queues as OVR+ until the next fixed interval so overdub continues as the loop cycles. Switch Mode to Auto for free recording where the loop ending defines project tempo; pressing [ENTER] to end that first take now continues directly into overdub. [ESC] cancels the dialog without arming. If you start an ARMED loop by pressing a pad or chop while record count-in is enabled, that key now plays immediately. Pad and chop hits during the final count-in beat are recorded at 0:00, so slightly early playing still lands on the loop downbeat. Earlier count-in hits are consumed as unrecorded start-signal updates.

​

Settings promoted to a top-level tab

Settings is now a dedicated top-level tab instead of a modal overlay. Open it with , or Tab cycling through Create → Perform → MIDI → Settings. The tab uses a two-pane layout: a sidebar listing categories on the left and a content pane showing fields on the right. Use Up/Down in the sidebar to switch categories, Enter or Right to enter the content pane, and Esc or H to return to the sidebar. What moved:

• Project save, open, and new actions are in the Project category (the default). Separate project save/load modals have been replaced by inline controls within Settings.
• Audio host, output device, buffer size, sample rate, quantization, and MIDI settings are in the Audio category.
• Stem separation and factory sounds are in the Addons category.
• Tutorial, account, analytics, video encoder, version/updates, and factory reset are in the General category.

Global shortcuts (Ctrl+S, Ctrl+Shift+S, Ctrl+O, Ctrl+N) continue to work from anywhere. The , shortcut still opens Settings. Settings are saved automatically when leaving the tab.

​

F1-F4 navigation shortcuts removed

F1, F2, F3, and F4 no longer jump directly to top-level tabs. Use Tab to cycle through available tabs and , to open Settings directly. If your PerformFX configuration contains bindings assigned to F-keys, those unsupported bindings are removed automatically on the first launch after upgrade. The cleaned configuration is saved immediately so the migration warning appears only once.

​

Linked and copied sample playback

Assigning the same local sample to another channel now opens a choice:

• Link keeps loop, trim, chop, chop-gate, and pattern-end settings shared through the file defaults.
• Copy snapshots the source channel’s playback settings into the target channel so later edits stay independent.
• Browser and details preview still edit file-level defaults.
• Assigning a different file to a channel resets that channel back to linked behavior for the new sample.

See Per-Channel Playback for the full guide.

​

Time-stretch engine migration

The time-stretch engine was replaced with a new formant-preserving spectral stretcher. This is a quality improvement with no workflow changes. What to expect on first launch after updating:

• Legacy stretch cache purged automatically. Cached .wav files from the previous engine (schema versions before v4) are deleted on startup. This is a one-time cleanup.
• First stretch after update takes longer. Because the cache was cleared, the first time you play a stretched loop it will be re-processed. Subsequent plays use the new cache.
• No action required. The migration is fully automatic. If you notice any stretch-related issues, see Audio And Playback Problems.

​

Loop loads can auto-enable Sync

Samples that load with Loop: ON now automatically receive the best-fit Sync value when a session clock exists. This is enabled by default at Settings → Audio → Stretch Loops on Load. Turn it OFF if you prefer to set Sync manually after loading loops. Existing projects keep their saved Sync values. Pads from older project files that already had an active Sync value are treated as auto-assigned so future Loop: ON sample loads can recalculate the best-fit value. Pads that had Loop: ON with Sync set to Off are still eligible for automatic Sync the next time a sample loads while the setting is on.

​

Auto-normalized project tempo

Projects saved by pre-release builds can contain an auto-normalized tempo override where bpm_override_is_manual is false. These projects keep their displayed project BPM on load, but playback uses the raw recorded timing until you manually change the project tempo.

​

0.15 project workflow changes

If you are coming from older session-only workflows:

• explicit .meiji project files are now part of the normal save/load flow
• dirty-state and overwrite confirmation are more prominent

​

Persistence hardening

Recent releases improved:

• atomic writes
• backup recovery
• corruption fallback behavior

That is good news, but it also means state and project handling now have clearer expectations. Save a real project for anything important.

​

macOS path migration

The codebase includes migration logic for older macOS path variants, including:

• legacy ~/.config/meiji-sampler/
• lowercase ~/Library/Application Support/meiji-sampler/

Current macOS docs should assume:

• ~/Library/Application Support/Meiji Sampler/

​

Terminal compatibility

Recent releases also improved behavior for older Apple Terminal builds that lack full true-color support. If the UI looked corrupt in older Apple Terminal versions, update first before troubleshooting layout issues in depth.

​

Linux audio changes

Recent releases added or improved:

• JACK backend support
• ALSA device handling
• Linux release compatibility work

If you are upgrading on Linux, re-check your audio host and device settings.