release(v3.0.2): ffmpeg-backed video thumbnails (Docker) + new thumbnail API (closes #79)

- Docker: ship ffmpeg so video thumbnails work out-of-the-box in container installs
- add /api/file/thumbnail.php endpoint to generate + cache JPEG thumbnails for video files
- UI: use ffmpeg-backed thumbnails for hover previews + gallery cards (fallback to movie icon)
- harden query param parsing for file endpoints (avoid array/querystring edge cases)
- docs: add FFmpeg + archive tools to THIRD_PARTY notices

Closes #79

Author: error311

CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## Changes 01/15/2026 (v3.0.2)
+
+`release(v3.0.2): ffmpeg-backed video thumbnails (Docker) + new thumbnail API (closes #79)`
+
+**Commit message**  
+
+```text
+release(v3.0.2): ffmpeg-backed video thumbnails (Docker) + new thumbnail API (closes #79)
+
+- Docker: ship ffmpeg so video thumbnails work out-of-the-box in container installs
+- add /api/file/thumbnail.php endpoint to generate + cache JPEG thumbnails for video files
+- UI: use ffmpeg-backed thumbnails for hover previews + gallery cards (fallback to movie icon)
+- harden query param parsing for file endpoints (avoid array/querystring edge cases)
+- docs: add FFmpeg + archive tools to THIRD_PARTY notices
+
+Closes #79
+```
+
+**Added**  
+
+- **Video thumbnail API endpoint:** `GET /api/file/thumbnail.php?folder=...&file=...`  
+  Returns a cached **JPEG** thumbnail for supported video files.
+- **Server-side thumbnail generator** (local sources only):
+  - Uses `ffmpeg` to extract a frame and writes it into a meta-root cache (`thumb_cache/`).
+  - Cache key includes file path + mtime + size + thumb dimensions for stable reuse.
+  - Optional env tuning:
+    - `FR_FFMPEG_PATH` (override ffmpeg path)
+    - `FR_VIDEO_THUMB_MAX_W`, `FR_VIDEO_THUMB_MAX_H` (thumbnail max size)
+- **Docker image now installs `ffmpeg`** so thumbnails work in Docker/Unraid without extra setup.
+
+**Changed**  
+
+- **Hover preview video thumbs** now use the thumbnail API instead of `<video preload="metadata">` seeking.
+- **Gallery view video cards** now render an `<img>` thumbnail with a play overlay; falls back to the movie icon on error.
+- **Thumbnail generation respects your existing “max video preview size (MB)” setting**:
+  - If a video exceeds the configured cap, the thumbnail endpoint returns “too large”.
+- **Source-aware behavior (when Sources is enabled):**
+
+**Security / Hardening**  
+
+- Thumbnails are only generated for authenticated users and still enforce:
+  - ACL read rules (and read_own ownership checks where applicable)
+  - no thumbnails for encrypted files
+- Cache responses include `X-Content-Type-Options: nosniff` and a private cache policy.
+
+**Docs / Compliance**  
+
+- Updated `THIRD_PARTY.md` to mention Docker-bundled system packages:
+  - FFmpeg (LGPL-2.1+; builds may include GPL components)
+  - p7zip / unar (for archive handling)
+
+---
+
 ## Changes 01/14/2026 (v3.0.1 Archive update + login focus)
 
 `release(v3.0.1): archive create/extract upgrades (7z + RAR via unar) + login focus fix (closes #82)`

Dockerfile

@@ -41,6 +41,7 @@ RUN if [ -f /etc/apt/sources.list.d/ubuntu.sources ]; then \
     apt-get install -y --no-install-recommends \
       apache2 \
       php php-json php-curl php-zip php-mbstring php-gd php-xml \
+      ffmpeg \
       ca-certificates curl git openssl \
       smbclient \
       7zip \

THIRD_PARTY.md

@@ -56,6 +56,21 @@ Used optionally for virus scanning of uploads (via the `clamscan` command).
 - **Source:** Available via your Linux distribution’s package repositories or from the ClamAV website.  
 - **Note:** ClamAV runs as a separate executable and is not part of the FileRise application code.
 
+Additional system packages bundled in the Docker image:
+
+- **FFmpeg** — LGPL-2.1+ (some builds include GPL components)  
+  **Home:** <https://ffmpeg.org/>  
+  **Source:** Linux distribution package repositories.  
+  **Note:** Installed for video thumbnail generation.
+
+- **7-Zip (p7zip)** — LGPL-2.1+ with unRAR restriction  
+  **Home:** <https://www.7-zip.org/>  
+  **Source:** Linux distribution package repositories.
+
+- **unar (The Unarchiver)** — LGPL-2.1+  
+  **Home:** <https://theunarchiver.com/>  
+  **Source:** Linux distribution package repositories.
+
 ### Base image and system packages
 
 The official Docker image is built on **Ubuntu 24.04** and includes common

public/api/file/thumbnail.php

@@ -0,0 +1,35 @@
+<?php
+// public/api/file/thumbnail.php
+
+/**
+ * @OA\Get(
+ *   path="/api/file/thumbnail.php",
+ *   summary="Get a video thumbnail image",
+ *   description="Returns a cached JPEG thumbnail for supported video files.",
+ *   operationId="getVideoThumbnail",
+ *   tags={"Files"},
+ *   security={{"cookieAuth": {}}},
+ *   @OA\Parameter(name="folder", in="query", required=true, @OA\Schema(type="string"), example="root"),
+ *   @OA\Parameter(name="file", in="query", required=true, @OA\Schema(type="string"), example="clip.mp4"),
+ *   @OA\Response(
+ *     response=200,
+ *     description="Thumbnail image",
+ *     content={
+ *       "image/jpeg": @OA\MediaType(
+ *         mediaType="image/jpeg",
+ *         @OA\Schema(type="string", format="binary")
+ *       )
+ *     }
+ *   ),
+ *   @OA\Response(response=400, description="Invalid folder/file"),
+ *   @OA\Response(response=401, description="Unauthorized"),
+ *   @OA\Response(response=403, description="Forbidden"),
+ *   @OA\Response(response=404, description="Not found")
+ * )
+ */
+
+require_once __DIR__ . '/../../../config/config.php';
+require_once PROJECT_ROOT . '/src/controllers/FileController.php';
+
+$fileController = new FileController();
+$fileController->videoThumbnail();