Turn any song into a Shawzin performance.
Some songs survive twelve notes and some do not. What it is good at, and what it is not is worth two minutes before your first conversion.
Drop a song. Play it in Warframe.
Website · Download · Docs · Troubleshooting · Contributing
SHAWZIFY converts ordinary music — an MP3, a WAV, a MIDI file — into a performance the Warframe Shawzin can actually play, then hands you the song code to paste into the game or plays it for you live.
Everything runs on your machine. No account, no upload, no cloud.
Existing tools map MIDI note numbers onto Shawzin keys. That works when the source already fits the instrument, and falls apart when it does not — which is almost always, because the Shawzin is a genuinely restrictive instrument:
- Twelve notes per scale, from three strings and four fret positions.
- Nine scales, each with a different pitch-class set and a different range. Chromatic covers one octave with every semitone; Pentatonic Minor spans two and a half octaves with five notes each.
- One fret position at a time. Notes sounding together must share a fret, so the only notes playable with a given note are the two others in its row. That single constraint is what makes arranging for it interesting.
- 1/16-second timing resolution, a 1000-note limit and a four-minute cap.
So the hard part is not "which key is this note". It is what should survive when the music is richer than the instrument. That is the whole product:
SHAWZIFY's arrangement engine scores every source note for importance, searches all nine scales across every transposition, maps the melody with a Viterbi pass that preserves contour rather than snapping each note independently, reduces polyphony by harmonic function, arpeggiates only where there is time, thins only the passages that actually exceed the density budget, and records a reason for every change it makes.
Input — WAV, MP3, FLAC, M4A, OGG, OPUS, AAC, AIFF, WMA, MIDI, and
.shawzify projects. Paste a YouTube or Spotify link and SHAWZIFY
fetches the track. Microphone and MIDI-keyboard input for live play.
Analysis — tempo, key, energy, onset density, polyphony estimate, register, each with a confidence value rather than a false certainty. Plus song structure: where the sections are, which repeat, and which one is the hook.
Which Shawzin to play it on — the eleven variants differ in polyphony, sustain and register, and two of them change what is even playable. SHAWZIFY measures the music and ranks them, with the reasoning shown.
Stem separation — Demucs (htdemucs), GPU when CUDA is available, CPU
otherwise, cached by audio content hash so it never runs twice on the same file.
Transcription — Spotify's Basic Pitch when installed, a built-in constant-Q multi-pitch estimator otherwise, and pYIN for monophonic sources. No backend is a stub; all three produce real notes from real audio.
Arrangement — four modes (Melody, Balanced, Chordal, Virtuoso), automatic or manual scale and transposition, quantization with a strength control, complexity and density controls, chord-to-arpeggio conversion, and intelligent octave folding.
Explainability — every note carries the operation applied to it and why.
Hover any note in the piano roll to see F#5 → F#4, octave folded to fit the instrument's range.
Output — Shawzin song code, arranged MIDI, source MIDI, a rendered preview
WAV, an analysis JSON, and a .shawzify project you can reopen.
Two interfaces — a desktop app, and shawzify web for the same thing in a
browser, bound to localhost. The browser one is not a cut-down view: drop a
file on it, paste a link, and download every export. Only live Warframe
playback is desktop-only, because a tab cannot send keystrokes to a game.
Live play — SHAWZIFY types the performance into Warframe using ordinary Windows keyboard input, the same way a macro pad or an external MIDI keyboard would. Warframe must be the focused window; playback stops the instant it is not, and Escape stops it at any time.
git clone <this repository>
cd shawzin
scripts\setup.ps1 # ~5 minutes, downloads PyTorch and Demucs
scripts\dev.ps1 # launches the desktop appThen drag a song onto the window, or paste a link.
Prefer a browser?
scripts\dev.ps1 -Cli webPrefer the terminal?
scripts\dev.ps1 -Cli convert assets\demo\demo.wav --tabSHAWZIFY 0.1.0
Input: demo.wav
Duration: 00:31
Tempo: 96 BPM
Detected Key: C Major
Transcription: 91 notes (basic_pitch)
Recommended Scale: Chromatic
Transpose: -12 semitones
Mode: Balanced
Quantization: 1/8
Compatibility: Original 40.9% Optimized 74.8%
Pitch Coverage 51.3%
Melody Preservation 91.0%
Rhythm Preservation 73.0%
Harmony Preservation 98.4%
scripts\setup.ps1 -SkipMl skips PyTorch, Demucs and Basic Pitch. The app still
works: it uses the built-in CQT and pYIN transcribers and the full mix instead
of a separated stem. It is a few hundred megabytes lighter and noticeably worse
on dense mixes; the UI says which backend produced a result.
shawzify analyze song.mp3 inspect a file without arranging it
shawzify convert song.mp3 convert, writing song.shawzin.txt
shawzify convert song.mp3 --mode melody --scale auto --transpose auto
shawzify convert input.mid --tab --export-midi --export-preview
shawzify convert "https://youtube.com/watch?v=..." --focus hook
shawzify convert "https://open.spotify.com/track/..."
shawzify fetch "https://youtu.be/..." -o song.m4a
shawzify shawzins song.mp3 which Shawzin suits this track
shawzify structure song.mp3 sections, repeats and the hook
shawzify web the browser interface, on localhost
shawzify decode 1BAACAIEAQJAYKAgMAo read a song code back as music
shawzify encode project.shawzify print a project's song code
shawzify scales list the scales and their ranges
shawzify doctor check the local environment
shawzify demo write the bundled demo material
Add --json to any command for machine-readable output.
The Shawzin holds four minutes and a thousand notes. A five-minute song does not, and the first four minutes are rarely the memorable ones.
So SHAWZIFY works out where the sections are, which of them repeat, and which one is the hook — by building a self-similarity matrix over chroma plus register, density and energy contours, finding the boundaries, and clustering the segments that match. That gets used twice:
- Focus. Hook Only arranges the four-minute window around the chorus instead of the opening. One importable code, and it is the part people recognise.
- What survives. Notes in a repeated, high-energy section outrank notes in an intro, so density reduction sacrifices the intro first.
Full Song remains the default and is never truncated — a long song is split into importable parts at phrase boundaries.
Not a cosmetic choice:
| Polyphony | Dax, Nelumbo, Aristei, Kira, Lonesome, Courtly ring three strings together. Void's Song manages two. Corbu, Tiamat, Narmer and Lizzie are monophonic — a strummed chord becomes an arpeggio whether you wanted one or not. |
| Sustain | Dax rings for 2 seconds; Lizzie for 28. A sustaining instrument turns a ballad lush and a fast run to mud. |
| Chords | Most play a real three-note chord on a combined fret. The Tiamat slaps the note instead. |
| Register | The Tiamat is a bass guitar. |
| Tuning | The Nelumbo sits 25 cents sharp. |
shawzify shawzins song.mp3 measures the music — density, note spacing, chord
fraction, register — and ranks all eleven with the reasoning and the cost. On a
low riff it picks the Tiamat; on slow chords, the harp; on a dense vocal line,
the shamisen.
apps/desktop/src React + TypeScript + Tailwind + Zustand
apps/desktop/src-tauri Rust: process lifecycle, Windows input, live scheduler
engine/shawzify_engine Python: DSP, transcription, arrangement, song code
sources/ local files, YouTube, Spotify metadata
web/ the browser interface, bound to 127.0.0.1
packages/shared-types TypeScript types mirroring the engine's payloads
The frontend never talks to Python directly. It calls Tauri commands; Rust owns a Python sidecar and speaks newline-delimited JSON to it over stdin/stdout. No socket is opened, so there is no port for anything outside the machine to reach.
The one thing Rust does not delegate is live playback timing: key scheduling runs against a monotonic clock in Rust, because musical timing should not depend on the GIL or on IPC latency.
The same React app runs in both shells: the desktop build talks to Tauri, the browser build talks to the same engine methods over HTTP with SSE for progress.
docs/architecture.md has the full picture,
docs/research/shawzin-format.md documents the song code format and where every
constant came from, and docs/research/music-sources.md covers what YouTube and
Spotify actually permit.
Stem separation uses CUDA when PyTorch reports a device, and falls back to CPU automatically if anything goes wrong — the UI reports which was used rather than surfacing a driver error. Nothing requires an NVIDIA card; on CPU, Demucs takes roughly real-time instead of a fraction of it.
shawzify doctor shows the detected hardware.
Live playback uses SendInput, the documented Windows API for synthesising key
presses. It is the same mechanism a gaming keyboard's macro feature uses.
SHAWZIFY does not inject DLLs, read or write the game's memory, hook game internals, or interact with anti-cheat in any way. It cannot see anything the game is doing beyond whether its window is focused.
Safety rules the code enforces, not just documents:
- Warframe must be the focused window before the countdown starts.
- Focus is re-checked before every event; losing it stops playback immediately.
- Escape stops playback from anywhere in the app.
- Every held key is released on stop, on focus loss, and on app exit.
Key bindings default to the documented in-game controls (1/2/3 for
strings, arrow keys for frets) and are fully rebindable, with a calibration
wizard in Settings.
shawzify webPrints a URL and opens it. Same engine, same features, minus the two that need the native shell: live Warframe playback and native file dialogs.
It is local-only, and enforced rather than merely intended:
- Binds 127.0.0.1. Passing any other host is refused outright.
- Every request needs a token generated at startup and carried in the URL, so nothing else on the machine can drive it by guessing the port.
- Cross-origin requests are refused, so a page you have open elsewhere cannot reach it.
- The media route only serves files inside SHAWZIFY's own cache.
Audio never leaves your machine. There is no telemetry, no analytics, and no network request except downloading a model the first time you use stem separation. Logs are local JSONL files, and "Copy Debug Info" redacts your home directory and never includes file contents.
- Audio transcription is genuinely hard. A solo instrument or a clear vocal transcribes well; a dense, heavily produced mix does not.
- The compatibility score cannot hear your recording, and this used to be
claimed the other way round here. It measures how faithfully the arrangement
keeps the notes it was handed. Hand it a transcription that missed the music
and it will report a high number in good faith: a metal track that transcribed
to 1.6 notes per second, over a riff that runs at eight to sixteen, arranged to
88%. The number was true and the answer was useless. The app now says which
kind of score you are looking at, and warns outright when a transcription came
back near-empty. Detecting the middle of that range automatically was tried and
abandoned, for reasons recorded in
engine/shawzify_engine/music/trust.py. - The Shawzin's four-minute limit is real. Longer songs are split into parts at phrase boundaries, never truncated.
- The engine's absolute pitch reference follows ShawzinBot's table; the
WARFRAME Wiki labels the same octave differently. See
docs/research/shawzin-format.md. - Live playback is Windows-only. Everything else works anywhere Python does.
- Microphone mode needs the optional
sounddevicepackage and is experimental. - Spotify cannot supply audio, and since November 2024 it no longer exposes
tempo or key analysis to new apps either. SHAWZIFY uses it to identify a track
precisely and finds the recording elsewhere; see
docs/research/music-sources.md. - YouTube fetching needs the optional
yt-dlppackage, which you should keep updated yourself — extraction breaks whenever the site changes. - Structure detection works well on songs with a clear verse/chorus shape. On through-composed or ambient material the sections are less meaningful, and the hook it picks is correspondingly less useful.
scripts\test.ps1 # pytest + ruff + tsc + vitest + cargo test
scripts\test.ps1 -Coverage
scripts\build.ps1 # Windows installer
scripts\dev.ps1 -Engine # drive the sidecar protocol by handdocs/development.md covers the layout and how to work on each layer;
docs/troubleshooting.md covers what to do when something is not working.
SHAWZIFY is an independent fan-made tool and is not affiliated with or endorsed by Digital Extremes. Warframe and Shawzin are trademarks of Digital Extremes Ltd.
SHAWZIFY is released under the MIT licence. The Shawzin scale and chord tables
were derived from publicly documented game behaviour and cross-checked against
several community projects, which are credited in
docs/research/existing-tools.md. No copyrighted game assets are included.
Do not use SHAWZIFY to reproduce music you do not have the right to reproduce. The YouTube and Spotify routes exist to get your own listening onto a game instrument; they bypass no access control and are not a download tool.
Bug reports, and especially arrangements that came out badly, are the most useful thing you can send — the engine is a pile of musical judgement calls and the only way to know one is wrong is to hear it.
- CONTRIBUTING.md — how to set up, what the code is opinionated about, and what is permanently out of scope.
- Report a bad arrangement
- Report a bug
- Security policy — please report vulnerabilities privately.
- Code of Conduct
MIT — see LICENSE. The projects this one learned the song format from, and the licences that apply to them, are credited in THIRD-PARTY-NOTICES.md and docs/research/existing-tools.md.
SHAWZIFY is an independent fan project. It is not affiliated with, endorsed by, or connected to Digital Extremes. WARFRAME and the Shawzin are trademarks of Digital Extremes Ltd. No game assets are included in this repository, and no copyrighted music is distributed with it.