Installation Guide

Getting Whispering Pines Running

This is probably the easiest setup of any project on the site. Ten minutes, tops, and most of that is just waiting for a download.

Prerequisites

• A modern browser. Chrome, Edge, Firefox or Safari — anything from the last three years is fine.
• A text editor if you want to change anything. VS Code is free, grab it from code.visualstudio.com.
• Python 3.x with OpenCV, but only if you plan to replace the forest video. Skip this otherwise. If you do need it, install Python from python.org (any 3.x, not 2.7) and run pip install opencv-python.

Step 1 — Unzip everything into one folder

Extract the ZIP you downloaded. You should see index.html, forest-scroll.mp4, and a folder called frames with 192 JPEGs inside it. Keep them together. The page looks for images at the relative path frames/frame_0001.jpg, so if you move index.html somewhere else on its own, the hero will render as a blank canvas.

Step 2 — Open it

Double-click index.html. That's the whole installation. No terminal, no server, no localhost port.

If you'd rather run a local server anyway — some people prefer it — open a terminal in that folder and run python -m http.server 8000, then visit http://localhost:8000 in your browser. Both approaches work identically here.

Step 3 — Let the frames load

The first few seconds after opening, the page is pulling in all 192 images. Scrolling before that finishes won't crash anything, the animation just won't respond yet. Give it a moment.

Step 4 — Scroll and watch

Scroll down slowly through the hero. The forest should advance frame by frame, tied directly to how far you've moved. Scroll back up and it plays in reverse. Keep going past the hero and the about section, stat counters and cards should fade in as they hit the viewport.

Optional — Use your own video

Drop your MP4 into the folder and run this in Python:

import cv2, os
os.makedirs('frames', exist_ok=True)
cap = cv2.VideoCapture('your-video.mp4')
count = 0
while True:
    ret, frame = cap.read()
    if not ret: break
    count += 1
    cv2.imwrite(f'frames/frame_{count:04d}.jpg', frame, [cv2.IMWRITE_JPEG_QUALITY, 82])
cap.release()

Delete the old frames first, otherwise you'll end up with a mix of two videos. Then note the final count value the script produced and set FRAME_COUNT in index.html to that number.

Common issues

The hero is just a blank or black rectangle

Nine times out of ten the frames folder isn't sitting next to index.html. Open DevTools with F12, click the Console tab, and look for 404 errors on frame paths. Fix the folder location and reload.

The animation feels choppy or laggy

Usually means the frames haven't all preloaded yet — wait a bit longer and try again. If it's still rough on an older laptop, reduce the frame count by deleting every alternate JPEG, renumbering them sequentially, and lowering FRAME_COUNT to match. Half the images, half the memory pressure, and honestly the motion still looks fine.

Scroll animation plays too fast

Find .scroll-section { height: 300vh; } in the style block and bump it to 400vh or 500vh. Bigger number means the same 192 frames spread across more scroll distance, so everything slows down.

Images don't load when opening the file directly

Rare, but some browser security settings block local file access. If that happens, use the python -m http.server 8000 method from Step 2 instead.

How to know it's actually working

Three checks. Scroll halfway through the hero and stop — the animation should freeze on a specific frame and stay there, not keep playing. Scroll upward and the frames should run backwards. Then scroll down to the stats section and confirm the numbers count up from zero when they appear rather than sitting at their final values. If all three behave, everything's wired correctly.