@kimjansheden/payload-video-processor 0.1.14 → 0.1.16

package/README.md

@@ -24,14 +24,16 @@ pnpm add @kimjansheden/payload-video-processor
 Peer dependencies (`payload`, `react`, `react-dom`) must already exist in your
 Payload project. The package bundles static FFmpeg/ffprobe binaries via
 `ffmpeg-static`; if those are blocked on your platform, set `FFMPEG_BIN` to a
-system ffmpeg binary.
+system ffmpeg binary (for example `/opt/homebrew/bin/ffmpeg` on macOS/Homebrew).
 
 ## Quick start
 
-1. Define presets and register the plugin in your `payload.config.ts`:
+### Step 1: Register the plugin
+
+Define presets and register the plugin in your `payload.config.ts` (or wherever you build your Payload config):
 
 ```ts
-import { buildConfig } from "payload/config";
+import { buildConfig } from "payload";
 import { mongooseAdapter } from "@payloadcms/db-mongodb";
 import videoPlugin from "@kimjansheden/payload-video-processor";
 
@@ -54,13 +56,16 @@ const videoOptions = {
   // Auto-enqueue a preset when a new video is uploaded.
   autoEnqueue: true,
   // Optional: override the default preset used on create.
-  autoEnqueuePreset: "hd1080",
+  autoEnqueuePreset: "hd720",
   // Optional: replace the original with the auto-generated variant.
   autoReplaceOriginal: true,
 };
 
 export default buildConfig({
-  db: mongooseAdapter({ url: process.env.MONGODB_URI ?? "" }),
+  // This plugin works with both DATABASE_URI and MONGODB_URI; the worker CLI maps DATABASE_URI -> MONGODB_URI.
+  db: mongooseAdapter({
+    url: process.env.DATABASE_URI ?? process.env.MONGODB_URI ?? "",
+  }),
   collections: [
     /* … */
   ],
@@ -68,11 +73,23 @@ export default buildConfig({
 });
 ```
 
+Recommended host pattern: export the options object from `src/videoPluginOptions.ts` and import it in both your Payload config and `worker/payload.worker.config.ts`, so presets/queue settings stay in one place.
+
 When `autoEnqueue` is `true`, the plugin
 tries a preset named `1080`, then `hd1080`, and finally falls back to the first
 configured preset.
 Set `autoEnqueuePreset` to force a specific preset name when auto-enqueueing.
 
+### Cropping behavior
+
+Cropping is optional and configured per preset via `enableCrop: true`.
+
+- `enableCrop` only exposes crop controls in the Admin UI.
+- Cropping is **opt-in per enqueue**: the generated variant is not cropped unless
+  the editor explicitly enables “Apply crop for this enqueue”.
+- If cropping is not enabled, no crop parameters are sent to the worker and the
+  full frame is preserved.
+
 ### Type-safe presets (TypeScript)
 
 ```ts
@@ -81,7 +98,7 @@ import videoPlugin, { type VideoPluginOptions } from "@kimjansheden/payload-vide
 const presets = {
   mobile360: { label: "360p Mobile", args: ["-vf", "scale=-2:360"] },
   hd1080: { label: "Full HD 1080p", args: ["-vf", "scale=-2:1080"] },
-} as const;
+} satisfies VideoPluginOptions["presets"];
 
 type PresetName = keyof typeof presets;
 
@@ -123,8 +140,53 @@ For the worker options module, either export default (ESM) or use
 | `access` | `AccessControl` | Optional access control hooks. |
 | `resolvePaths` | `(args) => ResolvePathsResult` | Override output directory/filename/URL. |
 
-1. Provide a worker options module and bundle it to JS (the CLI needs a JS file).
-   Example setup:
+### Step 2: Ensure the upload collection exposes `path` (local filesystem)
+
+The worker needs to read the original upload from disk. For local filesystem
+storage, the worker reads the original file path from `doc.path` (absolute path
+on disk). If your upload collection does not already provide a `path`, add a
+read-only field and populate it from your upload `staticDir` + `filename`:
+
+```ts
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CollectionConfig } from "payload";
+
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+
+const staticDir =
+  process.env.STATIC_DIR ?? path.resolve(dirname, "../../public/media");
+
+export const Media: CollectionConfig = {
+  slug: "media",
+  upload: {
+    staticDir,
+    mimeTypes: ["video/mp4", "video/webm", "video/quicktime"],
+  },
+  fields: [
+    {
+      name: "path",
+      type: "text",
+      admin: { readOnly: true, position: "sidebar" },
+    },
+  ],
+  hooks: {
+    afterRead: [
+      ({ doc }) => {
+        if (doc && typeof doc.filename === "string") {
+          doc.path = path.join(staticDir, doc.filename);
+        }
+        return doc;
+      },
+    ],
+  },
+};
+```
+
+### Step 3: Bundle the plugin options for the worker CLI
+
+Provide a worker options module and bundle it to JS (the CLI needs a JS file). Example:
 
 ```ts
 // src/videoPluginOptions.ts
