Getting started
Download the beta — a 172 MB disk image, signed and notarized. Open it, drag Uzume into Applications, and open it from there. You will need an Apple silicon Mac running macOS 15 Sequoia or later.
Then open a music file with File → Open Local File (⌘O). That path needs no permission and no account, and it is the quickest way to see whether any of this is for you. Everything below is the questions people ask before they get that far.
Can I build it myself?
Section titled “Can I build it myself?”Yes. The source is public and MIT-licensed. Building it needs Xcode 26.5, the version the repository pins.
git clone https://github.com/hoaxpoet/uzume.gitcd uzume
# The audio-analysis model weights are about 167 MB and ship as a release# asset rather than repository content, so they are fetched separately.Scripts/fetch_weights.sh
xcodebuild -scheme UzumeApp -destination 'platform=macOS' buildDoes it work with Apple Music and Spotify?
Section titled “Does it work with Apple Music and Spotify?”Yes, though not by controlling them. Uzume listens to the audio coming out of your Mac, so anything that plays on it can be accompanied — Apple Music, Spotify, a browser tab. You press play in your own app, and Uzume follows. Capturing that audio needs the macOS Screen Recording permission. Local files are the exception: open one in Uzume and it plays the file itself, with no permission and no account.
Uzume can also be handed the playlist in advance, which is what lets it hear a track before it plays rather than while it plays. Apple Music playlists are read from the running app, which macOS will ask you to allow the first time. Spotify playlists are read from the screen: Uzume brings the Spotify desktop app forward, you scroll the playlist once, and it reads each song’s title, artist and length from the window, on your Mac. There is no Spotify login, and you can correct the list before you continue. For now that reading expects the English Spotify desktop app; the web player is not supported.
Local files it plays for you: .m4a, .mp3 and .flac, single files, whole
folders, or an M3U playlist.
Does it need the Screen Recording permission?
Section titled “Does it need the Screen Recording permission?”Only to hear music playing in another app. On macOS, permission to capture system audio is bundled with screen recording permission — Apple groups them together, and Uzume uses only the audio portion. Nothing it hears leaves your Mac. Playing a local file in Uzume needs no permission at all.
The app asks for it on first launch and explains it there in the same terms. If you would rather not grant it, the local-file path is complete without it: the full analysis and the full visual pipeline run either way.
Is it free?
Section titled “Is it free?”Yes. The source is public and MIT-licensed, so you can build and run it today at no cost, and the public beta will be free and open source when it arrives.
Does it run on Intel Macs?
Section titled “Does it run on Intel Macs?”No. Uzume is Apple silicon only — an M1 Mac or newer. A few features are reserved for M3 and newer.
Which version of macOS does it need?
Section titled “Which version of macOS does it need?”macOS 14 Sonoma or later. Building it yourself also needs Xcode 26.5, the version the repository pins.
Is it safe to watch if I am sensitive to flashing light?
Section titled “Is it safe to watch if I am sensitive to flashing light?”Every scene in the gallery is tested for steady luminance: a bounded change in brightness from frame to frame, with beat-locked motion confined to parts of the frame rather than thrown across all of it. The app says the rest plainly before your first session: it renders high-contrast, fast-changing visuals, and if you are sensitive to flashing lights or strobe patterns you should turn on Reduce motion in Settings before you start.
Uzume honors your system’s reduced-motion setting as well, and so does this site — the gallery holds still until you ask it not to.
How do I write a scene?
Section titled “How do I write a scene?”A scene is two files — a Metal shader and a JSON file beside it — and the app picks the pair up on its own. The code and the repository call these presets, so that is the word you will meet in filenames and JSON keys; on this site they are scenes. Contributing a scene is the walkthrough — what the two files hold, how to get one rendering, and what the project’s gates check.
If a scene is merged it joins what every listener sees, and it keeps your name on it — the gallery is where they end up.
Drawn from the app repository: README.md, docs/UX_SPEC.md, docs/RUNBOOK.md, docs/PRODUCT_SPEC.md and CONTRIBUTING.md. Those are written maintainers-first and stay canonical; this page is a rewrite of the parts that face outward.