SPB Git

Repository Public

Simulator.swift 20.9 KB 405 lines swift

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
Files main
Menu

Theme