All documentation
Canvas and boards/04

Video playback and thumbnails

Free

Review video files directly on the board.

Video items let motion assets stay inside the same visual board as images, documents, and references. FenSight imports supported video files as VideoItem objects, stores duration and natural-size metadata when available, generates representative thumbnails in a dedicated backfill pass, and plays videos inline on the canvas through LibVLC rather than opening a separate review tool.

Screenshot coming soon

FenSight board with video thumbnails, a play badge, duration overlay, and one inline playing video

Screenshot placeholder. Expected production asset: /docs/screenshots/video-playback-and-thumbnails.png.

Video access paths

Menu

File -> Import Folder...

Recursively imports supported video files and schedules Phase 4 video metadata/thumbnail backfill after initial placement.

Drag/drop

Explorer -> drag videos or folders onto the canvas

Creates VideoItem objects for supported extensions and places them at the drop point before thumbnail backfill settles.

Context menu

Video item -> Play/Pause

Toggles inline playback. Double-clicking a video item uses the same playback command.

Context menu

Video item -> Generate Video Thumbnail

Forces a fresh representative-frame thumbnail for the selected video item.

Context menu

Selected videos -> Generate Video Thumbnails (N selected)

Evicts stale cached video thumbnails for the selected videos, clears their current thumbnails, then runs forced Phase 4 backfill.

Menu

File -> Rebuild Thumbnails

Runs video thumbnail repair first, then rebuilds remaining image, sequence, and document thumbnails.

Menu

View -> Video Corner Marker

Shows or hides the upper-left video marker on non-playing video items.

Menu

Settings -> Overlay -> Show video corner marker

Persists the same corner-marker preference as the View menu.

Menu

Settings -> Overlay -> Show play icon on videos

Controls the play glyph drawn over video thumbnails.

Menu

Settings -> Overlay -> Duration (video)

Shows known video duration in the item overlay text.

Supported video formats

These extensions enter the normal video ingest path and use LibVLC-backed playback. Thumbnail quality still depends on whether metadata and frame capture succeed for the specific file.

GroupExact extensionsImport behavior
PipelineSupportedVideosFree
.mp4, .mov, .avi, .mkv, .wmv, .webm, .m4v, .mpg, .mpeg, .mpe, .m2v, .m2ts, .mts, .ts, .3gp, .3g2, .flv, .f4v, .asf, .ogv, .rm, .rmvb, .vob, .divx, .xvid, .mxf, .m2p, .m1v, .dv, .mod, .tod, .tp, .trpCreates VideoItem objects. The initial item may use cached Shell metadata or a placeholder; a later video backfill pass fills natural dimensions, duration, rotation, and a representative thumbnail.
Video-icon-prone subsetFree
.mp4, .mov, .avi, .mkv, .wmv, .webm, .m4v, .mpg, .mpeg, .mpe, .m2v, .m2ts, .mts, .ts, .3gp, .3g2, .flv, .f4v, .asf, .ogv, .rm, .rmvbFenSight treats Shell thumbnails for these extensions with extra suspicion because Windows can return a generic media-player icon instead of a content frame.

Playback controls and overlays

ControlUser-facing behaviorTechnical behavior
Play/PauseFree
Starts or stops inline video playback on the board.ToggleVideoPlayback creates canvas video visuals if needed, ensures a LibVLC MediaPlayer, stops any other playing media item, seeks to the beginning, shows the VideoView, and starts the video-position timer.
Double-click videoFree
Starts or stops the video without opening the context menu.BoardInteractionController forwards double-clicks on VideoItem objects to the same ToggleVideoPlayback callback used by Play/Pause.
Play badgeFree
Shows an on-item play affordance when video play icons are enabled.EnsureVideoVisuals creates the clickable badge for video items. When playback starts, the badge is collapsed so the live video frame is unobstructed.
Inline VideoViewFree
Renders the playing video in place over the board item.FenSight hosts LibVLCSharp.WPF VideoView, an HwndHost-backed native child window. For newly created views, playback waits until the VideoView is loaded so LibVLC has a real render target.
Scrubber click-to-seekFree
Click near the bottom of a playing video to seek within it.BoardInteractionController maps the click X position to a 0-1 ratio and calls SeekMediaItem, which seeks the LibVLC MediaPlayer to that ratio of the known duration.
Video scrubber popupFree
Displays the current playback position above a playing inline video.Because WPF drawing renders below the LibVLC HwndHost, FenSight uses a transparent Popup window for the scrubber so it appears above the native video surface.
Duration (video)Free
Adds the video's duration to overlay text when duration metadata is known.BoardSurface appends formatted m:ss or h:mm:ss text when OverlayShowDuration is enabled and the VideoItem has a Duration value.
Video Corner MarkerFree
Marks video thumbnails with an upper-left corner triangle.BoardSurface draws the corner marker only when ShowVideoCornerBadge is enabled and the video is not currently showing the live VideoView.

Thumbnail and metadata pipeline

Videos are handled separately from still images because reliable thumbnails often require metadata probes, careful frame capture, and rejection of generic icons or black frames.

