webmanager-mvp/project_docs/VIDEO_THUMBNAIL_V1_DESIGN.md

Video Thumbnail v1

1. Doel

Video thumbnails voegen vooral waarde toe in directories met veel mediabestanden: de gebruiker kan sneller onderscheid maken tussen vergelijkbare videobestanden zonder elk bestand eerst te openen. Binnen de huidige dual-pane workflow moet dit dezelfde ondersteunende rol hebben als image thumbnails: een kleine visuele hint in de bestaande mediaslot links van de naam, niet een aparte mediabrowser.

Dit moet passen binnen de huidige lijstweergave:

• geen galerij-UI
• geen wijziging aan browse- of selectiegedrag
• alleen zichtbaar als Show thumbnails is ingeschakeld

2. Scope

Aanbevolen v1-scope:

• wel onderzoeken en eventueel ondersteunen:
  • mp4
• beperkt / best-effort:
  • mkv
• niet in v1:
  • video thumbnail-generatie zonder duidelijke technische basis
  • video contact sheets
  • hover-preview / animated preview
  • pdf thumbnails
  • subtitle-preview
  • generieke media analysis pipeline

Belangrijke conclusie voor scope:

• mp4 is de realistische primaire kandidaat
• mkv is niet gelijkwaardig aan mp4
• als mkv wordt meegenomen, moet dat expliciet best-effort zijn en niet als gegarandeerde happy path worden gepresenteerd

3. Technische haalbaarheid

Zonder extra dependency

Echte video thumbnails genereren zonder extra dependency is in de praktijk niet verstandig.

Waarom:

• een browser kan wel video afspelen, maar de backend heeft voor een lijstthumbnail een afbeeldingsrepresentatie nodig
• pure standaardbibliotheek in Python biedt geen bruikbare frame-extractie uit video
• alleen het originele videobestand serveren en hopen dat de browser daar in een <img> of simpele lijstweergave iets van maakt is geen robuuste aanpak

Conclusie zonder dependency:

• echte video thumbnails zijn niet netjes haalbaar
• zonder extra tool resteert alleen een video-icoon/placeholder

Met dependency zoals ffmpeg

ffmpeg is de technisch logische kandidaat voor frame-extractie.

Voordelen:

• breed inzetbaar
• kan één frame op een gekozen offset extraheren
• werkt voor veel containers/codecs, inclusief veel mp4- en mkv-varianten
• laat read-only thumbnailgeneratie toe zonder transcoding of volledige media pipeline

Nadelen:

• extra runtime dependency
• operationele afhankelijkheid op container/host
• frame-extractie is CPU- en I/O-werk
• caching- en invalidatievragen worden relevant
• mkv blijft afhankelijk van werkelijke codec-ondersteuning in de file, ook al helpt ffmpeg veel

Aanbeveling haalbaarheid

Eerlijke v1-aanbeveling:

• zonder extra dependency geen echte video thumbnails bouwen
• als video thumbnails echt gewenst zijn, dan is een beperkte ffmpeg-afhankelijke v1 de eerste technische route die verdedigbaar is
• als het project op dit moment dependency-arm moet blijven, is uitstel verstandiger dan een halfwerkende pseudo-thumbnailoplossing

4. Thumbnail-bron

Als video thumbnails later wél gebouwd worden, is het eerste frame meestal geen goede keuze:

• eerste frames zijn vaak zwart
• leader-frames geven weinig informatie

Veiligere keuze:

• een klein offsetmoment, bijvoorbeeld rond 00:00:02 of een klein percentage in het begin
• nog steeds read-only: alleen één frame extraheren, geen analysepipeline

Bij grote bestanden en netwerkvolumes betekent dit:

• thumbnailgeneratie veroorzaakt extra read-I/O op het videobestand
• bij veel bestanden in één directory kan dat snel oplopen
• juist daarom is caching of strikte lazy loading relevant zodra echte video thumbnails worden toegevoegd

5. UI-gedrag

De video thumbnail moet in dezelfde mediaslot komen als image thumbnails:

• links van de naam
• zelfde vaste slotbreedte
• geen verschuiving van de naamkolom

Gedrag:

• als Show thumbnails uit staat:
  • video krijgt gewoon het bestaande file-icoon of een video-icoon
• als Show thumbnails aan staat:
  • ondersteunde video met beschikbare thumbnail: toon thumbnail
  • als thumbnail niet beschikbaar is of niet ondersteund wordt: toon passend icoon/placeholder

Belangrijke UI-eis:

• de lijst mag niet instabiel worden
• thumbnails zijn een enhancement, geen vereiste voor nette uitlijning

6. Settings-relatie

Video thumbnails moeten alleen zichtbaar zijn als Show thumbnails aan staat.

Aanbevolen v1-keuze:

• geen aparte extra setting voor video thumbnails

Reden:

• een tweede thumbnailsetting maakt Settings complexer voordat er een bewezen implementatie is
• eerst moet duidelijk zijn of video thumbnails technisch en performance-matig verantwoord zijn

