Guide & reference
From installing to performing, without opening the documentation
First-time setup, the shortcuts card, the interface map, where your settings live, the command line, the built-in verification suite, the honest limitations and the licence — all on one page.
First-time setup
Seven things worth knowing before you play
- Audio output — Keyflow plays through the default Windows output device (waveOut). Change speakers or headphones in Windows Settings → System → Sound before opening the app.
- The SoundFont loads itself — The bundled Yamaha grand loads at startup — a few seconds, and the label on the Audio page says when it is ready. For another piano: SETTINGS → Audio → LOAD SOUNDFONT, pick a .sf2, then a bank/program preset. HALL REVERB toggles the room.
- Your MIDI keyboard — Plug it in before launching and Keyflow connects the first input by itself. Plugged in later? SETTINGS → MIDI → Refresh devices. The badge above the keyboard reads MIDI IN · C4 when a note arrives.
- Graphics need nothing — The stage runs on the GPU from the first launch. Frame rate, VSync, the second-screen stage window and the engine status line live in SETTINGS → General → GRAPHICS ENGINE — settings of the machine, so presets never change them.
- Pick a look — SETTINGS → Style for the preset (Neon Violet by default), SETTINGS → Theme for the concert interface (Concert Grand by default), then fine-tune on Notes, Particles, Keyboard, Background and Camera & FX. Every change applies live and saves itself.
- Where settings live — %LOCALAPPDATA%\Keyflow holds visual-settings.json, library.json, history\practice.jsonl, presets\*.json and themes\*.json. Move everything with --settings-dir=<folder>, or press RESET TO DEFAULT in the dock.
- Recording — On the Recording page choose Format — AVI, a 32-bit PNG sequence with alpha, or MP4 with the sound inside — plus Resolution and Frame rate. Then press REC in the corner of the stage, choose where it goes, and press again to stop.
Getting started
Five moves from the menu to a playing score
- The concert menu — The app opens on a menu: Perform & Play, Quick Adjustments, Stage Design Studio, Audio & MIDI Hardware Setup, Keyboard & Shortcuts, About, Exit. HOME on the header comes back to it at any time.
- Live Play first — Press a key on the piano, the computer keyboard or a MIDI instrument and only the notes you play appear. The Yamaha grand is already loaded, so everything sounds immediately; HALL toggles the concert reverb.
- Open the session dialog — Play on the header (or Perform & Play) opens it: choose a MIDI file or a MusicXML score, or Live Play. The button reads Choose a MIDI file, then Start playback, then Return to playback — it never restarts your song by accident.
- Play along — Notes travel down and touch the glowing line just above the keys. Play along and get hit/miss feedback, accuracy and streak under the stage.
- Esc goes back in order — Esc steps back through the surfaces you opened: Quick Adjust → Play → settings → menu → stage; on the stage it opens the dock, clearing the settings search and closing the F1 card first.
Keyboard & shortcuts
The same table the F1 card shows
Three groups, exactly as the in-app card lists them — so you never need this page open while playing.
| Group | Key or action | What it does |
|---|---|---|
| Play the stage | A W S E D F T G Y H U J K | One octave from middle C (C4); hold a key to sustain the note, release it to send Note Off. |
| Play the stage | Space | Start or pause the loaded MIDI score. |
| Play the stage | Click the keys | Play the on-screen piano with the full colour, spark and flame response. |
| Play the stage | MIDI keyboard | Velocity, Note On/Off and the three pedals (CC 64/66/67) enter the same feedback pipeline. |
| Move around | F11 | Toggle full screen. |
| Move around | F1 | Open or close the shortcuts card. |
| Move around | Tab | Open the Play dialog from the stage; in menus and dialogs Tab still moves focus normally. |
| Move around | Esc | Go back through the open surface (Quick Adjust → Play → settings → menu → stage); on the stage it opens the dock. |
| Move around | Ctrl+Z / Ctrl+Shift+Z | Undo and redo in the design dock: 32 states, one slider drag counts as one step, and it never steals the undo of the box you are typing in. |
| Move around | Leave the pointer still for ~2.8 s | The whole interface hides — header, transport, Menu, REC and the dock — leaving only the piano, the background and the notes. It never hides while you drag a slider, open a drop-down, use the colour picker, read the shortcuts card or type in settings. |
| Session & capture | A B × | Set or clear the A-B loop at the playhead. |
| Session & capture | Drag the timeline | Seek in the score; notes you skip are not counted as misses. |
| Session & capture | Practice page | Follow along, Wait for my note, Right hand only, Left hand only; tempo 50–150%. |
| Session & capture | REC | Record the stage to AVI, to a folder of 32-bit PNG frames with alpha, or to an MP4 with the audio already inside it. |
Interface map
Four areas around the stage
| Area | What is there |
|---|---|
| Header | Logo and brand, the open song, the LOOK chip with the current preset and a Change button, HOME, Play (score chooser, Live Play and quick settings), SETTINGS, and minimize / full screen / exit. |
| Stage | Notes and effects, the keyboard, the device badge, the REC button and the MENU button. |
| Footer | Play/Pause, back to the start, time and the note being played, the three pedals, ACCURACY / SCORE / STREAK, and the seek bar with progress. |
| Settings dock | A navigation column of four groups, a search box that covers every page and jumps to the first result, a slider plus a numeric box plus a reset per parameter, rows that hide and show themselves, SAVE and RESET PAGE, and autosave after 0.65 s. |
The thirteen dock pages, grouped into Stage design, Sound & input, Session and App, are listed on the design page.
Languages
Two languages, three ways to switch, and three rules
- General page (dock → APP): choose English, Tiếng Việt or Follow Windows; the line underneath says which language is running and where the choice came from.
- Start menu: the INTERFACE LANGUAGE chips change it on the very first launch, before you have found any settings page.
- Command line:
--lang=vi(oren) runs once in that language and does not write to visual-settings.json — which is how CI renders the Vietnamese pictures. - Rule one — ids never change, only captions do: values in visual-settings.json, preset names, theme ids, Windows device names and file names stay English, so switching language cannot break a saved preset and a preset travels to an English machine.
- Rule two — a missing translation prints English, never an empty box; unknown keys such as device names and user file names reach the screen verbatim.
- Rule three — adding a language means adding one table file: copy the English strings, translate the values, add a line to the language list; the renderer, the XAML and the settings file need no change, and a static check proves the new table covers every key.
Command line
Flags worth knowing
Run them against PianoPath.exe — the single executable inside every package.
| Flag | What it does |
|---|---|
--lang=vi / en | Run once in that language without saving the choice. |
--snapshot | Render the interface off-screen and write a screenshot — this is how the app captures used in the galleries are made. |
--show-settings --settings-tab=<page> | Open straight on one dock page. |
--play-chord | Start with a chord held, so the stage shows hold effects. |
--software | Use the software renderer once — the fallback path, and the one that draws transparent PNG takes. |
--background-image=<file.png> | Put a picture behind the keys for this run. |
--settings-dir=<folder> | Keep settings, library, history, presets and themes somewhere else. |
--verify | Run the built-in verification suite; exit code 0 means pass, 1 means something failed. |
--verify-log=<path> | Where to write the PASS/FAIL log (default %TEMP%\keyflow-verification.log). |
--bench | Print a benchmark report, including the version the app reads from its own assembly. |
Verification suite
The app can check itself on your machine
Keyflow ships a verification suite that runs inside the real application — it needs Windows, because it starts a real WPF window. It writes each PASS/FAIL line as it goes, so even a crash leaves a last line saying what it was doing. Subjects that need hardware you do not have report SKIP, which is not a failure.
- The MIDI parser: multi-track files, tempo maps, the beat grid, meter grouping (4/4, 3/4, 2/2, 3/8 and compound 6/8, 9/8, 12/8), format 2 sequences, SMPTE divisions, drum channel, corrupt files.
- SoundFont decoding and generator semantics, polyphony limits, release loops, the audio signal, Note Off and all three pedals.
- Settings save and clamp, presets (save, import, export, delete, corrupt files), preset thumbnails and share codes, user themes, the community preset shelf.
- The dock catalogue: thirteen pages in four groups agreeing between the code, the XAML and the tests; live language switching on an open window; accessibility names and high contrast.
- MusicXML import, the sheet layer (key signature, beaming, rests, ties, chords, hand changes), hand-split inference, practice tempo, history, ghost and chart, folder library.
- Recording: the 44-byte WAV header byte by byte, the PNG sequence with real alpha, the camera overlay read back from a take the app just wrote, and one real GPU frame drawn on WARP and read back for measuring.
Run it on the machine you just downloaded to
PianoPath.exe --verify ^ --verify-log=%TEMP%\keyflow-verify.log
Exit code 0 means pass, 1 means something failed. Every line is written as it happens, so a crash still leaves a last line saying what it was doing.
Privacy, plainly
This website sets no cookies, runs no analytics and loads no third-party script. Its only external requests are the fonts from Google Fonts and one call to GitHub's releases API, which is what keeps the download buttons pointing at the newest version.
The application needs no account and no sign-in. Settings, presets, themes, the song library and the practice history are plain files under %LOCALAPPDATA%\Keyflow, and camera frames are read locally and drawn locally — nothing is uploaded.
Honest limits
What 1.0.0 does not do
| Area | The limit |
|---|---|
| Sound | Only uncompressed SoundFont 2; .sf3 is not read, and advanced SF2 parts — modulators, instrument filters, reverb/chorus — are not fully reproduced, so the sound can differ from a dedicated synthesizer depending on the file. |
| Scores | Advanced MusicXML is still missing: slurs, repeats and several voices joined into one beat. Plain MusicXML, including .mxl, reads fine. |
| Recording | No direct WebM/VP9 writer — the 32-bit PNG sequence is the alpha path. MP4 depends on Windows' own H.264 and AAC encoders. |
| Camera | Hand tracking is classical computer vision: with two hands, or a skin-coloured backdrop, only the biggest hand is followed, and the finger count needs a large enough hand. No 3D perspective camera — the stage is a flat piano roll with slight parallax. |
| Stage | No particle compute shader, no depth of field, no velocity-buffer motion blur and no camera keyframing yet. The staff, hand marker, camera picture, watermark and counters stay WPF vector layers over the GPU frame. |
| Platform | Windows only: the app is built on WPF and WinMM. A Windows-on-ARM package is published but has not been run on real ARM hardware yet. |
The full list, with the reasons, is in the documentation's “Current limitations” section.
Licence & credits
MIT for the code, CC BY 3.0 for the piano
- Application licence
- MIT — LICENSE.txt travels inside every package; keep it when you pass a copy on.
- Bundled SoundFont
- YDP Grand Piano from FreePats, built from a Yamaha Disklavier Pro multisample, under CC BY 3.0; the credit is in Assets\ATTRIBUTION.txt.
- Graphics
- The Direct3D 11 engine is built on Vortice.Windows; the HLSL shaders are compiled at startup with the d3dcompiler_47.dll that ships with Windows.
- Authors
- Copyright belongs to Yami and Neyu; Jin contributes to the project.
- Reporting a problem
- Issues are tracked on GitHub — a screenshot, the settings profile and the verification log make a bug report actionable.
- What changed
- The changelog records everything a user can see, one entry per release.
Questions
The ones that come up most
Can I move my settings to another computer?
Yes. EXPORT PROFILE… on the General page writes one Keyflow.profile.json carrying the stage settings, the language and the interface; drag it onto the window of the other machine to apply it. Presets and themes travel as their own JSON files, each preset with a rendered thumbnail, and a share code carries a whole look as one line of text.
Does it work without a graphics card?
Yes. Keyflow tries your graphics card first, then WARP — Windows' software rasterizer running the same shaders, just slower — and finally the WPF renderer if Direct3D cannot start at all. General → GRAPHICS ENGINE always says which one is drawing and why.
Why is my MP4 silent, or missing entirely?
MP4 is written by Windows' own encoders. Without an H.264 encoder the format cannot be written at all and you get a message with the error code; with H.264 but no AAC encoder the take keeps the picture and the dialog says why there is no sound; with no SoundFont loaded the recording is picture only. AVI always writes a WAV beside it instead.
Can I put my own video or webcam on the stage?
Yes — Camera & FX has a webcam overlay that draws a live camera or a looping video file in any corner, at 15–60% of the stage width, with mirroring, opacity and a green key. Hand tracking works from the same frames and needs no model.
Is there a macOS or Linux version?
Not in 1.0.0. Keyflow is built on WPF and WinMM and records through Windows' Media Foundation, so this version is Windows-only. Windows on ARM has a published package that has not been tested on real ARM hardware yet.
How do I reset everything?
RESET TO DEFAULT in the dock, or delete visual-settings.json in %LOCALAPPDATA%\Keyflow. Presets, themes, the library and the practice history live in their own files, so removing them is a separate decision.
Can I help translate it?
Adding a language means adding one table of strings: the renderer, the interface and the settings format need no change, and a static check plus the verification suite prove the new table covers every key. Open an issue on GitHub to start.
Everything you just read ships in one file
Keyflow 1.0.0 · Windows 10 and 11, 64-bit · MIT licensed · English and Tiếng Việt.