@joaodotwork/finder-video-thumbnails 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joaodotwork
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# finder-video-thumbnails
+
+[![npm version](https://img.shields.io/npm/v/@joaodotwork/finder-video-thumbnails.svg)](https://www.npmjs.com/package/@joaodotwork/finder-video-thumbnails)
+[![npm downloads](https://img.shields.io/npm/dm/@joaodotwork/finder-video-thumbnails.svg)](https://www.npmjs.com/package/@joaodotwork/finder-video-thumbnails)
+[![license](https://img.shields.io/npm/l/@joaodotwork/finder-video-thumbnails.svg)](LICENSE)
+[![platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos)
+
+Generate macOS Finder thumbnails for video files that don't have one, using `ffmpeg` and [`fileicon`](https://github.com/mklement0/fileicon).
+
+By default, video files in Finder show a generic icon (or a low-res QuickLook preview that disappears when you scroll away). This tool grabs a frame from each video and sets it as a permanent custom Finder icon — so the thumbnails are always visible, in any view, with the natural aspect ratio preserved.
+
+## Requirements
+
+- macOS (uses `fileicon` which sets `com.apple.FinderInfo` xattr — won't work on Linux/Windows)
+- [`ffmpeg`](https://ffmpeg.org/) — `brew install ffmpeg`
+- [`fileicon`](https://github.com/mklement0/fileicon) — `brew install fileicon`
+
+## Install
+
+```sh
+npm install -g @joaodotwork/finder-video-thumbnails
+```
+
+Or run without installing:
+
+```sh
+npx @joaodotwork/finder-video-thumbnails <folder>
+```
+
+## Usage
+
+```sh
+finder-video-thumbnails [--force] <folder> [seek_seconds]
+```
+
+- `<folder>` — folder to process (recursive)
+- `--force` — re-generate icons even if a custom icon is already set
+- `seek_seconds` — timestamp (in seconds) to grab the frame from. Defaults to `1`
+
+### Examples
+
+Add thumbnails to every video in `~/Movies` (recursive):
+
+```sh
+finder-video-thumbnails ~/Movies
+```
+
+Grab the frame at the 5-second mark:
+
+```sh
+finder-video-thumbnails ~/Movies 5
+```
+
+Re-generate all thumbnails, overwriting existing ones:
+
+```sh
+finder-video-thumbnails --force ~/Movies
+```
+
+## Supported formats
+
+`.mov`, `.mp4`, `.m4v`, `.avi`, `.mkv`, `.webm` (case-insensitive)
+
+## How it works
+
+For each video without a custom icon:
+
+1. `ffmpeg` extracts a single frame at the seek timestamp.
+2. The frame is scaled to fit a 512×512 box, preserving aspect ratio, then padded to a square with a transparent background. This ensures Finder displays the thumbnail with the video's natural aspect ratio rather than stretching it.
+3. `fileicon` writes the resulting PNG as the file's custom Finder icon.
+
+Re-runs are idempotent: files that already have a custom icon are skipped unless `--force` is passed.
+
+## License
+
+MIT

package/bin/finder-video-thumbnails

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# finder-video-thumbnails
+# Generate macOS Finder thumbnails for video files using ffmpeg + fileicon.
+#
+# Usage: finder-video-thumbnails [--force] <folder> [seek_seconds]
+#   --force        re-generate icons even if one is already set
+#   seek_seconds   timestamp (in seconds) to grab the frame from. defaults to 1
+
+set -euo pipefail
+
+force=0
+if [[ "${1:-}" == "--force" ]]; then
+  force=1
+  shift
+fi
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: finder-video-thumbnails [--force] <folder> [seek_seconds]" >&2
+  exit 1
+fi
+
+folder="$1"
+seek="${2:-1}"
+
+if [[ ! -d "$folder" ]]; then
+  echo "error: not a directory: $folder" >&2
+  exit 1
+fi
+
+for cmd in ffmpeg fileicon; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "error: '$cmd' not found on PATH" >&2
+    echo "  install with: brew install $cmd" >&2
+    exit 1
+  fi
+done
+
+videos=()
+while IFS= read -r -d '' f; do
+  videos+=("$f")
+done < <(find "$folder" -type f \( \
+  -iname '*.mov' -o \
+  -iname '*.mp4' -o \
+  -iname '*.m4v' -o \
+  -iname '*.avi' -o \
+  -iname '*.mkv' -o \
+  -iname '*.webm' \) -print0)
+
+if [[ ${#videos[@]} -eq 0 ]]; then
+  echo "no video files found in: $folder"
+  exit 0
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+done_count=0
+skip_count=0
+fail_count=0
+i=0
+
+for video in "${videos[@]}"; do
+  name="${video#$folder/}"
+  ((i++))
+
+  if [[ $force -eq 0 ]] && fileicon test "$video" >/dev/null 2>&1; then
+    echo "skip  $name (already has icon)"
+    ((skip_count++))
+    continue
+  fi
+
+  thumb="$tmpdir/thumb_$i.png"
+  if ! ffmpeg -y -ss "$seek" -i "$video" -frames:v 1 -update 1 \
+        -vf "scale=512:512:force_original_aspect_ratio=decrease,format=rgba,pad=512:512:(ow-iw)/2:(oh-ih)/2:color=black@0" \
+        "$thumb" </dev/null >/dev/null 2>&1; then
+    echo "FAIL  $name (ffmpeg)"
+    ((fail_count++))
+    continue
+  fi
+
+  if ! fileicon set "$video" "$thumb" >/dev/null 2>&1; then
+    echo "FAIL  $name (fileicon)"
+    ((fail_count++))
+    continue
+  fi
+
+  echo "ok    $name"
+  ((done_count++))
+done
+
+echo
+echo "done: $done_count   skipped: $skip_count   failed: $fail_count"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@joaodotwork/finder-video-thumbnails",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Generate macOS Finder thumbnails for video files that don't have one, using ffmpeg + fileicon.",
+  "bin": {
+    "finder-video-thumbnails": "./bin/finder-video-thumbnails"
+  },
+  "scripts": {
+    "test": "echo \"no tests\" && exit 0"
+  },
+  "keywords": [
+    "macos",
+    "finder",
+    "thumbnail",
+    "video",
+    "ffmpeg",
+    "fileicon",
+    "icon",
+    "mov",
+    "mp4"
+  ],
+  "author": "joaodotwork",
+  "license": "MIT",
+  "os": [
+    "darwin"
+  ],
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joaodotwork/finder-video-thumbnails.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joaodotwork/finder-video-thumbnails/issues"
+  },
+  "homepage": "https://github.com/joaodotwork/finder-video-thumbnails#readme"
+}