oil-oil/oil-motion

What is Oil Motion?

Oil Motion is a tool that lets you create interactive, AI‑generated animations for web pages. Instead of writing CSS, JavaScript, or hand‑crafting video assets, you describe what you want to happen, give the source images or video, and the system (referred to as an Agent) will:

1. Design the key frames – the important “start”, “mid” and “end” pictures that define the animation’s structure.
2. Generate the in‑between motion with an AI video model.
3. Clean‑up, compress, and package the resulting frames into a web‑friendly format (MP4, WebP sprite‑sheet, etc.).
4. Wire the animation to user input – scroll, mouse movement, drag, touch, or device orientation – so the visual reacts in real time.

The whole pipeline is packaged as a Skill that can be installed into an AI‑agent platform (e.g., via npx skills add oil-oil/oil-motion). Once installed, the agent can be asked to produce a complete interactive animation with a single natural‑language command.

---

Who might use it?

• Product marketers who want a product‑exploded‑view that expands as the visitor scrolls.
• Game or character designers who need a character’s face to follow the cursor.
• Technical documentation writers who want a 3‑D‑like walkthrough of a device without writing WebGL code.
• Front‑end teams that prefer AI‑generated assets over manually drawing dozens of frames.

It is not meant for simple UI transitions (button hover, modal fade‑in) that can be done with CSS/JS, nor for full‑length video editing.

---

How does it work?

1. Define the goal – the user tells the agent the desired effect, the input media, and the control method (scroll, mouse, etc.).
2. Confirm key frames – the agent first generates a few critical frames and checks that the subject, style, and composition stay consistent.
3. Generate motion – an AI video model (accessed through the ZenMux service) creates the frames that interpolate between the key frames.
4. Post‑process – the agent removes pauses, duplicate frames, and visual glitches, then compresses the result to the appropriate format:
   • Full‑scene MP4 for narrative shots.
   • Alpha‑WebP sprite‑sheet for small 2‑D assets.
   • Green‑screen MP4 for large, scroll‑driven sequences.
5. Export – a ready‑to‑drop‑in JavaScript bundle, configuration file, and the optimized media are produced, along with a preview page.

All heavy lifting (AI generation, compression) happens offline; the browser only seeks within the pre‑generated frames, ensuring smooth, low‑latency interaction.

---

What does the repo contain?

Item	Purpose
SKILL.md	Specification of the Skill’s commands, inputs, and outputs.
references/	Docs on API‑key setup, ZenMux integration, and other technical details.
assets/readme/hero.svg	Visual banner for the README.
License	MIT – free to use and modify.

The repository does not ship the AI models themselves; it relies on the external ZenMux service (accessed with an API key) for image/video generation.

---

How to get started?

1. Install the Skill – either ask your agent (帮我安装 …) or run npx skills add oil-oil/oil-motion.
2. Provide an API key – a one‑time configuration page (Node 22+) stores the key in the OS credential store.
3. Issue a natural‑language request – e.g.,

   使用 oil-motion，把这两张产品图制作成随页面滚动逐步展开的动画。
   

4. The agent will:
   • generate/validate key frames,
   • call ZenMux to create the motion,
   • clean and compress the assets, and
   • output a ready‑to‑embed animation bundle.

---

Limitations & scope

• Works best when the subject needs to change shape or pose (product disassembly, character turning, camera fly‑through).
• Not intended for simple CSS/JS transitions, static image galleries, or full‑length video editing.
• Requires an external AI video service (ZenMux) and will incur usage costs per generation.
• The agent cannot fix a fundamentally wrong motion design; you must revise the key frames or prompts.

---

TL;DR

Oil Motion is an AI‑driven pipeline that turns a description and source media into a scroll‑, mouse‑, or touch‑controlled animation ready for the web. Install it as a Skill, give it an API key, and ask the agent to create the animation – the system handles key‑frame design, AI video generation, cleanup, compression, and code integration.