StopFrame

Live Demo: https://stopframe.vercel.app/

StopFrame is a high-performance web app that converts standard video into authentic stop-motion animation. By simulating "frame boil" and temporal downsampling, it recreates the jerky charm of traditional claymation directly in your browser.

🎨 Features

• Artistic Presets: One-click styles like "Classic Stop-Motion," "Cinematic Duo," and "Vintage 1920s."
• Temporal Downsampling: Precision control over frame rates (1-24 FPS) for that perfect "animated on twos" look.
• Hand-Moved Charm (Frame Boil): Simulate physical registration inconsistencies with adjustable jitter levels.
• Solo/Compare Modes: Instantly toggle between your raw input and transformed master to refine your aesthetic.
• Whimsical Processing: Real-time feedback with playful status updates and a sleek, animated progress interface.
• Client-Side Processing: High-performance rendering entirely in-browser using HTML5 Canvas and MediaRecorder.
• Premium Production Studio: A glassmorphic, responsive UI tailored for content creators and video editors.

🧠 The Strategy: "The Ghost Canvas"

1. Source Video: The actual <video> element is used as the data source but is often kept separate from the final visual output.
2. Sampling: The application samples frames from the video at a specific interval (e.g., 8 times per second).
3. Canvas Drawing: Each sampled frame is drawn onto an HTML5 <canvas>. During this step, "Frame Boil" is applied via random CSS transforms or canvas offsets.
4. Recording: The canvas stream is captured using canvas.captureStream() and recorded via the MediaRecorder API to generate a downloadable file.

🛠️ Tech Stack

• Framework: React 19
• Bundler: Vite
• Animations: Framer Motion
• Icons: Lucide React
• Styling: Vanilla CSS with a focus on modern aesthetics (Glassmorphism, HSL-tailored colors).

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repository:

   git clone https://github.com/peiyan0/stopframe.git
   cd stopframe

2. Install dependencies:

   npm install

3. Run the development server:

   npm run dev

🏗️ Project Structure

The project follows a modular React architecture for better maintainability:

• src/components/: Reusable UI components (Header, Controls, PreviewCard, UploadZone).
• src/constants/: Centralized configuration for presets and status messages.
• src/App.jsx: Main state management and core "Ghost Canvas" engine logic.
• src/index.css: Custom glassmorphic design system and layout utilities.

⚡ Performance Optimization

StopFrame is built for speed and responsiveness:

• React.memo: All UI components are memoized to prevent unnecessary re-renders during high-frequency progress updates.
• Offscreen Capture: Uses captureStream() on a canvas to ensure video processing happens at the desired frame rate regardless of UI load.
• Early Exit Handlers: Optimized processing loop with early termination logic to prevent resource leaks.

🎞️ Best Practices for the "Look"

The "Sweet Spot" FPS

For an authentic stop-motion feel, aim for:

• 12 FPS: The "cinematic" animation standard (animating on twos).
• 8 FPS: Gives it that distinct, jerky, amateur-claymation charm.

Adding "Boil"

Real stop-motion has "boil"—slight inconsistencies between frames because the physical objects move slightly. We simulate this by adding a tiny, random offset to the canvas every time a frame is drawn:

const offsetX = (Math.random() - 0.5) * jitter * 2;
const offsetY = (Math.random() - 0.5) * jitter * 2;
ctx.drawImage(video, sx + offsetX, sy + offsetY, sw, sh, 0, 0, canvas.width, canvas.height);

⚖️ License

MIT License. See LICENSE for details.