Repository Public
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