gsap-motion

ساخت موشن‌های وب با GSAP و خروجی MP4 دقیق و قابل‌تکرار

این Skill ابتدا سناریو و storyboard موشن را طراحی می‌کند، سپس با یک master timeline متوقف‌شده در GSAP، صحنه‌های زمان‌بندی‌شده برای عنوان‌ها، کارت‌ها، شمارنده‌ها و معرفی محصول می‌سازد. هر فریم به‌صورت قطعی seek می‌شود تا خروجی وب و ویدیو یکسان باشند.

در پایان، یک صفحه وب زنده، فریم‌های PNG برای بازبینی و ویدیوی MP4 با کیفیت 1080p تحویل می‌گیرید. فرآیند شامل preflight، نمونه‌برداری ۶۰ فریم، بررسی بصری، اصلاح و رندر نهایی است؛ ScrollTrigger در مسیر رندر ویدیو پشتیبانی نمی‌شود.

چه چیزی می‌گیرید

• storyboard و plan.md با beatها، easingها و زمان‌بندی مشخص
• پروژه کامل شامل index.html، scene.js و package.json
• master timeline قطعی GSAP با رندر headless در Chromium
• فریم‌های PNG برای بازبینی و فایل نهایی MP4
• مسیر صفحه وب زنده برای استفاده یا ویرایش‌های بعدی

برای چه کاری خوب است

• ساخت animated explainer، معرفی محصول و hero animation برای وب
• نمایش متحرک آمار، شمارنده‌ها، progress bar و کارت‌های اطلاعاتی
• پروژه‌هایی که به یک خروجی مشترک برای صفحه وب و ویدیوی MP4 نیاز دارند
• موشن‌های timeline-driven با زمان‌بندی دقیق و قابل‌تکرار

برای چه کاری نیست

• انیمیشن‌های مبتنی بر اسکرول با ScrollTrigger که باید در مسیر ویدیو رندر شوند
• پروژه‌هایی که به تعامل زنده و ورودی کاربر به‌جای timeline ثابت نیاز دارند
• استفاده تجاری ناسازگار با محدودیت‌های GSAP Standard License، به‌ویژه بند non-compete

دربارهٔ این اسکیل

GSAP Motion

Produce web motion graphics with GSAP that also render to video.
Act as a creative director first: timelines reward choreography (staggered
entrances over simultaneous pops). Then act as a GSAP engineer: one paused
master timeline, seeked explicitly per frame — same second, same pixels.

Scroll-driven animation (ScrollTrigger) is NOT in the video path: scroll is
input, not time, and cannot be stepped deterministically. Timelines, tweens,
and staggers are. Scroll stories stay web-only and are out of scope for renders.

Workflow at a glance

Phase 0 PREFLIGHT -> Phase 1 PLAN -> Phase 2 CODE -> Phase 3 DRAFT (60 frames)
    -> Phase 4 FINAL (full) -> Phase 5 DELIVER
                                   ^
        revisions: edit -> check -> DRAFT again -> user approves -> FINAL

Project layout contract

<cwd>/videos-web/<topic-slug>/
├── plan.md       # storyboard from Phase 1
├── package.json  # {gsap, playwright}
├── index.html    # stage markup + <script src gsap> + <script src scene.js>
├── scene.js      # THE animation: one paused master timeline (Phase 2 writes this)
├── frames/       # stepped PNGs — never hand-edited, gitignored
└── final.mp4     # delivered video (Phase 4; the page itself stays live too)

Reuse the folder per topic for revisions.

The deterministic timeline contract (non-negotiable)

const tl = gsap.timeline({paused: true, defaults: {ease: "power3.out"}});
tl.from("#title", {y: 40, opacity: 0, duration: 1}, 0)
  .from(".card", {y: 30, opacity: 0, duration: 0.6, stagger: 0.15}, 0.5);

window.__tl = tl;
window.__meta = {fps: 60, duration: 3, width: 1280, height: 720};
tl.time(0);

