Night Drive

//
//  NightDriveGraph.swift
//  Generated by Phonique from “Night Drive”.
//
//  Phonique writes this file afresh each time it exports the graph, so a
//  change made here is gone after the next export.
//

import AVFAudio
import Foundation
import NightDriveRealtime

/// “Night Drive”, as Phonique plays it: its nodes on an `AVAudioEngine`, connected as
/// the graph's cables connect them.
///
/// Make one, `start()` it to play through the device's output, and `stop()` it; it plays
/// again when it is started again. It is isolated to the main actor, where its engine is
/// driven: make it, start it and stop it there. Everything that can fail throws —
/// `Failure` for what this code checks itself, and AVFAudio's own errors — and nothing here
/// stops the app.
@MainActor
public final class NightDriveGraph {
    /// Why the graph could not be built or started, besides the errors AVFAudio throws.
    public nonisolated enum Failure: Error, Hashable, Sendable {
        /// The device has no audio output to play through: the engine's output node has no
        /// format.
        case outputUnavailable
        /// The device has no audio input to listen to: the graph uses the microphone, and the
        /// engine's input node has no format.
        case inputUnavailable
        /// A node could not be made: its name in the graph.
        case nodeNotMade(String)
        /// One of the package's audio files could not be found or read: its name.
        case audioFileUnreadable(String)
    }

    /// The engine the graph plays on.
    public let engine: AVAudioEngine

    /// The render time of the control nodes' last step, in frames at the output's sample rate;
    /// nil before their first.
    private var lastStepTime: AVAudioFramePosition?
    /// The render time the first step after a start saw, which the seconds count from: the
    /// output's sample time need not start at zero.
    private var stepOrigin: AVAudioFramePosition?
    /// The render time of the control nodes' last step, in seconds since the graph started,
    /// which a Timed Trigger works its presses out from; zero at the first.
    private var renderTime = 0.0
    /// Steps the control nodes while the engine runs.
    private var stepper: Task<Void, Never>?

    /// File Player “Drums loop”.
    private let drumsLoop: AVAudioPlayerNode

    /// Waveform “Sub sine”.
    private let subSine: WaveformNode

    /// Reverb “Hall”.
    private let hall: AVAudioUnitReverb

    /// Delay “Echo”.
    private let echo: AVAudioUnitDelay

    /// Mixer “Mix bus”.
    private let mixBus: AVAudioMixerNode

    /// Builds the graph on `engine`, ready to `start()`: makes each node, attaches it to the
    /// engine, sets its values and connects the cables, each on the bus Phonique connects it on.
    ///
    /// To render the graph offline, give it an engine already in manual rendering mode
    /// (`enableManualRenderingMode(_:format:maximumFrameCount:)`), which has to come before
    /// anything asks for the engine's output node.
    ///
    /// - Parameter engine: The engine to build on: a new one, unless you give your own.
    /// - Throws: `Failure`, or the error AVFAudio throws when it refuses a cable or a file.
    public init(engine: AVAudioEngine = AVAudioEngine()) throws {
        // Every cable carries one format: two channels of 32-bit float at the input's sample rate,
        // so nothing converts it on the way to the output; the input's own format comes out of the
        // input, and out of every effect it feeds.
        let output = engine.outputNode.outputFormat(forBus: 0)
        guard output.sampleRate > 0, output.channelCount > 0 else {
            throw Failure.outputUnavailable
        }
        let hardwareInput = engine.inputNode.inputFormat(forBus: 0)
        guard hardwareInput.sampleRate > 0, hardwareInput.channelCount > 0 else {
            throw Failure.inputUnavailable
        }
        let inputFormat = hardwareInput
        // The input's sample rate, so nothing between the input and the output converts it.
        guard let format = AVAudioFormat(standardFormatWithSampleRate: inputFormat.sampleRate, channels: 2) else {
            throw Failure.outputUnavailable
        }

        // Make each node.
        let drumsLoop = AVAudioPlayerNode()
        drumsLoop.sourceMode = .pointSource
        drumsLoop.renderingAlgorithm = .HRTFHQ
        guard let subSine = WaveformNode(shape: .sine) else {
            throw Failure.nodeNotMade("Sub sine")
        }
        let hall = AVAudioUnitReverb()
        let echo = AVAudioUnitDelay()
        let mixBus = AVAudioMixerNode()

        // Attach each to the engine.
        engine.attach(drumsLoop)
        engine.attach(subSine)
        engine.attach(hall)
        engine.attach(echo)
        engine.attach(mixBus)

        // Set each node's values.
        drumsLoop.position = AVAudio3DPoint(x: 0.0, y: 0.0, z: 0.0)
        subSine.shape = .sine
        subSine.frequency = 55.0
        subSine.amplitude = 0.5
        subSine.stereoPan = 0.0
        hall.bypass = false
        hall.loadFactoryPreset(.largeHall)
        hall.wetDryMix = 40.0
        echo.bypass = false
        echo.delayTime = 0.375
        echo.feedback = 42.0
        echo.lowPassCutoff = 8200.0
        echo.wetDryMix = 32.0
        mixBus.outputVolume = 0.71

        // Connect the cables, in the order they were made: a mixer's input takes its next free bus.
        try engine.connectNode(drumsLoop, to: hall, fromBus: 0, toBus: 0, format: format)
        try engine.connectNode(hall, to: mixBus, fromBus: 0, toBus: mixBus.nextAvailableInputBus, format: format)
        try engine.connectNode(subSine, to: mixBus, fromBus: 0, toBus: mixBus.nextAvailableInputBus, format: format)
        try engine.connectNode(engine.inputNode, to: echo, fromBus: 0, toBus: 0, format: inputFormat)
        try engine.connectNode(echo, to: mixBus, fromBus: 0, toBus: mixBus.nextAvailableInputBus, format: inputFormat)
        try engine.connectNode(mixBus, to: engine.outputNode, fromBus: 0, toBus: 0, format: format)

        // What each node does once it is connected.
        try drumsLoop.scheduleBuffer(
            Self.decodedAudio(at: Self.audioFile("drums.wav"), into: drumsLoop.outputFormat(forBus: 0)),
            at: nil,
            options: .loops,
            completionHandler: nil
        )
        subSine.renderingSampleRate = subSine.outputFormat(forBus: 0).sampleRate

        self.engine = engine
        self.drumsLoop = drumsLoop
        self.subSine = subSine
        self.hall = hall
        self.echo = echo
        self.mixBus = mixBus
    }

