Swipe Frame Transition Demo

Swipe Frame Transition Demo

Create a static HTML demo in which transition frames follow the user's finger. Prefer extracted JPEG frame sequences over live MP4 seeking because browser video seeking commonly causes black frames and flicker.

Input Convention

Ask the user to name ordered images and adjacent transition videos:

d1.png
d2.png
d3.png
d1d2.mp4
d2d3.mp4

Accept PNG, JPG, JPEG, or WebP images. Accept MP4, MOV, M4V, or WebM videos. Require consecutive image numbering and one adjacent transition video for every pair.

Build Workflow

1. Inventory the supplied files and verify that each dN image has the required adjacent dNdN+1 video.
2. Install media dependencies locally only when unavailable:

python3 -m pip install --target <project>/.python-packages imageio imageio-ffmpeg Pillow

3. Run the bundled builder with the local dependency directory on PYTHONPATH:

PYTHONPATH=<project>/.python-packages \
python3 <skill-root>/scripts/build_demo.py <input-media-directory> <output-demo-directory>

Useful options:

--frames 40
--max-long-side 1280
--jpeg-quality 82
--transition-seconds 0.9

4. Open the generated index.html for a local check. Use a local static server when file:// behavior differs from the final hosted environment.
5. Verify forward and reverse swipes for every adjacent pair.
6. Deliver the output demo folder. When the user needs a public link, deploy the folder as a static site.

Interaction Requirements

• Make the transition frame follow finger progress during the swipe.
• Support both forward and reverse swiping using the same frame sequence.
• Keep the current still image visible until the first useful forward frame is ready.
• Preload frame sequences to prevent first-swipe flicker.
• On completion, place the destination still image beneath the final transition frame before removing the frame layer.
• Avoid decorative rotation, blur, dark flashes, or unrelated page-transition effects.
• Keep the demo usable on mobile touch screens and desktop pointer devices.

Template Configuration

The generated HTML reads config.js. To adjust a demo manually, edit only this file:

window.SWIPE_DEMO_CONFIG = {
  images: ["assets/images/d1.png", "assets/images/d2.png"],
  videos: { "0-1": "assets/videos/d1d2.mp4" },
  frameSets: { "0-1": "assets/frames/d1d2" },
  frameCount: 40,
  transitionSeconds: 0.9,
  swipeThresholdRatio: 0.12,
};

Use zero-based keys in videos and frameSets: "0-1" means image 1 to image 2.

Validation

• Run node --check <output-demo-directory>/app.js.
• Confirm every configured image exists.
• Confirm each frame-set directory contains exactly frameCount images.
• Check the first forward swipe, all reverse swipes, and the final frame-to-still-image handoff.
• Report if dependencies could not be installed or visual browser testing could not be performed.

Bundled Resources

• scripts/build_demo.py: discover named assets, copy the HTML template, extract transition frames, and generate config.js.
• scripts/extract_frames.py: legacy helper for regenerating the bundled original four-image example; do not use for normal user projects.
• assets/html-template/: reusable configuration-driven static HTML demo.