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