Nova is a local-first personal media experience for iPhone, iPad, and Apple TV. It combines a user’s own libraries and sources with discovery, metadata, playback, progress, profiles, optional tracking services, and private backup in a native SwiftUI interface.
Current app version: 1.7. The project targets iOS/iPadOS 26 and tvOS 26, with separate app schemes plus an iOS widget extension.
Nova does not provide media or access to third-party content. Users are responsible for the sources they configure and for having permission to access and play them.
The approved Nova icon source is Nova/Resources/Brand/Nova-AppIcon-Pastel-Master.png. Regenerate every iOS and tvOS icon and Top Shelf variant together with:
python3 -m pip install -r requirements-brand-assets.txt
python3 generate_brand_assets.py Nova/Resources/Brand/Nova-AppIcon-Pastel-Master.pngThe compatibility command swift generate_brand_assets.swift <source.png> invokes the same generator.
- Home, Discover, Library, AI, and Settings destinations with iPhone tabs, an iPad sidebar, and an Apple TV floating navigation menu
- Personal library, collections, favorites, history, watchlist, continue watching, duplicates, quality checks, and metadata correction
- Catalog browsing through user-installed add-ons, people/title detail, recommendations, airing information, and personalized shelves
- Search cleanup/correction, title rules, metadata parsing, library enrichment, and optional AI-assisted search/filtering
- Compact AI task picker with multiline prompts and previewable multi-collection generation
- Press Back on a main page, or select its heading, to open the floating Remote / Home / Search / Library / Settings menu. Back closes the menu; detail screens keep native Back navigation. Ask Nova remains available from Search's browsing menu.
- Home presents real artwork, title artwork with a text fallback, metadata, Play/Resume and queue/detail controls, page indicators, and landscape Continue Watching cards.
- Library puts genre, type, and sort menus above six columns of 2:3 posters, with the actual matching item count. Genres come from cached title details; Library options retain collections, watch stats, sources, folders, categories, and editing actions.
- Settings uses horizontal category tabs and panels, with neutral white focus styling shared across the television interface. iPhone and iPad retain their existing layout and blue accent styling.
- iCloud settings show actual local counts and available mirror status, request manual Push/Pull, and preview URL snapshots before importing selected categories. Separate history, addon, preference, and Library resets offer device-only or device-and-iCloud scope. Device-only resets pause the affected sync until an explicit Push/Pull; media files and account credentials remain separate.
- Glow controls adjust the shared focus highlight. Player, subtitles, Auto-Play, Regex, Search, cache, and accessibility panels retain their working settings and maintenance actions.
Settings connects its named categories to Nova's existing features: MDBList guidance points to catalog addons, Trakt guidance points to portable import into Nova Tracker, and Web Management previews a private Nova snapshot before importing selected contents. Web Management does not run an HTTP server on the Apple TV.
- SMB shares, direct URLs, Live TV/EPG sources, magnet/source resolution, and user-installed Stremio-compatible add-ons
- Source ranking, filtering, health history, retry, network-condition monitoring, and failure explanations
- Native and VLCKit playback paths, subtitle discovery/matching, subtitle picker, playback gestures, skip segments, and binge settings
- Progress, now playing, watch statistics, show settings, player memory, and Spotlight indexing
- Optional TMDB, TMDB account, OMDb, Simkl, OpenSubtitles, Real-Debrid, and compatible add-on integrations
- Local Trakt export ZIP import into Nova Tracker, without Trakt OAuth, credentials, or live API access
- Keychain-backed secrets/tokens and provider-specific connection flows
- Local Codable stores and caches, offline catalog cache, download manager, and cleanup tools
- iCloud configuration backup plus portable
.novabackup/restore snapshots - Nova Tracker/shared-history support and encrypted one-time share storage through the Unified Worker
- Shared iOS/tvOS code with platform-specific navigation and playback behavior
- iOS widgets, changelog, setup checklist, guest/safe modes, diagnostics, privacy/legal disclosure, and internal QA reporting
- Registration and configuration guards that catch unregistered Swift sources and bundle-identifier drift
| Area | Key implementation |
|---|---|
| App lifecycle/environment | Nova/App/NovaApp.swift, Nova/App/AppEnvironment.swift |
| Adaptive navigation | Nova/Views/RootView.swift |
| Library and metadata | Nova/Services/LibraryStore.swift, Nova/Services/LibraryEnricher.swift, Nova/Views/Library/ |
| Catalog and add-ons | Nova/Services/AddonStore.swift, Nova/Services/StremioAddonClient.swift, Nova/Views/Catalog/ |
| Sources and playback | Nova/Services/StreamResolver.swift, Nova/Services/PlaybackCoordinator.swift, Nova/Views/Player/ |
| Provider integrations | Nova/Services/Tracking/, Nova/Services/*Client.swift, Nova/Services/KeychainStore.swift |
| Backup, sync, offline | Nova/Services/BackupManager.swift, Nova/Services/CloudSync.swift, Nova/Services/OfflineCatalogCache.swift |
| Widgets and tests | NovaWidgets/, Tests/ |
The app is local-first: provider outages should not corrupt the library, erase progress, or prevent playback of an otherwise reachable personal source. External metadata and tracking are enrichments, not the system of record for local data.
- macOS with Xcode
- iOS 26 and tvOS 26 SDKs for both schemes
- An Apple development team for physical-device and Apple TV installation
- Network access to any user-configured servers/providers
- Optional Unified Worker access for AI and sharing functions
VLCKit and SMB dependencies are resolved through Swift Package Manager and can consume significant DerivedData space. Prefer a physical-device workflow and place DerivedData on an external drive when local storage is constrained.
git clone https://github.com/sahmoee/Nova.git
cd Nova
open Nova.xcodeprojSelect Nova-iOS or Nova-tvOS, configure signing, and run on the corresponding connected device.
Generic iOS device build:
xcodebuild \
-project Nova.xcodeproj \
-scheme Nova-iOS \
-destination 'generic/platform=iOS' \
-skipPackagePluginValidation \
CODE_SIGNING_ALLOWED=NO \
clean buildGeneric tvOS device build:
xcodebuild \
-project Nova.xcodeproj \
-scheme Nova-tvOS \
-destination 'generic/platform=tvOS' \
-skipPackagePluginValidation \
CODE_SIGNING_ALLOWED=NO \
clean buildThe tvOS SDK must be installed in Xcode. A missing tvOS platform is a local toolchain issue, not an application compile failure.
Most provider credentials are entered in-app under Settings and stored through Keychain-backed services. NovaConfig.example.json documents the optional fallback file format; rename it to NovaConfig.json and place it in the app’s Documents directory or bundle it only for a controlled build.
| Value | Purpose | Notes |
|---|---|---|
tmdbApiKey |
TMDB metadata | Optional |
openSubtitlesApiKey |
Subtitle lookup | Optional |
aiWorkerUrl |
AI/search Worker override | Prefer the unified route |
novaTrackerBaseUrl |
Tracker endpoint override | Optional |
addonManifestURLs |
Initial user-configured add-ons | Only trusted HTTPS manifests |
Additional integrations—including OMDb, Simkl, TMDB account, Real-Debrid, SMB credentials, and Live TV sources—are configured in-app. Do not commit credentials, account exports, share URLs, or personal server addresses.
To migrate existing Trakt data without reconnecting Trakt, export it as a ZIP and open Settings → Accounts → Nova Tracker → Import Trakt Data ZIP. Nova reads supported JSON and CSV files on-device, shows a preview, skips rows without a portable IMDb/TMDB identity, merges duplicates, and sends only the confirmed normalized results to Nova Tracker. The original archive is never uploaded.
The production unified route is https://api.sowensstudios.com/nova. Server-side AI keys and optional shared tokens belong in Cloudflare secrets; see the Worker’s SECRETS.md.
Run repository guards before building:
./validate_nova_config.sh
./bundleid-guard.sh
./verify_registration.sh
plutil -lint Nova.xcodeproj/project.pbxprojTests/ covers parser behavior, disk caches, backup compatibility, add-on security, Worker configuration, and stream filtering. Hosted CI dynamically selects an available iPhone simulator, tests iOS, and builds tvOS. Local simulator builds/tests require user authorization; reuse approval already granted for the current scope. Simulator validation for the tvOS reference redesign was approved on September 8, 2026, for that pass only. Record build/test results and manual visual/focus checks separately; approval alone is not a successful test result.
When adding a Swift file, ensure it is registered in every intended target. Shared code may require both iOS and tvOS source build phases; verify_registration.sh checks this explicitly.
- Add-ons and source resolvers must be user-configured, transparent, removable, and failure-isolated.
- Media interoperability is data-only: iOS may import portable NFO metadata and M3U playlists, discover UPnP/DLNA devices, and use signed declarative providers. Third-party modules and binaries must never be executed inside Nova.
- Nova must not bundle unauthorized catalogs, credentials, decryption material, or copyrighted media.
- Metadata providers may have attribution, image, caching, and rate-limit requirements; follow each provider’s current terms.
- Real-Debrid and tracking providers are optional user accounts and must fail without breaking local playback/library features.
- SMB secrets and provider tokens must remain in protected local storage and be excluded from logs, tickets, backups where inappropriate, and screenshots.
Nova iOS includes an internal QA queue. Reports save locally before network work, then synchronize through the Unified Worker with device/build context and optional screenshots. Fixed tickets require a “What was fixed” explanation; testers use Verify Fix or Refile — still broken.
Report synchronization is an internal development operation and is intentionally not documented in the public repository. In-app diagnostics and support surfaces include Nova/Views/Settings/DebugReportView.swift, safe mode, source health, network status, library health, and backup tools.
- Update
CHANGELOG.md,APP_STORE_METADATA.md, and in-app What’s New content. - Increment iOS, tvOS, test, and widget versions/build numbers consistently.
- Run all configuration/registration guards, tests, and both affected platform builds.
- Verify real-device playback, SMB, subtitles, downloads, background/now-playing behavior, add-ons, metadata, backup/restore, provider sign-in, offline mode, and iPad/tvOS navigation.
- Review
PRIVACY.md,SECURITY.md,THIRD_PARTY_NOTICES.md, and personal-media disclosure. - Archive each platform with Xcode and use TestFlight for distribution testing.
- Build consumes too much disk: move DerivedData to an external drive and remove only known disposable build directories; do not delete the workspace.
- Package resolution/VLCKit fails: verify network access, resolved package versions, and sufficient disk space.
- A Swift file appears ignored: run
./verify_registration.shand inspect both platform source phases. - No playable source: inspect source health, resolver/filter output, network state, provider/add-on configuration, and
PlaybackFailureReason. - Metadata is wrong: use Fix Match or cleanup rules, then refresh/enrich the affected item.
- tvOS will not build locally: install the matching tvOS platform in Xcode and select the
Nova-tvOSscheme. - Backup restore is rejected: retain the original backup and inspect compatibility validation before modifying migration logic.
See SECURITY.md, PRIVACY.md, SUPPORT.md, LICENSE.md, and THIRD_PARTY_NOTICES.md. Apple privacy guidance is available at developer.apple.com/app-store/user-privacy-and-data-use.
CONTRIBUTING.md— contribution processdocs/NOVA_RENAME_COMPATIBILITY.md— naming and compatibility constraints
Preserve persisted-data and backup compatibility, keep shared iOS/tvOS behavior deliberate, add regression tests, avoid unsafe provider assumptions, and update all clients when a shared Worker contract changes.
On iPhone and iPad, open Addons → Media Tools for UPnP/DLNA discovery, NFO import/export, locally evaluated smart playlists, and signed/checksummed declarative providers. Provider traffic is limited to allow-listed HTTPS hosts; Nova does not execute repository code.