What's new in MusicUnderstanding

public struct AnalysisType : Hashable, Sendable, Codable {

    /// A value that identifies the type of music analysis to perform.
    public let rawValue: String

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: AnalysisType, b: AnalysisType) -> Bool

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws
}

extension AnalysisType {

    public static let instrumentActivity: AnalysisType

    public static let loudness: AnalysisType

    public static let pace: AnalysisType

    public static let rhythm: AnalysisType

    public static let structure: AnalysisType

    public static let key: AnalysisType
}

public struct InstrumentActivityResult : Codable, Sendable {

    /// The time ranges during which each instrument is detected.
    public let ranges: [InstrumentActivityResult.Instrument : [CMTimeRange]]

    /// The activity level of each instrument over time, as values from 0.0 to 1.0.
    ///
    public let activity: [InstrumentActivityResult.Instrument : [MusicUnderstandingSession.TimedValue<Float>]]

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    public var debugDescription: String { get }
}

extension InstrumentActivityResult.Instrument {

    /// The key to use to obtain vocal activity from an `InstrumentActivityResult`
    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public static let vocal: InstrumentActivityResult.Instrument

    /// The key to use to obtain drum activity from an `InstrumentActivityResult`
    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public static let drum: InstrumentActivityResult.Instrument

    /// The key to use to obtain bass activity from an `InstrumentActivityResult`
    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public static let bass: InstrumentActivityResult.Instrument

    /// The key to use to obtain other instrument activity from an `InstrumentActivityResult`
    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public static let other: InstrumentActivityResult.Instrument
}

extension InstrumentActivityResult.Instrument : CodingKeyRepresentable {

    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public var codingKey: any CodingKey { get }

    @available(iOS 27.0, macOS 27.0, tvOS 27.0, watchOS 27.0, *)
    public init?<T>(codingKey: T) where T : CodingKey
}

public struct KeyResult : Codable, Sendable {

    /// The detected key for each time range.
    public let ranges: [MusicUnderstandingSession.RangedValue<KeyResult.KeySignature>]

    /// The set of sharp and flat symbols for the notes.
    ///
    /// A key signature pairs a root note, ``tonic`` with a ``mode``, major or minor to describe the harmonic center of a section of audio.
    public struct KeySignature : Codable, Hashable, Sendable {

        /// The root note of the musical key.
        public let tonic: KeyResult.Tonic

        /// The mode of the musical key.
        public let mode: KeyResult.Mode

        /// Returns a Boolean value indicating whether two values are equal.
        ///
        /// Equality is the inverse of inequality. For any values `a` and `b`,
        /// `a == b` implies that `a != b` is `false`.
        ///
        /// - Parameters:
        ///   - lhs: A value to compare.
        ///   - rhs: Another value to compare.
        public static func == (a: KeyResult.KeySignature, b: KeyResult.KeySignature) -> Bool

        /// Encodes this value into the given encoder.
        ///
        /// If the value fails to encode anything, `encoder` will encode an empty
        /// keyed container in its place.
        ///
        /// This function throws an error if any values are invalid for the given
        /// encoder's format.
        ///
        /// - Parameter encoder: The encoder to write data to.
        public func encode(to encoder: any Encoder) throws

        /// Hashes the essential components of this value by feeding them into the
        /// given hasher.
        ///
        /// Implement this method to conform to the `Hashable` protocol. The
        /// components used for hashing must be the same as the components compared
        /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
        /// with each of these components.
        ///
        /// - Important: In your implementation of `hash(into:)`,
        ///   don't call `finalize()` on the `hasher` instance provided,
        ///   or replace it with a different instance.
        ///   Doing so may become a compile-time error in the future.
        ///
        /// - Parameter hasher: The hasher to use when combining the components
        ///   of this instance.
        public func hash(into hasher: inout Hasher)

        /// The hash value.
        ///
        /// Hash values are not guaranteed to be equal across different executions of
        /// your program. Do not save hash values to use during a future execution.
        ///
        /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
        ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
        ///   The compiler provides an implementation for `hashValue` for you.
        public var hashValue: Int { get }

