Luminous

March 3, 2026 · View on GitHub

Luminous

A Swift library that gives you quick access to system information on iOS.

Requirements

iOS 17+
Swift 6.0
Xcode 16+

Installation

Swift Package Manager

In Xcode: File → Add Package Dependencies, then enter:

https://github.com/andrealufino/Luminous

Or add it directly to Package.swift:

dependencies: [
    .package(url: "https://github.com/andrealufino/Luminous", from: "3.0.0")
]

Usage

All API is accessed through static properties and methods on nested structs under the Luminous namespace. No instantiation needed.

import Luminous

// Disk
let free = Luminous.Disk.freeSpace(in: .gigabytes)
let total = Luminous.Disk.totalSpaceInBytes

// Network
if Luminous.Network.isInternetAvailable {
    let expensive = Luminous.Network.isExpensive  // true on cellular/hotspot
}

// Hardware
let cores = Luminous.Hardware.processorsNumber
let model = Luminous.Hardware.modelIdentifier   // e.g. "iPhone16,1"
let thermal = Luminous.Hardware.thermalState    // ProcessInfo.ThermalState

// OS version comparison
let current = Luminous.Hardware.systemVersion
let ios18 = OperatingSystemVersion(majorVersion: 18, minorVersion: 0, patchVersion: 0)
if current >= ios18 { ... }

// Battery — requires @MainActor
let level = await MainActor.run { Luminous.Battery.level }   // Float? (0–100)
let state = await MainActor.run { Luminous.Battery.state }   // UIDevice.BatteryState

`@MainActor` properties

Battery, Hardware.Screen, and Hardware.Device access UIKit APIs and must be called on the main actor:

// In a @MainActor context (e.g. a SwiftUI view or view controller):
let brightness = Luminous.Hardware.Screen.brightness
let style = Luminous.Hardware.Device.userInterfaceStyle  // .light / .dark

// From a non-isolated context:
let brightness = await MainActor.run { Luminous.Hardware.Screen.brightness }

API Reference

`Luminous.Application`

Property	Type	Description
`version`	`String`	`CFBundleShortVersionString` (e.g. `"3.0.0"`); `""` if absent
`build`	`String`	`CFBundleVersion` (e.g. `"42"`); `""` if absent
`completeAppVersion`	`String`	`"3.0.0 (42)"`
`bundleIdentifier`	`String?`	Bundle identifier (e.g. `"com.example.MyApp"`); `nil` if absent
`displayName`	`String`	User-visible app name; `""` if absent

`Luminous.Audio`

Property	Type	Description
`currentAudioOutputVolume`	`Float?`	0.0–1.0; does not activate the audio session
`secondaryAudioShouldBeSilencedHint`	`Bool`	Another app is playing non-mixable audio
`isWiredHeadsetPluggedIn`	`Bool`	3.5 mm / Lightning / USB-C wired headset
`isAnyHeadphoneConnected`	`Bool`	Wired, AirPods, or any Bluetooth audio device

`Luminous.Battery` — `@MainActor`

Property	Type	Description
`level`	`Float?`	0–100; `nil` in Simulator
`state`	`UIDevice.BatteryState`	`.unknown` / `.unplugged` / `.charging` / `.full`
`isCharging`	`Bool`	Convenience shorthand for `state == .charging`

`Luminous.Disk`

All size methods accept a UnitInformationStorage parameter (default: .gigabytes).

Property / Method	Type	Description
`totalSpaceInBytes`	`Int64`	Raw total capacity
`freeSpaceInBytes`	`Int64`	Available space including purgeable content
`usedSpaceInBytes`	`Int64`	Used space in bytes
`totalSpace(in:)`	`Double`	Total capacity in the given unit
`freeSpace(in:)`	`Double`	Free space in the given unit
`usedSpace(in:)`	`Double`	Used space in the given unit

let gb = Luminous.Disk.freeSpace(in: .gigabytes)
let mb = Luminous.Disk.usedSpace(in: .megabytes)

`Luminous.Hardware`

Property / Method	Type	Description
`processorsNumber`	`Int`	Total processor count
`activeProcessorsNumber`	`Int`	Active processor count
`physicalMemory(in:)`	`Double`	Physical RAM in the given unit (default `.gigabytes`)
`availableMemoryInBytes`	`Int64`	Memory available to the process
`availableMemory(in:)`	`Double`	Available memory in the given unit (default `.megabytes`)
`systemVersion`	`OperatingSystemVersion`	Comparable — use `>=`, `<`, etc.
`uptime`	`TimeInterval`	Seconds since last boot
`isLowPowerModeEnabled`	`Bool`
`thermalState`	`ProcessInfo.ThermalState`	`.nominal` / `.fair` / `.serious` / `.critical`
`modelIdentifier`	`String`	Hardware model string (e.g. `"iPhone16,1"`)
`isSimulator`	`Bool`	`true` when running in the iOS Simulator

`Luminous.Hardware.Screen` — `@MainActor`

Property	Type	Description
`brightness`	`Float`	0.0–1.0
`isScreenMirrored`	`Bool`
`isZoomed`	`Bool`	Display Zoom is active
`nativeBounds`	`CGRect`	Physical screen bounds in pixels
`nativeScale`	`Float`	Physical screen scale
`bounds`	`CGRect`	Logical screen bounds in points
`scale`	`Float`	Logical screen scale
`maximumRefreshRate`	`Int`	60, 120, etc.

