@swiftbrowser/native 0.18.2 → 0.19.0

package/swift/Sources/SwiftBrowserNative/Host/AudioEngineBridge.swift

@@ -0,0 +1,921 @@
+#if canImport(SwiftUI)
+import Foundation
+import SwiftBrowserProtocol
+#if !canImport(FoundationBridge)
+import AVFoundation
+
+/// The `audioEngine` host request (packages/native/src/hostRequests.ts): the
+/// app's `AVAudioEngine` (@swiftbrowser/react, audioEngine.ts) answered by
+/// `AVAudioEngine` itself. The commands and their answers are the page's
+/// (Web/src/audioEngine.ts; docs/ops-protocol.md, "An audio engine"): the
+/// app names every engine, node, file and buffer by a number, and each
+/// command acts on them in the order sent. Commands are handled as they
+/// arrive, not on a later turn of the main actor (`HostRequestBridge`
+/// passes them straight here), so a note reaches the sampler at once and a
+/// `connect` never overtakes its `attach`. What finishes later answers
+/// later: `start` once the microphone is allowed, `openFile` once a remote
+/// file is downloaded, a scheduled file or buffer once it has played.
+///
+/// AVAudioEngine raises Objective-C exceptions (which end the app) for
+/// misuse a page shrugs off, so each command checks first: a player plays
+/// only connected and with its engine running, a buffer is converted to its
+/// player's format, the input is connected only with a format it has.
+///
+/// A sampler's `loadZones` loads the files with `loadAudioFiles(at:)`, so
+/// the instrument is the sampler's own default one (velocity, the pedal,
+/// the pitch wheel), then rewrites each zone's root and key range, and the
+/// envelope's attack and release, in the unit's state (`fullState`, the
+/// dictionary an `.aupreset` holds).
+///
+/// A kind a package added (`AudioEngineNodes`: SwiftBrowserDSP's `program`)
+/// is made by the package, which takes its properties and notes.
+@MainActor
+final class AudioEngineBridge {
+    typealias Answer = @MainActor @Sendable (Result<JSONValue, any Error>) -> Void
+
+    private final class Engine {
+        let engine = AVAudioEngine()
+        var nodes: [Int: AVAudioNode] = [:]
+        let mixer: Int
+        let output: Int
+        let input: Int
+        /// Players paused with the engine, to play again at `start`.
+        var paused: [AVAudioPlayerNode] = []
+        var configurationObserver: NSObjectProtocol?
+
+        init(mixer: Int, output: Int, input: Int) {
+            self.mixer = mixer
+            self.output = output
+            self.input = input
+        }
+    }
+
+    /// A tap's latest level, written on the audio thread and read on the main actor.
+    private final class Meter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value: Float = 0
+
+        var rms: Float {
+            get { lock.withLock { value } }
+            set { lock.withLock { value = newValue } }
+        }
+    }
+
+    private var engines: [Int: Engine] = [:]
+    /// Which engine each node is in.
+    private var owners: [Int: Int] = [:]
+    private var files: [Int: AVAudioFile] = [:]
+    private var buffers: [Int: AVAudioPCMBuffer] = [:]
+    private var meters: [Int: Meter] = [:]
+    /// Nodes of the kinds packages added, by id.
+    private var custom: [Int: any AudioEngineCustomNode] = [:]
+    /// Offline rendering in this format instead of the speakers (tests).
+    private let manualRendering: AVAudioFormat?
+
+    init(manualRendering: AVAudioFormat? = nil) {
+        self.manualRendering = manualRendering
+    }
+
+    /// Every engine stopped and let go (the app is going away).
+    func stop() {
+        for id in Array(engines.keys) { destroy(id) }
+    }
+
+    private static let noteActions: Set<String> = ["startNote", "stopNote", "controller", "pitchBend"]
+
+    /// Performs one command; `answer` is called once, now or when it finishes.
+    /// `bytes` are the typed arrays sent beside the command (a buffer's samples).
+    func perform(_ params: JSONObject, bytes: [HostBytes] = [], answer: @escaping Answer) {
+        do {
+            if let value = try handle(params, bytes: bytes, answer: answer) { answer(.success(value)) }
+        } catch {
+            answer(.failure(error))
+        }
+    }
+
+    /// The command's value, or nil when it answers later itself.
+    private func handle(_ params: JSONObject, bytes: [HostBytes], answer: @escaping Answer) throws -> JSONValue? {
+        let ok = JSONValue.object([:])
+        let action = params.string("action") ?? ""
+        // A note for a package's node goes to the package.
+        if Self.noteActions.contains(action), let id = params.int("node"), let made = custom[id] {
+            guard try made.note(action, params) else { throw HostRequestFailure("unsupported: node \(id) takes no notes") }
+            return ok
+        }
+        switch action {
+        case "create":
+            try create(params)
+        case "destroy":
+            destroy(params.int("engine") ?? -1)
+        case "attach":
+            try attach(params)
+        case "detach":
+            try detach(params)
+        case "connect":
+            try connect(params)
+        case "disconnectOutput":
+            let (engine, node) = try engineNode(params)
+            engine.engine.disconnectNodeOutput(node)
+        case "disconnectInput":
+            let (engine, node) = try engineNode(params)
+            engine.engine.disconnectNodeInput(node)
+        case "prepare":
+            try findEngine(params).engine.prepare()
+        case "start":
+            try start(findEngine(params), answer: answer)
+            return nil
+        case "pause":
+            pause(try findEngine(params))
+        case "stop":
+            let engine = try findEngine(params)
+            engine.paused = []
+            engine.engine.stop()
+            for node in engine.nodes.values { (node as? AVAudioPlayerNode)?.stop() }
+            for id in engine.nodes.keys { custom[id]?.halt() }
+        case "reset":
+            let engine = try findEngine(params)
+            engine.paused = []
+            for node in engine.nodes.values {
+                (node as? AVAudioPlayerNode)?.stop()
+                (node as? AVAudioUnitSampler)?.reset()
+            }
+            for id in engine.nodes.keys { custom[id]?.halt() }
+            engine.engine.reset()
+        case "set":
+            let id = params.int("node")
+            let node = try findNode(id)
+            for (key, value) in params.object("values") ?? [:] { try set(node, id: id, key, value) }
+        case "preset":
+            try preset(findNode(params.int("node")), params.string("preset") ?? "")
+        case "openFile":
+            try openFile(params, answer: answer)
+            return nil
+        case "readFile":
+            return try readFile(params)
+        case "writeBuffer":
+            try writeBuffer(params, bytes: bytes)
+        case "release":
+            let id = params.int("id") ?? -1
+            files[id] = nil
+            buffers[id] = nil
+        case "scheduleFile":
+            try scheduleFile(params, answer: answer)
+            return nil
+        case "scheduleBuffer":
+            try scheduleBuffer(params, answer: answer)
+            return nil
+        case "play":
+            try play(params)
+        case "pausePlayer":
+            try findPlayer(params.int("node")).pause()
+        case "stopPlayer":
+            try findPlayer(params.int("node")).stop()
+        case "playerTime":
+            let player = try findPlayer(params.int("node"))
+            guard let now = player.lastRenderTime, let time = player.playerTime(forNodeTime: now) else { return .null }
+            return .object(["sampleTime": .number(Double(time.sampleTime)), "sampleRate": .number(time.sampleRate)])
+        case "loadZones":
+            try loadZones(params)
+        case "loadInstrument":
+            try loadInstrument(params)
+        case "startNote":
+            let sampler = try findSampler(params.int("node"))
+            let velocity = midi(params.int("velocity"))
+            if velocity == 0 {
+                sampler.stopNote(midi(params.int("note")), onChannel: channel(params))
+            } else {
+                sampler.startNote(midi(params.int("note")), withVelocity: velocity, onChannel: channel(params))
+            }
+        case "stopNote":
+            try findSampler(params.int("node")).stopNote(midi(params.int("note")), onChannel: channel(params))
+        case "controller":
+            try findSampler(params.int("node")).sendController(midi(params.int("controller")), withValue: midi(params.int("value")), onChannel: channel(params))
+        case "pitchBend":
+            let value = UInt16(max(0, min(16383, params.int("value") ?? 8192)))
+            try findSampler(params.int("node")).sendPitchBend(value, onChannel: channel(params))
+        case "meter":
+            return .object(["level": .number(level(try findNode(params.int("node"))))])
+        default:
+            throw HostRequestFailure("unsupported: audioEngine \(params.string("action") ?? "without an action")")
+        }
+        return ok
+    }
+
+    // MARK: Engines and nodes
+
+    private func create(_ params: JSONObject) throws {
+        guard let id = params.int("engine"), let mixer = params.int("mixer"), let output = params.int("output"), let input = params.int("input") else {
+            throw HostRequestFailure("audioEngine: create expects an engine, mixer, output and input")
+        }
+        if engines[id] != nil { return }
+        let engine = Engine(mixer: mixer, output: output, input: input)
+        if let format = manualRendering {
+            try engine.engine.enableManualRenderingMode(.offline, format: format, maximumFrameCount: 4096)
+        }
+        engine.nodes[mixer] = engine.engine.mainMixerNode
+        engine.nodes[output] = engine.engine.outputNode
+        engines[id] = engine
+        for node in [mixer, output, input] { owners[node] = id }
+        // A route change (headphones in or out) stops the engine: it starts again if it was running.
+        engine.configurationObserver = NotificationCenter.default.addObserver(forName: .AVAudioEngineConfigurationChange, object: engine.engine, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated {
+                guard let engine = self?.engines[id], !engine.engine.isRunning, self?.manualRendering == nil else { return }
+                try? engine.engine.start()
+            }
+        }
+    }
+
+    private func destroy(_ id: Int) {
+        guard let engine = engines.removeValue(forKey: id) else { return }
+        if let observer = engine.configurationObserver { NotificationCenter.default.removeObserver(observer) }
+        engine.engine.stop()
+        for (nodeID, node) in engine.nodes {
+            if meters.removeValue(forKey: nodeID) != nil { node.removeTap(onBus: 0) }
+            owners[nodeID] = nil
+            custom.removeValue(forKey: nodeID)?.halt()
+        }
+        for node in [engine.mixer, engine.output, engine.input] { owners[node] = nil }
+        engine.nodes = [:]
+    }
+
+    private func findEngine(_ params: JSONObject) throws -> Engine {
+        guard let id = params.int("engine"), let engine = engines[id] else { throw HostRequestFailure("notFound: no engine \(params.int("engine") ?? -1)") }
+        return engine
+    }
+
+    /// The node a command names, with its engine; the input node is made the first time it is named.
+    private func engineNode(_ params: JSONObject) throws -> (Engine, AVAudioNode) {
+        let engine = try findEngine(params)
+        return (engine, try findNode(params.int("node"), in: engine))
+    }
+
+    private func findNode(_ id: Int?, in given: Engine? = nil) throws -> AVAudioNode {
+        guard let id, let engine = given ?? owners[id].flatMap({ engines[$0] }) else { throw HostRequestFailure("notFound: no node \(id ?? -1) is attached") }
+        if let node = engine.nodes[id] { return node }
+        if id == engine.input {
+            let input = engine.engine.inputNode
+            engine.nodes[id] = input
+            return input
+        }
+        throw HostRequestFailure("notFound: no node \(id) is attached")
+    }
+
+    private func findPlayer(_ id: Int?) throws -> AVAudioPlayerNode {
+        guard let player = try findNode(id) as? AVAudioPlayerNode else { throw HostRequestFailure("unsupported: node \(id ?? -1) is not a player") }
+        return player
+    }
+
+    private func findSampler(_ id: Int?) throws -> AVAudioUnitSampler {
+        guard let sampler = try findNode(id) as? AVAudioUnitSampler else { throw HostRequestFailure("unsupported: node \(id ?? -1) is not a sampler") }
+        return sampler
+    }
+
+    private func attach(_ params: JSONObject) throws {
+        let engine = try findEngine(params)
+        guard let id = params.int("node") else { throw HostRequestFailure("audioEngine: attach expects a node") }
+        if engine.nodes[id] != nil || owners[id] != nil { throw HostRequestFailure("exists: node \(id) is attached already") }
+        let node: AVAudioNode
+        switch params.string("kind") ?? "" {
+        case "player": node = AVAudioPlayerNode()
+        case "sampler": node = AVAudioUnitSampler()
+        case "mixer": node = AVAudioMixerNode()
+        case "reverb":
+            let reverb = AVAudioUnitReverb()
+            reverb.loadFactoryPreset(.mediumHall)
+            node = reverb
+        case "delay": node = AVAudioUnitDelay()
+        case "distortion": node = AVAudioUnitDistortion()
+        case "eq": node = AVAudioUnitEQ(numberOfBands: max(1, min(32, params.int("bands") ?? 1)))
+        case "timePitch": node = AVAudioUnitTimePitch()
+        case let kind:
+            let context = AudioEngineNodeContext(format: manualRendering ?? playerFormat(engine))
+            guard let made = try AudioEngineNodes.make(kind, context) else {
+                throw HostRequestFailure("unsupported: no node kind \(kind)\(kind == "program" ? " (the app installs SwiftBrowserDSP for it)" : "")")
+            }
+            node = made.node
+            custom[id] = made
+        }
+        engine.engine.attach(node)
+        engine.nodes[id] = node
+        owners[id] = params.int("engine")
+        do {
+            for (key, value) in params.object("values") ?? [:] {
+                if key == "preset" { try preset(node, value.string ?? "") } else { try set(node, id: id, key, value) }
+            }
+        } catch {
+            // A package's node that cannot take its values (a program that does not load) is not left attached.
+            if let made = custom.removeValue(forKey: id) {
+                made.halt()
+                engine.engine.detach(node)
+                engine.nodes[id] = nil
+                owners[id] = nil
+            }
+            throw error
+        }
+    }
+
+    private func detach(_ params: JSONObject) throws {
+        let engine = try findEngine(params)
+        guard let id = params.int("node"), let node = engine.nodes[id], id != engine.mixer, id != engine.output, id != engine.input else { return }
+        if meters.removeValue(forKey: id) != nil { node.removeTap(onBus: 0) }
+        (node as? AVAudioPlayerNode)?.stop()
+        custom.removeValue(forKey: id)?.halt()
+        engine.engine.detach(node)
+        engine.nodes[id] = nil
+        owners[id] = nil
+    }
+
+    /// The format a player sends in: stereo at the engine's rate, so a buffer is converted to it once.
+    private func playerFormat(_ engine: Engine) -> AVAudioFormat {
+        let rate = engine.engine.outputNode.outputFormat(forBus: 0).sampleRate
+        return AVAudioFormat(standardFormatWithSampleRate: rate > 0 ? rate : 48_000, channels: 2)!
+    }
+
+    /// Connects `from` to `to` (several: a fan-out), replacing where it went
+    /// before; a destination that is not a mixer takes one input, so what
+    /// was connected into it is let go first.
+    private func connect(_ params: JSONObject) throws {
+        let engine = try findEngine(params)
+        let from = try findNode(params.int("from"), in: engine)
+        let targets = try (params.array("to") ?? []).map { try findNode($0.int, in: engine) }
+        guard !targets.isEmpty else { throw HostRequestFailure("audioEngine: connect expects a destination") }
+        if targets.contains(where: { $0 is AVAudioPlayerNode || $0 is AVAudioUnitSampler || $0 is AVAudioInputNode || $0 is AVAudioSourceNode }) {
+            throw HostRequestFailure("unsupported: a player, a sampler, a source or the input takes no input")
+        }
+        if from is AVAudioOutputNode || targets.contains(where: { $0 === from }) {
+            throw HostRequestFailure("unsupported: the output sends nowhere, and a node cannot feed itself")
+        }
+        var format: AVAudioFormat?
+        if let input = from as? AVAudioInputNode {
+            let inputFormat = input.outputFormat(forBus: 0)
+            guard inputFormat.sampleRate > 0, inputFormat.channelCount > 0 else { throw HostRequestFailure("unavailable: this device has no microphone input") }
+            format = inputFormat
+        } else if from is AVAudioPlayerNode {
+            format = playerFormat(engine)
+        }
+        engine.engine.disconnectNodeOutput(from)
+        var points: [AVAudioConnectionPoint] = []
+        for target in targets {
+            if let mixer = target as? AVAudioMixerNode {
+                points.append(AVAudioConnectionPoint(node: mixer, bus: mixer.nextAvailableInputBus))
+            } else {
+                engine.engine.disconnectNodeInput(target)
+                points.append(AVAudioConnectionPoint(node: target, bus: 0))
+            }
+        }
+        engine.engine.connect(from, to: points, fromBus: 0, format: format)
+    }
+
+    private func start(_ engine: Engine, answer: @escaping Answer) throws {
+        if engine.engine.isRunning {
+            answer(.success(.object([:])))
+            return
+        }
+        let usesInput = engine.nodes[engine.input].map { !engine.engine.outputConnectionPoints(for: $0, outputBus: 0).isEmpty } ?? false
+        guard usesInput, manualRendering == nil else {
+            try run(engine, recording: false)
+            answer(.success(.object([:])))
+            return
+        }
+        // Asking for the microphone without the usage string in the app's
+        // Info.plist ends the app (iOS's privacy check): an error instead.
+        guard Bundle.main.object(forInfoDictionaryKey: "NSMicrophoneUsageDescription") != nil else {
+            throw HostRequestFailure("permission: the app's Info.plist has no NSMicrophoneUsageDescription")
+        }
+        Task { @MainActor in
+            #if os(iOS)
+            guard await AVAudioApplication.requestRecordPermission() else {
+                answer(.failure(HostRequestFailure("permission: the microphone was not allowed")))
+                return
+            }
+            #endif
+            do {
+                try self.run(engine, recording: true)
+                answer(.success(.object([:])))
+            } catch {
+                answer(.failure(error))
+            }
+        }
+    }
+
+    /// Sets up the session (iOS) and starts the engine; the players it paused play on.
+    private func run(_ engine: Engine, recording: Bool) throws {
+        #if os(iOS)
+        if manualRendering == nil {
+            let session = AVAudioSession.sharedInstance()
+            // Music plays with the ringer switch off, as a music app's does; recording plays through the speaker.
+            if recording {
+                try session.setCategory(.playAndRecord, mode: .default, options: [.defaultToSpeaker, .allowBluetoothA2DP])
+            } else if session.category != .playAndRecord {
+                try session.setCategory(.playback, mode: .default)
+            }
+            try session.setActive(true)
+        }
+        #endif
+        engine.engine.prepare()
+        do {
+            try engine.engine.start()
+        } catch {
+            throw HostRequestFailure("unavailable: the engine did not start (\(error.localizedDescription))")
+        }
+        for player in engine.paused { player.play() }
+        engine.paused = []
+    }
+
+    private func pause(_ engine: Engine) {
+        guard engine.engine.isRunning else { return }
+        engine.paused = engine.nodes.values.compactMap { $0 as? AVAudioPlayerNode }.filter(\.isPlaying)
+        for player in engine.paused { player.pause() }
+        engine.engine.pause()
+    }
+
+    // MARK: Properties
+
+    private func set(_ node: AVAudioNode, id: Int?, _ key: String, _ value: JSONValue) throws {
+        let number = Float(value.double ?? 0)
+        let flag = value.bool ?? false
+        if key == "volume" || key == "pan", let mixing = node as? AVAudioMixing {
+            if key == "volume" { mixing.volume = max(0, number) } else { mixing.pan = max(-1, min(1, number)) }
+            return
+        }
+        if let made = id.flatMap({ custom[$0] }) {
+            guard try made.set(key, value) else { throw HostRequestFailure("unsupported: this node has no \(key)") }
+            return
+        }
+        if key == "bypass" {
+            if let effect = node as? AVAudioUnitEffect { effect.bypass = flag }
+            if let effect = node as? AVAudioUnitTimeEffect { effect.bypass = flag }
+            return
+        }
+        switch node {
+        case let mixer as AVAudioMixerNode where key == "outputVolume":
+            mixer.outputVolume = max(0, number)
+        case let sampler as AVAudioUnitSampler:
+            switch key {
+            case "overallGain": sampler.overallGain = max(-90, min(12, number))
+            case "globalTuning": sampler.globalTuning = max(-2400, min(2400, number))
+            case "stereoPan": sampler.stereoPan = max(-100, min(100, number))
+            default: break
+            }
+        case let reverb as AVAudioUnitReverb where key == "wetDryMix":
+            reverb.wetDryMix = max(0, min(100, number))
+        case let delay as AVAudioUnitDelay:
+            switch key {
+            case "delayTime": delay.delayTime = TimeInterval(max(0, min(2, number)))
+            case "feedback": delay.feedback = max(-100, min(100, number))
+            case "lowPassCutoff": delay.lowPassCutoff = max(10, number)
+            case "wetDryMix": delay.wetDryMix = max(0, min(100, number))
+            default: break
+            }
+        case let distortion as AVAudioUnitDistortion:
+            switch key {
+            case "preGain": distortion.preGain = max(-80, min(20, number))
+            case "wetDryMix": distortion.wetDryMix = max(0, min(100, number))
+            default: break
+            }
+        case let eq as AVAudioUnitEQ:
+            try setEQ(eq, key, value)
+        case let timePitch as AVAudioUnitTimePitch:
+            switch key {
+            case "pitch": timePitch.pitch = max(-2400, min(2400, number))
+            case "rate": timePitch.rate = max(1.0 / 32, min(32, number))
+            case "overlap": timePitch.overlap = max(3, min(32, number))
+            default: break
+            }
+        default:
+            break
+        }
+    }
+
+    private static let filterTypes: [String: AVAudioUnitEQFilterType] = [
+        "parametric": .parametric, "lowPass": .lowPass, "highPass": .highPass, "resonantLowPass": .resonantLowPass,
+        "resonantHighPass": .resonantHighPass, "bandPass": .bandPass, "bandStop": .bandStop, "lowShelf": .lowShelf,
+        "highShelf": .highShelf, "resonantLowShelf": .resonantLowShelf, "resonantHighShelf": .resonantHighShelf,
+    ]
+
+    private func setEQ(_ eq: AVAudioUnitEQ, _ key: String, _ value: JSONValue) throws {
+        if key == "globalGain" {
+            eq.globalGain = max(-96, min(24, Float(value.double ?? 0)))
+            return
+        }
+        let parts = key.split(separator: ".")
+        guard parts.count == 3, parts[0] == "bands", let index = Int(parts[1]), eq.bands.indices.contains(index) else { return }
+        let band = eq.bands[index]
+        let number = Float(value.double ?? 0)
+        switch parts[2] {
+        case "filterType": if let type = Self.filterTypes[value.string ?? ""] { band.filterType = type }
+        case "frequency": band.frequency = max(10, number)
+        case "bandwidth": band.bandwidth = max(0.05, min(5, number))
+        case "gain": band.gain = max(-96, min(24, number))
+        case "bypass": band.bypass = value.bool ?? true
+        default: break
+        }
+    }
+
+    private static let reverbPresets: [String: AVAudioUnitReverbPreset] = [
+        "smallRoom": .smallRoom, "mediumRoom": .mediumRoom, "largeRoom": .largeRoom, "mediumHall": .mediumHall,
+        "largeHall": .largeHall, "plate": .plate, "mediumChamber": .mediumChamber, "largeChamber": .largeChamber,
+        "cathedral": .cathedral, "largeRoom2": .largeRoom2, "mediumHall2": .mediumHall2, "mediumHall3": .mediumHall3,
+        "largeHall2": .largeHall2,
+    ]
+
+    private static let distortionPresets: [String: AVAudioUnitDistortionPreset] = [
+        "drumsBitBrush": .drumsBitBrush, "drumsBufferBeats": .drumsBufferBeats, "drumsLoFi": .drumsLoFi,
+        "multiBrokenSpeaker": .multiBrokenSpeaker, "multiCellphoneConcert": .multiCellphoneConcert,
+        "multiDecimated1": .multiDecimated1, "multiDecimated2": .multiDecimated2, "multiDecimated3": .multiDecimated3,
+        "multiDecimated4": .multiDecimated4, "multiDistortedFunk": .multiDistortedFunk, "multiDistortedCubed": .multiDistortedCubed,
+        "multiDistortedSquared": .multiDistortedSquared, "multiEcho1": .multiEcho1, "multiEcho2": .multiEcho2,
+        "multiEchoTight1": .multiEchoTight1, "multiEchoTight2": .multiEchoTight2, "multiEverythingIsBroken": .multiEverythingIsBroken,
+        "speechAlienChatter": .speechAlienChatter, "speechCosmicInterference": .speechCosmicInterference,
+        "speechGoldenPi": .speechGoldenPi, "speechRadioTower": .speechRadioTower, "speechWaves": .speechWaves,
+    ]
+
+    private func preset(_ node: AVAudioNode, _ name: String) throws {
+        if let reverb = node as? AVAudioUnitReverb, let preset = Self.reverbPresets[name] {
+            reverb.loadFactoryPreset(preset)
+        } else if let distortion = node as? AVAudioUnitDistortion, let preset = Self.distortionPresets[name] {
+            distortion.loadFactoryPreset(preset)
+        } else {
+            throw HostRequestFailure("unsupported: no preset \(name) for this node")
+        }
+    }
+
+    // MARK: Files and buffers
+
+    /// Opens a file to read: the app's own (`file:`), a page's (`https:`, downloaded first) or a `data:` URL (written to a temporary file).
+    private func openFile(_ params: JSONObject, answer: @escaping Answer) throws {
+        guard let id = params.int("file"), let string = params.string("url"), let url = URL(string: string) else {
+            throw HostRequestFailure("audioEngine: openFile expects a file and a url")
+        }
+        let opened: @MainActor (URL) throws -> JSONValue = { [weak self] local in
+            let file: AVAudioFile
+            do {
+                file = try AVAudioFile(forReading: local)
+            } catch {
+                throw HostRequestFailure("decode: \(string.prefix(80)) is not audio the app can read (\(error.localizedDescription))")
+            }
+            self?.files[id] = file
+            return .object([
+                "length": .number(Double(file.length)),
+                "sampleRate": .number(file.processingFormat.sampleRate),
+                "channelCount": .number(Double(file.processingFormat.channelCount)),
+            ])
+        }
+        switch url.scheme?.lowercased() {
+        case "file":
+            let local = AppFiles.current(url)
+            guard FileManager.default.fileExists(atPath: local.path) else { throw HostRequestFailure("notFound: no file at \(local.path)") }
+            answer(.success(try opened(local)))
+        case "data":
+            answer(.success(try opened(try Self.temporaryFile(dataURL: string))))
+        case "http", "https":
+            Task { @MainActor in
+                do {
+                    let (download, response) = try await URLSession.shared.download(from: url)
+                    let ext = url.pathExtension.isEmpty ? Self.fileExtension(mime: response.mimeType ?? "") : url.pathExtension
+                    let local = FileManager.default.temporaryDirectory.appendingPathComponent("\(UUID().uuidString).\(ext)")
+                    try FileManager.default.moveItem(at: download, to: local)
+                    answer(.success(try opened(local)))
+                } catch let failure as HostRequestFailure {
+                    answer(.failure(failure))
+                } catch {
+                    answer(.failure(HostRequestFailure("notFound: \(string) could not be downloaded (\(error.localizedDescription))")))
+                }
+            }
+        default:
+            throw HostRequestFailure("unsupported: the app cannot open \(url.scheme ?? "this") URLs as audio")
+        }
+    }
+
+    private static func fileExtension(mime: String) -> String {
+        switch mime.lowercased() {
+        case "audio/wav", "audio/x-wav", "audio/wave", "audio/vnd.wave": return "wav"
+        case "audio/mpeg", "audio/mp3": return "mp3"
+        case "audio/aiff", "audio/x-aiff": return "aif"
+        case "audio/flac", "audio/x-flac": return "flac"
+        case "audio/caf", "audio/x-caf": return "caf"
+        default: return "m4a"
+        }
+    }
+
+    /// A `data:` URL's bytes in a temporary file named for its type (AVAudioFile reads the type from the name).
+    static func temporaryFile(dataURL: String) throws -> URL {
+        guard let comma = dataURL.firstIndex(of: ",") else { throw HostRequestFailure("decode: a data URL without data") }
+        let header = dataURL[dataURL.index(dataURL.startIndex, offsetBy: 5)..<comma]
+        let mime = String(header.split(separator: ";").first ?? "")
+        let payload = String(dataURL[dataURL.index(after: comma)...])
+        let data: Data?
+        if header.hasSuffix(";base64") {
+            data = Data(base64Encoded: payload)
+        } else {
+            data = payload.removingPercentEncoding.map { Data($0.utf8) }
+        }
+        guard let data else { throw HostRequestFailure("decode: the data URL's data could not be read") }
+        let file = FileManager.default.temporaryDirectory.appendingPathComponent("\(UUID().uuidString).\(fileExtension(mime: mime))")
+        try data.write(to: file)
+        return file
+    }
+
+    private func readFile(_ params: JSONObject) throws -> JSONValue {
+        guard let fileID = params.int("file"), let file = files[fileID] else { throw HostRequestFailure("notFound: no file \(params.int("file") ?? -1) is open") }
+        guard let bufferID = params.int("buffer") else { throw HostRequestFailure("audioEngine: readFile expects a buffer") }
+        let start = max(0, min(file.length, AVAudioFramePosition(params.int("start") ?? 0)))
+        let frames = AVAudioFrameCount(max(0, min(Int64(params.int("frames") ?? 0), file.length - start)))
+        guard let buffer = AVAudioPCMBuffer(pcmFormat: file.processingFormat, frameCapacity: max(1, frames)) else {
+            throw HostRequestFailure("unavailable: no buffer of \(frames) frames")
+        }
+        file.framePosition = start
+        if frames > 0 { try file.read(into: buffer, frameCount: frames) }
+        buffers[bufferID] = buffer
+        return .object([
+            "frameLength": .number(Double(buffer.frameLength)),
+            "sampleRate": .number(buffer.format.sampleRate),
+            "channelCount": .number(Double(buffer.format.channelCount)),
+        ])
+    }
+
+    /// The app's own samples (float32, base64, a channel each) as a buffer.
+    /// Each channel's samples: a `Float32Array` sent beside the command (`{ "$bytes": n }`), or base64 of float32 little-endian.
+    private func writeBuffer(_ params: JSONObject, bytes: [HostBytes]) throws {
+        guard let id = params.int("buffer") else { throw HostRequestFailure("audioEngine: writeBuffer expects a buffer") }
+        let channels = try (params.array("channels") ?? []).map { value -> [Float] in
+            guard let data = value.bytes(from: bytes) else { throw HostRequestFailure("audioEngine: a writeBuffer channel is neither samples nor base64") }
+            return Self.floats(data)
+        }
+        let rate = max(3000, min(768_000, params.double("sampleRate") ?? 48_000))
+        let frames = AVAudioFrameCount(max(1, channels.map(\.count).max() ?? 1))
+        guard !channels.isEmpty,
+              let format = AVAudioFormat(standardFormatWithSampleRate: rate, channels: AVAudioChannelCount(channels.count)),
+              let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: frames),
+              let data = buffer.floatChannelData else {
+            throw HostRequestFailure("unavailable: no buffer for those samples")
+        }
+        buffer.frameLength = frames
+        for (channel, samples) in channels.enumerated() {
+            let target = data[channel]
+            for i in 0..<Int(frames) { target[i] = i < samples.count ? samples[i] : 0 }
+        }
+        buffers[id] = buffer
+    }
+
+    /// Float32 samples from their bytes, whatever the data's alignment.
+    private static func floats(_ data: Data) -> [Float] {
+        let count = data.count / MemoryLayout<Float>.size
+        return [Float](unsafeUninitializedCapacity: count) { buffer, initialized in
+            initialized = data.copyBytes(to: UnsafeMutableRawBufferPointer(buffer)) / MemoryLayout<Float>.size
+        }
+    }
+
+    /// `buffer` in `format`, converted (sample rate, channels) where it is not.
+    private func converted(_ buffer: AVAudioPCMBuffer, to format: AVAudioFormat) throws -> AVAudioPCMBuffer {
+        if buffer.format.sampleRate == format.sampleRate, buffer.format.channelCount == format.channelCount, buffer.format.commonFormat == format.commonFormat, buffer.format.isInterleaved == format.isInterleaved {
+            return buffer
+        }
+        guard let converter = AVAudioConverter(from: buffer.format, to: format) else { throw HostRequestFailure("unsupported: the buffer's format cannot be converted") }
+        // A mono sample plays in both ears, not the left one only.
+        if buffer.format.channelCount == 1, format.channelCount == 2 { converter.channelMap = [0, 0] }
+        let capacity = AVAudioFrameCount(ceil(Double(buffer.frameLength) * format.sampleRate / buffer.format.sampleRate)) + 64
+        guard let output = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: max(1, capacity)) else { throw HostRequestFailure("unavailable: no buffer to convert into") }
+        if let error = Self.convert(buffer, with: converter, into: output) {
+            throw HostRequestFailure("decode: the buffer could not be converted (\(error.localizedDescription))")
+        }
+        return output
+    }
+
+    /// Runs the converter over the whole buffer at once (its input block hands the buffer over once).
+    private nonisolated static func convert(_ buffer: AVAudioPCMBuffer, with converter: AVAudioConverter, into output: AVAudioPCMBuffer) -> NSError? {
+        /// The input, handed over once; the block runs synchronously inside `convert`.
+        final class Feed: @unchecked Sendable {
+            var buffer: AVAudioPCMBuffer?
+            init(_ buffer: AVAudioPCMBuffer) { self.buffer = buffer }
+        }
+        let feed = Feed(buffer)
+        var error: NSError?
+        converter.convert(to: output, error: &error) { _, status in
+            guard let next = feed.buffer else {
+                status.pointee = .endOfStream
+                return nil
+            }
+            feed.buffer = nil
+            status.pointee = .haveData
+            return next
+        }
+        return error
+    }
+
+    // MARK: Players
+
+    private func time(_ spec: JSONObject?) -> AVAudioTime? {
+        guard let spec else { return nil }
+        if let sampleTime = spec.double("sampleTime"), let rate = spec.double("sampleRate"), rate > 0 {
+            return AVAudioTime(sampleTime: AVAudioFramePosition(sampleTime), atRate: rate)
+        }
+        if let delay = spec.double("delay") {
+            return AVAudioTime(hostTime: mach_absolute_time() + AVAudioTime.hostTime(forSeconds: max(0, delay)))
+        }
+        return nil
+    }
+
+    /// The player a schedule names, connected (a player sends nothing unconnected, and AVAudioEngine traps on its buffers).
+    private func connectedPlayer(_ params: JSONObject) throws -> (AVAudioPlayerNode, Engine) {
+        let player = try findPlayer(params.int("node"))
+        guard let engine = owners[params.int("node") ?? -1].flatMap({ engines[$0] }) else { throw HostRequestFailure("notFound: no engine for the player") }
+        guard !engine.engine.outputConnectionPoints(for: player, outputBus: 0).isEmpty else {
+            throw HostRequestFailure("notConnected: connect the player before scheduling or playing")
+        }
+        return (player, engine)
+    }
+
+    /// When a scheduled buffer counts as played: once heard, or rendering
+    /// offline (where nothing is heard), once rendered.
+    private var playedBack: AVAudioPlayerNodeCompletionCallbackType {
+        manualRendering == nil ? .dataPlayedBack : .dataRendered
+    }
+
+    /// A completion handler (called on the audio thread) answering on the main actor.
+    private nonisolated static func played(_ answer: @escaping Answer) -> AVAudioPlayerNodeCompletionHandler {
+        { _ in Task { @MainActor in answer(.success(.object([:]))) } }
+    }
+
+    private func scheduleFile(_ params: JSONObject, answer: @escaping Answer) throws {
+        let (player, engine) = try connectedPlayer(params)
+        guard let file = files[params.int("file") ?? -1] else { throw HostRequestFailure("notFound: no file \(params.int("file") ?? -1) is open") }
+        let start = max(0, min(file.length, AVAudioFramePosition(params.int("start") ?? 0)))
+        let frames = AVAudioFrameCount(max(0, min(Int64(params.int("frames") ?? Int(file.length - start)), file.length - start)))
+        let at = time(params.object("at"))
+        let format = playerFormat(engine)
+        guard frames > 0 else {
+            answer(.success(.object([:])))
+            return
+        }
+        if file.processingFormat.sampleRate == format.sampleRate, file.processingFormat.channelCount == format.channelCount {
+            player.scheduleSegment(file, startingFrame: start, frameCount: frames, at: at, completionCallbackType: playedBack, completionHandler: Self.played(answer))
+            return
+        }
+        // A file in another format is read and converted, then played as a buffer.
+        guard let buffer = AVAudioPCMBuffer(pcmFormat: file.processingFormat, frameCapacity: frames) else { throw HostRequestFailure("unavailable: no buffer of \(frames) frames") }
+        file.framePosition = start
+        try file.read(into: buffer, frameCount: frames)
+        player.scheduleBuffer(try converted(buffer, to: format), at: at, options: [], completionCallbackType: playedBack, completionHandler: Self.played(answer))
+    }
+
+    private func scheduleBuffer(_ params: JSONObject, answer: @escaping Answer) throws {
+        let (player, engine) = try connectedPlayer(params)
+        guard let buffer = buffers[params.int("buffer") ?? -1] else { throw HostRequestFailure("notFound: no buffer \(params.int("buffer") ?? -1)") }
+        var options: AVAudioPlayerNodeBufferOptions = []
+        if params.bool("loops") == true { options.insert(.loops) }
+        if params.bool("interrupts") == true { options.insert(.interrupts) }
+        if params.bool("interruptsAtLoop") == true { options.insert(.interruptsAtLoop) }
+        let playable = try converted(buffer, to: playerFormat(engine))
+        player.scheduleBuffer(playable, at: time(params.object("at")), options: options, completionCallbackType: playedBack, completionHandler: Self.played(answer))
+    }
+
+    private func play(_ params: JSONObject) throws {
+        let (player, engine) = try connectedPlayer(params)
+        guard engine.engine.isRunning else { throw HostRequestFailure("stopped: a player plays only while its engine runs") }
+        player.play(at: time(params.object("at")))
+    }
+
+    // MARK: Samplers
+
+    private func loadZones(_ params: JSONObject) throws {
+        let sampler = try findSampler(params.int("node"))
+        let zones = try (params.array("zones") ?? []).map { value -> (file: AVAudioFile, root: Int, low: Int, high: Int) in
+            let zone = value.object ?? [:]
+            guard let file = files[zone.int("file") ?? -1] else { throw HostRequestFailure("notFound: no file \(zone.int("file") ?? -1) is open") }
+            return (file, zone.int("root") ?? 60, zone.int("low") ?? 0, zone.int("high") ?? 127)
+        }
+        guard !zones.isEmpty else { throw HostRequestFailure("audioEngine: loadZones expects zones") }
+        do {
+            try sampler.loadAudioFiles(at: zones.map(\.file.url))
+        } catch {
+            throw HostRequestFailure("decode: the sampler could not load the files (\(error.localizedDescription))")
+        }
+        let placed = zones.map { (path: $0.file.url.resolvingSymlinksInPath().path, root: $0.root, low: $0.low, high: $0.high) }
+        Self.place(sampler, zones: placed, attack: params.double("attack") ?? 0.002, release: params.double("release") ?? 0.15)
+    }
+
+    /// Rewrites the loaded instrument's zones (root, key range) and its envelope (attack, release) in the unit's state.
+    static func place(_ sampler: AVAudioUnitSampler, zones: [(path: String, root: Int, low: Int, high: Int)], attack: Double, release: Double) {
+        guard var state = sampler.auAudioUnit.fullState,
+              var instrument = state["Instrument"] as? [String: Any],
+              var layers = instrument["Layers"] as? [[String: Any]], !layers.isEmpty else { return }
+        let references = state["file-references"] as? [String: Any] ?? [:]
+        var layer = layers[0]
+        if var placedZones = layer["Zones"] as? [[String: Any]] {
+            for (index, zone) in placedZones.enumerated() {
+                guard let waveform = (zone["waveform"] as? NSNumber)?.intValue,
+                      let path = references["Sample:\(waveform)"] as? String,
+                      let match = zones.first(where: { URL(fileURLWithPath: path).resolvingSymlinksInPath().path == $0.path || URL(fileURLWithPath: path).lastPathComponent == URL(fileURLWithPath: $0.path).lastPathComponent }) else { continue }
+                var updated = zone
+                updated["root key"] = match.root
+                updated["min key"] = match.low
+                updated["max key"] = match.high
+                placedZones[index] = updated
+            }
+            layer["Zones"] = placedZones
+        }
+        if var envelopes = layer["Envelopes"] as? [[String: Any]], var envelope = envelopes.first, var stages = envelope["Stages"] as? [[String: Any]] {
+            for (index, stage) in stages.enumerated() {
+                var updated = stage
+                switch (stage["stage"] as? NSNumber)?.intValue {
+                case 1: updated["time"] = max(0, attack)
+                case 5: updated["time"] = max(0, release)
+                default: continue
+                }
+                stages[index] = updated
+            }
+            envelope["Stages"] = stages
+            envelopes[0] = envelope
+            layer["Envelopes"] = envelopes
+        }
+        layers[0] = layer
+        instrument["Layers"] = layers
+        state["Instrument"] = instrument
+        sampler.auAudioUnit.fullState = state
+    }
+
+    private func loadInstrument(_ params: JSONObject) throws {
+        let sampler = try findSampler(params.int("node"))
+        guard let string = params.string("url"), let url = URL(string: string), url.isFileURL else {
+            throw HostRequestFailure("unsupported: a sound bank or preset loads from the app's files")
+        }
+        let local = AppFiles.current(url)
+        do {
+            if let program = params.int("program") {
+                try sampler.loadSoundBankInstrument(at: local, program: midi(program), bankMSB: midi(params.int("bankMSB") ?? 0x79), bankLSB: midi(params.int("bankLSB") ?? 0))
+            } else {
+                try sampler.loadInstrument(at: local)
+            }
+        } catch {
+            throw HostRequestFailure("decode: the sampler could not load \(local.lastPathComponent) (\(error.localizedDescription))")
+        }
+    }
+
+    private func midi(_ value: Int?) -> UInt8 {
+        UInt8(max(0, min(127, value ?? 0)))
+    }
+
+    private func channel(_ params: JSONObject) -> UInt8 {
+        UInt8(max(0, min(15, params.int("channel") ?? 0)))
+    }
+
+    // MARK: Meters
+
+    /// A node's output level on the meters' scale (0 at -50 dB, 1 at 0 dB), from a tap made the first time it is asked.
+    private func level(_ node: AVAudioNode) -> Double {
+        guard let id = nodeID(node) else { return 0 }
+        let meter: Meter
+        if let existing = meters[id] {
+            meter = existing
+        } else {
+            meter = Meter()
+            meters[id] = meter
+            node.installTap(onBus: 0, bufferSize: 1024, format: nil, block: Self.tap(meter))
+        }
+        return Self.meterLevel(Double(meter.rms))
+    }
+
+    /// The tap's block, made outside the main actor: it runs on the audio thread.
+    private nonisolated static func tap(_ meter: Meter) -> AVAudioNodeTapBlock {
+        { buffer, _ in
+            guard let data = buffer.floatChannelData, buffer.frameLength > 0 else { return }
+            var sum: Float = 0
+            let samples = data[0]
+            for i in 0..<Int(buffer.frameLength) { sum += samples[i] * samples[i] }
+            meter.rms = (sum / Float(buffer.frameLength)).squareRoot()
+        }
+    }
+
+    private func nodeID(_ node: AVAudioNode) -> Int? {
+        for engine in engines.values {
+            if let id = engine.nodes.first(where: { $0.value === node })?.key { return id }
+        }
+        return nil
+    }
+
+    static func meterLevel(_ rms: Double) -> Double {
+        guard rms > 0 else { return 0 }
+        return max(0, min(1, (20 * log10(rms) + 50) / 50))
+    }
+
+    // MARK: Tests
+
+    /// Renders `frames` offline (an engine made in manual rendering mode) and answers its first channel.
+    func render(engine id: Int, frames: Int) throws -> [Float] {
+        guard let engine = engines[id], let format = manualRendering else { throw HostRequestFailure("unsupported: not rendering offline") }
+        var samples: [Float] = []
+        var left = frames
+        while left > 0 {
+            let count = AVAudioFrameCount(min(4096, left))
+            guard let buffer = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: count) else { break }
+            let status = try engine.engine.renderOffline(count, to: buffer)
+            guard status == .success, let data = buffer.floatChannelData else { break }
+            samples.append(contentsOf: UnsafeBufferPointer(start: data[0], count: Int(buffer.frameLength)))
+            left -= Int(buffer.frameLength)
+        }
+        return samples
+    }
+}
+#endif
+#endif