        /// Creates a new instance by decoding from the given decoder.
        ///
        /// This initializer throws an error if reading from the decoder fails, or
        /// if the data read is corrupted or otherwise invalid.
        ///
        /// - Parameter decoder: The decoder to read data from.
        public init(from decoder: any Decoder) throws
    }

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

Truncated.

extension KeyResult {

    /// The root note of a musical key.
    @frozen public enum Tonic : String, Codable, Hashable, Sendable {

        /// Indicates that the song is in an A-Flat key.
        case aFlat

        /// Indicates that the song is in an A-Sharp key.
        case aSharp

        /// Indicates that the song is in an A key.
        case a

        /// Indicates that the song is in an B-Flat key.
        case bFlat

        /// Indicates that the song is in a B key.
        case b

        /// Indicates that the song is in a C key.
        case c

        /// Indicates that the song is in an C-Sharp key.
        case cSharp

        /// Indicates that the song is in a D key.
        case d

        /// Indicates that the song is in an D-Flat key.
        case dFlat

        /// Indicates that the song is in an D-Sharp key.
        case dSharp

        /// Indicates that the song is in an E-Flat key.
        case eFlat

        /// Indicates that the song is in an E key.
        case e

        /// Indicates that the song is in an F key.
        case f

        /// Indicates that the song is in an F-Sharp key.
        case fSharp

        /// Indicates that the song is in a G key.
        case g

        /// Indicates that the song is in a G-Flat key.
        case gFlat

        /// Indicates that the song is in an G-Sharp key.
        case gSharp

        /// Creates a new instance with the specified raw value.
        ///
        /// If there is no value of the type that corresponds with the specified raw
        /// value, this initializer returns `nil`. For example:
        ///
        ///     enum PaperSize: String {
        ///         case A4, A5, Letter, Legal
        ///     }
        ///
        ///     print(PaperSize(rawValue: "Legal"))
        ///     // Prints "Optional(PaperSize.Legal)"
        ///
        ///     print(PaperSize(rawValue: "Tabloid"))
        ///     // Prints "nil"
        ///
        /// - Parameter rawValue: The raw value to use for the new instance.
        public init?(rawValue: String)

        /// The raw type that can be used to represent all values of the conforming
        /// type.
        ///
        /// Every distinct value of the conforming type has a corresponding unique
        /// value of the `RawValue` type, but there may be values of the `RawValue`
        /// type that don't have a corresponding value of the conforming type.

Truncated.

extension KeyResult.Mode : RawRepresentable {
}

extension KeyResult.Tonic : RawRepresentable {
}

extension KeyResult.Tonic : BitwiseCopyable {
}

public struct LoudnessResult : Codable, Sendable {

    /// The integrated loudness of the song, measured in LUFS over its full duration.
    ///
    public let integrated: MusicUnderstandingSession.TimedValue<Float>

    /// An array of momentary loudness measurements sampled across the song in LUFS.
    ///
    /// The measurement happens in 400 millisecond (ms) increments that advance 100ms at a time.
    ///
    public let momentary: [MusicUnderstandingSession.TimedValue<Float>]

    /// An array of short-term loudness measurements sampled across the song in LUFS.
    ///
    /// Short-term loudness is a 3 second window that advances 100 milliseconds (ms) per result.
    /// 
    public let shortTerm: [MusicUnderstandingSession.TimedValue<Float>]

    /// The peak amplitude of the song in decibels (dB).
    ///
    public let peak: MusicUnderstandingSession.TimedValue<Float>

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    public var debugDescription: String { get }
}

public enum MusicUnderstandingError : Error {

    /// The error that occurs when analysis is requested while a session is already in progress.
    case sessionInProgress

    /// The error that occurs when analyze is called with an empty analysis set.
    case emptyAnalysisSet

    /// The error that occurs when a session is initialized with an invalid `AVAsset`.
    case invalidAsset

    /// The error that occurs when an unexpected internal failure prevents the session from completing.
    case internalError

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: MusicUnderstandingError, b: MusicUnderstandingError) -> Bool

