Velo v2.5.2

🍎 Velo runs on Mac now.

That's the headline. After Windows and Linux, Velo 2.5.2 brings macOS — Apple Silicon and Intel, both native, with the permission setup handled for you instead of left as homework.

It's an open beta, and we mean that plainly: every other platform got years of members finding things. This one has had none. It's here so that can start.

🐞 Found something on Mac? Open a ticket on the Discord server — not a message in chat, where it scrolls away. A ticket doesn't get lost, and we can ask you follow-up questions.

Also in this release: four bugs members found, all fixed.

---

⬇️ How to download and open Velo

Find your system below and follow the steps in order — especially on Mac, where step 2 matters more than it looks.

🪟 Windows

1. Download Velo-win.zip from the Assets at the bottom of this page.
2. Right-click the .zip → Properties → tick "Unblock" → OK. Do this before extracting — Windows marks downloaded files, and that mark causes most "it won't start" reports.
3. Extract the folder anywhere: Documents, Desktop, wherever. Don't run it from inside the .zip.
4. Open Velo.exe.

"Windows protected your PC" → click More info → Run anyway. Velo is unsigned: a code-signing certificate costs about US$300 a year, and Velo is free.

Your antivirus called it a keylogger? It isn't, and the reason is honest. Velo reads your keyboard on purpose — that's the whole feature. It turns your typing into piano notes and can play a song into a game's on-screen piano. Technically that's the same low-level trick a real keylogger uses, and heuristics can't tell "makes music" from "steals passwords". Velo never records, stores or sends your keystrokes. You can check yourself: the only thing it ever contacts is GitHub, to look for updates.

If antivirus already removed a file, restore it from quarantine — usually Velo\_internal\pythonnet\runtime\Python.Runtime.dll — and add the Velo folder as an exception.

Requires Windows 10/11 with the WebView2 Runtime, already present on up-to-date Windows.

🍎 macOS

First, which Mac do you have? Apple menu → About This Mac.

• Chip: Apple M1/M2/M3/M4 → take Velo-mac-AppleSilicon.dmg
• Processor: Intel → take Velo-mac-Intel.dmg

The Intel build runs on Apple Silicon through Rosetta. The Apple Silicon build does not run on an Intel Mac at all.

1. Download your .dmg.
2. Open it and drag Velo into the Applications folder — before you open it.
3. Open Applications and double-click Velo. macOS will refuse, because Velo isn't signed with an Apple certificate.
4. Go to System Settings → Privacy & Security, scroll to the bottom, and click Open Anyway next to the message about Velo. Confirm.
5. Velo will ask for Accessibility. Say yes — this is the permission that lets it press keys in the game. Without it the autoplayer runs and absolutely nothing happens.
6. macOS only applies that permission when an app launches, so Velo notices when you grant it and offers to reopen itself. Let it.

⚠️ Step 2 is not housekeeping. For an unsigned app, macOS ties the permission to where the app is. Open it from Downloads and move it to Applications later, and Velo silently loses that permission — the autoplayer stops working and nothing tells you why.

For the second permission (Input Monitoring, needed by the global hotkeys) and what to do if something looks dead, the full guide is in README-MAC.md.

Two limits that belong to macOS, not to Velo:

• A game in native fullscreen gets a Space of its own, and nothing can appear over it — not Velo, not anything. Keep the game in a window if you want the mini-player on top.
• Non-US keyboard layouts can play the wrong note. The Mac key path resolves keys by character rather than by physical position. It's known, it's on the list, and it's exactly what this beta exists to hear about.

🐧 Linux

Fedora, Ubuntu/Debian, Arch and openSUSE. Velo uses your system's WebKit instead of bundling a browser, so there's a one-time setup:

1. Download velo-linux.tar.gz.
2. In a terminal:

tar xzf velo-linux.tar.gz
cd velo-linux
./install-linux.sh

The installer pulls what it needs through your distro's package manager and adds Velo to your applications menu — then search for it like any app, or run velo. Full guide: README-LINUX.md.

If anything looks dead, run velo --doctor. It reports measured facts about your machine rather than guesses, and as of this release it also prints exactly what your copy of Velo can and cannot do there.

---

🐛 What's fixed

A MIDI keyboard was sending a burst of extra keystrokes on every note.
Velo changes the game's velocity level with a key combination, and with a MIDI keyboard it was sending that combination on every note instead of only when the dynamic actually changed — 160 keystrokes where 4 were needed. Without the gaps between them the game reads the level key as an ordinary note: the setting did nothing and a wrong note played. That's the noise, and the two notes at once. QWERTY was never affected, which is exactly why it looked like a hardware problem.

MIDI → Keys could type the piano into whatever window was focused.
The guard that keeps notes inside the game was only wired to the autoplayer. Live MIDI input runs in the background all the time, so alt-tabbing to Discord mid-song sent the notes there.

Half the Player could vanish when you came back to Velo.
The file card and the transport row were only visible because an entrance animation finished. An animation that never ran meant an element gone for good, and the only cure was switching tabs and back. Nothing in Velo depends on an animation finishing to be visible any more.

The Queue could show a song playing when nothing was.
If the playback thread hit an error it died silently, and Velo went on believing the song was still going. Worse: the same routine is what releases held keys, so a crash mid-chord could leave a key pressed down inside the game. Now it reports what happened, recovers, and lets go of the keys.

Plus: Stream mode works on macOS, and velo --doctor tells you what your Velo can actually do on your machine.