# Swipe Frame Transition Demo

> Build reusable mobile-friendly HTML demos where swiping between ordered images scrubs through adjacent transition videos converted into image-frame sequences. Use when a user provides images such as d1/d2/d3 and videos such as d1d2/d2d3, asks for smooth bidirectional swipe transitions, wants to avoid MP4 seek black screens or flicker, wants an interactive artwork/product/story demo, or wants a shareable static HTML demo.

- Skill: `arcdodo/swipe-frame-transition-demo` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add arcdodo/swipe-frame-transition-demo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arcdodo/swipe-frame-transition-demo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: arcdodo (https://skillmd.com/u/arcdodo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arcdodo/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:

```text
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:

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

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

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

Useful options:

```text
--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:

```js
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.