> ## 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. # Upgrade And Migration Notes > What to watch for when newer Meiji Sampler versions change storage, terminal behavior, or workflow assumptions. # 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: | Context | Old key | New key | Action | | ----------- | ------- | --------- | -------------------------------------- | | Loops row | `h` | `Shift+H` | Shorten loop by half | | Pads row | `j` | `Shift+J` | Toggle pad jump mode | | Perform tab | `k` | `Shift+K` | Kill all active PerformFX | | Browser | `l` | `Shift+L` | Toggle loop mode for the selected file | | Trim view | `l` | `o` | Toggle loop mode | 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](/guides/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](/troubleshooting/audio-and-playback). ## 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.