/// Audio System Protocol - Platform-agnostic audio handling
/// This module contains ONLY protocol definitions with no platform-specific imports

import Foundation

// MARK: - Audio Types

/// Audio source handle
public struct AudioHandle: Hashable, Sendable {
    public let id: UUID
    public init(id: UUID = UUID()) { self.id = id }
}

/// Audio configuration
public struct AudioConfig: Sendable {
    public var sampleRate: Int
    public var channels: Int
    public var bufferSize: Int
    
    public init(sampleRate: Int = 44100, channels: Int = 2, bufferSize: Int = 4096) {
        self.sampleRate = sampleRate
        self.channels = channels
        self.bufferSize = bufferSize
    }
}

/// 3D audio source properties
public struct AudioSource3D: Sendable {
    public var position: SIMD3<Float>
    public var velocity: SIMD3<Float>
    public var volume: Float
    public var pitch: Float
    public var looping: Bool
    public var spatialize: Bool
    
    public init(position: SIMD3<Float> = .zero, velocity: SIMD3<Float> = .zero,
                volume: Float = 1.0, pitch: Float = 1.0, looping: Bool = false, spatialize: Bool = true) {
        self.position = position
        self.velocity = velocity
        self.volume = volume
        self.pitch = pitch
        self.looping = looping
        self.spatialize = spatialize
    }
}

/// Audio listener properties (typically the camera)
public struct AudioListener: Sendable {
    public var position: SIMD3<Float>
    public var velocity: SIMD3<Float>
    public var forward: SIMD3<Float>
    public var up: SIMD3<Float>
    
    public init(position: SIMD3<Float> = .zero, velocity: SIMD3<Float> = .zero,
                forward: SIMD3<Float> = SIMD3<Float>(0, 0, -1), up: SIMD3<Float> = SIMD3<Float>(0, 1, 0)) {
        self.position = position
        self.velocity = velocity
        self.forward = forward
        self.up = up
    }
}

// MARK: - Audio Engine Protocol

/// Audio system abstraction - all platform-specific audio implementations must conform
public protocol AudioEngine: Sendable {
    /// Initialize the audio system
    func initialize(config: AudioConfig) async throws
    
    /// Load an audio clip from file
    func loadAudio(path: String) async throws -> AudioHandle
    
    /// Load audio from raw PCM data
    func loadAudioFromData(data: Data, sampleRate: Int, channels: Int) async throws -> AudioHandle
    
    /// Play an audio source
    func play(handle: AudioHandle, source: AudioSource3D) throws
    
    /// Stop an audio source
    func stop(handle: AudioHandle) throws
    
    /// Pause an audio source
    func pause(handle: AudioHandle) throws
    
    /// Resume a paused audio source
    func resume(handle: AudioHandle) throws
    
    /// Update audio source properties
    func updateSource(handle: AudioHandle, source: AudioSource3D) throws
    
    /// Set listener properties (camera/player position)
    func setListener(listener: AudioListener) throws
    
    /// Set master volume
    func setMasterVolume(_ volume: Float) throws
    
    /// Update audio system (called each frame)
    func update(deltaTime: Float) throws
    
    /// Shutdown the audio system
    func shutdown() async
}