Als video thumbnails later worden toegevoegd, vallen ze in eerste instantie onder dezelfde globale toggle.

7. Performance en caching

Belangrijkste risico:

• frame-extractie is duidelijk duurder dan het serveren van bestaande image files

Risico's

• grote directories met veel video’s kunnen browse-performance merkbaar verslechteren
• thumbnails op netwerkvolumes versterken latency
• gelijktijdige extracties kunnen CPU en disk-I/O onnodig belasten

Lazy loading

Lazy loading is verplicht zodra echte video thumbnails bestaan:

• alleen thumbnails laden voor zichtbare rijen
• beperkte concurrency
• geen eager generatie voor volledige directorylisting

Caching

Voor echte video thumbnails is een vorm van caching vrijwel onvermijdelijk zodra de feature meer dan experimenteel moet zijn.

Afweging:

• zonder cache: te veel herhaalde frame-extractie
• met disk-cache: meer complexiteit, maar technisch logisch

Aanbevolen v1-richting als ffmpeg later wordt toegestaan:

• kleine disk-cache of bestandsgebonden cache-key op pad + mtime
• maar alleen als de implementatieslice expliciet bereid is deze extra complexiteit te dragen

Aanbevolen richting voor nu met laag risico:

• geen caching bouwen zolang de dependency- en implementatiekeuze nog niet definitief is
• eerst expliciet besluiten of echte video thumbnails de extra complexiteit waard zijn

8. Backend-impact

Als video thumbnails later worden gebouwd, is een apart read-only endpoint logisch, bijvoorbeeld:

• GET /api/files/video-thumbnail?path=...

Waarom apart endpoint:

• scheidt image thumbnails van videothumbnails
• maakt eigen foutafhandeling, typevalidatie en caching later eenvoudiger
• houdt browse-response klein

Bestaande infrastructuur moet leidend blijven:

• path_guard
• whitelist/root containment
• bestaande foutmapping voor traversal / invalid root alias / not found / type conflicts waar passend
• read-only gedrag: alleen lezen, geen wijziging aan bronbestand

9. MKV-realiteit

mkv is een container, geen garantie voor uniforme technische behandeling.

Belangrijke realiteit:

• mkv-bestanden variëren sterk in codecs en encoding-eigenschappen
• browser playback en server-side frame-extractie zijn twee verschillende dingen
• zelfs als browserplayback soms lastig is, kan ffmpeg vaak nog wel een thumbnail extraheren
• maar dat maakt mkv nog niet gelijkwaardig qua voorspelbaarheid aan mp4

Aanbevolen v1-positionering:

• mkv hooguit best-effort
• mp4 is de primaire en verwachte happy path
• als thumbnail-extractie voor mkv faalt, toon gewoon het video-icoon/placeholder zonder extra dramatische fout in de lijst

10. Regressierisico

Belangrijkste regressierisico's:

• browse-performance verslechtert merkbaar
• thumbnail-latency maakt de lijst onrustig
• mediaslot wordt inconsistent tussen image/video/non-image
• externe toolchain verhoogt deploy-complexiteit
• caching kan nieuwe foutbronnen introduceren

Ook belangrijk:

• huidige image thumbnail-flow moet niet vervuild raken met video-specifieke uitzonderingen
• de lijst moet leesbaar blijven, ook als video thumbnails traag of afwezig zijn

11. Teststrategie

Backend golden tests

Als video thumbnails later echt gebouwd worden:

• success voor ondersteunde video met thumbnail
• not found
• traversal blocked
• invalid root alias
• unsupported/non-video type blocked
• nette fallback als thumbnail-extractie niet lukt

UI smoke/regressietests

• mediaslot blijft bestaan
• lijst blijft renderen met thumbnails aan/uit
• video zonder thumbnail toont icoon/placeholder
• image thumbnails blijven werken
• selectie/current row/active pane styling blijft intact

Handmatige validatie

• directory met veel video’s blijft bruikbaar
• thumbnails verschijnen alleen als setting aan staat
• mp4 thumbnail werkt voorspelbaar
• mkv faalt netjes terug op placeholder waar nodig
• geen merkbare regressie in browse-flow of selectie

12. Aanbeveling

Aanbevolen v1-richting met laag regressierisico:

• nu nog geen echte video thumbnails implementeren zonder extra dependency
• houd de huidige mediaslot-aanpak aan:
  • image thumbnails waar al ondersteund
  • voor video voorlopig een video-icoon/placeholder
• als de feature later echt gebouwd moet worden:
  • gebruik ffmpeg als expliciete dependency
  • scopeer eerst op mp4
  • behandel mkv als best-effort
  • combineer dit met lazy loading
  • overweeg pas daarna een eenvoudige cache

Samengevat:

• eerlijke technische conclusie: echte video thumbnails in v1 zonder dependency zijn niet verstandig
• veiligste huidige richting: uitstellen of beperken tot ontwerpvoorbereiding
• als later toch doorgepakt wordt, dan alleen met expliciete keuze voor ffmpeg en een smalle, performance-bewuste scope