Repository navigation
Getting Started
AMP is built with Svelte 5, Tauri v2, and Rust. Older releases used the Windows-only .NET/WPF app, so make sure the instructions match the version you're running.
Start with the project's Releases page and check the release notes. The packaging workflow supports these options; the packages available depend on the release:
| Platform | Package | What to do |
|---|---|---|
| Windows x64 | AutoMidiPlayer_v<version>_windows-x64-setup.exe |
Run the installer. |
| Windows x64 | AutoMidiPlayer_v<version>_windows-x64-portable.zip |
Extract everything, then run Auto MIDI Player.exe. Keep the resources folder alongside it. |
| macOS | DMG for Intel x64 or Apple silicon arm64 | Pick the one matching your Mac, then see First launch on macOS. |
| Linux x64 | AppImage or deb | Pick the format suitable for your distribution. |
Note
If you get a SmartScreen popup, click on "More info" and then "Run anyway" The reason this appears is because the application is not signed. Signing costs money which can get very expensive.
The macOS builds aren't notarized by Apple (that needs a paid Apple Developer membership), so Gatekeeper blocks the first launch with a message like "Apple could not verify Auto MIDI Player is free of malware". You only need to do this once per install:
- Drag Auto MIDI Player from the DMG into Applications, then open it once and dismiss the warning.
- Go to System Settings → Privacy & Security, scroll down, and click Open Anyway next to the Auto MIDI Player message. Confirm with your password.
Or, from Terminal:
xattr -cr "/Applications/Auto MIDI Player.app"On macOS 14 and earlier, you can also right-click the app and choose Open.
Important
Because the app isn't signed with an Apple Developer certificate, macOS may treat each update as a new app. If game keys stop working after an update, open System Settings → Privacy & Security → Accessibility, remove Auto MIDI Player with −, then add it again (or toggle it off and on).
- Finish the first-run setup. If AMP finds legacy data, review the migration choice before importing it.
- Use Import MIDI to choose
.midor.midifiles, or set a MIDI folder in Settings → Locations for folder scanning. - Pick your game, instrument, and keyboard layout. Open the same instrument in the game and check that its bindings match.
- Open Tracks and enable the parts you want. A melody track is a good starting point; every track in a full arrangement can get busy!
- Turn on Listen Mode to try it through your speakers. Raw plays the original pitches; Adapted previews pitches mapped to your selected instrument.
- Ready to play in-game? Turn Listen Mode off, open the game's instrument screen, and press Play. On Windows, macOS, and X11, AMP tries to focus your selected game and pauses when that game loses focus.
Discover and creating playlists are still under construction. Local MIDI files are the way to get started.
Head over to How to Use for track controls, note timing, SoundFonts, live MIDI input, and more.
AMP can build for Windows, macOS, and Linux. A bundled game profile doesn't mean that the game itself is available or tested on every platform, though.
Note
macOS and Linux support should work in theory, however it isn't tested due to my system's limitations, so help in testing would be appreciated!
- Windows: the current build requests administrator permission at launch. Game input needs the appropriate privilege level, including when the game itself runs as administrator.
- macOS: allow AMP in System Settings → Privacy & Security → Accessibility for game keys. Re-check this after updating, since unsigned updates can lose the permission (see First launch on macOS). Profiles that match a window title may also need Screen Recording permission to read it. Listen Mode and MIDI device discovery don't require game key output.
- Linux X11: game keys need a working X11 input connection; native MIDI device discovery uses ALSA.
- Linux Wayland: game keys need the XDG RemoteDesktop keyboard portal and an authorized MIDI input session opened by selecting a device on Instrument. The portal sends keys to whichever app has focus and cannot check that it's your game. Returning to AMP suspends output. Try X11 or Listen Mode if your desktop doesn't provide the portal.
See the native MIDI input notes for platform details. Automated builds and tests don't replace checking a real MIDI device or desktop session.
- Git.
-
Node.js 24 or later and pnpm. The project's pnpm version is recorded in
package.json. - A stable Rust toolchain. On Windows, use MSVC and the C++ build tools.
- The Tauri platform prerequisites for your OS, including WebView2 on Windows or WebKitGTK on Linux. Linux also needs the ALSA, udev, X11, and keyboard development libraries listed in the repository's release workflow.
git clone --branch main https://github.com/Jed556/AutoMidiPlayer.git
cd AutoMidiPlayer
pnpm install --frozen-lockfile
# Run the desktop app (Vite + Rust)
pnpm dev
# Start Vite alone (native app services still require Tauri)
pnpm dev:frontend
# Build native packages for your current platform
pnpm buildpnpm dev:frontend starts Vite alone for frontend development. The app's library, settings, and playback require the Tauri backend, so it isn't a standalone browser app. Use pnpm dev to try the working desktop app.
pnpm build builds packages for your current platform. Release naming, signing, updater manifests, and the Windows portable ZIP are handled separately by the release workflow and packaging scripts.
For development checks, the project uses:
pnpm build:frontend
cargo test --workspace --lib --locked
node --test tests/*.test.mjsPick the checks relevant to your change. The release workflow and native MIDI workflow show the platform build matrix.
Mappings are JSON files now! So you can customize your installed app without rebuilding it. To contribute a bundled mapping, edit the matching files under src-tauri/resources/defaults/ in the source tree.
Use Settings → Locations to open Games Folder or Keyboard Layouts. They live under this application-data root:
| Platform | Application-data root |
|---|---|
| Windows | %LOCALAPPDATA%\Jed556\AutoMIDIPlayer |
| macOS | ~/Library/Application Support/Jed556/AutoMIDIPlayer |
| Linux |
$XDG_DATA_HOME/Jed556/AutoMIDIPlayer, or ~/.local/share/Jed556/AutoMIDIPlayer when unset |
AMP fills in missing bundled files at startup without overwriting existing ones. It watches your active config folders for changes and reports malformed or duplicate definitions. If a save is malformed, an already loaded valid mapping is kept where possible; a deleted mapping becomes unavailable.
Stop playback and live MIDI input before editing, keep IDs unique, and back up your custom files before resetting configurations.
Create Games/My Game/game.json:
{
"id": "my-game",
"displayName": "My Game",
"processNames": ["MyGame"],
"icon": "icon.png",
"defaultInstrument": "my-harp",
"defaultLayout": "MyGame_QWERTY"
}Put the optional icon in the same folder. processNames identifies the executable; an optional windowNames array limits matches to exact window titles. You may need different executable names on another OS. A game profile can't make a game accept simulated keys if the game doesn't support them.
Create Games/My Game/Instruments/Strings/MyHarp.json:
{
"id": "my-harp",
"name": "My Harp",
"category": "Strings",
"layoutStyle": "genshin",
"keys": [[60, 62, 64, 65, 67, 69, 71]],
"supportedLayouts": ["MyGame_QWERTY"]
}keys contains rows of MIDI pitches (60 is C4). Their order pairs pitches with the keyboard bindings, so it doesn't have to run from lowest to highest. A null cell leaves a visual gap. Pitches must be unique and between 0 and 127. A flat notes array also works for older rewrite configs. Categories can come from the instrument's subfolder.
Create KeyboardLayouts/MyGame_QWERTY.json:
{
"id": "MyGame_QWERTY",
"name": "QWERTY",
"keys": [["q", "w", "e", "r", "t", "y", "u"]],
"sustainKey": "Space"
}Match the instrument and keyboard matrices by row and column. A flat key array also works. Binding examples:
-
q: a normal key. -
Qor!: Shift+Q or Shift+1. -
^a: Ctrl+A.^by itself means the caret key (Shift+6). -
SpaceorEnter: named keys.
Optional pedal fields are sustainKey, sostenutoKey, and unaCordaKey. Pedal bindings belong to the layout, so every instrument using it shares them.
For a game instrument with chord buttons, add chordPads to its instrument JSON and chordKeys to its layout in the same order. For example, { "name": "C", "pitchClasses": [0, 4, 7] } pairs with the first chord key. These stay separate from individual note keys. The bundled Lingering Euphonia and Ukulele files are useful examples.
See Support for bundled mappings and How it Works for what happens during playback.