Merge pull request #126 from USACE-RMC/enhancement/video-component-and-ffmpeg

Add Video scroll-into-view autoplay and video compression tooling

Author: AdamGohs

.gitignore

@@ -35,6 +35,12 @@ src/reportIdMap.js
 src/imageDimensions.js
 src/data/
 
+# Preserved raw originals from compress-video (kept locally, never deployed)
+*-raw.mp4
+*-raw.webm
+*-raw.mov
+*-raw.m4v
+
 /docx_converter/venv/
 /docx_converter/utils/__pycache__/
 *.py[cod]

docs/dev/documentation-guide/06-creating-editing-pages.mdx

@@ -582,7 +582,6 @@ import Video from '@site/src/components/Video';
 <Video
   videoKey="vid-demo"
   src="/videos/desktop-applications/lifesim/users-guide/v1.0/demo.mp4"
-  alt="Screen recording of the LifeSim setup process"
   caption="LifeSim setup demonstration"
 />
 ```
@@ -595,6 +594,16 @@ import VideoReference from '@site/src/components/VideoReference';
 See <VideoReference videoKey="vid-demo" /> for a walkthrough.
 ```
 
+:::tip Compress videos before committing
+Screen-capture files are often much larger than they need to be. Before adding a video, compress it with the built-in tool:
+
+```bash
+npm run compress-video -- static/figures/<path>/your-video.mp4
+```
+
+This re-encodes the file in place (so your `<Video src>` path stays the same) and preserves the untouched original beside it as `your-video-raw.mp4`. The `*-raw.*` originals are gitignored — kept locally as a backup, never committed or deployed. Add `--audio` to keep an audio track (dropped by default) or `--crf <n>` to adjust quality.
+:::
+
 See [React Components](./07-react-components.mdx) for full props documentation.
 
 ---

docs/dev/documentation-guide/07-react-components.mdx

@@ -3105,7 +3105,7 @@ import Video from '@site/src/components/Video';
       'Multiple sources <code>[{src, type}]</code>',
       'Display width',
       'Show video controls',
-      'Auto-play on load',
+      'Auto-play when scrolled into view (muted); pauses off-screen; off for reduced-motion users',
       'Loop playback',
       'Mute audio (auto=true if autoPlay)',
       'iOS inline playback',
@@ -3118,6 +3118,27 @@ import Video from '@site/src/components/Video';
   ]}
 />
 
+**Autoplay behavior:**
+
+When `autoPlay` is set, the video does **not** start on page load. It starts when the user scrolls it into view and pauses when it scrolls out of view (via an `IntersectionObserver`). Autoplay always plays **muted** (browsers block un-muted autoplay), and it is **disabled entirely for visitors who have enabled "reduce motion"** in their operating system.
+
+Use `autoPlay loop` with `controls={false}` as a lightweight, modern replacement for an animated GIF — the same continuous, silent loop, but a far smaller file with built-in pause-when-offscreen behavior:
+
+```jsx
+<Video
+  videoKey="video-gif-style"
+  caption="Looping UI animation"
+  src="/videos/ui-loop.mp4"
+  autoPlay
+  loop
+  controls={false}
+/>
+```
+
+:::warning Keep controls on for longer autoplay clips
+For an `autoPlay loop` clip longer than ~5 seconds, leave `controls` at its default (`true`) so viewers can pause it. Continuous motion with no pause control fails WCAG 2.2.2 (Pause, Stop, Hide), a Section 508 requirement. The `controls={false}` GIF style is only appropriate for very short loops.
+:::
+
 ---
 
 ### VideoReference

docs/dev/documentation-guide/17-appendix-b-build-process-overview.mdx

@@ -601,7 +601,7 @@ These files configure the build process but are rarely modified:
 **Contains:**
 
 - List of all npm packages used
-- Script definitions (`start`, `build`, `deploy`)
+- Script definitions (`start`, `build`, `deploy`, and the manual `compress-video` utility)
 - Node.js version requirements
 - Project metadata
 
@@ -625,6 +625,14 @@ These files configure the build process but are rarely modified:
 
 ---
 
+### `scripts/compress-video.js` (manual utility)
+
+**Purpose:** Compress oversized video files before committing them.
+
+Unlike the scripts above, this is **not** part of the automated build — it is an on-demand helper. Run `npm run compress-video -- <path-to-video>` to re-encode a video in place (H.264/CRF via the bundled `ffmpeg-static`, so no system install is required). The original is preserved as a gitignored `*-raw.*` file. See [Videos and GIFs](./06-creating-editing-pages.mdx) for the contributor workflow.
+
+---
+
 ## Deployment to Production (Administrator-Level Only)
 
 :::danger Important - Administrators Only

package-lock.json

@@ -8,6 +8,7 @@
     "versions": "node scripts/versions.js",
     "sidebars": "node scripts/generateSidebars.js",
     "report-map": "node scripts/generateReportIdMap.js",
+    "compress-video": "node scripts/compress-video.js",
     "generate-toc": "node scripts/generateEventTreeTOC.js",
     "image-dims": "node scripts/generateImageDimensions.js",
     "start": "cross-env DOCS_MODE=dev npm run image-dims && cross-env DOCS_MODE=dev npm run report-map && cross-env DOCS_MODE=dev npm run sidebars && cross-env DOCS_MODE=dev npm run counters && cross-env DOCS_MODE=dev npm run versions && cross-env DOCS_MODE=dev npm run generate-toc && cross-env DOCS_MODE=dev docusaurus start",
@@ -52,6 +53,7 @@
     "autoprefixer": "^10.4.21",
     "baseline-browser-mapping": "^2.9.19",
     "cross-env": "^7.0.3",
+    "ffmpeg-static": "^5.3.0",
     "postcss": "^8.5.6",
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.14"