CrystalSpace plays local video wallpapers, maintains an offline library, and can browse compatible remote catalogues such as Wallspace through an isolated provider layer. It is built in Swift and uses SwiftUI, AppKit, AVFoundation, SQLite, and supported macOS services where possible.
The project contains no AI features, analytics, telemetry, advertising, or mandatory account system.
Important
CrystalSpace is under active development. Desktop video wallpaper support is functional. Lock Screen animation uses an isolated, reversible experimental integration because macOS does not provide a public animated Lock Screen setter API. Read Docs/LockScreen.md before enabling it.
- Hardware-accelerated, muted video wallpapers through AVFoundation.
- Independent wallpaper sessions for multiple displays.
- Local video import and durable offline playback.
- Downloads with validation, progress, cancellation, and deduplication.
- Favorites and deterministic sequential or shuffled playlists.
- Display, Space, sleep/wake, battery, and thermal-state handling.
- Searchable and filterable multi-source catalogue.
- Wallspace-compatible provider with DTO/domain isolation.
- Native SwiftUI and AppKit interface with modern macOS materials.
- Launch at login through ServiceManagement.
- Native Icon Composer application icon and reproducible DMG build chain.
- macOS 15 or later.
- Xcode 26 command-line tools.
- Swift 6.2 or later.
Some optional appearance and Lock Screen functionality requires newer macOS versions. Unsupported optional integrations fail without disabling desktop wallpapers.
git clone https://github.com/DrapNard/CrystalSpace.git
cd CrystalSpace
swift test
./Scripts/build-app.sh
open build/CrystalSpace.appThe default command creates an ad-hoc-signed direct build. To produce a signed DMG:
./Scripts/build-dmg.sh \
release \
direct \
"Developer ID Application: Your Name (TEAMID)"See Docs/BUILDING.md for sandboxing, signing, notarization, and CI release instructions.
UI
↓
Features / AppState
↓
Repositories and services
↓
Domain models and persistence
↓
Providers / downloads / wallpaper engine / system integrations
Important boundaries:
- Wallspace-specific code lives under
CrystalSpace/Providers/WallSpace. - Remote DTOs are mapped into provider-independent CrystalSpace models.
- The wallpaper engine only receives validated local media.
- Desktop and experimental Lock Screen integrations have separate failure paths.
- Durable user data and disposable cache data use separate storage.
Wallspace is an external product and is not affiliated with CrystalSpace. CrystalSpace only implements behavior verified from public or user-authorized resources. It does not invent endpoints, bypass Wallspace Pro, defeat access controls, or expose Wallspace AI functionality.
Verified and unknown API behavior is documented in Docs/WallSpace/API-Research.md.
CrystalSpace:
- performs no analytics or telemetry;
- contains no remote crash reporter;
- contains no AI or machine-learning integration;
- does not create advertising or tracking identifiers;
- stores local preferences and library state on the Mac;
- keeps persistent secrets in Keychain when a feature requires them;
- does not log credentials, authorization headers, or private signed URLs.
Please report vulnerabilities privately according to SECURITY.md.
- Product specification
- Development rules
- Wallspace API specification
- Implementation progress
- Build and release guide
- Lock Screen notes
- Third-party notices
Contributions are welcome when they preserve CrystalSpace’s native, privacy-first architecture. Read CONTRIBUTING.md before opening a pull request. Participation is governed by the Code of Conduct.
CrystalSpace is available under the MIT License. Third-party components retain the licenses documented in Docs/ThirdPartyNotices.md.