oleg-motion
Turn static images into polished motion — looping banners, animated ads, stories, cinemagraph-style clips (MP4/WebM/GIF). Works from a flat JPG/PNG (auto-splits it into background, subject and text layers with depth), a layered PSD, or a folder of PNG layers, and adds parallax/2.5D camera moves, particles (snow, leaves, dust, confetti, bokeh), light (shine sweeps, star glints, flares, glow) and text/product motion while keeping prices, logos and legal text crisp. Use this skill whenever someone wants to animate, "оживити", bring to life, add motion or effects to a picture, banner, poster, product shot or PSD; asks for a looping video banner, animated GIF, motion ad, story/reel from an image, parallax or cinemagraph; or shows an animated banner and wants "something like this" — even if they never say "animation".
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bonchuk--oleg-motion)HTML
<a href="/listings/bonchuk--oleg-motion"><img src="/api/listings/bonchuk--oleg-motion/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
oleg-motion runs inside **Claude Code** — the terminal CLI, the IDE extensions, or the Code mode of the Claude desktop app. It does not work in regular claude.ai chats: rendering needs a local browser, ffmpeg and (optionally) local ML models.
What you need
- A Mac (Apple Silicon recommended) with the **Claude desktop app** and a plan that includes Claude Code. Nothing else: no GitHub account, no Terminal, no Homebrew, no admin password. - About **1.5 GB** of free disk space.
Setup downloads whatever is missing — Node.js (nodejs.org), ffmpeg (static build from ffmpeg.martin-riedl.de), Python (via Astral's `uv`) and Chromium (only if Google Chrome is absent) — as private copies into `~/.cache/oleg-motion`. Tools already installed on the machine are used instead when they are recent enough. Nothing outside that folder and `~/.rembg` (the cut-out model) is changed.
- **Linux** works the same, except automatic text detection (Apple Vision OCR is macOS-only) and ffmpeg, which you install with your package manager (`apt install ffmpeg`). - **Windows** is untested.
Option A — ask Claude to install it (recommended)
Open the Claude desktop app, switch to **Code**, and say (any language works):
> Install the oleg-motion skill: download https://github.com/bonchuk/oleg-motion/archive/refs/heads/main.zip, > unpack it into `~/oleg-motion`, link that folder into `~/.claude/skills/oleg-motion`, > then run `bash ~/oleg-motion/scripts/setup.sh --ml`.
Claude asks permission for each step — allow them. The first setup takes 10–20 minutes, mostly downloads. Then start a new session, drop an image and say "animate this".
Option B — manual (Terminal)
curl -L -o /tmp/om.zip https://github.com/bonchuk/oleg-motion/archive/refs/heads/main.zip mkdir -p ~/oleg-motion && tar -xf /tmp/om.zip -C ~/oleg-motion --strip-components 1 mkdir -p ~/.claude/skills && ln -s ~/oleg-motion ~/.claude/skills/oleg-motion bash ~/oleg-motion/scripts/setup.sh --ml # or: no flag = core only, --psd = core + PSD import
Developers can `git clone https://github.com/bonchuk/oleg-motion.git ~/oleg-motion` instead of the first two lines.
`setup.sh` levels:
| command | gives you | download | |---|---|---| | `setup.sh` | the engine: animate any image as a whole (camera, particles, light, overlays), PNG layer folders | ~20 MB (+ Node ~50 MB, ffmpeg ~55 MB, Chromium ~150 MB — each only if missing) | | `setup.sh --psd` | + layered PSD import | + ~110 MB (+ Python ~40 MB if missing) | | `setup.sh --ml` | + automatic layers from a flat image (subject cut-out, text, inpainting, depth) and region cut-outs | + ~1 GB (packages + models, first run only) |
`~/oleg-motion/om doctor` shows what is installed and what is missing. Set `OLEG_MOTION_HOME` to keep tools, the Python environment and models somewhere other than `~/.cache/oleg-motion`.
Update
Tell Claude "update the oleg-motion skill", or run `~/oleg-motion/om update`. It pulls with git when the folder is a git checkout and otherwise downloads the latest archive (your own files, such as brand kits, are kept), then re-runs setup at the installed level. Downloads already done are reused.
Uninstall
rm ~/.claude/skills/oleg-motion rm -rf ~/oleg-motion ~/.cache/oleg-motion ~/.rembg/models/birefnet-general-lite
Brand kits
Teams can keep their brand rules (palette, default format, what must never move) in a JSON kit — in `brands/` of this repo or next to their own files. See `references/brand-kit.md`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 192 lines
- ---
- name: oleg-motion
- description: Turn static images into polished motion — looping banners, animated ads, stories, cinemagraph-style clips (MP4/WebM/GIF). Works from a flat JPG/PNG (auto-splits it into background, subject and text layers with depth), a layered PSD, or a folder of PNG layers, and adds parallax/2.5D camera moves, particles (snow, leaves, dust, confetti, bokeh), light (shine sweeps, star glints, flares, glow) and text/product motion while keeping prices, logos and legal text crisp. Use this skill whenever someone wants to animate, "оживити", bring to life, add motion or effects to a picture, banner, poster, product shot or PSD; asks for a looping video banner, animated GIF, motion ad, story/reel from an image, parallax or cinemagraph; or shows an animated banner and wants "something like this" — even if they never say "animation".
- ---
- # oleg-motion
- Deterministic motion design from still images: an HTML scene rendered frame by frame in
- headless Chrome, encoded with ffmpeg. Everything is a pure function of time, so loops close
- exactly and renders are reproducible. Talk to the user in their language; keep file names
- and scene JSON in English.
- `$OM` below means the directory of this skill (the folder containing this SKILL.md).
- ## 0. Make sure it runs (once per machine)
- Run everything through the launcher `$OM/om` — it puts the skill's own Node, ffmpeg and
- Python first on PATH, so it works on a clean Mac with no developer tools.
- ```bash
- $OM/om doctor # what is installed
- bash $OM/scripts/setup.sh # core: Node.js, ffmpeg, rendering engine (downloads what is missing)
- $OM/om setup --psd # + PSD import
- $OM/om setup --ml # + auto-layers for flat images (~1 GB incl. models)
- $OM/om update # latest version from GitHub (works without git), then setup again
- ```
- Setup needs no admin password, Homebrew or git: missing tools are downloaded into
- `~/.cache/oleg-motion/tools` (override the folder with `OLEG_MOTION_HOME`); tools already on
- the machine are used when good enough. Core alone can already animate any image (camera,
- particles, light, overlays). Ask before running `--ml` — it downloads models. If `om` is not
- executable (unpacked from a zip), call `bash $OM/om …`.
- ## 1. Brief — look first, then ask with clickable options
- People drop a file and say "make it move". Most can't describe motion in words, so don't
- ask open questions — **look at the image yourself first** (open it), list its elements
- (headline, price, button, logo, photos, product, arrows…), then ask.
- **Brand kit first.** If the request names a brand/project, or a `*.brand.json` /
- `oleg-motion.brand.json` sits in the working folder, or `$OM/brands/` has a matching kit,
- load it and pass `--brand` to `scene`: its defaults answer most questions (skip those) and
- its `protect` / `avoid` / `notes` are hard rules. Format: references/brand-kit.md. No kit yet →
- offer to save one at delivery (step 6).
- **Never ask about craft** — timings, easing, amplitudes, staggers, particle counts are
- professional defaults (references/motion-guidelines.md). Change them only when the person
- asks. Every question offers a default they can just accept.
- **Skip the questions** when the user says "просто зроби" / "just do it" / "on your own",
- or answers are already in the request: pick defaults and state them in one line.
- **Otherwise ask once, with options** — use the `AskUserQuestion` tool when available
- (clickable cards; otherwise one message with numbered options). Up to 4 questions, each
- with your recommended option first, built from what you saw in the image:
- 1. **Where will it live?** → profile: **"як є — не змінювати пропорції"** (`source`: the
- original aspect ratio, long side capped at 1920 px), Instagram post 4:5
- (`feed-portrait`), Stories/Reels 9:16 (`story`), website banner (`web-hero` /
- `web-strip`), display ad GIF (`display-*`). Fit the 4 options to the image: if its ratio
- already matches a format (e.g. 4:5 → Instagram post), offer that format instead of a
- separate "як є" (same result) and recommend it; otherwise recommend "як є" first.
- A format with another ratio crops the image (`fit: cover`) or adds blurred margins
- (`contain-blur`) — say which, and what it cuts off (headline edges, the CTA), so the
- person isn't surprised.
- 2. **Character?** → 3–4 moods that fit the picture, described by feeling, not by name:
- "calm & premium", "energetic", "festive", "barely moving". Mention the matching mood
- in the description (`premium`, `energetic`, `festive`, `calm` …; full list: `$OM/om moods`).
- 3. **Structure?** → "elements appear, then loop" (`intro-loop`, good for social posts),
- "seamless loop only" (`loop`, good for site banners), "one pass with an ending" (`oneshot`).
- 4. **What is the hero?** (multiSelect) → the 3–4 most prominent elements you found, e.g.
- "headline SUMMER SALE", "CTA button", "photos", "product". The hero gets the main motion;
- everything else stays calm.
- Defaults if unanswered: profile from aspect ratio, 6 s (intro 2 s + loop 4 s for
- intro-loop), MP4, mood chosen from the palette and subject. A reference video ("like this")
- beats any answer — break it down with references/reference-analysis.md and copy its
- rhythm, not its content.
- ## 2. Motion plan — agree in words before rendering
- Before the first render, show the plan in plain language (user's language), one line per
- element, with timing — e.g.:
- > **Інтро (2 с):** логотип з'являється → заголовок піднімається рядками → «-30%»
- > вискакує → кнопка й товар з'являються знизу.
- > **Петля (4 с):** «-30%» ледь світиться, по ньому пробігає блиск · кнопка пульсує ·
- > товар ледь плаває · теплий пил на фоні.
- > **Не рухається:** логотип (лише іскра), ціна після появи, дати.
- Ask "Так робимо, чи щось змінити?" in the same message and proceed only after a yes (or
- when the user skipped questions — then render straight away and show the plan with the
- result). Changing the plan costs seconds; changing a render costs minutes. The plan also decides
- which elements need their own layer in the next step.
- ## 3. Get layers
- Pick by input — the goal is a `layers.json` with roles (see references/scene-format.md):
- | input | command |
- |---|---|
- | flat JPG/PNG, ML installed | `$OM/om py $OM/scripts/ml/auto_layers.py in.jpg --out work/layers` |
- | PSD | `$OM/om py $OM/scripts/psd_layers.py in.psd --out work/layers` |
- | folder of PNG layers | `$OM/om layers-from-dir path/to/pngs` |
- | designed creative (cards, buttons, arrows, photos with heads over the frame) or auto-layers got it wrong | write `regions.json` (boxes/polygons + mask mode) → `$OM/om py $OM/scripts/ml/cut_regions.py regions.json --out work/layers` (format in the script's docstring) |
- | flat image, no ML | write layers.json by hand: one `background` layer (and ask for text boxes if particles must avoid text) |
- For `regions.json`, find coordinates by measuring, not by eye: threshold bright/dark pixels
- and print component bounding boxes; for photo cards scan for the frame's colour and fit the
- edges (a polygon 3–5 px inside the real edge leaves a bright line in the background and
- clips the card). Use `mask: "contrast"` for text/logos/lines on a plain background, `"full"`
- + `popout` for photo cards with a head sticking out, `"seg"` for objects on busy photos.
- **Always open `preview.png` / the layer PNGs and check the split** before building the scene:
- auto-layers can mislabel (a logo detected as text, a price as headline, a subject that is
- really background). Fix roles in layers.json — roles decide what may move. If the subject
- cut-out is poor, drop that layer rather than animating a ragged edge.
- ## 4. Build the scene
- ```bash
- $OM/om scene --layers work/layers/layers.json --mood energetic \
- --profile feed-portrait --structure intro-loop [--brand brand.json] \
- [--intensity 1] [--speed 1] [--density 1] --out work/scene.json
- ```
- This drafts `scene.json` from the mood bundle (and brand kit). Then edit it to match the
- agreed plan — that is where the craft is: per-layer intro timings staggered 50–100 ms
- (whole cascade ≤ 2 s, entrances 400–800 ms, ease-out; bounce only on one playful element),
- the hero's light/glow, decor motion (arrows bounce, badges spin), particles in one accent
- colour from the image or brand kit. Read references/effects.md for every effect and its parameters, and
- references/motion-guidelines.md for limits that keep it professional.
- ## 5. Render, look, iterate
- ```bash
- $OM/om render work/scene.json --out work/out --quality draft # fast check
- $OM/om render work/scene.json --out work/out --formats mp4,webm,gif # final
- ```
- After every render **look at `*-sheet.jpg`** (8 frames) and, when something is in doubt,
- extract single frames (`ffmpeg -ss 2.5 -i out.mp4 -frames:v 1 f.png`) and view them. The
- report (`*-report.json`, summarised in stderr) checks: loop seam, flashes (≤3/s), locked
- layers not moving, safe zones (text/price/CTA ≥ 10 % from edges, logos ≥ 5 %; `cut` = a
- format change cropped it, `as-designed` = the source was already that tight), file budget.
- Fix failures before delivering — a visible seam usually
- means a non-integer `cycles`; a budget failure means fewer particles/grain, or lower GIF
- size/fps.
- Show the user the draft (contact sheet or the MP4) and invite tweaks in their own words —
- "повільніше", "менше блиску", "без частинок", "кнопку яскравіше", "прибери інтро".
- references/tweaks.md maps such phrases to scene edits; apply them, re-render as draft,
- and render the final only when they are happy.
- Cost on a laptop (M1, 8 GB): auto-layers ≈ 3–4 min per image (run it once, then iterate on
- the scene); render ≈ 0.2–0.4 s per frame (6 s at 30 fps ≈ 1 min). Tell the user before
- long steps.
- ## 6. Deliver
- Give the user: the files (paths + sizes), the poster JPG, one sentence on what moves, and
- for websites the embed hint `<video autoplay muted loop playsinline poster="…">`. If the
- target platform has hard limits (exact size, codec, max MB), say they were met — or not.
- If this was a brand's job and no kit exists yet, offer in one line to save one
- (references/brand-kit.md) so next time the questions are already answered.
- ## Rules that keep it good (and why)
- - **One hero motion, ≤ two ambient ones.** Viewers read one thing at a time; extra motion
- competes with the message.
- - **Prices, legal text and logos stay rigid.** Movement blurs and wobbles letterforms —
- readability and brand trust beat flair. Roles enforce this; don't reassign a price to
- `text` to get motion on it.
- - **Don't fake a person's movement.** A cut-out person can't run or wave; bobbing or
- pulsing the whole figure looks like a cardboard puppet. Give people depth (camera
- parallax) and an intro, nothing more.
- - **Small amplitudes.** 3–6 % camera push, 2–4° tilt, ≤ 2 % breathe. Large zooms and
- parallax cause motion sickness and look amateur.
- - **Whole cycles only.** The loop is seamless because every motion completes an integer
- number of cycles per loop — never set fractional `cycles`.
- - **First frame = finished poster.** In `loop` the first frame already has everything in
- place; use `intro-loop` when entrances are wanted.
- - **No generative redraw of text.** This skill never repaints text or products; AI video
- (optional, see references/ai-video.md) is only for backgrounds, with the original layers
- composited back on top.
- ## Troubleshooting
- - `Playwright is not installed`, `Node.js is missing`, `ffmpeg` errors → `bash $OM/scripts/setup.sh`.
- - Blank or black frames → a layer path is wrong (check stderr warnings) or the scene has
- no background layer.
- - Text detection skipped → `ocrmac` is macOS-only; elsewhere pass text layers manually.
- - Edge halos in parallax → lower `depthParallax.amp`, or inpaint the plate (auto-layers
- does it unless `--no-inpaint`).
- - GIF too big → `display-*` profiles shrink it automatically; otherwise lower fps/width.
README.md · README · 119 lines
- # oleg-motion
- A Claude Code skill (and standalone CLI) that turns still images into motion: seamless
- looping banners, intro + loop ads, stories and short one-shots in MP4 / WebM / GIF.
- - **Inputs**: a flat JPG/PNG (auto-split into background, subject, text and depth), a
- layered PSD, or a folder of PNG layers.
- - **Effects**: 2.5D/parallax camera, depth displacement, particles (snow, leaves, dust,
- sparks, confetti, bokeh, petals, hearts, bubbles, custom sprites), light (shine sweeps,
- star glints, lens flares, glow, rays, light leaks), text/product motion (tilt, breathe,
- float, sway), intros (fade, rise, slide, pop, wipe), fog, grain, vignette, water waves.
- - **Moods**: one command drafts a full scene — calm, premium, festive, autumn, spring,
- summer, hot-sale, energetic, launch, love, night, nature.
- - **Brief in clicks**: the agent looks at the image, asks up to 4 multiple-choice questions
- (where, character, structure, hero element), agrees a plain-language motion plan before
- rendering, and takes tweaks in everyday words ("slower", "less shine", "no intro").
- - **Brand kits**: a small JSON per brand (palette, defaults, what never moves, what to avoid).
- - **Checks**: loop seam, flashes (WCAG 2.3.1), prices/legal text not moving, file budgets,
- plus a contact sheet for a quick visual review.
- - **Engine**: an HTML scene rendered frame-by-frame in headless Chrome (Playwright) and
- encoded with ffmpeg. Deterministic — the same scene always renders the same frames.
- ## Installation
- oleg-motion runs inside **Claude Code** — the terminal CLI, the IDE extensions, or the Code
- mode of the Claude desktop app. It does not work in regular claude.ai chats: rendering needs
- a local browser, ffmpeg and (optionally) local ML models.
- ### What you need
- - A Mac (Apple Silicon recommended) with the **Claude desktop app** and a plan that includes
- Claude Code. Nothing else: no GitHub account, no Terminal, no Homebrew, no admin password.
- - About **1.5 GB** of free disk space.
- Setup downloads whatever is missing — Node.js (nodejs.org), ffmpeg (static build from
- ffmpeg.martin-riedl.de), Python (via Astral's `uv`) and Chromium (only if Google Chrome is
- absent) — as private copies into `~/.cache/oleg-motion`. Tools already installed on the
- machine are used instead when they are recent enough. Nothing outside that folder and
- `~/.rembg` (the cut-out model) is changed.
- - **Linux** works the same, except automatic text detection (Apple Vision OCR is macOS-only)
- and ffmpeg, which you install with your package manager (`apt install ffmpeg`).
- - **Windows** is untested.
- ### Option A — ask Claude to install it (recommended)
- Open the Claude desktop app, switch to **Code**, and say (any language works):
- > Install the oleg-motion skill: download https://github.com/bonchuk/oleg-motion/archive/refs/heads/main.zip,
- > unpack it into `~/oleg-motion`, link that folder into `~/.claude/skills/oleg-motion`,
- > then run `bash ~/oleg-motion/scripts/setup.sh --ml`.
- Claude asks permission for each step — allow them. The first setup takes 10–20 minutes,
- mostly downloads. Then start a new session, drop an image and say "animate this".
- ### Option B — manual (Terminal)
- ```bash
- curl -L -o /tmp/om.zip https://github.com/bonchuk/oleg-motion/archive/refs/heads/main.zip
- mkdir -p ~/oleg-motion && tar -xf /tmp/om.zip -C ~/oleg-motion --strip-components 1
- mkdir -p ~/.claude/skills && ln -s ~/oleg-motion ~/.claude/skills/oleg-motion
- bash ~/oleg-motion/scripts/setup.sh --ml # or: no flag = core only, --psd = core + PSD import
- ```
- Developers can `git clone https://github.com/bonchuk/oleg-motion.git ~/oleg-motion` instead
- of the first two lines.
- `setup.sh` levels:
- | command | gives you | download |
- |---|---|---|
- | `setup.sh` | the engine: animate any image as a whole (camera, particles, light, overlays), PNG layer folders | ~20 MB (+ Node ~50 MB, ffmpeg ~55 MB, Chromium ~150 MB — each only if missing) |
- | `setup.sh --psd` | + layered PSD import | + ~110 MB (+ Python ~40 MB if missing) |
- | `setup.sh --ml` | + automatic layers from a flat image (subject cut-out, text, inpainting, depth) and region cut-outs | + ~1 GB (packages + models, first run only) |
- `~/oleg-motion/om doctor` shows what is installed and what is missing. Set
- `OLEG_MOTION_HOME` to keep tools, the Python environment and models somewhere other than
- `~/.cache/oleg-motion`.
- ### Update
- Tell Claude "update the oleg-motion skill", or run `~/oleg-motion/om update`. It pulls with
- git when the folder is a git checkout and otherwise downloads the latest archive (your own
- files, such as brand kits, are kept), then re-runs setup at the installed level. Downloads
- already done are reused.
- ### Uninstall
- ```bash
- rm ~/.claude/skills/oleg-motion
- rm -rf ~/oleg-motion ~/.cache/oleg-motion ~/.rembg/models/birefnet-general-lite
- ```
- ### Brand kits
- Teams can keep their brand rules (palette, default format, what must never move) in a
- JSON kit — in `brands/` of this repo or next to their own files. See
- `references/brand-kit.md`.
- ## CLI in 3 commands
- ```bash
- ./om py scripts/ml/auto_layers.py banner.jpg --out work/layers
- ./om scene --layers work/layers/layers.json --mood autumn --profile story --out work/scene.json
- ./om render work/scene.json --out work/out --formats mp4,webm,gif
- ```
- See `SKILL.md` for the agent workflow, `references/` for the effect catalogue and scene
- format, and `docs/research/` for the research behind the defaults.
- ## Models and licences
- Only permissively licensed models are used by default: BiRefNet (MIT, via rembg),
- LaMa (Apache-2.0, ONNX), Depth Anything V2 **Small** (Apache-2.0, ONNX), Apple Vision
- OCR (macOS system framework). Non-commercial checkpoints (BRIA RMBG-2.0, Depth Anything
- Base/Large) are intentionally not used.
- ## License
- MIT — see `LICENSE`. Models downloaded at setup keep their own licences (listed above).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.