RUWIO/dev_docs/06_electron-rendering-manual-checks.md

Electron MP4 Render Manual Checks

Date: 2026-06-05

Use this checklist before treating desktop MP4 export as release-ready.

Automated Desktop Render Checks

Before the manual checks below, run the headless harness suite (requires a display, ffmpeg, and ffprobe). It drives the real worker end-to-end and covers frame capture, MP4 output, cancel, the inactivity watchdog, the render-window network block, and transparent-region flattening:

npm run test:render-desktop

All six checks should print RESULT: PASS and the run ends with ALL DESKTOP RENDER CHECKS PASSED.

Build Checks

1. Stage a redistributable ffmpeg binary for the target platform:

   npm run stage:ffmpeg -- --source /path/to/ffmpeg
   

2. Build an unpacked app:

   npm run desktop:pack
   

3. Confirm packaged resources exist:

   find release/linux-unpacked/resources -maxdepth 4 -type f | sort | rg 'server/render.html|bin/.*/ffmpeg'
   

4. Confirm Unix executable permissions on Linux/macOS:

   ls -l release/linux-unpacked/resources/bin/linux/ffmpeg
   

5. Confirm the packaged binary runs:

   release/linux-unpacked/resources/bin/linux/ffmpeg -version
   

App Checks

1. Launch the unpacked app.
2. Create a tiny scene with at least one visible animated layer.
3. Export MP4 at the default FPS and confirm:
   • a native save dialog appears
   • progress advances in the export dialog
   • the final file exists at the selected path
   • the file opens in a standard media player
4. Start another MP4 export and cancel after progress starts. Confirm:
   • progress stops
   • the app remains responsive
   • no partial MP4 remains at the selected path
5. Repeat with:
   • image assets
   • text layers using non-default fonts
   • non-default FPS
   • layers hidden from render

Server Fallback Checks

Automated route smoke:

npm run test:render-server

Automated MP4 E2E smoke:

npm run test:render-server:e2e

The E2E smoke starts the standalone server on a temporary localhost port, submits a tiny scene, waits for SSE completion, downloads the MP4, and verifies the H.264 stream with ffprobe. It requires Chromium, ffmpeg, and ffprobe.

Manual browser fallback:

1. Start the standalone server:

   cd server
   HOST=127.0.0.1 PORT=6000 RENDER_TOKEN="choose-a-long-random-token" npm start
   

2. Start the browser app with matching render settings:

   VITE_RENDER_SERVER=http://localhost:6000 VITE_RENDER_TOKEN="choose-a-long-random-token" npm run dev
   

3. Export MP4 from the browser app and confirm the server path still works.

ffmpeg Release Notes

For every bundled ffmpeg binary, record:

• source URL
• upstream version
• target platform and architecture
• whether the build is static or dynamically linked
• configured codecs, especially libx264
• GPL/LGPL license obligations
• required attribution or license files to ship with the app

The local staging script may copy a system ffmpeg. That is useful for package path verification, but release artifacts should use reviewed redistributable binaries for each platform.