Skip to content
Back to search

oleg-motion

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bonchuk--oleg-motion/badge.svg)](/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

i

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.