@@ -135,16 +197,47 @@ export default videoOptions;
 tsup src/videoPluginOptions.ts --format esm --platform node --target es2022 --out-dir dist-config --minify
 ```
 
-1. Start a worker in a separate process:
+### Step 4: Add a minimal Payload config for the worker (recommended)
+
+When you pass `--payload-config`, the worker can initialize Payload locally and update documents via the local Node API.
+
+```ts
+// worker/payload.worker.config.ts
+import { mongooseAdapter } from "@payloadcms/db-mongodb";
+import { buildConfig } from "payload";
+import videoPlugin from "@kimjansheden/payload-video-processor";
+
+import { Media } from "../src/collections/Media";
+import videoPluginOptions from "../src/videoPluginOptions";
+
+export default buildConfig({
+  telemetry: false,
+  secret: process.env.PAYLOAD_SECRET || "dev-secret",
+  db: mongooseAdapter({
+    url: process.env.MONGODB_URI || process.env.DATABASE_URI || "",
+  }),
+  plugins: [videoPlugin(videoPluginOptions)],
+  collections: [Media],
+});
+```
+
+Bundle it:
+
+```bash
+tsup worker/payload.worker.config.ts --format esm --platform node --target es2022 --out-dir dist-config --minify
+```
+
+### Step 5: Start the worker
+
+Start the worker in a separate process:
 
 ```bash
 payload-video-worker \
   --config ./dist-config/videoPluginOptions.js \
