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