This folder is the only place the Cinematic Nature Engine reads media from.
The project ships with footage for all six scenes (Mixkit clips, about 22 MB in total; origin and licences are in public/nature/CREDITS.md). A scene without footage — and any device where video is not allowed, for example with Save-Data on — uses its built-in fallback look (a graded gradient with mist, grain and light), which is a complete, working design on its own, so nothing breaks without footage. The steps below replace or add clips.
SOURCES.md lists checked Mixkit pages for all six scenes, or use your own footage. Preview every clip first.hero.mp4, valley.mp4, forest.mp4, river.mp4, lake.mp4, blue-hour.mp4. .mov, .m4v, .mkv and .webm also work.public/nature/source/. This folder is git-ignored and never deployed.ffmpeg and ffprobe must be on your PATH; Node 18+) and run from the project root:
node tools/make-nature-assets.mjs
The tool trims each clip, loops it seamlessly, and writes WebM and MP4 files in every tier your source is big enough for, plus posters and manifest.json.
credits.example.json to credits.json, fix any entry where you chose a different clip, and add the download date. Run the tool again (it regenerates CREDITS.md), then verify everything:
node tools/make-nature-assets.mjs --check
node tools/dev-server.mjs and open http://localhost:8080/?nature-debug. The console logs every decision the engine makes.public/nature/
source/ your raw downloads (git-ignored, never deployed)
videos/<category>/<scene>-<tier>.webm VP9
videos/<category>/<scene>-<tier>.mp4 H.264 fallback, same tiers
posters/<scene>-<tier>.webp exact first frame of each loop
manifest.json written by the tool, read by the engine
credits.json you fill this in: title, url, author, license, licenseUrl, downloaded, notes
CREDITS.md generated from credits.json
credits.example.json template for the suggested clips
SOURCES.md where the suggested clips come from, and which ones to avoid
Category folders: mountains (hero, valley), forest, rivers, sunset (lake) and night (blue-hour). waterfalls and clouds are empty folders reserved for future scenes. The tool reads its scene list from js/data/scenes.js.
Tiers (never upscaled: a tier larger than the source is skipped):
| Tier | Size | Used for |
|---|---|---|
portrait |
540×960 (9:16 centre crop) | phones held upright |
hd |
1280×720 | laptops, constrained devices |
fhd |
1920×1080 | desktops |
qhd |
2560×1440 | large high-DPI screens (needs a source above 1080p) |
Audio is always removed. Frame rate is capped at 30. The end of each clip is cross-faded into its start (1.5 s by default), so the loop has no visible seam; a clip too short for a cross-fade loops plainly. Posters are the exact first frame, so the poster-to-video fade is invisible.
node tools/make-nature-assets.mjs --list # scene ids, folders, what each clip should show
node tools/make-nature-assets.mjs --scene hero,lake # only these scenes
node tools/make-nature-assets.mjs --start 6 --max 14 # use 14 s starting at second 6 of the source
node tools/make-nature-assets.mjs --focus 0.3 # move the phone crop left (0 = left edge, 1 = right edge)
node tools/make-nature-assets.mjs --loop 2 # longer cross-fade (0 = no loop fade)
node tools/make-nature-assets.mjs --tiers hd,fhd # subset of portrait,hd,fhd,qhd
node tools/make-nature-assets.mjs --quick # fast, low-quality encode, previews only
node tools/make-nature-assets.mjs --force # re-encode even if outputs are newer than the source
node tools/make-nature-assets.mjs --check # verify manifest, files and credits; encodes nothing
Defaults: --max 16, --start 0, --loop 1.5, --focus 0.5. Scenes that are already up to date (same source, same settings) are skipped. Re-run the tool after editing credits.json; it refreshes CREDITS.md each time.
devicePixelRatio. Touch devices, weak CPUs (2 cores or fewer, or 2 GB RAM or less) and slow networks are capped at hd.?nature=off, reduced motion, the header pause button, Save-Data or reduced-data mode, or a very slow connection.Transparent PNG or WebP files can float above the footage. Add them to a scene in manifest.json; the tool keeps them when it re-encodes:
"hero": { "...": "written by the tool", "layers": [ { "src": "layers/hero-foreground.webp", "depth": 0.9 } ] }
src is relative to this folder. depth runs from 0.1 to 1.4 (the footage itself sits at 0.35, and the default is 0.7); higher values move more with the pointer and scroll.
| Flag | Effect |
|---|---|
?nature=off |
posters and fallback only: no video, mist or parallax |
?nature=low |
behave like a constrained phone |
?nature=high |
behave like a desktop, even on a touch screen; the frame-rate guard is ignored, so the footage is never stepped down |
?nature-debug |
log engine decisions to the console and expose window.__nature |
?nature-debug and the Network tab. Look for a 404, a wrong content type, or a server without HTTP Range support (Safari needs Range to play video). node tools/dev-server.mjs supports it.vercel.json lets browsers cache clips and posters for 7 days, so lower max-age there if that is too long.veil in js/data/scenes.js; it sets how dark the readability overlay is.blue-hour, say). Tune that scene’s tint, veil and mist in js/data/scenes.js, or choose another clip.credits.json. --check flags any that don’t.source/ are not part of the site. Never deploy them.