Repository Public
1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXMIDI/MIDIMapping.swift3// Description: Control identity, mapping description and the target events a mapping produces.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai78import Foundation910/// Identifies one physical control on a controller, independently of its current value.11/// Note-on and note-off of the same key share one identity.12public struct MIDIControlID: Hashable, Codable, Sendable {13 public enum Kind: String, Codable, Sendable {14 case note15 case controlChange = "cc"16 case pitchBend17 }1819 public var kind: Kind20 /// Zero-based MIDI channel, `0...15`.21 public var channel: UInt822 /// Note number or controller number; always 0 for pitch bend.23 public var number: UInt82425 public init(kind: Kind, channel: UInt8, number: UInt8) {26 self.kind = kind27 self.channel = channel28 self.number = kind == .pitchBend ? 0 : number29 }3031 /// The control a message comes from; `nil` for program change (not mappable).32 public init?(message: MIDIMessage) {33 switch message {34 case .noteOn(let c, let n, _), .noteOff(let c, let n, _):35 self.init(kind: .note, channel: c, number: n)36 case .controlChange(let c, let n, _):37 self.init(kind: .controlChange, channel: c, number: n)38 case .pitchBend(let c, _):39 self.init(kind: .pitchBend, channel: c, number: 0)40 case .programChange:41 return nil42 }43 }4445 public static func note(channel: UInt8, note: UInt8) -> MIDIControlID {46 MIDIControlID(kind: .note, channel: channel, number: note)47 }4849 public static func cc(channel: UInt8, controller: UInt8) -> MIDIControlID {50 MIDIControlID(kind: .controlChange, channel: channel, number: controller)51 }5253 public static func pitchBend(channel: UInt8) -> MIDIControlID {54 MIDIControlID(kind: .pitchBend, channel: channel, number: 0)55 }56}5758/// How a control's messages are interpreted.59public enum MIDIMappingMode: String, Codable, Sendable, CaseIterable {60 /// Fader/knob: 7-bit (CC, note velocity) or 14-bit (pitch bend) position scaled to `minValue...maxValue`.61 case absolute62 /// Endless encoder (CC only): each message is a signed step added to the current value.63 case relative64 /// Button: emits `.toggle` on press; the app flips its own state.65 case toggle66 /// Button: emits `.trigger` on press.67 case trigger68 /// Button: emits `.momentary(pressed:)` on press and on release.69 case momentary70}7172/// How a relative encoder encodes its step in the 7-bit CC value.73public enum MIDIRelativeEncoding: String, Codable, Sendable, CaseIterable {74 /// `1...63` = +1...+63, `127...65` = -1...-63, `64` = -64, `0` = no movement.75 case twosComplement76 /// Bit 6 is the sign: `0x01...0x3F` = +1...+63, `0x41...0x7F` = -1...-63. `0x00`/`0x40` = no movement.77 case signedBit78 /// `64` = no movement, `65...127` = +1...+63, `63...0` = -1...-64.79 case binaryOffset8081 /// Signed number of encoder steps for a CC value.82 public func delta(for value: UInt8) -> Int {83 let v = Int(value & 0x7F)84 switch self {85 case .twosComplement: return v < 64 ? v : v - 12886 case .signedBit: return v & 0x40 == 0 ? v : -(v & 0x3F)87 case .binaryOffset: return v - 6488 }89 }90}9192/// Binds one physical control to one app-owned target.93public struct MIDIMapping: Codable, Sendable, Identifiable, Equatable {94 public var id: UUID95 public var control: MIDIControlID96 /// Restricts the mapping to one device (`MIDIDeviceInfo.uniqueID`); `nil` matches any device.97 public var deviceUniqueID: Int32?98 /// Opaque identifier owned by the app, e.g. `"deck.A.play"` or `"mixer.crossfader"`.99 public var target: String100 public var mode: MIDIMappingMode101 /// Used only by `.relative`.102 public var relativeEncoding: MIDIRelativeEncoding103 /// Used only by `.relative`: one encoder step moves the normalised value by `sensitivity / 127`.104 public var sensitivity: Double105 /// Output for the control's lowest position (normalised, `0...1`). May exceed `maxValue` to reverse the range.106 public var minValue: Double107 /// Output for the control's highest position (normalised, `0...1`).108 public var maxValue: Double109 /// Absolute: mirrors the control. Relative: reverses direction. Buttons: press and release are swapped.110 public var invert: Bool111 /// Absolute CC / pitch bend only: no output until the hardware position reaches or crosses the current112 /// software value (as returned by the engine's current-value closure).113 public var softTakeover: Bool114115 public init(116 id: UUID = UUID(),117 control: MIDIControlID,118 deviceUniqueID: Int32? = nil,119 target: String,120 mode: MIDIMappingMode,121 relativeEncoding: MIDIRelativeEncoding = .twosComplement,122 sensitivity: Double = 1,123 minValue: Double = 0,124 maxValue: Double = 1,125 invert: Bool = false,126 softTakeover: Bool = false127 ) {128 self.id = id129 self.control = control130 self.deviceUniqueID = deviceUniqueID131 self.target = target132 self.mode = mode133 self.relativeEncoding = relativeEncoding134 self.sensitivity = sensitivity135 self.minValue = minValue136 self.maxValue = maxValue137 self.invert = invert138 self.softTakeover = softTakeover139 }140141 private enum CodingKeys: String, CodingKey {142 case id, control, deviceUniqueID, target, mode, relativeEncoding, sensitivity, minValue, maxValue, invert, softTakeover143 }144145 /// Tolerant decoding: everything except `control`, `target` and `mode` is optional, so hand-written146 /// profiles stay short.147 public init(from decoder: Decoder) throws {148 let c = try decoder.container(keyedBy: CodingKeys.self)149 id = try c.decodeIfPresent(UUID.self, forKey: .id) ?? UUID()150 control = try c.decode(MIDIControlID.self, forKey: .control)151 deviceUniqueID = try c.decodeIfPresent(Int32.self, forKey: .deviceUniqueID)152 target = try c.decode(String.self, forKey: .target)153 mode = try c.decode(MIDIMappingMode.self, forKey: .mode)154 relativeEncoding = try c.decodeIfPresent(MIDIRelativeEncoding.self, forKey: .relativeEncoding) ?? .twosComplement155 sensitivity = try c.decodeIfPresent(Double.self, forKey: .sensitivity) ?? 1156 minValue = try c.decodeIfPresent(Double.self, forKey: .minValue) ?? 0157 maxValue = try c.decodeIfPresent(Double.self, forKey: .maxValue) ?? 1158 invert = try c.decodeIfPresent(Bool.self, forKey: .invert) ?? false159 softTakeover = try c.decodeIfPresent(Bool.self, forKey: .softTakeover) ?? false160 }161}162163/// What a mapping asks the app to do.164public enum MIDITargetEvent: Sendable, Equatable {165 /// New normalised value (`0...1`) from an absolute or relative control.166 case value(target: String, normalized: Double)167 case trigger(target: String)168 case toggle(target: String)169 case momentary(target: String, pressed: Bool)170171 public var target: String {172 switch self {173 case .value(let t, _), .trigger(let t), .toggle(let t), .momentary(let t, _): return t174 }175 }176}177