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.

Luminous

master

Luminous

Requirements

Installation

Swift Package Manager

Usage

@MainActor properties

API Reference

Luminous.Application

Luminous.Audio

Luminous.Battery — @MainActor

Luminous.Disk

Luminous.Hardware

Luminous.Hardware.Screen — @MainActor

Luminous.Hardware.Device — @MainActor

Luminous.Locale

Luminous.Network

OperatingSystemVersion — Comparable

Migrating from v2

Removed (no replacement)

Renamed / Moved

Replaced

New in v3

Author

License

Description

Dependencies

`@MainActor` properties

`Luminous.Application`

`Luminous.Audio`

`Luminous.Battery` — `@MainActor`

`Luminous.Disk`

`Luminous.Hardware`

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

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

`Luminous.Locale`

`Luminous.Network`

`OperatingSystemVersion` — `Comparable`