MusaveraKit

One-line Swift APIs for Apple's MusicUnderstanding.framework.

MusaveraKit is the music-intelligence sibling to MusadoraKit. Where MusadoraKit makes MusicKit and the Apple Music API easier to use, MusaveraKit makes Apple's new MusicUnderstanding framework easier to use.

import AVFoundation
import MusaveraKit

let asset = AVURLAsset(url: songURL)
let analysis = try await Musavera.analyze(asset: asset)

print(analysis.beatsPerMinute)
print(analysis.key?.primarySignature?.musaveraDescription)
print(analysis.structure?.sections)
print(analysis.instrumentActivity?.vocalRanges)

Requirements

• Xcode 27 beta
• Swift 6.4 toolchain
• iOS 27.0+
• macOS 27.0+
• tvOS 27.0+
• watchOS 27.0+
• visionOS 27.0+

MusicUnderstanding.framework is currently available in the Xcode 27 beta SDK.

What It Wraps

MusaveraKit sits on top of:

MusicUnderstandingSession
AnalysisType
RhythmResult
KeyResult
LoudnessResult
PaceResult
StructureResult
InstrumentActivityResult

One-Line APIs

Analyze everything:

let analysis = try await Musavera.analyze(asset: asset)

Analyze selected dimensions:

let analysis = try await Musavera.analyze(
    asset: asset,
    options: [.rhythm, .key, .structure]
)

Fetch focused results:

let rhythm = try await Musavera.rhythm(for: asset)
let key = try await Musavera.key(for: asset)
let loudness = try await Musavera.loudness(for: asset)
let pace = try await Musavera.pace(for: asset)
let structure = try await Musavera.structure(for: asset)
let instruments = try await Musavera.instrumentActivity(for: asset)

Convenience Helpers

analysis.beatsPerMinute
analysis.beatCount
analysis.barCount
analysis.sectionCount
analysis.keySignature(at: time)

key.primarySignature?.musaveraDescription
key.signature(at: time)

rhythm.nearestBeat(to: time)
rhythm.nearestBar(to: time)

structure.section(containing: time)
structure.phrase(containing: time)
structure.segment(containing: time)

instruments.vocalRanges
instruments.drumRanges
instruments.bassRanges
instruments.otherRanges

Installation

dependencies: [
    .package(url: "https://github.com/rryam/MusaveraKit.git", branch: "main")
]

.product(name: "MusaveraKit", package: "MusaveraKit")

Current Status

This is a beta SDK package. It is intentionally small and compiler-first while Apple finishes documenting the MusicUnderstanding framework.

The first version focuses on:

• clean one-line analysis calls
• focused helpers for each result type
• timeline-friendly convenience APIs
• testable option/result helpers

Build

DEVELOPER_DIR=/Users/rudrank/Downloads/Xcode-beta.app/Contents/Developer \
xcodebuild -scheme MusaveraKit \
  -destination 'generic/platform=iOS' \
  -derivedDataPath ./.build/xcode \
  build

swift test currently compiles the package, but cannot run on a Mac that does not have the macOS 27 MusicUnderstanding.framework runtime installed in /System/Library/Frameworks.