@frkntmbs/strapi-plugin-video-optimizer 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 frkntmbs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,6 +23,8 @@ Strapi's Media Library uploads videos as-is unless you add custom server logic.
 
 Encoding runs **asynchronously in the background** — the original file appears in the Media Library immediately, and FFmpeg replaces it when the job completes.
 
+> **Server notice:** Video encoding is CPU-intensive. Large files can consume significant server resources. Use `maxConcurrentJobs` and `maxFfmpegThreads` on small VPS hosts. This plugin is recommended for server/VPS environments where FFmpeg is available.
+
 Upload UX mirrors [`strapi-plugin-image-optimizer`](https://github.com/frkntmbs/strapi-plugin-image-optimizer); image processing is replaced with FFmpeg-based video encoding.
 
 ## Screenshots
@@ -104,8 +106,40 @@ flowchart LR
 - [Strapi](https://strapi.io) **5.x**
 - Node.js **20–24**
 - `@strapi/plugin-upload` (included with Strapi)
+- **FFmpeg** — required for video encoding (see [FFmpeg requirement](#ffmpeg-requirement) below)
+
+## FFmpeg requirement
+
+This plugin requires an FFmpeg executable at runtime. Resolution order:
+
+1. [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) — installed as an npm dependency and used when available (may pull platform-specific FFmpeg binaries into `node_modules`)
+2. **System FFmpeg** — if `ffmpeg-static` is unavailable, the plugin falls back to an `ffmpeg` binary on the host `PATH`
+
+You are responsible for ensuring your FFmpeg installation and use comply with the applicable **LGPL/GPL** license terms.
+
+### Install FFmpeg on the host (recommended for Docker/production)
+
+**macOS**
+
+```bash
+brew install ffmpeg
+```
+
+**Ubuntu / Debian**
+
+```bash
+sudo apt update && sudo apt install ffmpeg
+```
+
+**Docker**
 
-FFmpeg is bundled via [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static). If unavailable, the plugin falls back to a system `ffmpeg` binary on `PATH`.
+Install FFmpeg in your Strapi application image, for example:
+
+```dockerfile
+RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
+```
+
+Or use a base image that already includes FFmpeg.
 
 ## Installation
 
@@ -165,6 +199,8 @@ All options can be set in `config/plugins.ts` (defaults) and overridden from the
 
 ### Server resource tuning
 
+Large videos can consume significant CPU and memory during encoding. On small VPS hosts, keep concurrency low:
+
 | Setting | Weak VPS suggestion | Notes |
 |---------|---------------------|-------|
 | `maxConcurrentJobs` | `1` | Only one video encodes at a time |
@@ -215,6 +251,14 @@ Configure settings for a single video:
 
 While a video is queued or encoding, hover the card and click the **stop** button to cancel the job. If the file was deleted during encoding, the job is cancelled automatically.
 
+## Test results
+
+Real-world encode runs on a Strapi 5 project with default plugin settings (`maxConcurrentJobs: 1`, `maxFfmpegThreads: 2`). Results vary by source file, output format, and server CPU.
+
+> **Note:** Optimization controls encoding — it does **not** guarantee a smaller file. Re-encoding an already compressed source at the same resolution may increase size. For size reduction, raise CRF, lower resolution, or stay on H.264 instead of switching to WebM.
+
+_Test results will be added here after benchmark runs (e.g. 4K → 1920 scaling)._
+
 ## Permissions
 
 Global settings are protected by admin permissions:
@@ -277,6 +321,20 @@ npx yalc add --link @frkntmbs/strapi-plugin-video-optimizer && npm install
 npm run develop
 ```
 
+## Legal note
+
+This plugin's **source code** is licensed under [MIT](LICENSE).
+
+Video encoding relies on **FFmpeg**, which is licensed under LGPL/GPL. By default, the plugin uses the [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) npm package, which may install platform-specific FFmpeg binaries as a transitive dependency. When `ffmpeg-static` is unavailable, the plugin uses the FFmpeg executable available on the host system.
+
+Please make sure your FFmpeg installation and use comply with the applicable LGPL/GPL license terms.
+
+## Disclaimer
+
+This is a **community plugin** and is not an official Strapi plugin.
+
+Strapi is a trademark of Strapi Solutions SAS.
+
 ## License
 
 [MIT](LICENSE)

package/admin/src/components/BridgeProviders.tsx

@@ -28,6 +28,9 @@ const enMessages: Record<string, string> = {
   [`${PLUGIN_ID}.choice.custom`]: 'Custom',
   [`${PLUGIN_ID}.choice.custom.description`]:
     'Configure format and quality settings specifically for this video.',
+  [`${PLUGIN_ID}.optimization.warning.title`]: 'This video may already be well optimized',
+  [`${PLUGIN_ID}.optimization.warning.description`]:
+    'Re-encoding may not reduce file size and can even make it larger. Consider Keep original, or raise CRF / lower resolution if you need a smaller output.',
   [`${PLUGIN_ID}.settings.global.defaultFormat`]: 'Output format',
   [`${PLUGIN_ID}.settings.global.videoCodec`]: 'Video codec',
   [`${PLUGIN_ID}.settings.global.crf`]: 'CRF (quality)',

package/admin/src/components/MediaLibraryCardActionsBridge.tsx

@@ -9,6 +9,7 @@ import {
 } from '@strapi/design-system';
 import { Cross, Sparkle, Stop } from '@strapi/icons';
 import { useIntl } from 'react-intl';
+import { OptimizationBenefitWarning } from './OptimizationBenefitWarning';
 import { OptimizationChoicePicker } from './OptimizationChoicePicker';
 import { OptimizationCustomForm } from './OptimizationVideoFields';
 import { getTranslationKey } from '../pluginId';
@@ -21,6 +22,7 @@ import {
   closeMediaLibraryEditor,
   createCustomForMediaLibraryFile,
   getEditingMediaLibraryDimensions,
+  getEditingMediaLibrarySizeBytes,
   getEditingMediaLibraryFileId,
   getEditingMediaLibraryFileName,
   getMediaLibraryCards,
@@ -49,6 +51,10 @@ export const MediaLibraryCardActionsBridge = () => {
     subscribeMediaLibraryCards,
     getEditingMediaLibraryDimensions
   );
+  const editingSizeBytes = useSyncExternalStore(
+    subscribeMediaLibraryCards,
+    getEditingMediaLibrarySizeBytes
+  );
   const draftPreference = useSyncExternalStore(
     subscribeMediaLibraryCards,
     getMediaLibraryDraftPreference
@@ -142,6 +148,15 @@ export const MediaLibraryCardActionsBridge = () => {
                   {editingFileName}
                 </Typography>
               )}
+              <OptimizationBenefitWarning
+                choice={draftPreference.choice}
+                metadata={{
+                  width: editingDimensions?.width,
+                  height: editingDimensions?.height,
+                  sizeBytes: editingSizeBytes,
+                }}
+                customSettings={resolvedCustom ?? undefined}
+              />
               <OptimizationChoicePicker
                 value={draftPreference.choice}
                 onChange={setMediaLibraryDraftChoice}
@@ -212,6 +227,7 @@ export const MediaLibraryCardActionsBridge = () => {
                       openMediaLibraryEditor(card.fileId, card.fileName, {
                         width: card.width,
                         height: card.height,
+                        sizeBytes: card.sizeBytes,
                       });
                     }}
                   >

package/admin/src/components/OptimizationBenefitWarning.tsx

@@ -0,0 +1,52 @@
+import { Box, Typography } from '@strapi/design-system';
+import { useIntl } from 'react-intl';
+import { getTranslationKey, type OptimizationChoice, type OptimizationSettings } from '../pluginId';
+import {
+  evaluateOptimizationBenefit,
+  type VideoSourceMetadata,
+} from '../utils/evaluateOptimizationBenefit';
+import { getGlobalSettings } from '../utils/uploadAssetStore';
+
+interface OptimizationBenefitWarningProps {
+  choice: OptimizationChoice;
+  metadata: VideoSourceMetadata;
+  customSettings?: OptimizationSettings;
+}
+
+export const OptimizationBenefitWarning = ({
+  choice,
+  metadata,
+  customSettings,
+}: OptimizationBenefitWarningProps) => {
+  const { formatMessage } = useIntl();
+  const showWarning = evaluateOptimizationBenefit(
+    choice,
+    metadata,
+    getGlobalSettings(),
+    customSettings
+  );
+
+  if (!showWarning) {
+    return null;
+  }
+
+  return (
+    <Box
+      padding={4}
+      hasRadius
+      background="warning100"
+      borderColor="warning200"
+      borderStyle="solid"
+      borderWidth="1px"
+    >
+      <Typography variant="omega" fontWeight="bold" textColor="warning700">
+        {formatMessage({ id: getTranslationKey('optimization.warning.title') })}
+      </Typography>
+      <Box paddingTop={1}>
+        <Typography variant="pi" textColor="warning700">
+          {formatMessage({ id: getTranslationKey('optimization.warning.description') })}
+        </Typography>
+      </Box>
+    </Box>
+  );
+};

package/admin/src/components/UploadEnhancerBridge.tsx

@@ -10,6 +10,7 @@ import {
 import { Cross, Sparkle } from '@strapi/icons';
 import { useIntl } from 'react-intl';
 import { AssetOptimizationLabel } from './AssetOptimizationLabel';
+import { OptimizationBenefitWarning } from './OptimizationBenefitWarning';
 import { OptimizationChoicePicker } from './OptimizationChoicePicker';
 import { OptimizationCustomForm } from './OptimizationVideoFields';
 import { getTranslationKey } from '../pluginId';
@@ -20,6 +21,7 @@ import {
   getDraftPreference,
   getEditingAssetId,
   getSourceDimensionsForAsset,
+  getSourceMetadataForAsset,
   getUploadAssetCards,
   getUploadDialogElement,
   openAssetEditor,
@@ -43,6 +45,7 @@ export const UploadEnhancerBridge = () => {
 
   const editingCard = cards.find((card) => card.assetId === editingAssetId);
   const sourceDimensions = editingAssetId ? getSourceDimensionsForAsset(editingAssetId) : undefined;
+  const sourceMetadata = editingAssetId ? getSourceMetadataForAsset(editingAssetId) : {};
   const resolvedCustom =
     editingAssetId && draftPreference.choice === 'custom'
       ? resolveCustomSettingsForAsset(editingAssetId, draftPreference.custom)
@@ -132,6 +135,16 @@ export const UploadEnhancerBridge = () => {
                   {editingCard.assetName}
                 </Typography>
               )}
+              <OptimizationBenefitWarning
+                choice={draftPreference.choice}
+                metadata={{
+                  width: editingCard?.width ?? sourceMetadata.width ?? sourceDimensions?.width,
+                  height: editingCard?.height ?? sourceMetadata.height ?? sourceDimensions?.height,
+                  sizeBytes: editingCard?.sizeBytes ?? sourceMetadata.sizeBytes,
+                  durationSeconds: editingCard?.durationSeconds ?? sourceMetadata.durationSeconds,
+                }}
+                customSettings={resolvedCustom ?? undefined}
+              />
               <OptimizationChoicePicker
                 value={draftPreference.choice}
                 onChange={setDraftChoice}

package/admin/src/components/upload/PendingAssetStep.tsx

@@ -3,12 +3,14 @@ import { Box, Flex, Typography } from '@strapi/design-system';
 import { Sparkle } from '@strapi/icons';
 import { useIntl } from 'react-intl';
 import { AssetOptimizationLabel } from '../AssetOptimizationLabel';
+import { OptimizationBenefitWarning } from '../OptimizationBenefitWarning';
 import { OptimizationChoicePicker } from '../OptimizationChoicePicker';
 import { OptimizationCustomForm } from '../OptimizationVideoFields';
 import {
   createCustomForAsset,
   getAssetPreference,
   getSourceDimensionsForAsset,
+  getSourceMetadataForAsset,
   resolveCustomSettingsForAsset,
   type UploadAssetEntry,
 } from '../../utils/uploadAssetStore';
@@ -28,6 +30,7 @@ export const PendingAssetStep = ({
   const { formatMessage } = useIntl();
 
   const sourceDimensions = getSourceDimensionsForAsset(asset.assetId);
+  const sourceMetadata = getSourceMetadataForAsset(asset.assetId);
   const resolvedCustom = resolveCustomSettingsForAsset(asset.assetId, preference.custom);
 
   const handleChoiceChange = (choice: AssetOptimizationPreference['choice']) => {
@@ -54,6 +57,17 @@ export const PendingAssetStep = ({
           {asset.assetName}
         </Typography>
 
+        <OptimizationBenefitWarning
+          choice={preference.choice}
+          metadata={{
+            width: asset.width ?? sourceMetadata.width ?? sourceDimensions?.width,
+            height: asset.height ?? sourceMetadata.height ?? sourceDimensions?.height,
+            sizeBytes: asset.sizeBytes ?? sourceMetadata.sizeBytes,
+            durationSeconds: asset.durationSeconds ?? sourceMetadata.durationSeconds,
+          }}
+          customSettings={preference.choice === 'custom' ? resolvedCustom : undefined}
+        />
+
         <OptimizationChoicePicker value={preference.choice} onChange={handleChoiceChange} />
 
         {preference.choice === 'custom' && (

package/admin/src/translations/en.json

@@ -45,6 +45,8 @@
   "choice.global.description": "Uses the global optimization profile configured in Settings.",
   "choice.custom": "Custom",
   "choice.custom.description": "Configure format and quality settings specifically for this video.",
+  "optimization.warning.title": "This video may already be well optimized",
+  "optimization.warning.description": "Re-encoding may not reduce file size and can even make it larger. Consider Keep original, or raise CRF / lower resolution if you need a smaller output.",
   "upload.optimization.label": "Optimization",
   "upload.button.label": "Optimization settings",
   "upload.modal.title": "Video optimization",

package/admin/src/translations/tr.json

@@ -45,6 +45,8 @@
   "choice.global.description": "Settings altındaki global optimizasyon profilini kullanır.",
   "choice.custom": "Özel",
   "choice.custom.description": "Bu video için format ve kalite ayarlarını ayrıca yapılandırın.",
+  "optimization.warning.title": "Bu video zaten iyi optimize edilmiş olabilir",
+  "optimization.warning.description": "Yeniden encode dosya boyutunu düşürmeyebilir, hatta büyütebilir. Olduğu gibi bırakmayı düşünün; daha küçük çıktı için CRF değerini yükseltin veya çözünürlüğü düşürün.",
   "upload.optimization.label": "Optimizasyon",
   "upload.button.label": "Optimizasyon ayarları",
   "upload.modal.title": "Video optimizasyonu",

package/admin/src/utils/evaluateOptimizationBenefit.ts

@@ -0,0 +1,113 @@
+import type {
+  GlobalOptimizationSettings,
+  OptimizationChoice,
+  OptimizationSettings,
+} from '../pluginId';
+
+export interface VideoSourceMetadata {
+  width?: number;
+  height?: number;
+  sizeBytes?: number;
+  durationSeconds?: number;
+}
+
+const willResize = (
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+  resizeMode: 'exact' | 'fit-within'
+) => {
+  if (targetWidth === sourceWidth && targetHeight === sourceHeight) {
+    return false;
+  }
+
+  if (resizeMode === 'fit-within') {
+    return sourceWidth > targetWidth || sourceHeight > targetHeight;
+  }
+
+  return true;
+};
+
+const bitrateMbps = (sizeBytes: number, durationSeconds: number) =>
+  (sizeBytes * 8) / durationSeconds / 1_000_000;
+
+const maxBitrateMbpsForResolution = (maxDimension: number) => {
+  if (maxDimension <= 720) {
+    return 1.5;
+  }
+
+  if (maxDimension <= 1080) {
+    return 2.5;
+  }
+
+  if (maxDimension <= 1440) {
+    return 5;
+  }
+
+  return 8;
+};
+
+const isBitrateAlreadyEfficient = (metadata: VideoSourceMetadata) => {
+  const { width, height, sizeBytes, durationSeconds } = metadata;
+
+  if (!width || !height || !sizeBytes || !durationSeconds || durationSeconds <= 0) {
+    return false;
+  }
+
+  const maxDimension = Math.max(width, height);
+  const bitrate = bitrateMbps(sizeBytes, durationSeconds);
+
+  return bitrate <= maxBitrateMbpsForResolution(maxDimension);
+};
+
+export const evaluateOptimizationBenefit = (
+  choice: OptimizationChoice,
+  metadata: VideoSourceMetadata,
+  globalSettings: GlobalOptimizationSettings,
+  customSettings?: OptimizationSettings
+): boolean => {
+  if (choice === 'original') {
+    return false;
+  }
+
+  const { width, height } = metadata;
+
+  if (!width || !height) {
+    return false;
+  }
+
+  if (choice === 'global') {
+    const wouldResize = willResize(
+      width,
+      height,
+      globalSettings.maxWidth,
+      globalSettings.maxHeight,
+      'fit-within'
+    );
+
+    if (wouldResize) {
+      return false;
+    }
+
+    return isBitrateAlreadyEfficient(metadata) || Boolean(metadata.sizeBytes);
+  }
+
+  if (choice === 'custom' && customSettings) {
+    const wouldResizeCustom = willResize(
+      width,
+      height,
+      customSettings.maxWidth,
+      customSettings.maxHeight,
+      'exact'
+    );
+
+    if (wouldResizeCustom) {
+      return false;
+    }
+
+    return isBitrateAlreadyEfficient(metadata) || Boolean(metadata.sizeBytes);
+  }
+
+  return false;
+};

package/admin/src/utils/initMediaLibraryCardActions.ts

@@ -200,8 +200,14 @@ const collectCardActions = (uploadAssets: UploadAssetRecord[]): MediaLibraryCard
     entries.push({
       fileId,
       fileName: asset?.name ?? card.querySelector('[id$="-title"]')?.textContent?.trim() ?? '',
-      width: dimensions?.width,
-      height: dimensions?.height,
+      width: dimensions?.width ?? asset?.width,
+      height: dimensions?.height ?? asset?.height,
+      sizeBytes:
+        typeof asset?.sizeInBytes === 'number'
+          ? asset.sizeInBytes
+          : typeof asset?.size === 'number'
+            ? Math.round(asset.size * 1024)
+            : undefined,
       optimizeHost,
       cancelHost,
     });

package/admin/src/utils/initUploadEnhancer.ts

@@ -11,7 +11,7 @@ import {
   setGlobalSettings,
   setUploadAssetCards,
   setUploadDialogElement,
-  updateAssetDimensions,
+  updateAssetMetadata,
   type UploadAssetEntry,
 } from './uploadAssetStore';
 import { isVideoFileName } from '../pluginId';
@@ -20,7 +20,7 @@ import {
   ensureVideoElementDimensions,
   findUploadFilesInDialog,
   matchUploadFile,
-  probeVideoFileDimensions,
+  probeVideoFileMetadata,
 } from './probeVideoDimensions';
 
 const pendingDimensionProbes = new Set<string>();
@@ -312,12 +312,17 @@ const queueDimensionProbe = (
         const file = matchUploadFile(files, assetName);
 
         if (file) {
-          dimensions = await probeVideoFileDimensions(file);
+          const metadata = await probeVideoFileMetadata(file);
+
+          if (metadata) {
+            updateAssetMetadata(assetId, metadata);
+            return;
+          }
         }
       }
 
       if (dimensions) {
-        updateAssetDimensions(assetId, dimensions);
+        updateAssetMetadata(assetId, dimensions);
       }
     } finally {
       pendingDimensionProbes.delete(assetId);

package/admin/src/utils/mediaLibraryCardStore.ts

@@ -12,6 +12,7 @@ export interface MediaLibraryCardEntry {
   fileName: string;
   width?: number;
   height?: number;
+  sizeBytes?: number;
   optimizeHost: HTMLElement;
   cancelHost: HTMLElement;
 }
@@ -23,6 +24,7 @@ const listeners = new Set<() => void>();
 let editingFileId: number | null = null;
 let editingFileName: string | null = null;
 let editingDimensions: { width?: number; height?: number } | null = null;
+let editingSizeBytes: number | undefined;
 let draftPreference: AssetOptimizationPreference | null = null;
 let enqueueInFlight = false;
 let cancelInFlight = new Set<number>();
@@ -96,6 +98,8 @@ export const getEditingMediaLibraryFileName = () => editingFileName;
 
 export const getEditingMediaLibraryDimensions = () => editingDimensions;
 
+export const getEditingMediaLibrarySizeBytes = () => editingSizeBytes;
+
 export const getMediaLibraryDraftPreference = (): AssetOptimizationPreference => {
   return draftPreference ?? STABLE_EMPTY_DRAFT;
 };
@@ -107,11 +111,12 @@ export const isMediaLibraryCancelInFlight = (fileId: number) => cancelInFlight.h
 export const openMediaLibraryEditor = (
   fileId: number,
   fileName: string,
-  dimensions?: { width?: number; height?: number }
+  metadata?: { width?: number; height?: number; sizeBytes?: number }
 ) => {
   editingFileId = fileId;
   editingFileName = fileName;
-  editingDimensions = dimensions ?? null;
+  editingDimensions = metadata ? { width: metadata.width, height: metadata.height } : null;
+  editingSizeBytes = metadata?.sizeBytes;
   draftPreference = createDefaultPreference();
 
   if (draftPreference.choice === 'custom') {
@@ -125,6 +130,7 @@ export const closeMediaLibraryEditor = () => {
   editingFileId = null;
   editingFileName = null;
   editingDimensions = null;
+  editingSizeBytes = undefined;
   draftPreference = null;
   notify();
 };

package/admin/src/utils/mediaLibraryQueryBridge.ts

@@ -10,6 +10,10 @@ export interface UploadAssetRecord {
   url?: string;
   mime?: string;
   ext?: string;
+  width?: number;
+  height?: number;
+  size?: number;
+  sizeInBytes?: number;
 }
 
 let queryClientRef: QueryClient | null = null;

package/admin/src/utils/probeVideoDimensions.ts

@@ -1,6 +1,17 @@
 export const probeVideoFileDimensions = (
   file: File
 ): Promise<{ width: number; height: number } | undefined> =>
+  probeVideoFileMetadata(file).then((metadata) =>
+    metadata?.width && metadata?.height
+      ? { width: metadata.width, height: metadata.height }
+      : undefined
+  );
+
+export const probeVideoFileMetadata = (
+  file: File
+): Promise<
+  { width: number; height: number; durationSeconds?: number; sizeBytes: number } | undefined
+> =>
   new Promise((resolve) => {
     const url = URL.createObjectURL(file);
     const video = document.createElement('video');
@@ -13,12 +24,20 @@ export const probeVideoFileDimensions = (
     };
 
     video.onloadedmetadata = () => {
-      const dimensions =
+      const metadata =
         video.videoWidth > 0 && video.videoHeight > 0
-          ? { width: video.videoWidth, height: video.videoHeight }
+          ? {
+              width: video.videoWidth,
+              height: video.videoHeight,
+              durationSeconds:
+                Number.isFinite(video.duration) && video.duration > 0
+                  ? video.duration
+                  : undefined,
+              sizeBytes: file.size,
+            }
           : undefined;
       cleanup();
-      resolve(dimensions);
+      resolve(metadata);
     };
 
     video.onerror = () => {