SPB Git

Repository Public

Session.swift 24.2 KB 466 lines swift

1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXDJEngine/Session.swift3// Description: The session coordinator: ties the library, the analysis pipeline, the engine, automation, MIDI,4//              recording and Auto DJ together. Everything slow (decode, analysis, import) runs on background queues.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import AVFoundation9import Foundation10import ORIXAnalysis11import ORIXLibrary12import ORIXMIDI13import ORIXScript1415public struct SessionDirectories: Sendable, Equatable {16    public var root: URL17    public var libraryDatabase: URL { root.appendingPathComponent("Library.sqlite") }18    public var recordings: URL { root.appendingPathComponent("Recordings", isDirectory: true) }19    public var demoTracks: URL { root.appendingPathComponent("Demo Tracks", isDirectory: true) }20    public var autosave: URL { root.appendingPathComponent("Autosave.orixdjproject", isDirectory: true) }21    public init(root: URL) { self.root = root }22}2324public enum SessionError: Error, LocalizedError, Equatable {25    case trackNotFound26    case missingMedia(String)27    case deckBusy(String)28    case loadFailed(String)2930    public var errorDescription: String? {31        switch self {32        case .trackNotFound: "The track is no longer in the library."33        case let .missingMedia(path): "The audio file is missing: \(path)"34        case let .deckBusy(letter): "Deck \(letter) is playing. Pause it before loading another track."35        case let .loadFailed(reason): reason36        }37    }38}3940public struct AnalysisProgress: Sendable, Equatable {41    public var completed: Int42    public var total: Int43    public var currentTitle: String44    public var failures: Int45}4647public struct AutoDJStatus: Sendable, Equatable {48    public init() {}49    public var enabled = false50    public var state = "Off"51    public var currentDeck: Int?52    public var nextTitle = ""53    public var queue: [Int64] = []54    public var lastScript = ""55    public var transitions = 056}5758public final class DJSession: @unchecked Sendable {59    public let directories: SessionDirectories60    public let engine: DJEngine61    public let host: AutomationHost62    public let recorder: Recorder63    public let surface: ControlSurface64    public let library: LibraryStore65    public let midi = MIDIManager()6667    /// Called (on a background queue) when a deck finished loading, analysis progressed, or Auto DJ changed state.68    public var onChange: (@Sendable () -> Void)?6970    private let lock = NSRecursiveLock()71    private let workQueue = DispatchQueue(label: "ai.spboucher.orix.dj.work", qos: .userInitiated, attributes: .concurrent)72    private let analysisQueue = DispatchQueue(label: "ai.spboucher.orix.dj.analysis", qos: .utility)73    private var loadingDecks: [Int: Double] = [:]74    private var loadGeneration = [Int](repeating: 0, count: deckCount)75    private var deckTrackIDs = [Int64?](repeating: nil, count: deckCount)76    private var playRecorded = [Bool](repeating: false, count: deckCount)77    private var historySession: Int64?78    private var analysisCancelled = false79    private var analysisRunning = false80    private var analysisState: AnalysisProgress?81    private var autoDJ = AutoDJStatus()82    private var autoDJSettings = AutoDJSettings()83    private var autoDJRun: Int?84    private var autoDJTimer: DispatchSourceTimer?85    private var lastLoadError: String?8687    public init(root: URL, configuration: EngineConfiguration = .init()) throws {88        directories = SessionDirectories(root: root)89        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)90        library = try LibraryStore(url: directories.libraryDatabase)91        engine = DJEngine(configuration: configuration)92        host = AutomationHost(engine: engine)93        recorder = Recorder(engine: engine)94        surface = ControlSurface(engine: engine, host: host)95        historySession = try? library.beginSession(name: "").id9697        host.scriptSource = { [weak self] name in98            (try? self?.library.script(named: name))??.source ?? PresetLibrary.preset(named: name)?.source99        }100        host.scriptNames = { [weak self] in101            let saved = ((try? self?.library.scripts()) ?? [])?.map(\.name) ?? []102            return saved + PresetLibrary.all.map(\.name).filter { !saved.contains($0) }103        }104        host.onEngineEvent = { [weak self] event in self?.handle(event) }105        engine.loadHandler = { [weak self] deck, query in self?.scriptedLoad(deck: deck, query: query) }106        surfaceBindMIDI()107    }108109    // MARK: MIDI110111    private func surfaceBindMIDI() {112        let surface = surface113        midi.onTargetEvent = { event in surface.apply(event) }114        midi.currentValueProvider = { target in surface.normalizedValue(of: target) }115    }116117    /// Starts CoreMIDI. Must be the first CoreMIDI user in the process for hot-plug to be delivered.118    public func startMIDI() {119        try? midi.start()120        if let name = try? library.setting("midi.activeProfile"), let doc = try? library.document(kind: DocumentKind.midiMapping, name: name),121           let profile = try? MIDIMappingProfile(jsonData: Data(doc.json.utf8)) { midi.activeProfile = profile }122    }123124    public func midiProfiles() -> [MIDIMappingProfile] {125        ((try? library.documents(kind: DocumentKind.midiMapping)) ?? []).compactMap { try? MIDIMappingProfile(jsonData: Data($0.json.utf8)) }126    }127128    public func saveMIDIProfile(_ profile: MIDIMappingProfile, activate: Bool = true) throws {129        let json = String(decoding: try profile.jsonData(), as: UTF8.self)130        _ = try library.saveDocument(kind: DocumentKind.midiMapping, name: profile.name, json: json)131        if activate { midi.activeProfile = profile; try library.setSetting("midi.activeProfile", value: profile.name) }132    }133134    // MARK: Engine events135136    private func handle(_ event: EngineEvent) {137        guard case let .deck(d, name) = event else { onChange?(); return }138        if name == "play" {139            lock.lock()140            let id = deckTrackIDs[d]; let already = playRecorded[d]; playRecorded[d] = true141            let session = historySession142            lock.unlock()143            if let id, !already { _ = try? library.recordPlay(trackID: id, deck: deckLetters[d], sessionID: session) }144        }145        if name != "beat" { onChange?() }146    }147148    // MARK: Analysis storage149150    /// Tempo is reported between 78 and 156 BPM, the convention of DJ software: one octave, so half- and double-time151    /// readings of the same track always agree. The deck's ÷2 and ×2 buttons change it per track.152    public static let analysisOptions: AnalysisOptions = { var o = AnalysisOptions(); o.bpmRange = 78 ... 156; return o }()153154    static func encode(_ result: AnalysisResult) -> Data? {155        guard let json = try? JSONEncoder().encode(result) else { return nil }156        return (try? (json as NSData).compressed(using: .zlib)) as Data?157    }158159    static func decode(_ data: Data) -> AnalysisResult? {160        guard let raw = try? (data as NSData).decompressed(using: .zlib) as Data else { return nil }161        return try? JSONDecoder().decode(AnalysisResult.self, from: raw)162    }163164    /// Stored analysis of a track, when it is current.165    public func storedAnalysis(for track: Track) -> AnalysisResult? {166        guard track.analysisVersion == AnalysisResult.currentVersion, let blob = try? library.analysisBlob(for: track.id), let r = Self.decode(blob) else { return nil }167        return r168    }169170    /// Analyses decoded audio and stores the result. This replaces the stored tempo and grid, including manual edits171    /// (it is what "Analyse Again" asks for); a loaded deck keeps the grid it already has.172    @discardableResult func analyze(_ track: Track, buffer: TrackBuffer, isCancelled: (() -> Bool)? = nil) throws -> (Track, AnalysisResult) {173        let result = try TrackAnalyzer.analyze(left: buffer.leftBuffer, right: buffer.rightBuffer, sampleRate: buffer.sampleRate, options: Self.analysisOptions, isCancelled: isCancelled)174        let analysis = TrackAnalysis(175            bpm: result.grid?.bpm, bpmConfidence: result.bpmConfidence, gridFirstBeat: result.grid?.firstBeatSeconds, gridDownbeatIndex: result.grid?.downbeatIndex,176            key: result.key?.shortName, camelot: result.key?.camelot, keyConfidence: result.key?.confidence,177            loudnessLUFS: result.integratedLUFS, peakDBFS: result.peakDBFS, gainDB: result.suggestedGainDB,178            analysisVersion: AnalysisResult.currentVersion, data: Self.encode(result)179        )180        let updated = try library.setAnalysis(trackID: track.id, analysis)181        return (updated, result)182    }183184    private func gridFor(_ track: Track, _ result: AnalysisResult?) -> BeatGrid? {185        if let bpm = track.bpm, bpm > 0, track.analysisVersion > 0 {186            return BeatGrid(bpm: bpm, firstBeatSeconds: track.gridFirstBeat ?? 0, downbeatIndex: track.gridDownbeatIndex ?? 0)187        }188        return result?.grid189    }190191    // MARK: Loading192193    public var loadProgress: [Int: Double] { lock.withLock { loadingDecks } }194    public func trackID(onDeck d: Int) -> Int64? { lock.withLock { deckTrackIDs[d] } }195    public var lastError: String? { lock.withLock { lastLoadError } }196197    /// Decodes, analyses when needed, and loads a library track on a deck. `completion` runs on a background queue.198    public func load(trackID: Int64, deck d: Int, completion: (@Sendable (Result<LoadedTrack, SessionError>) -> Void)? = nil) {199        guard (0 ..< deckCount).contains(d) else { completion?(.failure(.loadFailed("No such deck."))); return }200        if engine.deckStatus(d).playing { completion?(.failure(.deckBusy(deckLetters[d]))); return }201        lock.lock()202        loadGeneration[d] += 1203        let generation = loadGeneration[d]204        loadingDecks[d] = 0205        lock.unlock()206        onChange?()207        workQueue.async { [self] in208            let result = performLoad(trackID: trackID, deck: d, generation: generation)209            lock.lock()210            if loadGeneration[d] == generation { loadingDecks[d] = nil }211            if case let .failure(e) = result { lastLoadError = e.errorDescription }212            lock.unlock()213            completion?(result)214            onChange?()215        }216    }217218    private func performLoad(trackID: Int64, deck d: Int, generation: Int) -> Result<LoadedTrack, SessionError> {219        guard var track = try? library.track(id: trackID) else { return .failure(.trackNotFound) }220        if let resolved = try? MediaImporter().resolve(track: track, updating: library) { track = resolved.track }221        guard !track.missing, FileManager.default.fileExists(atPath: track.path) else { return .failure(.missingMedia(track.path)) }222        func current() -> Bool { lock.withLock { loadGeneration[d] == generation } }223        let buffer: TrackBuffer224        do {225            buffer = try TrackBuffer.load(url: track.url, progress: { [weak self] p in226                guard let self else { return }227                self.lock.withLock { if self.loadGeneration[d] == generation { self.loadingDecks[d] = p * 0.7 } }228            }, isCancelled: { !current() })229        } catch let e as TrackLoadError { return .failure(.loadFailed(e.errorDescription ?? "The track could not be loaded.")) } catch { return .failure(.loadFailed(error.localizedDescription)) }230        var analysis = storedAnalysis(for: track)231        if analysis == nil {232            lock.withLock { loadingDecks[d] = 0.75 }233            onChange?()234            if let (updated, result) = try? analyze(track, buffer: buffer, isCancelled: { !current() }) { track = updated; analysis = result }235        }236        guard current() else { return .failure(.loadFailed("Superseded by another load.")) }237        let info = LoadedTrack(libraryID: track.id, url: track.url, title: track.title, artist: track.artist, duration: buffer.duration, sampleRate: buffer.sampleRate,238                               grid: gridFor(track, analysis), key: analysis?.key, bpmConfidence: analysis?.bpmConfidence ?? 0, waveform: analysis?.waveform)239        guard engine.load(deck: d, buffer: buffer, info: info) else { return .failure(.deckBusy(deckLetters[d])) }240        var hot = [Double?](repeating: nil, count: ScriptSchema.hotCueCount)241        var cuePoint: Double?242        for c in track.cues {243            if c.index == -1 { cuePoint = c.seconds } else if hot.indices.contains(c.index) { hot[c.index] = c.seconds }244        }245        engine.restore(deck: d, cuePoint: cuePoint, hotcues: hot)246        if autoDJSettings.autoGain, autoDJ.enabled, let g = track.gainDB { engine.set(.deck(d, "gain"), .gain(min(6, max(-12, g)))) }247        lock.withLock { deckTrackIDs[d] = track.id; playRecorded[d] = false }248        return .success(info)249    }250251    /// Stores the deck's cue point and hot cues in the library (index -1 is the main cue).252    public func persistCues(deck d: Int) {253        guard let id = trackID(onDeck: d) else { return }254        let s = engine.deckStatus(d)255        var cues = [CuePoint(index: -1, seconds: s.cuePoint, label: "Cue")]256        for (i, h) in s.hotcues.enumerated() { if let h { cues.append(CuePoint(index: i, seconds: h, label: "\(i + 1)")) } }257        _ = try? library.setCues(trackID: id, cues: cues)258    }259260    /// Replaces the beat grid of the track on a deck and stores it.261    public func setGrid(deck d: Int, _ grid: BeatGrid?) {262        engine.setGrid(deck: d, grid)263        if let id = trackID(onDeck: d) { _ = try? library.setBeatGrid(trackID: id, bpm: grid?.bpm, firstBeat: grid?.firstBeatSeconds, downbeatIndex: grid?.downbeatIndex) }264        onChange?()265    }266267    private func scriptedLoad(deck d: Int, query: String?) -> String? {268        if let query {269            var q = TrackQuery(); q.search = query; q.limit = 1270            guard let track = (try? library.tracks(query: q))?.first else { return "No library track matches \"\(query)\"." }271            load(trackID: track.id, deck: d)272            return nil273        }274        let next: Int64? = lock.withLock { autoDJ.queue.isEmpty ? nil : autoDJ.queue.removeFirst() }275        guard let next else { return "The Auto DJ queue is empty." }276        load(trackID: next, deck: d)277        return nil278    }279280    // MARK: Import and background analysis281282    /// Imports files and folders (no audio is copied), then analyses the new tracks in the background.283    public func importURLs(_ urls: [URL], progress: (@Sendable (ImportProgress) -> Void)? = nil) async -> ImportSummary {284        let importer = MediaImporter()285        let files = importer.scan(urls: urls)286        let summary = await importer.importFiles(files, into: library, progress: progress)287        analyzePending()288        return summary289    }290291    public var analysisProgress: AnalysisProgress? { lock.withLock { analysisState } }292293    public func cancelAnalysis() { lock.withLock { analysisCancelled = true } }294295    /// Analyses every track that has no current analysis. One track at a time, cancellable, off the main thread.296    public func analyzePending() {297        lock.lock()298        if analysisRunning { lock.unlock(); return }299        analysisRunning = true; analysisCancelled = false300        lock.unlock()301        analysisQueue.async { [self] in302            var q = TrackQuery(); q.scope = .unanalysed303            let pending = ((try? library.tracks(query: q)) ?? []).filter { !$0.missing }304            var failures = 0305            for (i, track) in pending.enumerated() {306                if lock.withLock({ analysisCancelled }) { break }307                lock.withLock { analysisState = AnalysisProgress(completed: i, total: pending.count, currentTitle: track.title, failures: failures) }308                onChange?()309                do {310                    let buffer = try TrackBuffer.load(url: track.url, isCancelled: { [weak self] in self?.lock.withLock { self?.analysisCancelled ?? true } ?? true })311                    try analyze(track, buffer: buffer, isCancelled: { [weak self] in self?.lock.withLock { self?.analysisCancelled ?? true } ?? true })312                } catch { failures += 1 }313            }314            lock.withLock { analysisState = nil; analysisRunning = false }315            onChange?()316        }317    }318319    // MARK: Demo tracks320321    public static let demoSpecs: [(title: String, spec: SignalSynth.TrackSpec)] = [322        ("Night Drive", .init(bpm: 124, tonic: 9, mode: .minor, seconds: 150, style: .house, seed: 11)),323        ("Solar Wind", .init(bpm: 126, tonic: 4, mode: .minor, seconds: 150, style: .house, seed: 23)),324        ("Deep Current", .init(bpm: 128, tonic: 11, mode: .minor, seconds: 150, style: .techno, seed: 37)),325        ("Glass Harbour", .init(bpm: 122, tonic: 0, mode: .major, seconds: 140, style: .house, seed: 41)),326        ("Broken Signal", .init(bpm: 140, tonic: 7, mode: .minor, seconds: 130, style: .breakbeat, seed: 53)),327        ("First Light", .init(bpm: 100, tonic: 5, mode: .major, seconds: 120, style: .ambient, seed: 67)),328    ]329330    /// Synthesises the built-in demo tracks (original material generated by ORIX DJ, no samples) and imports them.331    @discardableResult public func installDemoTracks(seconds: Double? = nil) throws -> [Track] {332        try FileManager.default.createDirectory(at: directories.demoTracks, withIntermediateDirectories: true)333        var out: [Track] = []334        for (title, base) in Self.demoSpecs {335            var spec = base336            if let seconds { spec.seconds = seconds }337            let url = directories.demoTracks.appendingPathComponent(title).appendingPathExtension("wav")338            if !FileManager.default.fileExists(atPath: url.path) {339                let audio = SignalSynth.track(spec, sampleRate: 44100)340                try Self.writeWAV(left: audio.left, right: audio.right, sampleRate: 44100, to: url)341            }342            var track = Track(path: url.path, bookmark: try? url.bookmarkData(), title: title, artist: "ORIX DJ", album: "Demo Tracks", genre: spec.style.rawValue.capitalized,343                              duration: spec.seconds, sampleRate: 44100, channels: 2, format: "wav")344            track.fileSize = Int64((try? url.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? 0)345            out.append(try library.upsertTrack(track))346        }347        analyzePending()348        return out349    }350351    public static func writeWAV(left: [Float], right: [Float], sampleRate: Double, to url: URL) throws {352        let settings: [String: Any] = [AVFormatIDKey: kAudioFormatLinearPCM, AVSampleRateKey: sampleRate, AVNumberOfChannelsKey: 2, AVLinearPCMBitDepthKey: 16,353                                       AVLinearPCMIsFloatKey: false, AVLinearPCMIsBigEndianKey: false, AVLinearPCMIsNonInterleaved: false]354        let file = try AVAudioFile(forWriting: url, settings: settings, commonFormat: .pcmFormatFloat32, interleaved: false)355        guard let buffer = AVAudioPCMBuffer(pcmFormat: file.processingFormat, frameCapacity: AVAudioFrameCount(left.count)), let data = buffer.floatChannelData else { return }356        left.withUnsafeBufferPointer { data[0].update(from: $0.baseAddress!, count: left.count) }357        right.withUnsafeBufferPointer { data[1].update(from: $0.baseAddress!, count: right.count) }358        buffer.frameLength = AVAudioFrameCount(left.count)359        try file.write(from: buffer)360    }361362    // MARK: Auto DJ363364    public var autoDJStatus: AutoDJStatus { lock.withLock { autoDJ } }365    public var autoDJConfiguration: AutoDJSettings {366        get { lock.withLock { autoDJSettings } }367        set { lock.withLock { autoDJSettings = newValue } }368    }369370    /// Starts Auto DJ on a list of library tracks. Uses decks A and B; the transition is an ORIX Script run by the automation host.371    public func startAutoDJ(trackIDs: [Int64]) {372        let tracks = (try? library.tracks(ids: trackIDs)) ?? []373        let byID = Dictionary(uniqueKeysWithValues: tracks.map { ($0.id, $0) })374        let candidates = trackIDs.compactMap { byID[$0] }.map { AutoDJCandidate(id: $0.id, bpm: $0.bpm, camelot: $0.camelot) }375        let settings = autoDJConfiguration376        var ordered = AutoDJPlanner.order(candidates, settings: settings).map(\.id)377        guard !ordered.isEmpty else { return }378        let a = engine.deckStatus(0), b = engine.deckStatus(1)379        lock.lock()380        autoDJ = AutoDJStatus(); autoDJ.enabled = true; autoDJ.state = "Starting"381        autoDJRun = nil382        lock.unlock()383        if a.playing || b.playing {384            // Keep what is playing; the queue feeds the other deck.385            let current = a.playing ? 0 : 1386            lock.withLock { autoDJ.currentDeck = current; autoDJ.queue = ordered; autoDJ.state = "Playing" }387            prepareNext()388        } else {389            let first = ordered.removeFirst()390            lock.withLock { autoDJ.queue = ordered; autoDJ.currentDeck = 0 }391            load(trackID: first, deck: 0) { [weak self] result in392                guard let self else { return }393                if case .success = result { _ = self.engine.play(deck: 0); self.lock.withLock { self.autoDJ.state = "Playing" }; self.prepareNext() }394                else { self.stopAutoDJ(reason: "Could not load the first track") }395            }396        }397        let t = DispatchSource.makeTimerSource(queue: analysisQueue)398        t.schedule(deadline: .now() + .milliseconds(250), repeating: .milliseconds(250))399        t.setEventHandler { [weak self] in self?.autoDJTick() }400        t.resume()401        lock.withLock { autoDJTimer?.cancel(); autoDJTimer = t }402        onChange?()403    }404405    public func stopAutoDJ(reason: String = "Off") {406        lock.lock()407        autoDJTimer?.cancel(); autoDJTimer = nil408        let run = autoDJRun; autoDJRun = nil409        autoDJ.enabled = false; autoDJ.state = reason410        lock.unlock()411        if let run { host.stop(run: run) }412        onChange?()413    }414415    private func prepareNext() {416        lock.lock()417        guard autoDJ.enabled, let current = autoDJ.currentDeck, !autoDJ.queue.isEmpty else { lock.unlock(); return }418        let next = autoDJ.queue.removeFirst()419        lock.unlock()420        let other = 1 - current421        if engine.deckStatus(other).playing { engine.pause(deck: other) }422        load(trackID: next, deck: other) { [weak self] result in423            guard let self else { return }424            if case let .success(info) = result { self.lock.withLock { self.autoDJ.nextTitle = info.title } }425            else { self.prepareNext() } // skip unreadable tracks426        }427    }428429    /// Auto DJ step (4 times per second). Public so tests can drive it without waiting for the timer.430    public func autoDJTick() {431        lock.lock()432        guard autoDJ.enabled, let current = autoDJ.currentDeck else { lock.unlock(); return }433        let run = autoDJRun434        let settings = autoDJSettings435        lock.unlock()436        let other = 1 - current437        let cur = engine.deckStatus(current), nxt = engine.deckStatus(other)438        if let run {439            // A transition is in progress: wait for its script to finish.440            if host.activeRuns.contains(where: { $0.id == run }) { return }441            lock.withLock { autoDJRun = nil; autoDJ.currentDeck = other; autoDJ.transitions += 1; autoDJ.state = "Playing"; autoDJ.nextTitle = "" }442            persistCues(deck: current)443            prepareNext()444            onChange?()445            return446        }447        guard cur.playing else {448            // The current track ended (or was stopped) before a transition could run.449            if nxt.track != nil, !nxt.playing, loadProgress[other] == nil { _ = engine.play(deck: other); lock.withLock { autoDJ.currentDeck = other; autoDJ.state = "Playing" }; prepareNext() }450            else if nxt.track == nil, lock.withLock({ autoDJ.queue.isEmpty }), loadProgress.isEmpty { stopAutoDJ(reason: "Queue finished") }451            return452        }453        guard nxt.track != nil, !nxt.playing, loadProgress[other] == nil else { return }454        let lead = AutoDJPlanner.leadSeconds(settings: settings, bpm: cur.bpm > 0 ? cur.bpm : engine.clock.bpm)455        guard cur.remaining / max(0.5, cur.rate) <= lead else { return }456        let source = AutoDJPlanner.transitionScript(from: deckLetters[current], to: deckLetters[other], settings: settings)457        let compiled = ScriptCompiler.compile(source)458        guard let program = compiled.program, let id = host.start(program, origin: "auto-dj") else {459            stopAutoDJ(reason: "Transition script rejected: \(compiled.errors.first?.message ?? "unknown error")")460            return461        }462        lock.withLock { autoDJRun = id; autoDJ.lastScript = source; autoDJ.state = "Mixing \(deckLetters[current]) → \(deckLetters[other])" }463        onChange?()464    }465}466
Files main
Menu

Theme