`Luminous.Hardware.Device` — `@MainActor`

Property	Type	Description
`identifierForVendor`	`String?`	Vendor UUID
`name`	`String`	User-assigned device name (e.g. `"Andrea's iPhone"`)
`orientation`	`UIDeviceOrientation`	Current device orientation
`systemName`	`String`	OS name (e.g. `"iPhone OS"`)
`userInterfaceStyle`	`UIUserInterfaceStyle`	`.light` / `.dark` / `.unspecified`

`Luminous.Locale`

Property	Type	Description
`currentLanguage`	`String?`	BCP 47 code (e.g. `"en"`, `"it"`)
`currentTimeZone`	`TimeZone`	Current time zone
`currentTimeZoneName`	`String`	IANA identifier (e.g. `"Europe/Rome"`)
`currentCountry`	`String?`	ISO 3166-1 (e.g. `"US"`, `"IT"`)
`currentCurrency`	`String?`	ISO 4217 (e.g. `"USD"`, `"EUR"`)
`currentCurrencySymbol`	`String?`	e.g. `"$"`, `"€"`
`usesMetricSystem`	`Bool`
`decimalSeparator`	`String?`	`"."` or `","`

`Luminous.Network`

Property	Type	Description
`isConnectedViaWiFi`	`Bool`
`isConnectedViaCellular`	`Bool`
`isInternetAvailable`	`Bool`	Any satisfied path
`isExpensive`	`Bool`	Cellular or personal hotspot
`isConstrained`	`Bool`	Low Data Mode is active
`supportsIPv4`	`Bool`
`supportsIPv6`	`Bool`

`OperatingSystemVersion` — `Comparable`

Luminous adds retroactive Equatable and Comparable conformance to Foundation's OperatingSystemVersion, enabling direct comparison operators:

let current = Luminous.Hardware.systemVersion
let ios18 = OperatingSystemVersion(majorVersion: 18, minorVersion: 0, patchVersion: 0)

if current >= ios18 {
    // iOS 18+ code path
}

Migrating from v2

Removed (no replacement)

API	Reason
`Luminous.Carrier`	`CTCarrier` deprecated since iOS 16.1; no reliable replacement
`Luminous.Hardware.Sensors`	All sensors have returned `true` on every iPhone since 2014
`Luminous.Hardware.Accessory`	MFi-only niche API with no broad use case
`Luminous.Network.SSID`	Dead on iOS 13+ without entitlements and location access
`Luminous.Application.clipboardString`	Triggered iOS paste permission banner as a side-effect
`Luminous.Hardware.Screen.snapshotOfCurrentView`	Used deprecated `UIScreen` API, no `@MainActor` safety
CocoaPods support	SPM is the standard; use `Package.swift`

Renamed / Moved

v2	v3
`Hardware.bootTime`	`Hardware.uptime`
`Hardware.systemName`	`Hardware.Device.systemName`
`Hardware.Accessory.isHeadsetPluggedIn`	`Audio.isWiredHeadsetPluggedIn`

Replaced

v2	v3
`BatteryState` (custom enum)	`UIDevice.BatteryState` directly
`MeasureUnit` (custom enum)	`UnitInformationStorage` from Foundation
`SystemVersion` struct	`OperatingSystemVersion` + `Comparable` extension (see above)
`Disk.totalSpace(measureUnit:)`	`Disk.totalSpace(in: UnitInformationStorage)`
`Disk.freeSpace(measureUnit:)`	`Disk.freeSpace(in: UnitInformationStorage)`
`Disk.usedSpace(measureUnit:)`	`Disk.usedSpace(in: UnitInformationStorage)`
`Hardware.physicalMemory(with:)`	`Hardware.physicalMemory(in: UnitInformationStorage)`
`Audio.currentAudioOutputVolume` → `Double?`	`Audio.currentAudioOutputVolume` → `Float?` (no session activation side-effect)
Deprecated Disk string properties	Use `totalSpace(in:)` / `freeSpace(in:)` / `usedSpace(in:)`

New in v3

API	Description
`Audio.isAnyHeadphoneConnected`	Includes AirPods and all Bluetooth audio
`Hardware.thermalState`	`ProcessInfo.ThermalState` — nominal / fair / serious / critical
`Hardware.modelIdentifier`	Hardware model string, e.g. `"iPhone16,1"`
`Hardware.availableMemoryInBytes` / `availableMemory(in:)`	Memory available to the process
`Hardware.Screen.maximumRefreshRate`	60, 120, etc.
`Hardware.Device.userInterfaceStyle`	Light / dark / unspecified
`Network.isExpensive`	True on cellular or personal hotspot
`Network.isConstrained`	True when Low Data Mode is active
`Network.supportsIPv4` / `supportsIPv6`	IP protocol support on current path
`OperatingSystemVersion` Comparable	Use `>=`, `<`, `==` directly on OS version values

Author

Andrea Mario Lufino

License

Luminous is available under the MIT license. See the LICENSE file for details.