walkthrough-video

演示视频生成器

使用 Remotion，通过应用截图或实时网站创建专业的演示视频。生成带有转场、缩放效果和文字叠加的流畅精致 MP4 视频。

概述

此技能会获取一组截图（也可以从运行中的应用中截取），并将其编排为 Remotion 视频合成，其中包括：

• 流畅转场，在不同画面之间切换（淡入淡出、滑动、擦除）
• 缩放效果，突出显示特定 UI 区域
• 文字叠加，包含标题、描述和提示说明
• 进度指示器，显示演示中的当前位置
• 可选旁白音轨

前提条件

• 已安装 Node.js 18+
• 应用的截图（或可供截图的运行中应用）
• 无需 Remotion 使用经验——此技能会生成所有代码

工作流

步骤 1：收集截图

选择一种方式：

选项 A：使用现有截图

如果用户已有截图（例如来自 design-loop 或 product-showcase）：

Read screenshots from:
- .design/screenshots/
- .jez/screenshots/
- User-specified directory

按演示顺序排列（按文件名的字母顺序排列，或按用户指定的顺序排列）。

选项 B：从运行中的应用截取

如果应用正在本地运行：

1. 启动 Playwright CLI 会话
2. 按顺序浏览每个画面
3. 使用统一的尺寸截图（视频推荐使用 1280x720）
4. 保存到 video/public/screens/

playwright-cli -s=walkthrough open http://localhost:3000
playwright-cli -s=walkthrough resize 1280 720
playwright-cli -s=walkthrough screenshot --filename=video/public/screens/01-home.png
# Navigate to next page...
playwright-cli -s=walkthrough screenshot --filename=video/public/screens/02-dashboard.png

选项 C：从实时 URL 截取

与选项 B 相同，但使用公共 URL。截取每个关键页面。

步骤 2：创建画面清单

构建描述演示内容的 screens.json：

{
  "projectName": "My App Walkthrough",
  "fps": 30,
  "width": 1280,
  "height": 720,
  "screens": [
    {
      "id": "home",
      "title": "Welcome to MyApp",
      "description": "The landing page introduces the core value proposition",
      "imagePath": "screens/01-home.png",
      "durationSeconds": 4,
      "transition": "fade",
      "zoomTarget": null
    },
    {
      "id": "dashboard",
      "title": "Your Dashboard",
      "description": "See all your projects at a glance",
      "imagePath": "screens/02-dashboard.png",
      "durationSeconds": 5,
      "transition": "slide-left",
      "zoomTarget": { "x": 100, "y": 200, "width": 400, "height": 300, "delay": 2 }
    }
  ]
}

字段	类型	描述
id	string	唯一画面标识符
title	string	文字叠加标题
description	string	副标题或旁白文本
imagePath	string	相对于 video/public/ 的路径
durationSeconds	number	此画面的显示时长
transition	string	fade、slide-left、slide-right、slide-up、wipe、none
zoomTarget	object/null	若设置，则在 delay 秒后缩放到此区域

步骤 3：搭建 Remotion 项目

如果不存在 Remotion 项目：

mkdir -p video
cd video
npm init -y
npm install remotion @remotion/cli @remotion/transitions react react-dom
npm install -D typescript @types/react

创建项目结构：

video/
├── src/
│   ├── Root.tsx                    # Remotion entry point
│   ├── WalkthroughComposition.tsx  # Main composition
│   ├── components/
│   │   ├── ScreenSlide.tsx         # Individual screen display
│   │   ├── TextOverlay.tsx         # Title/description overlay
│   │   ├── ProgressBar.tsx         # Walkthrough progress indicator
│   │   └── ZoomEffect.tsx          # Zoom into regions
│   └── config.ts                   # Load screens.json, calculate durations
├── public/
│   └── screens/                    # Screenshot assets
│       ├── 01-home.png
│       └── 02-dashboard.png
├── screens.json                    # Screen manifest
├── remotion.config.ts
├── tsconfig.json
└── package.json

步骤 4：生成 Remotion 组件

生成每个组件文件。关键模式：

Root.tsx

import { Composition } from "remotion";
import { WalkthroughComposition } from "./WalkthroughComposition";
import { screens, totalDurationInFrames, FPS, WIDTH, HEIGHT } from "./config";

export const RemotionRoot = () => (
  <Composition
    id="Walkthrough"
    component={WalkthroughComposition}
    durationInFrames={totalDurationInFrames}
    fps={FPS}
    width={WIDTH}
    height={HEIGHT}
    defaultProps={{ screens }}
  />
);

ScreenSlide.tsx 模式

import { AbsoluteFill, Img, spring, useCurrentFrame, useVideoConfig } from "remotion";

interface ScreenSlideProps {
  imageSrc: string;
  title: string;
  description: string;
}

