Repository Public
1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXScript/Simulator.swift3// Description: Offline automation simulator and debugger: a simulated DJ rig (decks, mixer, effects, beat clock) driven4// by the same runtime as the live engine, producing traces and parameter curves without touching audio.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import ORIXDSP1011public struct SimulatedDeckConfig: Sendable, Equatable, Codable {12 public var loaded = true13 public var playing = false14 public var bpm = 128.015 public var lengthBeats = 512.016 public var positionBeats = 0.017 public var title = "Simulated track"18 public var key = "8A"1920 public init(loaded: Bool = true, playing: Bool = false, bpm: Double = 128, lengthBeats: Double = 512, positionBeats: Double = 0, title: String = "Simulated track", key: String = "8A") {21 self.loaded = loaded; self.playing = playing; self.bpm = bpm; self.lengthBeats = lengthBeats; self.positionBeats = positionBeats; self.title = title; self.key = key22 }23}2425public struct SimulationConfig: Sendable, Equatable {26 /// Free-running clock tempo, used while no deck is playing.27 public var bpm = 128.028 public var decks: [SimulatedDeckConfig] = [29 SimulatedDeckConfig(playing: true, title: "Track A"), SimulatedDeckConfig(title: "Track B", key: "9A"),30 SimulatedDeckConfig(loaded: false, title: ""), SimulatedDeckConfig(loaded: false, title: ""),31 ]32 /// The simulation stops after this many beats even if the automation is still alive.33 public var maxBeats = 256.034 public var stepsPerBeat = 1635 /// Triggers fired during the run: (beat offset, trigger number).36 public var triggers: [(beat: Double, number: Int)] = []37 public var limits = RuntimeLimits()3839 public init() {}4041 public static func == (a: SimulationConfig, b: SimulationConfig) -> Bool {42 a.bpm == b.bpm && a.decks == b.decks && a.maxBeats == b.maxBeats && a.stepsPerBeat == b.stepsPerBeat && a.limits == b.limits43 && a.triggers.map(\.beat) == b.triggers.map(\.beat) && a.triggers.map(\.number) == b.triggers.map(\.number)44 }45}4647/// A simulated rig. Implements the same contract as the live engine binding.48public final class SimulatedRig: AutomationTarget {49 public struct Deck: Equatable, Sendable {50 public var loaded: Bool51 public var playing: Bool52 public var trackBPM: Double53 public var rate = 1.054 public var lengthBeats: Double55 public var positionBeats: Double56 public var cueBeats = 0.057 public var hotcues: [Int: Double] = [:]58 public var loop: (start: Double, length: Double)?59 public var lastLoop: (start: Double, length: Double)?60 public var loopInBeat: Double?61 public var title: String62 public var key: String63 public var brakeRemaining: Double?6465 public static func == (a: Deck, b: Deck) -> Bool {66 a.loaded == b.loaded && a.playing == b.playing && a.positionBeats == b.positionBeats && a.rate == b.rate && a.loop?.start == b.loop?.start && a.loop?.length == b.loop?.length67 }68 }6970 public private(set) var decks: [Deck]71 public private(set) var values: [ParamAddress: Value] = [:]72 public private(set) var freeBPM: Double73 public private(set) var beat = 0.074 public private(set) var masterDeck: Int?75 /// Events produced by the last `step`, to be posted to the automation.76 public private(set) var pendingEvents: [(EventKey, Double)] = []77 public var library: [String] = ["Track A", "Track B", "Night Drive", "Solar Wind", "Deep Current"]7879 public init(config: SimulationConfig = .init()) {80 decks = config.decks.map { Deck(loaded: $0.loaded, playing: $0.playing && $0.loaded, trackBPM: $0.bpm, lengthBeats: $0.lengthBeats, positionBeats: $0.positionBeats, title: $0.title, key: $0.key) }81 while decks.count < ScriptSchema.deckCount { decks.append(Deck(loaded: false, playing: false, trackBPM: 0, lengthBeats: 0, positionBeats: 0, title: "", key: "")) }82 freeBPM = config.bpm83 masterDeck = decks.firstIndex { $0.playing }84 }8586 public var clockBPM: Double {87 if let m = masterDeck, decks[m].playing, decks[m].trackBPM > 0 { return decks[m].trackBPM * decks[m].rate }88 return freeBPM89 }9091 private func updateMaster() {92 if let m = masterDeck, decks[m].playing { return }93 masterDeck = decks.firstIndex { $0.playing }94 }9596 // MARK: AutomationTarget9798 public func read(_ a: ParamAddress) -> Value? {99 switch a.area {100 case .master:101 switch a.key {102 case "bpm": return .number(clockBPM)103 case "beat": return .number(beat)104 case "bar": return .number((beat / ORIXScriptLanguage.beatsPerBar).rounded(.down))105 case "deck": return .string(masterDeck.map { deckLetters[$0] } ?? "")106 default: return nil107 }108 case .deck:109 guard let i = a.deck, decks.indices.contains(i) else { return nil }110 let d = decks[i]111 let bpm = d.trackBPM * d.rate112 switch a.key {113 case "bpm": return .number(bpm)114 case "trackBpm": return .number(d.trackBPM)115 case "rate": return .number(d.rate)116 case "position": return .duration(.seconds(d.trackBPM > 0 ? d.positionBeats * 60 / d.trackBPM : 0))117 case "remaining": return .duration(.seconds(bpm > 0 ? max(0, d.lengthBeats - d.positionBeats) * 60 / bpm : 0))118 case "duration": return .duration(.seconds(d.trackBPM > 0 ? d.lengthBeats * 60 / d.trackBPM : 0))119 case "beat": return .number(d.positionBeats)120 case "playing": return .bool(d.playing)121 case "loaded": return .bool(d.loaded)122 case "looping": return .bool(d.loop != nil)123 case "key": return .string(d.key)124 case "title": return .string(d.title)125 case "level":126 guard d.playing, case let .gain(v)? = read(.deck(i, "volume")) else { return .gain(-60) }127 return .gain(max(-60, v - 6))128 default: break129 }130 case .mixer:131 if a.key == "master.level" { return .gain(decks.contains { $0.playing } ? -6 : -60) }132 case .fx: break133 }134 if let v = values[a] { return v }135 return ScriptSchema.definition(for: a)?.defaultValue136 }137138 public func write(_ a: ParamAddress, _ value: Value, atBeat: Double, rampBeats: Double) {139 if a.area == .deck, let i = a.deck, decks.indices.contains(i) {140 switch (a.key, value) {141 case let ("rate", .number(r)): decks[i].rate = r; return142 case let ("bpm", .number(b)): if decks[i].trackBPM > 0 { decks[i].rate = min(2, max(0.5, b / decks[i].trackBPM)) }; return143 case ("sync", .bool(true)): syncDeck(i)144 default: break145 }146 }147 if a.area == .master, a.key == "bpm", case let .number(b) = value { freeBPM = b; return }148 values[a] = value149 }150151 private func syncDeck(_ i: Int) {152 guard decks[i].trackBPM > 0 else { return }153 let masterTempo = (masterDeck != nil && masterDeck != i) ? clockBPM : freeBPM154 decks[i].rate = min(2, max(0.5, masterTempo / decks[i].trackBPM))155 }156157 public func perform(_ action: ActionAddress, _ args: [Value], atBeat: Double) -> String? {158 if action.area == .fx {159 let addr = ParamAddress(area: .fx, deck: action.deck, effect: action.effect, key: "enabled")160 let on: Bool = { if case .bool(true)? = values[addr] { true } else { false } }()161 switch action.name {162 case "enable": values[addr] = .bool(true)163 case "disable": values[addr] = .bool(false)164 case "toggle": values[addr] = .bool(!on)165 default: return "Unknown effect action '\(action.name)'."166 }167 return nil168 }169 guard action.area == .deck, let i = action.deck, decks.indices.contains(i) else { return "Unknown action '\(action)'." }170 let letter = deckLetters[i]171 func needLoaded() -> String? { decks[i].loaded ? nil : "Deck \(letter) has no track loaded." }172 func beatsArg(_ k: Int) -> Double? {173 guard args.count > k, case let .duration(span) = args[k] else { return nil }174 return span.beats(atBPM: max(20, decks[i].trackBPM * decks[i].rate))175 }176 func quantized(_ b: Double) -> Double {177 if case .bool(false)? = values[.deck(i, "quantize")] { return b }178 return b.rounded()179 }180 switch action.name {181 case "play":182 if let e = needLoaded() { return e }183 if !decks[i].playing {184 decks[i].playing = true185 if case .bool(true)? = values[.deck(i, "sync")] { syncDeck(i) }186 pendingEvents.append((.deck(i, "play"), atBeat)); updateMaster()187 }188 case "pause":189 if decks[i].playing { decks[i].playing = false; pendingEvents.append((.deck(i, "pause"), atBeat)); updateMaster() }190 case "toggle":191 return perform(ActionAddress(area: .deck, deck: i, name: decks[i].playing ? "pause" : "play"), [], atBeat: atBeat)192 case "stop":193 if decks[i].playing { decks[i].playing = false; pendingEvents.append((.deck(i, "pause"), atBeat)) }194 decks[i].positionBeats = 0; decks[i].loop = nil; updateMaster()195 case "cue":196 if let e = needLoaded() { return e }197 if decks[i].playing { decks[i].playing = false; pendingEvents.append((.deck(i, "pause"), atBeat)); updateMaster() }198 decks[i].positionBeats = decks[i].cueBeats199 case "setCue": decks[i].cueBeats = quantized(decks[i].positionBeats)200 case "seek":201 if let e = needLoaded() { return e }202 guard args.count == 1, case let .duration(span) = args[0] else { return "seek() needs a position." }203 let b = span.beats(atBPM: max(20, decks[i].trackBPM))204 decks[i].positionBeats = min(max(0, b), decks[i].lengthBeats)205 case "jump":206 if let e = needLoaded() { return e }207 guard let b = beatsArg(0) else { return "jump() needs a distance." }208 decks[i].positionBeats = min(max(0, decks[i].positionBeats + b), decks[i].lengthBeats)209 case "loop":210 if let e = needLoaded() { return e }211 guard let b = beatsArg(0), b > 0 else { return "loop() needs a length." }212 let start = quantized(decks[i].positionBeats)213 decks[i].loop = (start, b); decks[i].lastLoop = decks[i].loop214 case "loopIn": decks[i].loopInBeat = quantized(decks[i].positionBeats)215 case "loopOut":216 guard let start = decks[i].loopInBeat else { return "Deck \(letter): call loopIn() before loopOut()." }217 let end = quantized(decks[i].positionBeats)218 guard end > start else { return "Deck \(letter): the loop end must be after the loop start." }219 decks[i].loop = (start, end - start); decks[i].lastLoop = decks[i].loop; decks[i].positionBeats = start220 case "loopExit": decks[i].loop = nil221 case "reloop":222 guard let l = decks[i].lastLoop else { return "Deck \(letter) has no previous loop." }223 decks[i].loop = l; decks[i].positionBeats = l.start224 case "loopHalve": if let l = decks[i].loop, l.length > 1.0 / 32 { decks[i].loop = (l.start, l.length / 2); decks[i].lastLoop = decks[i].loop }225 case "loopDouble": if let l = decks[i].loop, l.length < 128 { decks[i].loop = (l.start, l.length * 2); decks[i].lastLoop = decks[i].loop }226 case "hotcue":227 if let e = needLoaded() { return e }228 guard case let .number(n)? = args.first else { return "hotcue() needs an index." }229 guard let pos = decks[i].hotcues[Int(n)] else { return "Deck \(letter): hot cue \(Int(n)) is not set." }230 decks[i].positionBeats = pos231 if !decks[i].playing { decks[i].playing = true; pendingEvents.append((.deck(i, "play"), atBeat)); updateMaster() }232 case "setHotcue":233 guard case let .number(n)? = args.first else { return "setHotcue() needs an index." }234 decks[i].hotcues[Int(n)] = quantized(decks[i].positionBeats)235 case "clearHotcue":236 guard case let .number(n)? = args.first else { return "clearHotcue() needs an index." }237 decks[i].hotcues[Int(n)] = nil238 case "sync":239 let on: Bool = { if case let .bool(b)? = args.first { b } else { true } }()240 values[.deck(i, "sync")] = .bool(on)241 if on { syncDeck(i) }242 case "brake":243 decks[i].brakeRemaining = beatsArg(0) ?? 1244 case "load":245 guard case let .string(q)? = args.first else { return "load() needs a title." }246 guard let match = library.first(where: { $0.localizedCaseInsensitiveContains(q) }) else { return "No library track matches \"\(q)\"." }247 if decks[i].playing { return "Deck \(letter) is playing; pause it before loading." }248 decks[i].loaded = true; decks[i].title = match; decks[i].positionBeats = 0; decks[i].loop = nil249 if decks[i].trackBPM <= 0 { decks[i].trackBPM = 128 }; if decks[i].lengthBeats <= 0 { decks[i].lengthBeats = 512 }250 pendingEvents.append((.deck(i, "loaded"), atBeat))251 case "loadNext":252 if decks[i].playing { return "Deck \(letter) is playing; pause it before loading." }253 decks[i].loaded = true; decks[i].title = library[(library.firstIndex(of: decks[i].title).map { $0 + 1 } ?? 0) % library.count]254 decks[i].positionBeats = 0; decks[i].loop = nil255 if decks[i].trackBPM <= 0 { decks[i].trackBPM = 128 }; if decks[i].lengthBeats <= 0 { decks[i].lengthBeats = 512 }256 pendingEvents.append((.deck(i, "loaded"), atBeat))257 case "eject":258 if decks[i].playing { return "Deck \(letter) is playing; pause it before ejecting." }259 decks[i].loaded = false; decks[i].title = ""260 default: return "Unknown deck action '\(action.name)'."261 }262 return nil263 }264265 // MARK: Time266267 /// Advances the simulated world by `delta` clock beats.268 public func step(_ delta: Double) {269 let tempo = max(20, clockBPM)270 for i in decks.indices where decks[i].playing {271 var d = decks[i]272 let deckDelta = delta * (d.trackBPM * d.rate) / tempo273 let before = d.positionBeats274 d.positionBeats += deckDelta275 if let l = d.loop, d.positionBeats >= l.start + l.length, before < l.start + l.length + 1e-9 {276 d.positionBeats = l.start + (d.positionBeats - l.start).truncatingRemainder(dividingBy: l.length)277 }278 if before.rounded(.down) < d.positionBeats.rounded(.down) { pendingEvents.append((.deck(i, "beat"), beat + delta)) }279 if let remaining = d.brakeRemaining {280 d.brakeRemaining = remaining - delta281 if remaining - delta <= 0 { d.brakeRemaining = nil; d.playing = false; pendingEvents.append((.deck(i, "pause"), beat + delta)) }282 }283 if d.positionBeats >= d.lengthBeats {284 d.positionBeats = d.lengthBeats; d.playing = false285 pendingEvents.append((.deck(i, "trackEnd"), beat + delta)); pendingEvents.append((.deck(i, "pause"), beat + delta))286 }287 decks[i] = d288 }289 updateMaster()290 beat += delta291 }292293 public func drainEvents() -> [(EventKey, Double)] { defer { pendingEvents.removeAll() }; return pendingEvents }294}295296public struct CurvePoint: Sendable, Equatable { public var beat: Double; public var value: Double }297298public struct SimulationResult: Sendable {299 public var trace: [TraceEvent]300 /// Sampled scalar value of every parameter the automation wrote, relative beats from the automation start.301 public var curves: [ParamAddress: [CurvePoint]]302 /// Spans during which each deck was playing (relative beats).303 public var playSpans: [[ClosedRange<Double>]]304 public var state: AutomationState305 public var beats: Double306 public var timedOut: Bool307 public var stats: AutomationStats308 public var finalVariables: [VariableSnapshot]309310 public var error: ScriptRuntimeError? { if case let .failed(e) = state { e } else { nil } }311 public var warnings: [TraceEvent] { trace.filter { $0.kind == .warning } }312 public var actions: [TraceEvent] { trace.filter { $0.kind == .action } }313}314315/// Step-by-step simulation, used directly by the debugger and wrapped by `Simulator.run`.316public final class DebugSession {317 public let rig: SimulatedRig318 public let instance: AutomationInstance319 public let config: SimulationConfig320 public private(set) var trace: [TraceEvent] = []321 public private(set) var curves: [ParamAddress: [CurvePoint]] = [:]322 public private(set) var playSpans: [[ClosedRange<Double>]]323 public private(set) var timedOut = false324 private var playStart: [Double?]325 private var triggers: [(beat: Double, number: Int)]326 private var written: Set<ParamAddress> = []327328 public init(program: Program, automation: CompiledAutomation, config: SimulationConfig = .init()) {329 self.config = config330 rig = SimulatedRig(config: config)331 instance = AutomationInstance(program: program, automation: automation, target: rig, nowBeat: 0, limits: config.limits)332 playSpans = Array(repeating: [], count: rig.decks.count)333 playStart = rig.decks.map { $0.playing ? 0 : nil }334 triggers = config.triggers.sorted { $0.beat < $1.beat }335 instance.onTrace = { [unowned self] e in336 var e = e337 e.beat -= self.instance.startBeat338 self.trace.append(e)339 if let a = e.address, e.kind == .write || e.kind == .ramp { self.written.insert(a) }340 if e.kind == .write || e.kind == .rampEnd, let a = e.address, let s = e.value?.scalar { self.written.insert(a); self.curves[a, default: []].append(CurvePoint(beat: e.beat, value: s)) }341 }342 trace.append(TraceEvent(beat: 0, kind: .start, text: "start \"\(automation.name)\" at \(formatNumber(config.bpm)) BPM"))343 }344345 public var beat: Double { rig.beat }346 public var isPaused: Bool { instance.pausedAtLine != nil }347 public var isOver: Bool { !instance.state.isAlive || timedOut }348349 /// Runs until the automation ends, a breakpoint is hit, or the beat limit is reached.350 public func run() {351 let delta = 1.0 / Double(max(1, config.stepsPerBeat))352 // Resume a task interrupted by a breakpoint before moving time.353 if instance.pausedAtLine != nil { return }354 if !instance.advance(to: rig.beat) { return }355 while instance.state.isAlive {356 if rig.beat >= config.maxBeats { timedOut = true; break }357 rig.step(delta)358 for (event, at) in rig.drainEvents() { instance.post(event, atBeat: at) }359 while let t = triggers.first, t.beat <= rig.beat { instance.post(.trigger(t.number), atBeat: t.beat); triggers.removeFirst() }360 let completed = instance.advance(to: rig.beat)361 for (event, at) in rig.drainEvents() { instance.post(event, atBeat: at) }362 sample()363 if !completed { return }364 }365 closeSpans()366 }367368 public func resume() { instance.continueFromBreakpoint(step: false); run() }369 public func stepOver() { instance.continueFromBreakpoint(step: true); run() }370371 private func sample() {372 let rel = rig.beat - instance.startBeat373 for a in written {374 guard let s = rig.read(a)?.scalar else { continue }375 if curves[a]?.last?.value != s || curves[a] == nil { curves[a, default: []].append(CurvePoint(beat: rel, value: s)) }376 }377 for (i, d) in rig.decks.enumerated() {378 if d.playing, playStart[i] == nil { playStart[i] = rel }379 if !d.playing, let s = playStart[i] { playSpans[i].append(s ... max(s, rel)); playStart[i] = nil }380 }381 }382383 private func closeSpans() {384 let rel = rig.beat - instance.startBeat385 for i in playStart.indices { if let s = playStart[i] { playSpans[i].append(s ... max(s, rel)); playStart[i] = nil } }386 }387388 public func result() -> SimulationResult {389 var spans = playSpans390 let rel = rig.beat - instance.startBeat391 for i in playStart.indices { if let s = playStart[i] { spans[i].append(s ... max(s, rel)) } }392 return SimulationResult(trace: trace, curves: curves, playSpans: spans, state: instance.state, beats: max(0, rel), timedOut: timedOut, stats: instance.stats, finalVariables: instance.variables)393 }394}395396public enum Simulator {397 /// Runs an automation to completion in the simulated rig.398 public static func run(_ program: Program, automation name: String? = nil, config: SimulationConfig = .init()) -> SimulationResult? {399 guard let automation = name.flatMap({ program.automation(named: $0) }) ?? program.automations.first else { return nil }400 let session = DebugSession(program: program, automation: automation, config: config)401 session.run()402 return session.result()403 }404}405