Status: Maintenance Mode
This project is no longer under active feature development as I’m currently focused on other private work.
However, the project is stable and still usable, and I intend to keep it available.
- Bug fixes are welcome
- Small improvements and refactors are welcome
- New feature requests may be slow, limited, or declined
- PR reviews may take time, but they won’t be ignored
I’m open to adding co-maintainers to help keep the project healthy.
If you:
- Use this project regularly
- Have contributed before (or want to)
- Are comfortable with Rust / Tauri / Svelte
👉 Please open an issue with a short intro and how you’d like to help.
I’m happy to delegate review or merge access to trusted contributors.
A beautiful, feature-rich MIDI music player for Where Winds Meet that plays your songs by automatically pressing the correct keyboard keys in-game.
⚠️ WARNING: Use at Your Own Risk The publisher has started banning players for using third-party tools (a broad category that includes many types of programs). It is unclear whether MIDI players specifically trigger bans, but the risk exists. Chinese server players have not yet reported any bans for using MIDI players. Proceed with caution.
Note:
36-key mode uses instant Shift/Ctrl combos for sharps and flats.
If notes are dropping, try increasing the modifier delay in Settings → Input.
1.0.3.mp4
Recording.2025-11-29.065402.mp4
Collapse the app into a tiny floating icon while playing.
The icon glows green when music is playing.
Press Insert to toggle mini mode or use the minimize button in the sidebar.
- What is this?
- Support
- Features
- Getting Started
- Keyboard Shortcuts
- Note Modes & Key Modes
- Cloud Gaming Mode
- Song Library (P2P Sharing)
- Library Management
- Settings & Customization
- Band Mode (Experimental)
- In-App Controls
- Managing Playlists
- Tips
- Troubleshooting
- MIDI Folder Structure
- Building from Source
- Credits
WWM Overlay – MIDI Music Player lets you play music in Where Winds Meet’s music minigame using your own MIDI files.
- Load
.midfiles into the app - Hit Play
- The app automatically sends the correct keyboard keys to the game
It’s basically an auto-play piano for the in-game instrument, with a modern Spotify-style UI and lots of controls.
If you enjoy this app and want to support development:
- Spotify-style interface – Dark theme, smooth animations
- Easy to use – Drag & drop your MIDI files, then click play
- Mini mode – Tiny floating icon that glows while playing
- Always on top toggle – Pin button to keep window above others
- Real-time progress – See where you are in the song
- Seek support – Click the timeline to jump to any position
- Song info – Shows BPM and difficulty (Easy / Medium / Hard / Expert)
- Remembers window position across sessions
- Multiple note modes – 9 different note-mapping algorithms
- 21/36 key toggle – Natural notes only or 36-key sharps/flats mode
- Real-time mode switching – Change note mode mid-song
- Track selector – Solo specific MIDI tracks (e.g., melody only)
- Speed control – 0.25× to 2× playback speed
- Octave shift – Shift pitch up/down by up to 2 octaves
- Queue system – Build a playlist and play in order
- Loop / repeat – Keep your favorite song running
- Large library support – Optimized for 10,000+ MIDI files
- Favorites – Mark songs and drag to reorder favorites
- Multiple playlists – Create, rename, and manage custom lists
- Search & sort – Search inside library, favorites, queue, playlists
- Multi-select – Ctrl+click / Shift+click for bulk operations
- Import folders & ZIPs – Bulk import MIDI files
- Drag & drop reordering – Queue, favorites, playlists
- Custom album folder – Set your own library directory
- Global hotkeys – Control playback even while the game is focused
- Play without focus (local mode) – Game window can be unfocused
- Custom keyboard layouts – Presets for QWERTY, QWERTZ, AZERTY, plus fully custom bindings
- Custom window detection – Add your own process/window titles for game detection
- Song Library (P2P) – Share and download songs from other users
- Band Mode (experimental) – Synchronized multi-player performance
- Relay / TURN support – For stricter NAT / network setups
- Custom discovery server URL – For advanced users
- Multi-language support: English, 日本語, 한국어, ไทย, 中文
-
Download the app
Get the latest release from the Releases page. -
Extract the files
Unzip to any folder (e.g.C:\Games\wwm-overlay). -
Add your MIDI files
Put your.midfiles in thealbumfolder (see folder structure). -
Run as Administrator
Right-clickwwm-overlay.exe→ Run as administrator.Needed to send keyboard input to the game.
-
Open the game
Start Where Winds Meet and open the music minigame. -
Select a song
In the app, click a song in your library. -
Add to queue
Use the playlist icon to add songs to queue or playlists. -
Play Click Play or press
ScrollLock. -
Enjoy
The app sends keys directly to the game window.
You can use your PC as normal in the background (local mode).
💡 Tip: In Local mode, the game window can be in the background (but not minimized).
These work even when the game has focus:
| Key | Action |
|---|---|
| ScrollLock | Play / Pause |
| F10 | Previous track |
| F11 | Next track |
| F12 | Stop |
| End | Stop (alternative) |
[ |
Previous note mode |
] |
Next note mode |
| Insert | Toggle mini mode |
The app offers 9 algorithms for mapping MIDI notes to in-game keys:
| Mode | Description |
|---|---|
| YueLyn | Recommended mode – YueLyn’s favorite all-round play mode |
| Closest | Finds the nearest available note (works well for most songs) |
| Wide | Uses higher & lower rows more often (wider spread) |
| Sharps | 36-key mode: prefers Shift/Ctrl sharps and flats |
| Quantize | Snaps to strict scale notes |
| Transpose Only | Direct mapping with only octave shifting |
| Pentatonic | 5-note pentatonic scale (do–re–mi–so–la) |
| Chromatic | 12-semitone → 7-key detailed mapping |
| Raw | Raw 1:1 mapping (MIDI note % 21), no extra processing |
Change modes in real time via [ / ] or the mode selector in the bottom bar.
| Mode | Description |
|---|---|
| 21 Keys | Natural notes only (default, simpler & safer) |
| 36 Keys | Adds sharps/flats with Shift/Ctrl modifier combos |
Toggle via the “21 / 36” button in the bottom bar.
In 36-key mode, sharps/flats send key combos like Shift+X or Ctrl+X instantly.
If notes are missing, increase the modifier delay in Settings.
Designed for GeForce Now, Xbox Cloud Gaming, and similar services.
| Mode | How it works | Background play |
|---|---|---|
| Local | PostMessage to game window |
✅ Yes |
| Cloud Gaming | SendInput (global keyboard) |
❌ No |
- Uses SendInput → sends real global keystrokes
- You must keep the cloud gaming window focused
- Don’t type in chat or other apps while playing
- Background playback is not possible in this mode
Share and discover MIDI files with other players using a built-in peer-to-peer library.
- Go to the Online → Share tab
- Enable “Sharing”
- Choose which songs to share (all or selected)
- Browse songs from others and click to download
- Downloaded songs appear in your library
- Shows how many songs are available from others
- Already owned songs are marked “Owned”
- Real-time download progress
- Auto-reconnect & re-share after restart (if enabled)
- Custom discovery server URL (for advanced users)
- Share picker – full-screen UI with:
- Alphabet navigation
- Search
- Batch selection
- Floating notifications – bottom bar for download progress/errors
- Only valid MIDI files are accepted
- Executables (
.exe, scripts, ELF, Mach-O, etc.) are blocked - MIDI header validation (
MThd/MTrkrequired) - Max file size: 50 MB
- Filenames sanitized to prevent path traversal
- Only file names & hashes are shared for discovery
- File contents transfer directly P2P
- No account or login required
Right-click any song in your library to:
- Rename – Change its file name
- Delete – Remove with confirmation
- Open Location – Open its folder in Explorer
- Use the search bar at the top of Settings to quickly find options
- Use quick navigation chips to jump between sections
Settings → Note Keys:
- Choose preset layouts:
- QWERTY
- QWERTZ
- AZERTY
- Or fully customize:
- Click any key to rebind
- Perfect for non-standard layouts
If the game isn’t detected properly (e.g., through a launcher / different name):
- Open
Settings → Window Detection - Add window titles or process names
- Click Add
Built-in detection includes:
Where Winds MeetWWMGeForce Now燕云十六声연운
⚠️ Experimental & unstable.
Tested mainly on local networks. Expect bugs.
Play together with friends by splitting notes or tracks between multiple players.
- One player creates a room (host)
- Host shares the 6-character room code
- Friends join using the code
- Host picks a song (auto-transfers to players who don't have it)
- Each member clicks Ready
- Host clicks Play for synchronized playback
| Mode | Description |
|---|---|
| Split Notes | Notes distributed round-robin among players |
| By Track | Each player picks a MIDI track (e.g. melody, bass) |
- Host can adjust sync delay from -2s to +5s
- Test mode: plays test notes to all members
- If others sound ahead of you → decrease delay
- If others sound behind you → increase delay
- For strict NAT / firewalled networks:
- Enable Relay Server before creating/joining
- Helps P2P connections succeed where direct connections fail
- Click any song – start playing
- Ctrl+click – select/deselect songs
- Shift+click – select a range
- Right-click – rename / delete / open file location
- Heart icon – add/remove favorite
- Playlist icon – add to queue / playlist
- Drag handle (top of sidebar) – move window
- Bottom bar:
- Play / Pause / Stop
- Timeline: click/drag to seek
- Loop toggle
- Octave shift (+/-)
- Note mode selector
- Track selector
- Mini mode button – collapse to floating icon
- Open the Playlists tab
- Click New to create a playlist
- Name it and confirm
- Add songs using the playlist icon in the library
- Click a playlist to view and edit
- Drag to reorder songs
- Click X to remove from playlist
- Click Play to load playlist into queue and start playing
- Finding MIDI files:
Search"song name midi"or"song name .mid"online. - Bulk import:
Use the Import button to load entire folders or ZIPs. - Song sounds wrong?
- Try different note modes (
[/]) - Adjust octave shift (+/-)
- Try different note modes (
- Too high / too low?
Octave shift can fix pitch. - Continuous playback:
Add multiple songs to the queue. - Quick access:
Use the search box and sort options. - Mini mode:
Press Insert to hide the full UI while playing. - Track selector:
Use it to play only melody/lead instruments from a MIDI.
- Make sure Where Winds Meet is running
- Game window must be open (can be in background, not minimized)
- You must be inside the music minigame
- Some keys may be used by other apps
- Browsers use F12 for dev tools → try End instead
- Make sure the app is actually running (check system tray)
- The game only supports 21 keys (3 octaves) – complex songs may be imperfect
- Try other note modes
- Use octave shift to move the song into a better range
- Try different MIDI versions of the song
.midextension is required- Files must be in the configured album folder
- Click Refresh in the sidebar to reload
- Can happen if multiple playback sources conflict
- Try Stop → Play again
wwm-overlay/
├── wwm-overlay.exe
├── album/ <- Put your .mid files here!
│ ├── song1.mid
│ ├── song2.mid
│ └── song3.mid
└── ...
npm run test- run the Vitest suite once (global jest-dom helpers are preloaded via src/setupTests.js).npm run test:watch- keep Vitest in watch mode while you edit.npm run test:coverage- emit coverage reports (text + lcov.info) via the built-in v8 provider; the report now covers every JavaScript/TypeScript/Svelte file undersrc/andsrc-tauri/(excluding folders likenode_modulesand the stores we intentionally skip) and writes results under coverage/.npm run coverage:check- parse coverage/lcov.info and emit a warning if the line coverage forsrc/lib/utils/**/*.jsandsrc/lib/version.jsstays below 80% so the gate stays focused on the shared helper logic.
The coverage workflow (.github/workflows/coverage.yml) runs npm run test:coverage and npm run coverage:check on pushes to main and on pull requests so reviewers get soft warnings whenever coverage dips below the project-wide 80% target.