    /// Starts the engine, then each node that plays once the engine has started. If a node
    /// does not start, the graph stops again and the error is thrown.
    public func start() throws {
        // The control nodes' first step is at render time zero, before the engine starts, so what
        // they set is there from the first frame.
        lastStepTime = nil
        stepOrigin = nil
        renderTime = 0
        stepControls(elapsed: 0)
        try engine.start()
        do {
            try startNodes()
        } catch {
            stop()
            throw error
        }
        startStepping()
    }

    /// Stops the graph: each node that has something to do first, then the engine. `start()`
    /// plays it again.
    public func stop() {
        stepper?.cancel()
        stepper = nil
        lastStepTime = nil
        stepOrigin = nil
        renderTime = 0
        drumsLoop.pause()
        slowWobblePhase = 0
        echo.wetDryMix = .init(32.0)
        engine.stop()
    }

    /// What each node does once the engine has started.
    private func startNodes() throws {
        try drumsLoop.playAudio()
        // A reverb preset loaded before the engine starts is not heard on macOS 27.0, though the
        // audio unit still names it as its current preset: it is loaded again once the engine has
        // started, which is heard, and the mix set above stays.
        hall.loadFactoryPreset(.largeHall)
    }

    /// The package's audio file `name`, from the package's resources: “Always use
    /// `Bundle.module` when you access resources” (Bundling resources with a Swift package).
    private static func audioFile(_ name: String) throws -> URL {
        guard let url = Bundle.module.url(forResource: name, withExtension: nil) else {
            throw Failure.audioFileUnreadable(name)
        }
        return url
    }

    /// Steps the graph's control nodes — its LFOs, Triggers and Listeners — to render time `time`,
    /// in frames at the output's sample rate: each moves on by the render time since the last
    /// step, and sets the value it moves. While the graph plays, `start()` does this every 5 ms
    /// from the output node's `lastRenderTime`; an app that renders the graph offline, in manual
    /// rendering mode, calls it instead at each render time it reaches, every 256 frames, say.
    public func step(to time: AVAudioFramePosition) {
        let sampleRate = engine.outputNode.outputFormat(forBus: 0).sampleRate
        var elapsed = 0.0
        if let lastStepTime, sampleRate > 0 {
            elapsed = Double(time - lastStepTime) / sampleRate
        }
        lastStepTime = time
        let origin = stepOrigin ?? time
        stepOrigin = origin
        if sampleRate > 0 {
            renderTime = max(0, Double(time - origin) / sampleRate)
        }
        stepControls(elapsed: max(0, elapsed))
    }

    /// Looks for a new render time every 5 ms, on the main actor, and steps the control nodes to
    /// it: the look is only how often; the render time says how far they move.
    private func startStepping() {
        stepper = Task { [weak self] in
            while !Task.isCancelled {
                try? await Task.sleep(for: .milliseconds(5))
                guard let self, !Task.isCancelled else { return }
                if let time = engine.outputNode.lastRenderTime, time.isSampleTimeValid {
                    step(to: time.sampleTime)
                }
            }
        }
    }