    /// Hashes the essential components of this value by feeding them into the
    /// given hasher.
    ///
    /// Implement this method to conform to the `Hashable` protocol. The
    /// components used for hashing must be the same as the components compared
    /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
    /// with each of these components.
    ///
    /// - Important: In your implementation of `hash(into:)`,
    ///   don't call `finalize()` on the `hasher` instance provided,
    ///   or replace it with a different instance.
    ///   Doing so may become a compile-time error in the future.
    ///
    /// - Parameter hasher: The hasher to use when combining the components
    ///   of this instance.
    public func hash(into hasher: inout Hasher)

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }
}

extension MusicUnderstandingError : Equatable {
}

extension MusicUnderstandingError : Hashable {
}

public actor MusicUnderstandingSession : Sendable {

    /// An async sequence that yields loudness analysis results as they become available.
    ///
    nonisolated public var loudnessResults: some Sendable & AsyncSequence<LoudnessResult, any Error> { get }

    /// Creates a music understanding session that accepts streaming audio buffers.
    ///
    /// - Parameter audioProvider: A non-throwing async sequence of audio buffers.
    ///   The sequence must have `Failure == Never`, meaning callers are responsible
    ///   for handling any errors in their audio pipeline before passing buffers to the session.
    ///
    public convenience init<Provider>(audioProvider: Provider) where Provider : AsyncSequence, Provider.Element == AVReadOnlyAudioPCMBuffer, Provider.Failure == Never

    /// Creates a music understanding session from an audio asset.
    ///
    /// Use this initializer when your audio source is an AVAsset rather than a streaming sequence of audio buffers.
    ///
    /// - Parameter asset: An `AVAsset` containing an audio track.
    ///
    /// - Throws: If the asset is unreadable, does not contain valid audio tracks, or cannot be processed for analysis.
    ///
    /// - Note: This initializer does not support HTTP live streams (HLS). The asset must represent locally available media or a complete file.
    ///
    public convenience init(asset: any AVAsset & Sendable) async throws

    /// Performs the specified analyses on the session's audio source.
    ///
    /// - Parameter analysisTypes: A `Set` of `AnalysisType` values specifying which analyses to perform.
    ///
    /// - Returns: The aggregated session result containing all requested analyses.
    ///
    /// - Throws: If the analysis types set is empty, or if analysis is already running on this session.
    ///
    /// - Note: Call this method only once per session instance. Create a new session to run additional analyses.
    ///
    /// Example usage:
    ///    ```swift
    ///    let session = MusicUnderstandingSession(audioProvider: provider)
    ///    let result = try await session.analyze(for: [.rhythm, .pace, .loudness])
    ///    ```
    ///
    @discardableResult
    public func analyze(for analysisTypes: Set<AnalysisType>) async throws -> MusicUnderstandingSession.SessionResult

    /// Performs all available analyses on the session's audio source.
    ///
    /// - Returns: The aggregated session result containing all analyses.
    ///
    /// - Throws: If analysis is already running on this session.
    ///
    /// - Note: This method can only be called once per session instance. Create a new session to run additional analyses.
    ///
    /// Example usage:
    /// ```swift
    /// let session = MusicUnderstandingSession(audioProvider: provider)
    /// let result = try await session.analyze()
    /// ```
    ///
    @discardableResult
    public func analyze() async throws -> MusicUnderstandingSession.SessionResult

    /// Cancels any ongoing analysis.
    ///
    /// Once a session has been canceled it cannot be re-used.
    ///
    public func cancel() async

    @objc deinit

    /// Retrieve the executor for this actor as an optimized, unowned
    /// reference.
    ///
    /// This property must always evaluate to the same executor for a
    /// given actor instance, and holding on to the actor must keep the
    /// executor alive.
    ///
    /// This property will be implicitly accessed when work needs to be
    /// scheduled onto this actor.  These accesses may be merged,
    /// eliminated, and rearranged with other work, and they may even

Truncated.

public struct PaceResult : Codable, Sendable {

    /// The pace for a range of a song.
    ///
    public let ranges: [MusicUnderstandingSession.RangedValue<Double>]

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    public var debugDescription: String { get }
}

public struct RhythmResult : Codable, Sendable {

    /// The timestamp of each detected beat.
    ///
    public let beats: [CMTime]

    /// The start time of each bar. A bar is a musical unit typically containing several beats.
    ///
    public let bars: [CMTime]

    /// The tempo of the song in beats per minute.
    ///
    /// This value may be nil until enough audio has been analyzed.
    /// 
    public let beatsPerMinute: Float?

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    public var debugDescription: String { get }
}

public struct StructureResult : Codable, Sendable {

    /// The time ranges of each section in the song.
    ///
    /// A section contains one or more segments and represents a major structural component, such as a verse or chorus.
    ///
    public let sections: [CMTimeRange]

    /// The time range of each segment in the song.
    ///
    /// A segment is a collection of phrases that form a distinct part of a song.
    ///
    public let segments: [CMTimeRange]

    /// The time range of each phrase in the song.
    ///
    /// A phrase is a group of bars that form a distinct part of a song.
    ///
    public let phrases: [CMTimeRange]

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    public var debugDescription: String { get }
}

public struct Instrument : Hashable, Sendable, Codable {

    /// The raw value String.
    public let rawValue: String

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    /// The hash value.
    ///
    /// Hash values are not guaranteed to be equal across different executions of
    /// your program. Do not save hash values to use during a future execution.
    ///
    /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
    ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
    ///   The compiler provides an implementation for `hashValue` for you.
    public var hashValue: Int { get }

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws
}

public struct RangedValue<Value> : Codable, Equatable, Sendable where Value : Decodable, Value : Encodable, Value : Equatable, Value : Sendable {

    /// The time range over which the value applies.
    public let range: CMTimeRange

    /// The value associated with the time range.
    public let value: Value

    /// Creates a ranged value by decoding from the given decoder.
    public init(from decoder: any Decoder) throws

    /// Encodes the ranged value into the given encoder.
    public func encode(to encoder: any Encoder) throws

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: MusicUnderstandingSession.RangedValue<Value>, b: MusicUnderstandingSession.RangedValue<Value>) -> Bool
}

public struct SessionResult : Codable, Sendable {