The driver seeks tl.time(t) per frame and screenshots. Two laws:

1. The master timeline is paused: true and nothing else advances it.
2. page.evaluate callbacks use block bodies — NEVER return the timeline (returning it makes the driver serialize GSAP's circular object graph and hang forever with zero output).

Phase 0: Preflight

node <skill-dir>/scripts/preflight.mjs

Then per video project (GSAP library + headless stepper; Chromium binary once
per machine):

npm i gsap playwright --prefix <cwd>/videos-web/<slug>
npx playwright install chromium

GSAP installs from npm normally; the license restriction is on USE (review the
Standard License, non-compete clause), not on download.

Phase 1: Plan (no code yet)

Read references/gsap-api.md and classify into one tier:

Write <cwd>/videos-web/<slug>/plan.md: title, arc, beat list with concrete
tweens (from y:40 opacity:0, stagger 0.15, scaleX progress), easings,
palette. Fidelity rules: title mirrors the topic; state the point before
animating it.

Phase 2: Code

Hand-laid project (no scaffolder): package.json, index.html (stage markup,
fixed viewport size, gsap via /node_modules/gsap/dist/gsap.min.js), scene.js
(master timeline + contract).

Consult references/gsap-api.md,
references/troubleshooting.md, and
examples/ (hero-intro pair verified render; stat-counters pair).
Copy their patterns.

Coding standards:

• One master timeline, paused: true, all beats positioned absolutely (tl.from(..., position)). No delay:-chained mysteries — positions read top to bottom.
• transform-origin on the element being scaled, never its parent (a center-origin progress bar reads as broken).
• Fixed viewport stage (1280x720, overflow: hidden): screenshots capture CSS pixels 1:1.
• System font stacks for drafts; webfonts wired + still-reviewed before finals.

Gate before stepping (instant):

node --check <cwd>/videos-web/<slug>/scene.js

Phase 3: Draft render (mandatory, never skip)

node <skill-dir>/scripts/render.mjs --project <cwd>/videos-web/<slug> --frames 60

Default (no --frames) steps the full fps * duration span. Frames land in
<slug>/frames/ as zero-padded 6-digit PNGs.

Visual frame review (mandatory): open 3 PNGs (first/middle/last). Check:
entrances complete (no half-faded rests), stagger rhythm even, origins correct
(bars grow from the edge, not the middle), no overflow past the stage.
Fix, re-step, re-review.

Phase 4: Final render

node <skill-dir>/scripts/render.mjs --project <cwd>/videos-web/<slug>
ffmpeg -y -framerate <fps> -i <slug>/frames/%06d.png -c:v libx264 -pix_fmt yuv420p -crf 18 <slug>/final.mp4

Take <fps> from __meta. Prefer shared/ffmpeg/README.md over inventing flags.

Phase 5: Deliver

**Video ready**

Topic: <topic>
Plan recap:
- Beat 1: <one line>
...

File: <absolute path to final.mp4> (<WxH>@<fps>, ~M:SS estimated)
Source: <absolute path to videos-web/<slug>/scene.js (+ index.html live page)>

License note: GSAP is gratis but proprietary (Standard License, non-compete).
Confirm https://gsap.com/community/standard-license/ covers your use.

Want any changes? Timeline edits re-step fast at 60 frames; full render once satisfied.

Revision policy

1. Edit scene.js. 2. node --check. 3. Draft-step 60. 4. Iterate.
2. Full step + encode + redeliver.

Hard rules

• Paused master timeline only; ScrollTrigger never in the render path.
• Block-body evaluates (never return GSAP objects to the driver).
• Always preflight before planning; always check before stepping; always draft + frame review before finals.
• Never hand-edit frames/; regenerate via the driver.
• One video project per topic under <cwd>/videos-web/<slug>/.
• If any phase fails repeatedly (2+ fix attempts), report the blocker honestly.

دانلود ZIP