-  --env .env
+  --payload-config ./dist-config/payload.worker.config.js
 ```
 
-If you want the worker to initialize Payload locally, also pass
-`--payload-config` and ensure `PAYLOAD_SECRET` + `MONGODB_URI` are set. If you
+To initialize Payload locally, ensure `PAYLOAD_SECRET` + `DATABASE_URI` (or `MONGODB_URI`) are set. If you
 prefer the REST fallback, omit `--payload-config` and provide
 `PAYLOAD_REST_URL` + `PAYLOAD_ADMIN_TOKEN`.
 
@@ -152,13 +245,45 @@ The CLI loads `.env`, `.env.local`, `.env.development`, and `.env.production`
 automatically (unless you pass `--no-default-env`). Additional `--env` flags can
 point to project-specific files.
 
+Example (explicit env + static dir, useful in monorepos):
+
+```bash
+FFMPEG_BIN=/opt/homebrew/bin/ffmpeg payload-video-worker \
+  --no-default-env \
+  --config ./dist-config/videoPluginOptions.js \
+  --payload-config ./dist-config/payload.worker.config.js \
+  --env .env \
+  --env .env.development \
+  --static-dir ./public/media
+```
+
 Prefer a fully programmatic setup? Import `createWorker` directly and pass the
 same options object you provide to the plugin.
 
-1. In the Admin UI a "Video processing" panel appears on any upload collection
-   that accepts `video/*` mime types. Editors can enqueue presets, preview
-   variants, replace the original file with a processed version, or delete
-   unwanted variants without writing custom endpoints.
+### Step 6: Use the Admin UI
+
+In the Admin UI a "Video processing" panel appears on any upload collection that accepts `video/*` mime types. Editors can enqueue presets, preview variants, replace the original file with a processed version, or delete unwanted variants without writing custom endpoints.
+
+### Recommended host project scripts (example)
+
+Most projects bundle both the plugin options and a minimal Payload config for the worker:
+
+```jsonc
+{
+  "scripts": {
+    "bundle:video-plugin-options": "tsup src/videoPluginOptions.ts --format esm --platform node --target es2022 --out-dir dist-config --minify",
+    "bundle:payload-worker-config": "tsup worker/payload.worker.config.ts --format esm --platform node --target es2022 --out-dir dist-config --minify",
+    "video:worker": "pnpm bundle:payload-worker-config && pnpm bundle:video-plugin-options && payload-video-worker --config ./dist-config/videoPluginOptions.js --payload-config ./dist-config/payload.worker.config.js",
+    "video:worker:dev": "pnpm bundle:payload-worker-config && pnpm bundle:video-plugin-options && FFMPEG_BIN=/opt/homebrew/bin/ffmpeg payload-video-worker --no-default-env --config ./dist-config/videoPluginOptions.js --payload-config ./dist-config/payload.worker.config.js --env .env --env .env.development --static-dir ./public/media"
+  }
+}
+```
+
+## Example project (repo)
+
+This repository also includes `apps/example-payload`, a **CLI-only** reference
+project that demonstrates plugin configuration + worker processing without
+shipping a full `/admin` UI app. See `apps/example-payload/README.md`.
 
 ## Scripts
 
@@ -176,7 +301,7 @@ same options object you provide to the plugin.
 | `REDIS_URL`                                 | Default Redis connection string for queue + worker.                          |
 | `FFMPEG_BIN`                                | Optional path to a system ffmpeg binary (overrides `ffmpeg-static`).         |
 | `STATIC_DIR`                                | Base media directory for the worker (used when resolving paths).             |
-| `PAYLOAD_SECRET` / `MONGODB_URI`            | Required to bootstrap the Payload local API from the worker.                 |
+| `PAYLOAD_SECRET` / `DATABASE_URI` / `MONGODB_URI` | Required to bootstrap the Payload local API from the worker.            |
 | `PAYLOAD_REST_URL` + `PAYLOAD_ADMIN_TOKEN`  | REST fallback when local init is not possible.                               |
 | `PAYLOAD_PUBLIC_URL` / `PAYLOAD_SERVER_URL` | Alternative base URL for REST fallback if `PAYLOAD_REST_URL` is not set.     |
 | `PAYLOAD_CONFIG_PATH`                       | Absolute/relative path to the host `payload.config.ts` for worker bootstrap. |

package/dist/admin/VideoField.cjs

@@ -128,7 +128,7 @@ var mergeReadOnlyFields = (current, doc) => {
 var VideoField = (props) => {
   const { useEffect, useMemo, useState, useCallback, useRef } = React__default.default;
   const { field } = props;
-  const { id, lastUpdateTime, setData, data: formData } = ui.useDocumentInfo();
+  const { id, setData, data: formData } = ui.useDocumentInfo();
   const formModified = ui.useFormModified();
   const custom = field.custom ?? (isVideoVariantFieldConfig(props) ? props : void 0);
   const presets = custom?.presets ?? {};
@@ -144,13 +144,14 @@ var VideoField = (props) => {
     return value;
   }, [id]);
   const [EasyCrop, setEasyCrop] = useState(null);
+  const [applyCrop, setApplyCrop] = useState(false);
   useEffect(() => {
-    if (typeof window !== "undefined" && !EasyCrop) {
+    if (typeof window !== "undefined" && applyCrop && !EasyCrop) {
       import('react-easy-crop').then((module) => {
         setEasyCrop(() => module.default);
       });
     }
-  }, [EasyCrop]);
+  }, [EasyCrop, applyCrop]);
   const [selectedPreset, setSelectedPreset] = useState(
     presetNames[0]
   );
@@ -170,13 +171,27 @@ var VideoField = (props) => {
   const [zoom, setZoom] = useState(1);
   const [cropSelection, setCropSelection] = useState(DEFAULT_CROP);
   const expectedPresetRef = useRef(null);
+  const formDataRef = useRef(formData);
+  const formModifiedRef = useRef(formModified);
   const sleep = useCallback(
     (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     []
   );
+  useEffect(() => {
+    formDataRef.current = formData;
+  }, [formData]);
+  useEffect(() => {
+    formModifiedRef.current = formModified;
+  }, [formModified]);
   useEffect(() => {
     expectedPresetRef.current = expectedPreset;
   }, [expectedPreset]);
+  useEffect(() => {
+    setApplyCrop(false);
+    setCropSelection(DEFAULT_CROP);
+    setCropState({ x: 0, y: 0 });
+    setZoom(1);
+  }, [selectedPreset]);
   useEffect(() => {
     if (!processingStatus) return;
     const statusJobId = typeof processingStatus.jobId === "string" ? processingStatus.jobId.trim() : "";
@@ -467,7 +482,7 @@ var VideoField = (props) => {
         return null;
       }
       setDocData(nextDoc);
-      const nextFormData = formModified ? mergeReadOnlyFields(formData, nextDoc) : nextDoc;
+      const nextFormData = formModifiedRef.current ? mergeReadOnlyFields(formDataRef.current, nextDoc) : nextDoc;
       setData(nextFormData);
       setProcessingStatus(nextDoc.videoProcessingStatus ?? null);
       const docVariants = Array.isArray(nextDoc.variants) ? nextDoc.variants : [];
@@ -481,10 +496,10 @@ var VideoField = (props) => {
     } finally {
       setLoadingDoc(false);
     }
-  }, [apiBase, custom, docId, formData, formModified, setData]);
+  }, [apiBase, custom, docId, setData]);
   useEffect(() => {
     void fetchDocument();
-  }, [fetchDocument, jobStatus?.state, lastUpdateTime]);
+  }, [fetchDocument]);
   const enqueue = useCallback(async () => {
     if (!custom || !docId || !selectedPreset) return;
     try {
@@ -495,16 +510,23 @@ var VideoField = (props) => {
       const data = await sendEnqueueRequest({
         documentId: docId,
         presetName: selectedPreset,
-        crop: allowCrop ? cropSelection : void 0
+        crop: allowCrop && applyCrop ? cropSelection : void 0
       });
       setJobStatus(data);
       setPollingJobId(String(data.id));
+      if (allowCrop && applyCrop) {
+        setApplyCrop(false);
+        setCropSelection(DEFAULT_CROP);
+        setCropState({ x: 0, y: 0 });
+        setZoom(1);
+      }
     } catch (enqueueError) {
       setError(
         enqueueError instanceof Error ? enqueueError.message : "Failed to enqueue job."
       );
     }
   }, [
+    applyCrop,
     custom,
     cropSelection,
     docId,
@@ -599,19 +621,24 @@ var VideoField = (props) => {
   );
   useEffect(() => {
     if (!cropEnabled) {
+      setApplyCrop(false);
       setCropSelection(DEFAULT_CROP);
       setCropState({ x: 0, y: 0 });
       setZoom(1);
     }
   }, [cropEnabled]);
-  const handleCropComplete = useCallback((area) => {
-    setCropSelection({
-      width: area.width / 100,
-      height: area.height / 100,
-      x: area.x / 100,
-      y: area.y / 100
-    });
-  }, []);
+  const handleCropComplete = useCallback(
+    (area) => {
+      if (!applyCrop) return;
+      setCropSelection({
+        width: area.width / 100,
+        height: area.height / 100,
+        x: area.x / 100,
+        y: area.y / 100
+      });
+    },
+    [applyCrop]
+  );
   const handleTogglePreview = useCallback((key) => {
     setPreviewKey((current) => current === key ? null : key);
   }, []);
@@ -778,46 +805,67 @@ var VideoField = (props) => {
     ] }),
     cropEnabled && docData?.url ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-3", children: [
       /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-xs font-medium uppercase tracking-wide text-slate-500", children: "Crop" }),
-      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "video-crop-wrapper", children: EasyCrop ? /* @__PURE__ */ jsxRuntime.jsx(
-        EasyCrop,
-        {
-          video: docData.url,
-          crop: cropState,
-          zoom,
-          rotation: 0,
-          aspect: 4 / 3,
-          minZoom: 1,
-          maxZoom: 3,
-          cropShape: "rect",
-          zoomSpeed: 1,
-          restrictPosition: true,
-          mediaProps: {},
-          cropperProps: {},
-          style: {},
-          classes: {},
-          keyboardStep: 1,
-          onCropChange: setCropState,
-          onZoomChange: setZoom,
-          onCropComplete: handleCropComplete,
-          objectFit: "contain",
-          showGrid: true
-        }
-      ) : /* @__PURE__ */ jsxRuntime.jsx("div", { children: "Loading cropper..." }) }),
       /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "flex items-center gap-2 text-xs text-slate-600", children: [
-        "Zoom",
         /* @__PURE__ */ jsxRuntime.jsx(
           "input",
           {
-            type: "range",
-            min: 1,
-            max: 3,
-            step: 0.1,
-            value: zoom,
-            onChange: (event) => setZoom(Number(event.target.value)),
-            className: "w-48"
+            type: "checkbox",
+            checked: applyCrop,
+            onChange: (event) => {
+              const nextApplyCrop = event.target.checked;
+              setApplyCrop(nextApplyCrop);
+              if (!nextApplyCrop) {
+                setCropSelection(DEFAULT_CROP);
+                setCropState({ x: 0, y: 0 });
+                setZoom(1);
+              }
+            }
           }
-        )
-      ] })
+        ),
+        "Apply crop for this enqueue"
+      ] }),
+      applyCrop ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "video-crop-wrapper", children: EasyCrop ? /* @__PURE__ */ jsxRuntime.jsx(
+          EasyCrop,
+          {
+            video: docData.url,
+            crop: cropState,
+            zoom,
+            rotation: 0,
+            aspect: 4 / 3,
+            minZoom: 1,
+            maxZoom: 3,
+            cropShape: "rect",
+            zoomSpeed: 1,
+            restrictPosition: true,
+            mediaProps: {},
+            cropperProps: {},
+            style: {},
+            classes: {},
+            keyboardStep: 1,
+            onCropChange: setCropState,
+            onZoomChange: setZoom,
+            onCropComplete: handleCropComplete,
+            objectFit: "contain",
+            showGrid: true
+          }
+        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { children: "Loading cropper..." }) }),
+        /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "flex items-center gap-2 text-xs text-slate-600", children: [
+          "Zoom",
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              type: "range",
+              min: 1,
+              max: 3,
+              step: 0.1,
+              value: zoom,
+              onChange: (event) => setZoom(Number(event.target.value)),
+              className: "w-48"
+            }
+          )
+        ] })
+      ] }) : /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-xs text-slate-500", children: "Cropping is off by default. Enable it to crop the generated variant." })
     ] }) : null,
     posterUrl ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-2 text-xs text-slate-600", children: [
       /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-semibold uppercase tracking-wide text-slate-500", children: "Poster" }),