SPB Git

Repository Public

AutomationHost.swift 24.1 KB 464 lines swift

1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXDJEngine/AutomationHost.swift3// Description: Live automation: binds ORIX Script to the engine, runs automations on a dedicated scheduler thread4//              with look-ahead so actions land on exact samples, executes console lines, and measures itself.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import ORIXDSP10import ORIXScript11import Synchronization1213public struct AutomationLogLine: Sendable, Equatable, Identifiable {14    public var id: Int15    public var runID: Int16    public var automation: String17    public var beat: Double18    public var kind: TraceKind19    public var text: String20    public var line: Int21    public var date: Date22}2324public struct AutomationRunInfo: Sendable, Equatable, Identifiable {25    public var id: Int26    public var name: String27    public var origin: String28    public var state: AutomationState29    public var elapsedBeats: Double30    public var lengthBeats: Double?31    public var nextWakeBeat: Double?32    public var tasks: Int33    public var ramps: Int34    public var handlers: [String]35    public var stats: AutomationStats36}3738/// Measured behaviour of the scheduler and of event delivery.39public struct SchedulerStats: Sendable, Equatable {40    public init() {}41    public var ticks = 042    public var lastTickMicros = 0.043    public var maxTickMicros = 0.044    public var totalTickMicros = 0.045    /// Largest gap between two ticks, in milliseconds (scheduler jitter).46    public var maxTickGapMillis = 0.047    public var activeAutomations = 048    public var pendingTasks = 049    public var activeRamps = 050    public var started = 051    public var finished = 052    public var runtimeErrors = 053    public var validationErrors = 054    /// Commands whose timing is measured on the render thread.55    public var trackedEvents: UInt64 = 056    public var lateEvents: UInt64 = 057    public var maxLateSamples: Int64 = 058    public var meanLateSamples = 0.059    public var droppedControlEvents = 060    public var averageTickMicros: Double { ticks > 0 ? totalTickMicros / Double(ticks) : 0 }61}6263public enum ConsoleLineKind: String, Sendable { case input, result, info, error }6465public struct ConsoleLine: Sendable, Equatable, Identifiable {66    public var id: Int67    public var kind: ConsoleLineKind68    public var text: String69}7071public final class AutomationHost: @unchecked Sendable, AutomationTarget {72    public let engine: DJEngine73    public var limits = RuntimeLimits()74    /// How far ahead of the clock automations are evaluated, so that their commands can be scheduled on exact samples.75    public var lookaheadSeconds = 0.0376    /// Receives every log line (scheduler thread or caller thread).77    public var onLog: (@Sendable (AutomationLogLine) -> Void)?78    /// Forwards engine events after the host has seen them.79    public var onEngineEvent: (@Sendable (EngineEvent) -> Void)?80    /// Source of a saved script by name, and the list of names (set by the application).81    public var scriptSource: (@Sendable (String) -> String?)?82    public var scriptNames: (@Sendable () -> [String])?8384    private let lock = NSRecursiveLock()85    private var runs: [(id: Int, origin: String, instance: AutomationInstance)] = []86    private var finishedRuns: [AutomationRunInfo] = []87    private var nextRunID = 188    private var nextLogID = 189    private var nextConsoleID = 190    private var log: [AutomationLogLine] = []91    private var statsValue = SchedulerStats()92    private var pendingEvents: [(EventKey, Double)] = []93    private var schedulerThread: Thread?94    private let schedulerRunning = Atomic<Bool>(false)95    private var lastTickTime: UInt64 = 096    private var currentBeat = 0.097    private var currentBPM = 120.098    private var captureRun: Int?99    private var captured: [TraceEvent] = []100101    public init(engine: DJEngine) {102        self.engine = engine103        engine.onEvent = { [weak self] event in self?.handle(event) }104    }105106    deinit { schedulerRunning.store(false, ordering: .relaxed) }107108    // MARK: Scheduler thread109110    /// Starts the live scheduler: a dedicated thread that wakes every 4 ms under the Mach time-constraint policy111    /// (the class Core Audio uses for its own threads), so it keeps its cadence when the machine is busy.112    public func startScheduler() {113        lock.lock(); defer { lock.unlock() }114        guard schedulerThread == nil else { return }115        schedulerRunning.store(true, ordering: .relaxed)116        let thread = Thread { [weak self] in117            var timebase = mach_timebase_info_data_t(); mach_timebase_info(&timebase)118            func ticks(_ nanos: Double) -> UInt64 { UInt64(nanos * Double(timebase.denom) / Double(timebase.numer)) }119            var policy = thread_time_constraint_policy_data_t(period: UInt32(ticks(4_000_000)), computation: UInt32(ticks(400_000)), constraint: UInt32(ticks(2_000_000)), preemptible: 1)120            let count = mach_msg_type_number_t(MemoryLayout<thread_time_constraint_policy_data_t>.size / MemoryLayout<integer_t>.size)121            _ = withUnsafeMutablePointer(to: &policy) { p in122                p.withMemoryRebound(to: integer_t.self, capacity: Int(count)) { thread_policy_set(pthread_mach_thread_np(pthread_self()), thread_policy_flavor_t(THREAD_TIME_CONSTRAINT_POLICY), $0, count) }123            }124            let period = ticks(4_000_000)125            var next = mach_absolute_time() + period126            while let host = self, host.schedulerRunning.load(ordering: .relaxed) {127                host.tick()128                let now = mach_absolute_time()129                if next <= now { next = now + period / 4 }130                mach_wait_until(next)131                next += period132            }133        }134        thread.name = "ai.spboucher.orix.dj.automation"135        thread.qualityOfService = .userInteractive136        thread.start()137        schedulerThread = thread138    }139140    public func stopScheduler() {141        lock.lock(); defer { lock.unlock() }142        schedulerRunning.store(false, ordering: .relaxed)143        schedulerThread = nil144    }145146    private func handle(_ event: EngineEvent) {147        if case let .deck(d, name) = event { lock.withLock { pendingEvents.append((.deck(d, name), currentBeat)) } }148        onEngineEvent?(event)149    }150151    private static let timebase: (Double) = { var t = mach_timebase_info_data_t(); mach_timebase_info(&t); return Double(t.numer) / Double(t.denom) }()152153    /// One scheduler step: service the engine, deliver events, advance every automation. Called by the timer, or by tests.154    public func tick() {155        let started = mach_absolute_time()156        let clock = engine.service()157        lock.lock()158        if lastTickTime != 0 { statsValue.maxTickGapMillis = max(statsValue.maxTickGapMillis, Double(started - lastTickTime) * Self.timebase / 1e6) }159        lastTickTime = started160        currentBeat = clock.beat; currentBPM = clock.bpm161        let horizon = clock.beat + lookaheadSeconds * clock.bpm / 60162        let events = pendingEvents; pendingEvents.removeAll(keepingCapacity: true)163        for (_, _, instance) in runs {164            for (key, beat) in events { instance.post(key, atBeat: beat) }165            instance.advance(to: horizon)166        }167        reap()168        statsValue.ticks += 1169        statsValue.activeAutomations = runs.count170        statsValue.pendingTasks = runs.reduce(0) { $0 + $1.instance.taskSnapshots.count }171        statsValue.activeRamps = runs.reduce(0) { $0 + $1.instance.rampSnapshots.count }172        let micros = Double(mach_absolute_time() - started) * Self.timebase / 1000173        statsValue.lastTickMicros = micros; statsValue.maxTickMicros = max(statsValue.maxTickMicros, micros); statsValue.totalTickMicros += micros174        lock.unlock()175    }176177    private func info(_ run: (id: Int, origin: String, instance: AutomationInstance)) -> AutomationRunInfo {178        let i = run.instance179        return AutomationRunInfo(id: run.id, name: i.automation.name, origin: run.origin, state: i.state, elapsedBeats: i.elapsedBeats, lengthBeats: i.automation.requirements.lengthBeats,180                                 nextWakeBeat: i.nextWakeBeat, tasks: i.taskSnapshots.count, ramps: i.rampSnapshots.count, handlers: i.handlerDescriptions, stats: i.stats)181    }182183    private func reap() {184        for run in runs where !run.instance.state.isAlive {185            if case .failed = run.instance.state { statsValue.runtimeErrors += 1 } else { statsValue.finished += 1 }186            finishedRuns.append(info(run))187            if finishedRuns.count > 50 { finishedRuns.removeFirst(finishedRuns.count - 50) }188        }189        runs.removeAll { !$0.instance.state.isAlive }190    }191192    // MARK: Runs193194    /// Starts an automation of a compiled program. Returns the run id.195    @discardableResult public func start(_ program: Program, automation name: String? = nil, origin: String = "script") -> Int? {196        guard let automation = name.flatMap({ program.automation(named: $0) }) ?? program.automations.first else { return nil }197        lock.lock(); defer { lock.unlock() }198        let clock = engine.clock199        currentBeat = clock.beat; currentBPM = clock.bpm200        let id = nextRunID; nextRunID += 1201        let instance = AutomationInstance(program: program, automation: automation, target: self, nowBeat: clock.beat, limits: limits)202        instance.onTrace = { [weak self] e in self?.record(e, run: id, name: automation.name) }203        runs.append((id, origin, instance))204        statsValue.started += 1205        record(TraceEvent(beat: clock.beat, kind: .start, text: "started"), run: id, name: automation.name)206        return id207    }208209    private func record(_ e: TraceEvent, run: Int, name: String) {210        lock.lock()211        if captureRun == run { captured.append(e) }212        // Ramp end and wait lines are kept out of the live log to keep it readable.213        guard e.kind != .wait, e.kind != .rampEnd else { lock.unlock(); return }214        let line = AutomationLogLine(id: nextLogID, runID: run, automation: name, beat: e.beat, kind: e.kind, text: e.text, line: e.line, date: Date())215        nextLogID += 1216        log.append(line)217        if log.count > 2000 { log.removeFirst(log.count - 2000) }218        let handler = onLog219        lock.unlock()220        handler?(line)221    }222223    public func stop(run id: Int) { lock.withLock { runs.first { $0.id == id }?.instance.stop(); reap() } }224225    public func stop(named name: String) { lock.withLock { for r in runs where r.instance.automation.name == name { r.instance.stop() }; reap() } }226227    public func stopAll() { lock.withLock { for r in runs { r.instance.stop() }; reap() } }228229    public func pause(named name: String? = nil) { lock.withLock { for r in runs where name == nil || r.instance.automation.name == name { r.instance.pause(atBeat: currentBeat) } } }230231    public func resume(named name: String? = nil) { lock.withLock { for r in runs where name == nil || r.instance.automation.name == name { r.instance.resume(atBeat: engine.clock.beat) } } }232233    /// Fires automation trigger `n` (1...16).234    public func fire(trigger n: Int) { lock.withLock { pendingEvents.append((.trigger(n), currentBeat)) } }235236    /// Emergency stop: every automation ends and every effect is bypassed. Decks keep playing.237    public func emergencyStop() {238        stopAll()239        engine.bypassAllEffects()240        record(TraceEvent(beat: currentBeat, kind: .warning, text: "emergency stop: all automations stopped, all effects bypassed"), run: 0, name: "host")241    }242243    public var activeRuns: [AutomationRunInfo] { lock.withLock { runs.map(info) } }244    public var recentRuns: [AutomationRunInfo] { lock.withLock { finishedRuns } }245    public var logLines: [AutomationLogLine] { lock.withLock { log } }246    public func clearLog() { lock.withLock { log.removeAll() } }247248    public var stats: SchedulerStats {249        lock.lock(); defer { lock.unlock() }250        var s = statsValue251        let r = engine.renderState252        s.trackedEvents = r.trackedEvents; s.lateEvents = r.lateEvents; s.maxLateSamples = r.maxLateSamples253        s.meanLateSamples = r.trackedEvents > 0 ? Double(r.totalLateSamples) / Double(r.trackedEvents) : 0254        s.droppedControlEvents = engine.droppedControlEvents255        return s256    }257258    public func noteValidationError() { lock.withLock { statsValue.validationErrors += 1 } }259260    public func resetStats() { lock.withLock { statsValue = SchedulerStats(); lastTickTime = 0 } }261262    /// Renders offline while ticking the scheduler between blocks (tests and benchmarks).263    public func renderOffline(frames: Int) -> [[Float]] {264        var out: [[Float]] = [[], []]265        let block = max(16, engine.configuration.bufferFrames)266        var done = 0267        while done < frames {268            tick()269            let n = min(block, frames - done)270            let part = engine.renderOffline(frames: n)271            out[0] += part[0]; out[1] += part[1]272            done += n273        }274        return out275    }276277    // MARK: AutomationTarget278279    public var clockBPM: Double { currentBPM }280281    public func read(_ address: ParamAddress) -> Value? { engine.value(of: address) }282283    public func write(_ address: ParamAddress, _ value: Value, atBeat beat: Double, rampBeats: Double) {284        let time = engine.sampleTime(forBeat: beat)285        if let message = engine.set(address, value, at: time, rampSeconds: rampBeats * 60 / max(20, currentBPM), tracked: rampBeats == 0) {286            // The engine refused the write (no beat grid, full rack…): say so in the log instead of doing nothing silently.287            record(TraceEvent(beat: beat, kind: .warning, text: "\(address): \(message)"), run: 0, name: "engine")288        }289    }290291    public func perform(_ action: ActionAddress, _ args: [Value], atBeat beat: Double) -> String? {292        let time = engine.sampleTime(forBeat: beat)293        if action.area == .fx {294            guard let kind = action.effect else { return "No effect named." }295            let address = ParamAddress.fx(kind, deck: action.deck, "enabled")296            let on: Bool297            switch action.name {298            case "enable": on = true299            case "disable": on = false300            case "toggle": on = !(engine.value(of: address)?.boolValue ?? false)301            default: return "Unknown effect action '\(action.name)'."302            }303            return engine.set(address, .bool(on), at: time, tracked: true)304        }305        guard action.area == .deck, let d = action.deck, d >= 0, d < deckCount else { return "Unknown action '\(action)'." }306        let status = engine.deckStatus(d)307        let letter = deckLetters[d]308        func span(_ i: Int) -> TimeSpan? { if args.count > i, case let .duration(s) = args[i] { s } else { nil } }309        func index(_ i: Int) -> Int? { if args.count > i, case let .number(n) = args[i] { Int(n) - 1 } else { nil } }310        let deckBPM = status.bpm > 0 ? status.bpm : currentBPM311        switch action.name {312        case "play": return engine.play(deck: d, at: time, tracked: true)313        case "pause": engine.pause(deck: d, at: time, tracked: true)314        case "toggle": if status.playing { engine.pause(deck: d, at: time, tracked: true) } else { return engine.play(deck: d, at: time, tracked: true) }315        case "stop": engine.stopDeck(d, at: time)316        case "cue":317            guard status.track != nil else { return "Deck \(letter) has no track loaded." }318            engine.cue(deck: d, at: time)319        case "setCue": engine.setCue(deck: d)320        case "seek":321            guard let track = status.track else { return "Deck \(letter) has no track loaded." }322            guard let s = span(0) else { return "seek() needs a position." }323            switch s {324            case let .seconds(x): engine.seek(deck: d, seconds: x, at: time, tracked: true)325            case let .beats(b):326                guard let grid = track.grid else { return "Deck \(letter) has no beat grid; seek with seconds instead." }327                engine.seek(deck: d, seconds: grid.seconds(atBeat: b), at: time, tracked: true)328            }329        case "jump":330            guard status.track != nil else { return "Deck \(letter) has no track loaded." }331            guard let s = span(0) else { return "jump() needs a distance." }332            engine.jump(deck: d, beats: s.beats(atBPM: max(20, status.trackBPM > 0 ? status.trackBPM : currentBPM)), at: time, tracked: true)333        case "loop":334            guard let s = span(0) else { return "loop() needs a length." }335            return engine.loop(deck: d, beats: s.beats(atBPM: max(20, deckBPM)), at: time, tracked: true)336        case "loopIn": engine.loopIn(deck: d)337        case "loopOut": return engine.loopOut(deck: d, at: time)338        case "loopExit": engine.loopExit(deck: d, at: time)339        case "reloop": return engine.reloop(deck: d, at: time)340        case "loopHalve": engine.scaleLoop(deck: d, by: 0.5, at: time)341        case "loopDouble": engine.scaleLoop(deck: d, by: 2, at: time)342        case "hotcue":343            guard let i = index(0) else { return "hotcue() needs an index." }344            return engine.hotcue(deck: d, index: i, at: time, tracked: true)345        case "setHotcue": if let i = index(0) { engine.setHotcue(deck: d, index: i) }346        case "clearHotcue": if let i = index(0) { engine.clearHotcue(deck: d, index: i) }347        case "sync":348            let on: Bool = { if case let .bool(b)? = args.first { b } else { true } }()349            return engine.set(.deck(d, "sync"), .bool(on), at: time)350        case "brake":351            guard status.playing else { return nil }352            engine.brake(deck: d, seconds: (span(0) ?? .beats(1)).seconds(atBPM: max(20, deckBPM)), at: time)353        case "load":354            guard case let .string(q)? = args.first else { return "load() needs a title." }355            guard !status.playing else { return "Deck \(letter) is playing; pause it before loading." }356            guard let handler = engine.loadHandler else { return "No music library is available." }357            return handler(d, q)358        case "loadNext":359            guard !status.playing else { return "Deck \(letter) is playing; pause it before loading." }360            guard let handler = engine.loadHandler else { return "No music library is available." }361            return handler(d, nil)362        case "eject":363            guard engine.unload(deck: d) else { return "Deck \(letter) is playing; pause it before ejecting." }364        default: return "Unknown deck action '\(action.name)'."365        }366        return nil367    }368369    // MARK: Console370371    private func out(_ kind: ConsoleLineKind, _ text: String) -> ConsoleLine {372        defer { nextConsoleID += 1 }373        return ConsoleLine(id: nextConsoleID, kind: kind, text: text)374    }375376    /// Executes one console line against the live engine and returns what to print.377    public func execute(console line: String) -> [ConsoleLine] {378        lock.lock(); defer { lock.unlock() }379        var lines = [out(.input, line)]380        switch ConsoleParser.parse(line) {381        case .empty: return []382        case let .invalid(diagnostics):383            statsValue.validationErrors += 1384            lines += diagnostics.map { out(.error, "\($0.message) [\($0.code)]") }385        case let .script(program):386            guard let id = start(program, automation: "console", origin: "console"), let run = runs.first(where: { $0.id == id }) else { return lines + [out(.error, "Nothing to run.")] }387            captureRun = id; captured = []388            run.instance.advance(to: currentBeat + lookaheadSeconds * currentBPM / 60)389            captureRun = nil390            var printed = false391            for e in captured {392                switch e.kind {393                case .print: lines.append(out(.result, e.text)); printed = true394                case .error: lines.append(out(.error, e.text)); printed = true395                case .warning: lines.append(out(.info, e.text))396                default: break397                }398            }399            if run.instance.state.isAlive { lines.append(out(.info, "Automation scheduled (run \(id))")) } else if !printed { lines.append(out(.result, "OK")) }400            reap()401        case let .command(name, argument):402            lines += command(name, argument)403        }404        return lines405    }406407    private func command(_ name: String, _ argument: String?) -> [ConsoleLine] {408        switch name {409        case "help":410            if let topic = argument {411                if let doc = Autocomplete.documentation(for: topic) { return doc.split(separator: "\n").map { out(.result, String($0)) } }412                return [out(.error, "No reference entry for '\(topic)'. Try a path such as deck.A.volume or fx.delay.")]413            }414            return [out(.info, "Type any ORIX Script statement or expression, or a command:")] + ConsoleParser.commands.map { out(.result, $0.usage.padding(toLength: 26, withPad: " ", startingAt: 0) + $0.doc) }415        case "version": return [out(.result, "ORIX Script \(ORIXScriptLanguage.version)")]416        case "clear": return []417        case "list":418            let names = scriptNames?() ?? []419            return names.isEmpty ? [out(.info, "No saved automation.")] : names.map { out(.result, $0) }420        case "run":421            guard let argument, !argument.isEmpty else { return [out(.error, "Usage: run \"Name\"")] }422            guard let source = scriptSource?(argument) else { return [out(.error, "No saved automation named \"\(argument)\". Type 'list' to see them.")] }423            let result = ScriptCompiler.compile(source)424            guard let program = result.program else {425                statsValue.validationErrors += 1426                return result.errors.prefix(6).map { out(.error, "line \($0.location.line): \($0.message) [\($0.code)]") }427            }428            guard let id = start(program, automation: argument, origin: "console") else { return [out(.error, "The script defines no automation.")] }429            return [out(.result, "Automation scheduled (run \(id))")]430        case "stop":431            let before = runs.count432            if let argument, argument != "all" { stop(named: argument) } else { stopAll() }433            return [out(.result, "Stopped \(before - runs.count) automation\(before - runs.count == 1 ? "" : "s")")]434        case "pause": pause(named: argument); return [out(.result, "Paused")]435        case "resume": resume(named: argument); return [out(.result, "Resumed")]436        case "panic": emergencyStop(); return [out(.result, "Emergency stop: automations stopped, effects bypassed")]437        case "trigger":438            guard let n = argument.flatMap({ Int($0) }), n >= 1, n <= ScriptSchema.triggerCount else { return [out(.error, "Usage: trigger <1…\(ScriptSchema.triggerCount)>")] }439            fire(trigger: n); return [out(.result, "Trigger \(n) fired")]440        case "status":441            let c = engine.clock442            var l = [out(.result, "Clock: beat \(String(format: "%.2f", c.beat)), \(String(format: "%.2f", c.bpm)) BPM, master " + (c.masterDeck.map { "deck " + deckLetters[$0] } ?? "free-running"))]443            if runs.isEmpty { l.append(out(.info, "No automation is running.")) }444            for r in runs.map(info) { l.append(out(.result, "#\(r.id) \"\(r.name)\" \(r.state == .paused ? "paused" : "running"), beat \(String(format: "%.1f", r.elapsedBeats))" + (r.lengthBeats.map { " of \(String(format: "%.0f", $0))" } ?? "") + ", \(r.tasks) pending, \(r.ramps) ramps")) }445            return l446        case "decks":447            return (0 ..< deckCount).map { d in448                let s = engine.deckStatus(d)449                guard let t = s.track else { return out(.result, "Deck \(deckLetters[d]): empty") }450                return out(.result, "Deck \(deckLetters[d]): \(s.playing ? "playing" : "paused") \"\(t.title)\" \(String(format: "%.1f", s.position)) s / \(String(format: "%.1f", t.duration)) s, \(s.bpm > 0 ? String(format: "%.2f BPM", s.bpm) : "no tempo")" + (s.sync ? ", sync" : "") + (s.isMaster ? ", master" : ""))451            }452        case "fx":453            var l: [ConsoleLine] = []454            for rack in [nil] + (0 ..< deckCount).map(Optional.some) {455                let slots = engine.rackStatus(rack)456                if slots.isEmpty { continue }457                l.append(out(.result, (rack.map { "Deck \(deckLetters[$0])" } ?? "Master") + ": " + slots.map { "\($0.kind.rawValue)\($0.enabled ? " (on)" : "")" }.joined(separator: " → ")))458            }459            return l.isEmpty ? [out(.info, "Every rack is empty.")] : l460        default: return [out(.error, "Unknown command '\(name)'.")]461        }462    }463}464
Files main
Menu

Theme