Media Library Change Tracking#

Overview#

Screenbox uses the Windows StorageLibrary.ChangeTracker API to avoid full re-scans on every launch. When a valid cache exists and the library's folder composition hasn't changed, only the delta of file-level changes (additions, deletions, renames, content updates) is applied against the cached media list. The key components are:

• LibraryService — orchestrates change detection and cache reconciliation 1
• DatabaseService.LibraryCache — persists and loads library folder paths and media records 2
• DatabaseService.Schema — defines library_folders and media_records tables 3

How Change Tracking Works#

Initialization#

Both InitializeMusicLibraryAsync and InitializeVideosLibraryAsync call StorageLibrary.GetLibraryAsync and then library.ChangeTracker.Enable(). Exceptions from Enable() are silently swallowed so the app degrades gracefully if the platform doesn't support the API.

Cache Validation — Folder Path Check#

On each fetch (FetchMusicAsync / FetchVideosAsync), the cache is considered stale if the current library folder set doesn't match what was saved. AreLibraryPathsChanged compares the count and paths of library.Folders against the persisted library_folders rows. Any mismatch forces a full rescan instead of incremental reconciliation.

Cache is also unconditionally disabled on Xbox (useCache = useCache && !SystemInformation.IsXbox) 4.

Incremental Change Resolution#

When the folder set is unchanged, TryResolveLibraryChangeAsync is called:

1. If GetLastChangeId() is available (Win10 1803+) and returns Unknown, the tracker has overflowed — falls back to full rescan.
2. If changeId == 0, no changes exist — cache is used as-is.
3. Otherwise, TryResolveLibraryBatchChangeAsync processes the batch.

TryResolveLibraryBatchChangeAsync iterates changeReader.ReadBatchAsync() and handles these change types in-memory:

Accepting or Resetting Changes#

After a successful incremental pass, changeReader.AcceptChangesAsync() advances the tracker's checkpoint 5. After a full rescan, libraryChangeTracker.Reset() clears all pending changes so the next launch starts fresh 6.

Cache Persistence#

DatabaseService.LibraryCache stores two kinds of data per media type:

• library_folders — one row per folder path per media type; fully replaced on each save (DELETE then INSERT) 7
• media_records — upserted with INSERT OR REPLACE keyed on path 8

LoadLibraryCacheAsync reads both tables in a single connection and returns a RawCacheLoadResultDto containing folder paths and raw media records.

Known Gap: Orphaned Records on Folder Changes#

When a folder change triggers a full rescan, media_records rows for files in the old folder set are never explicitly deleted. The save path (CacheSongsAsync / CacheVideosAsync) uses INSERT OR REPLACE, which only upserts the current scan result. Records for deleted or moved files remain in the media_records table until the path appears again or a schema drop-and-recreate occurs.

This means after a folder removal + full rescan, the media_records table may contain orphaned rows (files no longer in any library folder). These orphans are invisible at runtime — LoadLibraryCacheAsync returns all records regardless of whether their paths still exist — but they consume space and can cause unexpected behavior if path collisions occur with future additions.

External Events and Debouncing#

ContentsChanged events from StorageFileQueryResult are debounced by 1 second in LibraryCoordinator before a re-fetch is triggered. The StorageLibrary.DefinitionChanged event (folder additions/removals) is intentionally not subscribed to — the comment in InitializeMusicLibraryAsync notes "No need to add handler for StorageLibrary.DefinitionChanged" 9. Folder changes are instead detected lazily on the next fetch via AreLibraryPathsChanged.

Key Files#