    /// The aggregated instrument activity results, identifying which instruments are present and when they're active.
    public let instrumentActivity: InstrumentActivityResult?

    /// The aggregated key results, identifying the central note (tonic) and mode around which a piece of music is organized.
    public let key: KeyResult?

    /// The aggregated loudness results, providing information about volume levels throughout the audio.
    public let loudness: LoudnessResult?

    /// The aggregated pace results, describing the energy and momentum variations over time.
    public let pace: PaceResult?

    /// The aggregated rhythm results, including detected beats, bars, and BPM.
    public let rhythm: RhythmResult?

    /// The aggregated structure results, identifying musical sections and their boundaries.
    public let structure: StructureResult?

    /// Encodes this value into the given encoder.
    ///
    /// If the value fails to encode anything, `encoder` will encode an empty
    /// keyed container in its place.
    ///
    /// This function throws an error if any values are invalid for the given
    /// encoder's format.
    ///
    /// - Parameter encoder: The encoder to write data to.
    public func encode(to encoder: any Encoder) throws

    /// Creates a new instance by decoding from the given decoder.
    ///
    /// This initializer throws an error if reading from the decoder fails, or
    /// if the data read is corrupted or otherwise invalid.
    ///
    /// - Parameter decoder: The decoder to read data from.
    public init(from decoder: any Decoder) throws
}

public struct TimedValue<Value> : Codable, Equatable, Sendable where Value : Decodable, Value : Encodable, Value : Equatable, Value : Sendable {

    /// The time at which the value applies.
    public let time: CMTime

    /// The value associated with the time.
    public let value: Value

    /// Creates a timed value by decoding from the given decoder.
    public init(from decoder: any Decoder) throws

    /// Encodes the timed value into the given encoder.
    public func encode(to encoder: any Encoder) throws

    /// Returns a Boolean value indicating whether two values are equal.
    ///
    /// Equality is the inverse of inequality. For any values `a` and `b`,
    /// `a == b` implies that `a != b` is `false`.
    ///
    /// - Parameters:
    ///   - lhs: A value to compare.
    ///   - rhs: Another value to compare.
    public static func == (a: MusicUnderstandingSession.TimedValue<Value>, b: MusicUnderstandingSession.TimedValue<Value>) -> Bool
}