What's new in AVFAudio

extension AVAudioFile {

    public func read(frameCount: AVAudioFrameCount) throws -> AVReadOnlyAudioPCMBuffer

    public func write(from buffer: AVReadOnlyAudioPCMBuffer) throws
}

extension AVAudioPCMBuffer {

    /// Creates a mutable buffer by copying a read-only buffer's audio data.
    ///
    /// This initializer allocates a new mutable buffer and copies all audio data from the read-only buffer.
    ///
    /// - Parameter readOnlyBuffer: The read-only buffer to copy from.
    public convenience init(copying readOnlyBuffer: AVReadOnlyAudioPCMBuffer)

    /// Creates a mutable buffer by copying another PCM buffer's audio data.
    ///
    /// This initializer allocates a new mutable buffer and copies all audio data channel by channel.
    ///
    /// - Parameter source: The source PCM buffer to copy from.
    public convenience init(copying source: AVAudioPCMBuffer)

    /// Represents read-only channel data.
    ///
    /// For **deinterleaved** formats:
    /// - The span contains only the requested channel's samples in contiguous memory
    ///
    /// For **interleaved** formats:
    /// - The span contains the entire interleaved buffer starting at the channel's first sample
    public enum ChannelData : ~Escapable {

        case int16(Span<Int16>)

        case int32(Span<Int32>)

        case float(Span<Float>)
    }

    /// Represents mutable channel data.
    ///
    /// For **deinterleaved** formats:
    /// - The span contains only the requested channel's samples in contiguous memory
    ///
    /// For **interleaved** formats:
    /// - The span contains the entire interleaved buffer starting at the channel's first sample
    public enum MutableChannelData : ~Copyable, ~Escapable {

        case int16(MutableSpan<Int16>)

        case int32(MutableSpan<Int32>)

        case float(MutableSpan<Float>)
    }

    /// Provides scoped read-only access to the audio buffer list.
    ///
    /// - Parameter body: A closure that receives a pointer to the audio buffer list.
    /// - Returns: The value returned by the closure.
    public func withUnsafeAudioBufferList<R>(_ body: (UnsafePointer<AudioBufferList>) throws -> R) rethrows -> R

    /// Returns read-only access to a specific channel's data.
    ///
    /// The returned `ChannelData` is tied to the lifetime of this buffer and provides
    /// type-safe read-only access to the channel's sample data.
    ///
    /// - Warning: This function cannot enforce exclusivity at compile time because `AVAudioPCMBuffer`
    ///   is an Objective-C class. The caller must ensure proper synchronization when accessing
    ///   the buffer concurrently or when the buffer might be modified.
    ///
    /// - Note: Provides access to valid data only (up to `frameLength`).
    ///
    /// - Parameter index: The zero-based channel index.
    /// - Returns: A `ChannelData` enum containing the channel's sample data.
    ///
    /// - Example:
    /// ```swift
    /// for channelIndex in 0..<Int(buffer.format.channelCount) {
    ///     let channelData = buffer.channelData(channelIndex)
    ///     switch channelData {
    ///     case .float(let samples):
    ///         // Read Float32 data
    ///         for frame in 0..<samples.count {
    ///             let value = samples[frame]
    ///         }
    ///     case .int16(let samples):
    ///         // Read Int16 data

Truncated.

extension AVAudioPlayer : @unchecked Sendable {
}

extension AVAudioUnitComponent {

    /// Type-safe notification message for audio unit component tag changes.
    ///
    /// This notification is posted when the user tags of an audio unit component are modified.
    /// The notification object is the `AVAudioUnitComponent` whose tags changed.
    ///
    /// - Note: User tags are only supported on macOS.
    public struct TagsDidChangeMessage : NotificationCenter.AsyncMessage {

        /// A type which you can optionally post and observe along with this `AsyncMessage`.
        public typealias Subject = AVAudioUnitComponent

        /// A optional name corresponding to this type, used to interoperate with notification posters and observers.
        public static var name: Notification.Name { get }

        /// Converts a posted asynchronous message into a notification for any observers.
        ///
        /// To implement this method in your own `AsyncMessage` conformance, use the properties defined by the message to populate the ``Notification``'s ``Notification/userInfo``.
        /// - Parameters:
        ///   - message: The posted `AsyncMessage`.
        /// - Returns: The converted ``Notification``.
        public static func makeNotification(_ message: AVAudioUnitComponent.TagsDidChangeMessage) -> Notification

        /// Converts a posted notification into this asynchronous message type for any observers.
        ///
        /// To implement this method in your own `AsyncMessage` conformance, retrieve values from the ``Notification``'s ``Notification/userInfo`` and set them as properties on the message.
        /// - Parameter notification: The posted ``Notification``.
        /// - Returns: The converted `AsyncMessage`, or `nil` if conversion is not possible.
        public static func makeMessage(_ notification: Notification) -> AVAudioUnitComponent.TagsDidChangeMessage?
    }
}

public struct AVReadOnlyAudioPCMBuffer : Sendable {