StepUser-facing resultTechnical behavior
Initial importFree
Adds the video to the board quickly even if the rich thumbnail is not ready yet.The ingest path creates a VideoItem with source path and provisional size. Cached thumbnails or placeholders can display first while video-specific backfill runs later.
Phase 4 video backfillFree
Updates missing video thumbnails, natural size, rotation, and duration after ingest.RunVideoBackfillPhase4Async filters videos needing metadata or thumbnails, lowers process priority, uses the shared decode arbiter's video lane, and drains results back to the UI in small batches.
NeedsVideoThumbnailFree
Decides whether a video still needs thumbnail repair.A video needs work when its thumbnail is null, placeholder/tiny, likely a generic video icon, likely black, or smaller than the minimum sizing threshold.
Forced regenerationFree
Replaces stale or bad thumbnails on selected video items.Generate Video Thumbnail(s) evicts the media-cache video-thumb entry, clears the item thumbnail, marks the item Placeholder, then runs Phase 4 with force: true.
Representative seek pointFree
Avoids using a black intro frame when regenerating thumbnails.Forced Phase 4 seeks to the midpoint of known duration, or falls back to 3 seconds when duration is unavailable, and bypasses Shell icon fallback.
Natural dimensions and rotationFree
Sizes and rotates video thumbnails correctly when metadata is available.TryGetVideoNaturalSize reads width, height, and rotation. ApplyVideoNaturalMetadata updates default placeholder-sized items but avoids clobbering items the user has already placed or resized.
Media cacheFree
Keeps regenerated video thumbnails available for future board opens.Generated thumbnails are cached under the video-thumb key when cache settings allow video/document thumbnail caching.

Thumbnail generation backends

BackendUsed forTechnical behavior
Windows thumbnail cacheFree
Uses existing Explorer thumbnails when a content thumbnail is already cached.Non-forced Phase 4 asks ThumbnailProvider.GetThumbnailCacheOnly so large imports do not hammer Shell thumbnail providers.
WPF MediaPlayer fallbackFree
Captures a frame for videos when the cache-only path is missing or unusable.GetVideoThumbnailOffUi can use an STA WPF MediaPlayer capture path with a bounded timeout when aggressive or forced generation permits active decoding.
LibVLC frame captureFree
Provides a deeper fallback for formats Windows/WPF cannot frame-capture reliably.The VLC capture path uses LibVLC callbacks without a render window, waits for a decoded frame, rejects black results, and can retry from the start if the seeked attempt fails.
Icon rejectionFree
Prevents generic video-app icons from being saved as thumbnails.FenSight checks video-icon-prone extensions, image dimensions, and visual heuristics before accepting a thumbnail as real content.
Black-frame rejectionFree
Retries or leaves a video for repair instead of saving an all-black representative image.NeedsVideoThumbnail and frame-capture paths reject likely black frames so generated thumbnails can be retried through stronger capture paths.

Settings and commands

Exact labelUser-facing behaviorStored setting or implementation
Video Corner MarkerFree
Shows or hides the video marker from the View menu.Mirrors ShowVideoCornerBadge and redraws the board surface.
Show video corner markerFree
Draws the upper-left triangle on non-playing video items.Persists ShowVideoCornerBadge. Playing videos suppress the marker while the live VideoView is visible.
Show play icon on videosFree
Shows a play glyph over video thumbnails.Persists ShowVideoPlayIcon. The board surface uses it for thumbnail-state video affordances; playback hides the badge.
Duration (video)Free
Shows known video duration in overlay text.Persists OverlayShowDuration and depends on duration metadata being read successfully.
Aggressive video thumbnail backfillFree
Tries active frame generation when cached Windows thumbnails are missing or bad.Persists EagerVideoThumbnailBackfill. When disabled, non-forced paths lean more heavily on cache-only thumbnails and placeholders.
Also cache video/document thumbnailsFree
Stores generated video thumbnails on disk so reopen and reimport paths are faster.Persists CacheVideoAndDocumentThumbnails and lets MediaCache keep video-thumb entries.
Generate Video ThumbnailFree
Regenerates a thumbnail for one selected video.Runs the forced Phase 4 path after evicting the existing video-thumb cache entry.
Generate Video Thumbnails (N selected)Free
Regenerates thumbnails for multiple selected videos.Appears when multiple selected items are VideoItem objects and runs the same forced regeneration path for the selected set.

Playback performance model

FenSight keeps video playback intentionally narrow: one current media item plays at a time, the live video surface is created only when needed, and it is torn down after stop so pan and zoom do not keep paying for an inactive native child window.

  • Starting one video stops the previous playing video or audio item.
  • Stopping a video disposes the LibVLC MediaPlayer on a background task and removes the VideoView from the WPF visual tree.
  • The video-position timer updates PlaybackPosition and scrubber state while the video is visible and playing.
  • If the playing item goes offscreen, FenSight can stop it instead of keeping hidden playback active.
  • FenSight returns keyboard focus to the main window after playback starts so canvas shortcuts still work.

When thumbnails look wrong

A video can import successfully before it has a useful representative frame. The repair path is designed for common failures such as Windows returning a generic icon, the first frame being black, or metadata arriving after initial layout.

  • Use Generate Video Thumbnail when a video shows a generic player icon, a black frame, or an outdated cached thumbnail.
  • Use File -> Rebuild Thumbnails when many board thumbnails need repair; video repair is handled before still-image/document rebuild work.
  • If Aggressive video thumbnail backfill is off, uncached videos may remain placeholders until you force regeneration.
  • Duration overlays appear only after duration metadata is available.
  • Some codec/container combinations may still fail all thumbnail paths; the VideoItem remains on the board and can still be opened externally.

Video import, inline playback, duration overlays, video corner markers, video thumbnail backfill, and manual video-thumbnail regeneration are Free.

Video thumbnails are representative frames, not edits to the source file. Regeneration updates FenSight's cached board preview and does not transcode or modify the original video.

Connected guides

Follow these related pages when the workflow crosses into setup, search, organization, export, security, or another board-level system.