SPB Git

Repository Public

MIDIMapping.swift 7.1 KB 177 lines swift

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

Theme