A utility based on Apple Music Understanding.

Turn any track into complete Apple Music Understanding data.

Why Sozo

Building software for music and visual performance requires you to have a synchronized master clock. With macOS 27 and the Apple Music Understanding framework, there's now a standardized musical vocabulary plus a state-of-the-art analysis tool that can serve as that clock. This is why Sozo exists.

How I use it

Currently the utility is centered around the Apple Music Understanding JSON file. I am experimenting with this file as a conditioner in various applications that play generative music, existing audio files, MIDI files, beat-sliced samples, and granular synthesis for live performance.

How it works

Sozo is a small command-line tool, built on Apple's on-device Music Understanding framework, that analyzes an audio file and writes the whole analysis out as a clean, portable JSON. This output is split into a series of dimensions, which are detailed below.

Every sidecar carries the full six-dimension AMU palette:

Rhythm

Exact BPM plus the bar and beat grid as absolute, drift-free timestamps.

rhythm ├─ bpm number ├─ bars [sec…] └─ beats [sec…]

Key

Key as a timeline — tonic and mode over time, correctly spelled, so changes are captured.

key [ range… ] └─ { start, end, tonic, mode }

Structure

The song's shape at three zoom levels.

structure ├─ sections [span…] ├─ segments [span…] └─ phrases [span…] span = {start,end,dur}

Loudness

Integrated, peak, and the moment-to-moment LUFS envelope (EBU R128).

loudness ├─ integrated LUFS ├─ peak dB ├─ momentary [pt…] └─ shortTerm [pt…]

Pace

A perceived drive/energy curve over time, independent of tempo.

pace [ span… ] └─ { start, end, value }

Instruments

Per-stem activity — when each plays and how strongly.

instrumentActivity └─ drum·bass·vocal·other ├─ ranges [span…] └─ activity [pt…]

How to use it

Get it on GitHub Read the docs

Point it at a song.
It runs Apple's Music Understanding analysis on-device — on your Mac, free, no account, no network.
It writes a sidecar: a JSON file, named like the track, holding everything the framework extracted.
That sidecar is plain, open data any tool on any platform can read.
Any problems? Drop the repo bundle into Claude Code.