export const ScreenSlide: React.FC<ScreenSlideProps> = ({ imageSrc, title, description }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  // Fade in
  const opacity = spring({ frame, fps, config: { damping: 20 } });

  // Subtle zoom (Ken Burns effect)
  const scale = 1 + frame * 0.0002;

  return (
    <AbsoluteFill style={{ backgroundColor: "#000" }}>
      <Img
        src={imageSrc}
        style={{
          width: "100%",
          height: "100%",
          objectFit: "contain",
          opacity,
          transform: `scale(${scale})`,
        }}
      />
      {/* Text overlay at bottom */}
      <div style={{
        position: "absolute",
        bottom: 40,
        left: 40,
        right: 40,
        opacity: spring({ frame: frame - 15, fps, config: { damping: 20 } }),
      }}>
        <h2 style={{ color: "#fff", fontSize: 32, fontWeight: 700, textShadow: "0 2px 8px rgba(0,0,0,0.8)" }}>
          {title}
        </h2>
        <p style={{ color: "#ccc", fontSize: 18, textShadow: "0 1px 4px rgba(0,0,0,0.8)" }}>
          {description}
        </p>
      </div>
    </AbsoluteFill>
  );
};

画面间转场

使用 @remotion/transitions 实现转场：

import { TransitionSeries } from "@remotion/transitions";
import { fade } from "@remotion/transitions/fade";
import { slide } from "@remotion/transitions/slide";

// In WalkthroughComposition:
<TransitionSeries>
  {screens.map((screen, i) => (
    <TransitionSeries.Sequence
      key={screen.id}
      durationInFrames={screen.durationSeconds * FPS}
    >
      <ScreenSlide {...screen} />
    </TransitionSeries.Sequence>
    // Add transition between screens (not after last)
    {i < screens.length - 1 && (
      <TransitionSeries.Transition
        presentation={getTransition(screens[i + 1].transition)}
        timing={springTiming({ config: { damping: 20 }, durationInFrames: 15 })}
      />
    )}
  ))}
</TransitionSeries>

步骤 5：预览并优化

cd video
npx remotion studio

这会打开基于浏览器的预览。检查：

• 每个画面的时长是否合适
• 转场是否流畅
• 文字叠加是否清晰易读
• 缩放目标是否准确定位到相应区域
• 进度条（如有）是否准确

步骤 6：渲染视频

cd video
npx remotion render Walkthrough output.mp4 --codec h264

要获得更高质量：

npx remotion render Walkthrough output.mp4 --codec h264 --quality 90

要为 Web 优化（减小文件体积）：

npx remotion render Walkthrough output.webm --codec vp8

高级功能

缩放到区域

放大屏幕上的特定区域，以突出某项功能：

// In ZoomEffect.tsx — interpolate scale and translate
const zoomScale = interpolate(frame, [delayFrames, delayFrames + 30], [1, 2.5], {
  extrapolateRight: "clamp",
});
const translateX = interpolate(frame, [delayFrames, delayFrames + 30], [0, -targetX], {
  extrapolateRight: "clamp",
});

动画提示圆圈

吸引注意力到 UI 元素上：

// Pulsing circle that appears at a specific point
const scale = spring({ frame: frame - delay, fps, config: { damping: 8, stiffness: 80 } });
<div style={{
  position: "absolute",
  left: x - 20, top: y - 20,
  width: 40, height: 40,
  borderRadius: "50%",
  border: "3px solid #3B82F6",
  transform: `scale(${scale})`,
  opacity: Math.min(1, scale),
}} />

背景音乐

添加一段轻柔的背景音轨：

import { Audio } from "remotion";

<Audio src={staticFile("music/background.mp3")} volume={0.15} />

片头和片尾画面

在开头添加标题卡片，在结尾添加 CTA：

// First sequence: Title card (3 seconds)
<TransitionSeries.Sequence durationInFrames={90}>
  <TitleCard projectName="MyApp" tagline="The future of project management" />
</TransitionSeries.Sequence>

// ... screen sequences ...

// Last sequence: CTA card (4 seconds)
<TransitionSeries.Sequence durationInFrames={120}>
  <CtaCard url="myapp.com" text="Try it free" />
</TransitionSeries.Sequence>

转场参考

名称	效果	适用场景
fade	交叉淡化	默认选项，适用于各种场景
slide-left	新画面从右侧滑入	顺序流程（下一页）
slide-right	新画面从左侧滑入	返回上一页
slide-up	新画面从底部滑入	深入查看详情
wipe	擦除转场	戏剧化揭示
none	直接切换	快速对比

输出选项

格式	命令	用途
MP4 (H.264)	--codec h264	通用兼容性
WebM (VP8)	--codec vp8	网页嵌入，文件体积更小
GIF	--image-format png 然后使用 ffmpeg	短循环动画、社交媒体
PNG 序列	--image-format png --sequence	后期制作编辑

提示与常见问题

• 1280×720，每个画面 3-5 秒，总时长不超过 90 秒——超出这些限制，观众的注意力会下降
• 淡入淡出是最稳妥的转场效果——选择 1-2 种转场效果并保持一致
• 文字叠加需要有足够的对比度——使用 text-shadow 或半透明背景；文字太小或对比度太低，会显得像是“AI 做的”
• Ken Burns（轻微缩放）能避免静态截图显得死板。添加片头和片尾卡片，让视频过渡更自然
• 渲染前先预览——与完整渲染相比，npx remotion studio 能节省时间
• 使截图尺寸一致（尺寸不匹配会导致缩放问题）。对 public/ 资源使用 staticFile()