Storage Library Permissions#

Screenbox accesses the Windows MusicLibrary and VideosLibrary KnownFolders at startup and re-checks access whenever the coordinator re-initializes watchers. Because UWP apps require explicit user consent for these folders, the codebase has a structured flow for requesting access, detecting denial, and surfacing a user-facing error notification.

Key Components#

All of these are registered in ServiceHelpers.PopulateCoreServices — ILibraryCoordinator and ILibraryService as singletons, and LibraryContext as a singleton shared state container.

Startup Sequence#

On app launch, App.OnLaunched fires StartupInitAsync() (database initialization only), and then the UI layer calls MainPageViewModel.FetchLibraries(). The sequence inside FetchLibraries is:

1. EnsureWatchingAsync() — called first; wrapped in its own try/catch so a failure here does not block library fetching 1.
2. Concurrent fetch — FetchMusicLibraryAsync(), FetchVideosLibraryAsync(), and FetchPlaylistsAsync() run in parallel via Task.WhenAll 2.
3. Second playlist fetch — after libraries complete, playlists are re-fetched so playlist items can reference the now-loaded library media 3.

Permission Check in LibraryCoordinator#

EnsureWatchingMusicAsync and EnsureWatchingVideosAsync each:

1. Lazily initialize the StorageLibrary via LibraryService.InitializeMusicLibraryAsync() / InitializeVideosLibraryAsync(), which call StorageLibrary.GetLibraryAsync and enable the ChangeTracker.
2. Call KnownFolders.RequestAccessAsync(KnownFolderId.MusicLibrary) / KnownFolderId.VideosLibrary.
3. Only create and register the StorageFileQueryResult watcher if the result is Allowed or AllowedPerAppFolder 4 5. If access is denied, no query watcher is created and FetchMusicAsync/FetchVideosAsync will be no-ops (they guard on _musicQuery is null) 6 7.

On Xbox, removable storage access (KnownFolderId.RemovableDevices) follows the same RequestAccessAsync pattern inside FetchMusicAsync/FetchVideosAsync 8.

Unauthorized Access Error Handling#

FetchMusicLibraryAsync and FetchVideosLibraryAsync in MainPageViewModel each wrap the coordinator fetch call in a specific handler 9:

catch (UnauthorizedAccessException)
{
    Messenger.Send(new RaiseLibraryAccessDeniedNotificationMessage(KnownLibraryId.Music /* or Videos */));
}

The same pattern appears in SettingsPageViewModel for library refreshes triggered from the settings page.

NotificationViewModel.Receive(RaiseLibraryAccessDeniedNotificationMessage) handles the message 10:

• Selects a localized title (AccessDeniedMusicLibraryTitle / AccessDeniedVideosLibraryTitle).
• Sets the deep-link URI to ms-settings:privacy-musiclibrary or ms-settings:privacy-videos.
• Displays an error-level notification with an "Open Privacy Settings" action button that launches the URI.
• Auto-dismisses after 15 seconds 11.

Note: KnownLibraryId.Documents access denial is silently ignored — Receive returns early without showing a notification 12.

Change Tracking & Cache Invalidation#

LibraryService uses StorageLibrary.ChangeTracker to avoid full re-scans on subsequent launches. The cache (SQLite via IDatabaseService) stores folder paths alongside media records; if the library's folder set changes, the cache is invalidated and a full scan runs 13. Content changes (file added, removed, renamed) are reconciled incrementally via TryResolveLibraryBatchChangeAsync.

Watcher ContentsChanged events from StorageFileQueryResult are debounced at 1 second before triggering a re-fetch 14 15.