    /// Creates a read-only buffer by copying audio data from an existing PCM buffer.
    ///
    /// This initializer creates a new `AVAudioPCMBuffer` and copies all audio data,
    /// ensuring the original buffer can continue to be used safely.
    ///
    /// - Parameter buffer: The source PCM buffer to copy from.
    public init(copying buffer: AVAudioPCMBuffer)

    /// Creates a read-only buffer by retaining the existing PCM buffer without copying.
    ///
    /// - Warning: The caller must ensure the original buffer is not modified while this
    ///   read-only buffer is in use. Violating this contract results in undefined behavior.
    ///
    /// - Parameter buffer: The PCM buffer to retain (not copied).
    public init(unsafeRetaining buffer: sending AVAudioPCMBuffer)

    /// Creates a read-only buffer by allocating and initializing audio data via closure.
    ///
    /// - Parameters:
    ///   - format: The audio format for the buffer.
    ///   - frameCapacity: The capacity in audio frames.
    ///   - initializingWith: Closure that receives the mutable AudioBufferList to initialize.
    /// - Throws: An error if allocation fails or the closure throws.
    public init(format: AVAudioFormat, frameCapacity: Int, initializingWith: (_ audioBufferList: UnsafeMutablePointer<AudioBufferList>) throws -> Void) throws

    public var format: AVAudioFormat { get }

    public var frameCapacity: Int { get }

    public var frameLength: Int { get }

    public var stride: Int { get }

    /// Represents read-only channel data.
    ///
    /// For **deinterleaved** formats:
    /// - The span contains only the requested channel's samples in contiguous memory
    ///
    /// For **interleaved** formats:
    /// - The span contains the entire interleaved buffer starting at the channel's first sample
    public enum ChannelData : ~Escapable {

        case int16(Span<Int16>)

        case int32(Span<Int32>)

        case float(Span<Float>)
    }

    /// Provides scoped read-only access to the audio buffer list.
    ///
    /// - Warning: Although the `AudioBufferList` pointer is const, each `AudioBuffer` within
    ///   the list exposes `mData` as `UnsafeMutableRawPointer`. You must not modify the buffer
    ///   data through these pointers. Doing so results in undefined behavior and violates the
    ///   read-only contract of this type.
    ///
    /// - Parameter body: A closure that receives a pointer to the audio buffer list.
    /// - Returns: The value returned by the closure.
    public func withUnsafeAudioBufferList<R>(_ body: (UnsafePointer<AudioBufferList>) throws -> R) rethrows -> R

    /// Returns read-only access to a specific channel's data.
    ///
    /// The returned `ChannelData` is tied to the lifetime of this buffer and provides
    /// type-safe access to the channel's sample data.
    ///
    /// - Note: Provides access to valid data only (up to `frameLength`).
    ///
    /// - Parameter index: The zero-based channel index.
    /// - Returns: A `ChannelData` enum containing the channel's sample data.
    ///
    /// - Example:
    /// ```swift
    /// for channelIndex in 0..<Int(buffer.format.channelCount) {
    ///     let channelData = buffer.channelData(channelIndex)
    ///     switch channelData {
    ///     case .float(let samples):
    ///         // Process Float32 data
    ///         for frame in 0..<samples.count {

Truncated.

extension NotificationCenter.MessageIdentifier where Self == NotificationCenter.BaseMessageIdentifier<AVAudioUnitComponentManager.RegistrationsChangedMessage> {

    public static var registrationsChanged: NotificationCenter.BaseMessageIdentifier<AVAudioUnitComponentManager.RegistrationsChangedMessage> { get }
}

extension NotificationCenter.MessageIdentifier where Self == NotificationCenter.BaseMessageIdentifier<AVAudioSession.DidBecomeActiveMessage> {

    public static var didBecomeActive: NotificationCenter.BaseMessageIdentifier<AVAudioSession.DidBecomeActiveMessage> { get }
}

extension NotificationCenter.MessageIdentifier where Self == NotificationCenter.BaseMessageIdentifier<AVAudioSession.DidBecomeInactiveMessage> {

    public static var didBecomeInactive: NotificationCenter.BaseMessageIdentifier<AVAudioSession.DidBecomeInactiveMessage> { get }
}

extension NotificationCenter.MessageIdentifier where Self == NotificationCenter.BaseMessageIdentifier<AVAudioSession.ResumptionRecommendationMessage> {

    public static var resumptionRecommendation: NotificationCenter.BaseMessageIdentifier<AVAudioSession.ResumptionRecommendationMessage> { get }
}

extension NotificationCenter.MessageIdentifier where Self == NotificationCenter.BaseMessageIdentifier<AVAudioUnitComponent.TagsDidChangeMessage> {

    public static var tagsDidChange: NotificationCenter.BaseMessageIdentifier<AVAudioUnitComponent.TagsDidChangeMessage> { get }
}

public enum DeactivationSource : Int, @unchecked Sendable {

    case app = 1

    case system = 2
}

public enum ResumptionRecommendation : Int, @unchecked Sendable {

    case shouldNotResume = 0

    case shouldResume = 1
}