feat: iconenen aangepast

project_docs/VIDEO_THUMBNAIL_V1_DESIGN.md

@@ -0,0 +1,231 @@
+# 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