    /// One step of every control node, `elapsed` seconds of render time after the last, at
    /// `renderTime` seconds since the graph started.
    private func stepControls(elapsed: Double) {
        // LFO “Slow wobble” moves Delay “Echo”'s wetDryMix between 20.0 and 44.0 along a sine wave,
        // 0.2 times a second of render time; switched off, the value is the document's.
        if slowWobbleRate.isFinite, elapsed > 0 {
            let advanced = slowWobblePhase + slowWobbleRate * elapsed
            slowWobblePhase = advanced - advanced.rounded(.down)
        }
        if slowWobbleBypass {
            echo.wetDryMix = .init(32.0)
        } else {
            let value = 20.0 + (44.0 - 20.0) * (1 + sin(2 * .pi * slowWobblePhase)) / 2
            echo.wetDryMix = .init(value)
        }
    }

    /// The whole of the audio file at `url`, decoded to loop in `format`: read until the file
    /// ends, then converted to its sample rate and its channels — a mono file into every
    /// channel, a file with more channels mixed down — as Phonique's File Player reads its file.
    /// A file that would decode to more than 512 MiB is refused before a byte is decoded,
    /// and one that ends before its length is unreadable, never a loop missing its end.
    private static func decodedAudio(at url: URL, into format: AVAudioFormat) throws -> AVAudioPCMBuffer {
        let name = url.lastPathComponent
        let file = try AVAudioFile(forReading: url)
        let source = file.processingFormat
        guard file.length > 0, source.sampleRate > 0, source.channelCount > 0, format.sampleRate > 0 else {
            throw Failure.audioFileUnreadable(name)
        }
        let largest = Double(512 * 1024 * 1024)
        let frames = (Double(file.length) * format.sampleRate / source.sampleRate).rounded(.up)
        let bytesPerFrame = Double(max(source.channelCount, format.channelCount)) * Double(MemoryLayout<Float>.size)
        guard frames * bytesPerFrame <= largest,
              Double(file.length) * Double(source.channelCount) * Double(MemoryLayout<Float>.size) <= largest,
              let whole = AVAudioPCMBuffer(pcmFormat: source, frameCapacity: AVAudioFrameCount(file.length))
        else {
            throw Failure.audioFileUnreadable(name)
        }
        // One read "attempts to fill the buffer to its capacity" and can come back short with no
        // error, so what is left is read into a buffer of its own and copied on, until the file's
        // position reaches its length. A file that ends before its length is an error, never a
        // buffer missing its end: AVFAudio's error for a read past the end, or this one for a
        // read that gives no frames.
        try file.read(into: whole)
        while file.framePosition < file.length {
            let left = AVAudioFrameCount(file.length - file.framePosition)
            guard let rest = AVAudioPCMBuffer(pcmFormat: source, frameCapacity: left) else {
                throw Failure.audioFileUnreadable(name)
            }
            try file.read(into: rest)
            guard rest.frameLength > 0 else {
                throw Failure.audioFileUnreadable(name)
            }
            // Onto the end of the whole, in the one format both are in: each of its buffers — one
            // a channel deinterleaved, one for all of them interleaved — at the format's bytes a
            // frame.
            let bytesPerFrame = Int(source.streamDescription.pointee.mBytesPerFrame)
            let read = UnsafeMutableAudioBufferListPointer(UnsafeMutablePointer(mutating: rest.audioBufferList))
            let kept = UnsafeMutableAudioBufferListPointer(whole.mutableAudioBufferList)
            for (from, to) in zip(read, kept) {
                guard let from = from.mData, let to = to.mData else { continue }
                (to + Int(whole.frameLength) * bytesPerFrame).copyMemory(from: from, byteCount: Int(rest.frameLength) * bytesPerFrame)
            }
            whole.frameLength += rest.frameLength
        }
        if source == format {
            return whole
        }
        guard let converter = AVAudioConverter(from: source, to: format) else {
            throw Failure.audioFileUnreadable(name)
        }
        converter.downmix = true
        converter.sampleRateConverterQuality = AVAudioQuality.max.rawValue
        let capacity = AVAudioFrameCount((Double(whole.frameLength) * format.sampleRate / source.sampleRate).rounded(.up)) + 1
        guard let converted = AVAudioPCMBuffer(pcmFormat: format, frameCapacity: capacity) else {
            throw Failure.audioFileUnreadable(name)
        }
        // The whole file, once, then the end of the stream: the converter calls this on the
        // calling thread, inside `convert(to:error:withInputFrom:)`.
        var given = false
        var error: NSError?
        let status = converter.convert(to: converted, error: &error) { _, inputStatus in
            if given {
                inputStatus.pointee = .endOfStream
                return nil
            }
            given = true
            inputStatus.pointee = .haveData
            return whole
        }
        if let error {
            throw error
        }
        guard status == .haveData || status == .endOfStream, converted.frameLength > 0 else {
            throw Failure.audioFileUnreadable(name)
        }
        return converted
    }

    /// LFO “Slow wobble”: its phase, in cycles since the graph started, and the values of its own that
    /// a control cable can move.
    private var slowWobblePhase = 0.0
    private var slowWobbleBypass = false
    private var slowWobbleRate = 0.2
}