<!--
{
  "availability" : [
    "Mac Catalyst: 27.0.0 -",
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MusicUnderstanding",
  "identifier" : "/documentation/MusicUnderstanding",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "Music Understanding"
    ],
    "preciseIdentifier" : "MusicUnderstanding"
  },
  "title" : "Music Understanding"
}
-->

# Music Understanding

Analyze audio content and extract music information.

## Overview

Use the Music Understanding framework to analyze your audio content and receive information like the rhythm, pace, loudness, key, and instrument activity.

![Framework overview art showing a music note and audio stream.](images/com.apple.MusicUnderstanding/music-understanding-hero@2x.png)

You create a [`MusicUnderstandingSession`](/documentation/MusicUnderstanding/MusicUnderstandingSession), specify which analysis to run, and receive the results. When complete, the framework presents the results in a single aggregate from [`MusicUnderstandingSession.SessionResult`](/documentation/MusicUnderstanding/MusicUnderstandingSession/SessionResult), or as a livestream of partial results. You can provide audio from an `AVAsset` for file-based analysis of a complete audio track, or an `AsyncSequence` of `AVReadOnlyAudioPCMBuffer` for a stream analysis of audio buffers.

Some analyses also support incremental delivery through async sequences on the session. Use [`loudnessResults`](/documentation/MusicUnderstanding/MusicUnderstandingSession/loudnessResults) to receive values intermittently while analysis is in-progress. Call [`cancel()`](/documentation/MusicUnderstanding/MusicUnderstandingSession/cancel()) to stop an in-progress analysis.

The framework returns each analysis type as a dedicated result structure, giving you detailed, time-stamped data for the requested analyses:

- Rhythm: Beat positions, bar boundaries, and tempo in beats per minute (BPM).
- Key: Musical key (tonic and mode) detected over time ranges.
- Loudness: Perceptual loudness measurements following the ITU-R BS.1770 standard, including integrated, short-term, momentary, and peak values.
- Pace: Perceptual energy and momentum expressed as an events-per-minute rate, independent of fixed tempo.
- Structure: Song-level organization in terms of sections, segments, and phrases.

## Topics

### Essentials

[Creating visuals with Music Understanding analysis results](/documentation/MusicUnderstanding/create-visuals-using-musicunderstanding-analysis-results)

Create a multiplatform app that presents analysis results from the Music Understanding framework.

### Audio analysis

[`MusicUnderstandingSession`](/documentation/MusicUnderstanding/MusicUnderstandingSession)

An object that performs music analysis on an audio source and provides the results.

### Content results

[`MusicUnderstandingSession.SessionResult`](/documentation/MusicUnderstanding/MusicUnderstandingSession/SessionResult)

The aggregated results for all analysis types that a music understanding session performs.

[`RhythmResult`](/documentation/MusicUnderstanding/RhythmResult)

A structure that describes a song’s rhythm results in terms of beats, bars, and beats per minute (BPM).

[`KeyResult`](/documentation/MusicUnderstanding/KeyResult)

A value describing the musical key detected over a time range.

[`LoudnessResult`](/documentation/MusicUnderstanding/LoudnessResult)

A structure that contains perceptual loudness measurements for a song, including integrated, momentary, short-term, and peak values.

[`PaceResult`](/documentation/MusicUnderstanding/PaceResult)

A pace analysis results for the song.

[`StructureResult`](/documentation/MusicUnderstanding/StructureResult)

A song’s structural boundary information, including sections, segments, and phrases.

[`InstrumentActivityResult`](/documentation/MusicUnderstanding/InstrumentActivityResult)

A structure containing the activity levels and detected time ranges for instruments in a song.

### Support types

[`MusicUnderstandingSession.TimedValue`](/documentation/MusicUnderstanding/MusicUnderstandingSession/TimedValue)

A structure that pairs a value with a time.

[`MusicUnderstandingSession.RangedValue`](/documentation/MusicUnderstanding/MusicUnderstandingSession/RangedValue)

A structure that pairs a value over a time range.

[`AnalysisType`](/documentation/MusicUnderstanding/AnalysisType)

The analysis type for each session.

### Errors

[`MusicUnderstandingError`](/documentation/MusicUnderstanding/MusicUnderstandingError)

An error that occurs during a music understanding session.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)