Media File Activation#

Screenbox supports two distinct activation paths for opening media files: in-app activation (file picker, library browsing, drag-and-drop) and external file association activation (double-clicking a file in File Explorer). Both paths converge on the same message-driven queue pipeline but differ in their entry point, timing constraints, and the extra metadata attached to the activation.

Activation Entry Points#

External File Association (File Explorer / OS shell)#

When a file is opened externally, the OS invokes App.OnFileActivated. The override:

1. Records a Sentry breadcrumb with PreviousExecutionState 1.
2. Initialises or reuses the root frame and navigates to MainPage if needed 2.
3. Sends a PlayFilesMessage carrying both args.Files and args.NeighboringFilesQuery — the shell-supplied query that lets the player enumerate sibling files in the same folder 3.

Multi-instance handling runs before OnFileActivated in Program.Main. When the UseMultipleInstances setting is on and the activation kind is File, a new app instance is registered; otherwise the activation is redirected to an existing instance 4. Xbox always reuses a single instance 5.

Important: OnFileActivated does not call LibVLCSharp.Shared.Core.Initialize() — that only happens in OnLaunched 6. For externally activated instances, LibVLC is already initialized because the instance was either new (launch precedes activation) or redirected to a running one.

In-App Activation#

In-app file opens send a PlayMediaMessage (for single items, URIs, or existing queue items) or a PlayFilesMessage (for multi-file selections). Examples:

• File picker (CommonViewModel.OpenFilesAsync): picks files then sends PlayMediaMessage(files) 7.
• Drag-and-drop (PlayerPageViewModel.OnDropAsync): sends PlayFilesMessage(items) for storage items, or PlayMediaMessage(uri) for web links 8.

Queue Pipeline and Timing#

PlayQueueCoordinator is the sole handler for both message types.

PlayFilesMessage → ProcessPlayFilesAsync#

Receive(PlayFilesMessage) immediately calls ProcessPlayFilesAsync. If MediaPlayer is null at the time of receipt (a race that can occur on first external launch before the player view is ready), the message is stored in _delayPlay and replayed when the player becomes available 9 10.

ProcessPlayFilesAsync follows a two-phase approach:

1. Immediate playback: ParseAndPlayAsync creates a MediaViewModel, starts playback, then parses the full media list (useful when the file is a playlist) 11.
2. Neighboring-file enqueue: If exactly one file was opened and EnqueueAllFilesInFolder is enabled, sibling files are fetched and added to the queue. When the shell provided NeighboringFilesQuery, that is used directly; otherwise one is obtained via IFilesService.GetNeighboringFilesQueryAsync 12.

PlayMediaMessage → ParseAndPlayAsync#

Receive(PlayMediaMessage) either plays an item already in the queue (Existing: true) or clears the queue and calls ParseAndPlayAsync. The same deferred-player guard applies here 13.

MediaViewModel Lifecycle#

A MediaViewModel wraps a StorageFile, Uri, or Media object. The PlaybackItem it exposes is a Lazy<T> — it is not created until first access, which happens when the coordinator assigns it to MediaPlayer.PlaybackItem 14.

After QueueCurrentItemChangedMessage is broadcast, PlayerPageViewModel fires two async loads:

1. LoadDetailsAsync – reads MusicProperties/VideoProperties from the StorageFile and optionally enriches from LibVLC metadata once the media is parsed 15.
2. LoadThumbnailAsync – loads artwork then updates the Thumbnail property 16.

Thumbnail / Cover Art Extraction#

LoadThumbnailAsync tries two sources in order:

1. Tag-embedded cover art (GetCoverFromTagAsync): Opens the file stream, reads via TagLib# (ReadStyle.PictureLazy), and prefers FrontCover or Media picture types. All exceptions (FileNotFoundException, UnsupportedFormatException, CorruptFileException) are silently swallowed; the method returns null on any failure 17.

2. Shell thumbnail (GetStorageFileThumbnailAsync): Falls back to StorageFile.GetThumbnailAsync(ThumbnailMode.SingleItem). Only ThumbnailType.Image results are used. Exceptions (e.g. 0x8000000A – data not yet available; 0x800706BA – RPC server unavailable) are silently swallowed 18.

3. LibVLC ArtworkURL: If the source is not a StorageFile and the PlaybackItem has been created with a parsed Media, the MetadataType.ArtworkURL value is used to construct a BitmapImage directly 19.

If all three sources fail, Thumbnail stays null — no error is surfaced to the user. Callers should treat a null thumbnail as normal. Thumbnail bitmaps are stored as WeakReference<BitmapImage> to allow GC under memory pressure 20.

The coordinator also maintains a thumbnail pre-buffer: UpdateMediaBufferAsync is called whenever the current item changes and pre-loads thumbnails for items adjacent to the current position, releasing thumbnails for items that scroll out of the buffer window.

Media Load Failure Handling#

Failures during PlaybackItem creation send a MediaLoadFailedNotificationMessage with a Reason and Path 21. NotificationViewModel.Receive formats these into an in-app error toast 22. On playback start, OnMediaFailed marks the current item IsAvailable = false 23. If loading succeeds and playback begins, IsAvailable is flipped back to true 24.