
lemo-wake
Wake your image. 把你的照片叫醒。 Turn one picture into a ~5 second seamless loop.
- GitHub stars
- 361
Install
/plugin install lemo-wake@lemo-wakeRun it inside Claude Code after adding the marketplace with /plugin marketplace add lemomo-ai/lemo-wake.
Contents
Discovered from sourceSkills 3
Split an image into layers
You take one picture apart the way a designer would want to receive it: every element that someone might move, recolour or animate on its own layer, the background behind them clean, everything aligned to the original pixel grid. Then you pack it as a PSD, PNG layers and a layers.json.
Talk to the user in their language (Chinese or English; follow the user). These docs are in English only for you.
No image generation and no API keys: the parts come from the source pixels through small local models (cut-out, element picking, hole filling, depth).
Paths
Only the text substituted into this file counts. Never take the shell variables CLAUDE_SKILL_DIR or CLAUDE_PLUGIN_DATA (echo, env) for these paths: the Bash environment can carry values that belong to another plugin.
$L= this skill's folder:${CLAUDE_SKILL_DIR}. If that still reads literally as a${...}placeholder, it is the folder that contains this SKILL.md.$W= the wake skill's scripts, next to this skill:$L/../wake/scripts. The model tools live there (segment.py,inpaint.py,depth.py,models.py,measure.py). If that folder is missing, this skill was installed on its own; tell the user to install the lemo-wake plugin (claude plugin install lemo-wake@lemo-wake).- Models folder:
${CLAUDE_PLUGIN_DATA}. If that shows a real path that belongs to lemo-wake, prefix every model command withLEMO_WAKE_MODELS="<that path>/models"(shell variables do not survive between your commands, so write the prefix each time). If it still starts with${, set nothing; the scripts find their folder themselves ($W/models.py where). - Output goes into the current working directory, never into the folder of the user's image.
Local models and consent
The tools use up to five small ONNX models on the CPU: BiRefNet-lite (subject, 224 MB), MODNet (people, 26 MB), MobileSAM (pick elements, 44 MB), LaMa (fill the background, 208 MB), Depth Anything V2 Small (depth, 99 MB). A model already on disk just runs. If $W/models.py (no arguments) shows some missing and consent "not asked yet", ask once before you start, in one short message: what they are for, about 600 MB in all from Hugging Face, where they are stored. Only a clear yes counts; record it with $W/models.py consent yes|no. A script that stops with exit code 10 means the same question. If the user declines, you can still pack layers from masks you draw yourself (measure.py bbox, colour keys, polygons) and fill small holes with inpaint.py --engine opencv; say what that costs.
1. Find the input
- A lemo-wake project (
<slug>-alive/, or itssrc/): the parts are usually already there. List them:
It shows every image in$L/scripts/layers.py scan <project>src/assets/and what it looks like:source,cut-out(RGBA at the source's size),mask,depth,plate?, orother size(an already cropped part;buildfinds its place in the source by itself). For plates it also says how much of the picture each one changed (differs_from_source: the one with the most lifted out is usually the cleanest full background). Parts made for an animation may have been trimmed or repainted (a missing edge, a redrawn top);buildchecks the stacked layers against the source and marks the mismatch in red, so recut what does not match. Lift whatever is missing as in step 2. - An image: make a folder
<slug>-layers/in the current working directory and normalise the image there (HEIC, EXIF rotation):
It writes$L/scripts/layers.py prep <image> <slug>-layers/work<slug>-layers/work/assets/source.png; below,<a>stands for thatwork/assetsfolder. Keep every mask and cut-out in<a>too. All coordinates are pixels of<a>/source.png.
If the user said what to separate ("just the two people", "the product and the logo"), that is the brief. Otherwise decide yourself and do not ask.
2. Take the picture apart
Look at the image first: what is in it, what covers what, what a designer would want to move. Usually that means:
- each person whole, one layer per person. A person includes what they wear and hold, and their own hands even where they rest on someone else. Never cut off a head, an arm or a leg as its own layer: the cut and the hole at the joint look like a broken doll, and nobody can use a loose arm.
- One person:
--model portrait(keeps hair) merged with--model generalrun inside a box around that person (keeps the body and what they hold). General and portrait both grab nearby things (a picnic blanket, a basket), so subtract the masks of objects that will be their own layers. - People who touch or overlap: one SAM box each often comes out with missing pieces. More reliable: make one mask of all the people together (portrait + general as above, objects subtracted), put a SAM point or box on each person as a seed, and give every pixel of the joint mask to the person whose seed mask it belongs to or lies nearest. Loose fragments go to the person they touch.
- One person:
- each object that stands on its own: SAM, one box each (a box is steadier than a point; add
--negpoints to drop a neighbour; one click often gets only part of a thing, so add a point on the missing part). A container keeps its contents (the basket with its fruit, the vase with its flowers;generaltends to drop thin stems, so add SAM points on them) unless the user wants the contents separately (food lifted off its plate). - many small things of one kind (scattered berries, confetti, stars): one layer for the group, unless the user asked for each piece or each one clearly matters on its own.
- openwork shapes (a lattice tower, a fence, branches, lace): the mask also fills the gaps. Clear the gaps where the pixels match the background around them (compare with the filled background or key out the background colour inside the shape's box); where the gaps cannot be told apart, say so.
- text blocks and logos on posters and cards, as pixel layers (box select); they stay pixels, not editable text.
- the background behind all of them, filled in, so every element can be moved off it.
- a depth map, for the pack and for the user's own parallax work.
Do not split what belongs together (a cup and its saucer, a bouquet and the hands holding it), and do not cut tiny details nobody would move.
LEMO_WAKE_MODELS=... $W/depth.py <a>/source.png --out <a>/depth.png
LEMO_WAKE_MODELS=... $W/segment.py <a>/source.png --out <a>/person1.png --model portrait
LEMO_WAKE_MODELS=... $W/segment.py <a>/source.png --out <a>/person1_g.png --model general --box x0,y0,x1,y1
LEMO_WAKE_MODELS=... $W/segment.py <a>/source.png --out <a>/cup.png --box x0,y0,x1,y1 # sam
LEMO_WAKE_MODELS=... $W/inpaint.py <a>/source.png <a>/all.png --out <a>/plate.png --dilate 6 # all = union of every element mask
$W/measure.py grid <a>/source.png <a>/grid.png # coordinates, if you need them
$W/sheet.py <a>/../parts.png --parts <a>/.. # every mask over the image, cut-outs on a checkerboard
Masks are 8-bit grey at the source's size (white = the element); build takes masks or RGBA cut-outs directly. Combine and clean masks with NumPy / OpenCV through uv (maximum of two masks, remove one from another, feather or shrink 1-2 px where a halo of the old background shows); do not fetch other models. Look at the parts sheet before packing.
The background: inpaint the union of all element masks.
inpaint.pygrows the mask by about 1% of the diagonal by default. For clean edges (posters, illustrations, cut-outs that already include their soft edge) pass a small--dilate(4-8); keep the default for photos with hair and motion blur.--splitfills separate regions one by one at near-native resolution. When the elements join into one big region it cannot split them, and the fill is downscaled (stderr says "downscale"); a soft result is acceptable. Large calm areas (sky, a wall, paper, a flat colour) can be filled in code with their own colour or gradient instead.- Never fill part of a hole while the rest of the object is still in the picture: LaMa copies what it sees and paints the object back. Every pass masks the whole object (all of it, also the parts you fill later); to work at higher resolution, crop around a region so the whole hole inside the crop is masked.
- Even when the elements cover most of the frame, still make the background, but tell the user plainly that it is soft there because those pixels never existed. That is the honest limit without image generation.
Where one element covers another (a cat in front of a sofa), the lower layer has a gap where the upper one was. Leave it, or fill small gaps with inpaint.py on that layer's own cut-out. A simple flat shape may be completed in code from what is visible (a sun disc, a colour band, a circle badge: fit the shape, fill it with its own colour or texture). Never invent complex hidden content (a face, a hand, a building's hidden side).
3. Pack the layers
$L/scripts/layers.py build <slug>-layers --source <a>/source.png --plate <a>/plate.png --depth <a>/depth.png \
--names "背景,原图,景深" --layer "背景人物=<a>/crowd.png" --layer "女孩=<a>/girl.png" --layer "帽子=<project>/src/assets/cap.png"
- Name each layer in the user's language, plainly ("女孩", "左边的杯子", "标题"), and pass
--namesfor the background, source and depth layers in that language too. - Order: list the layers from the bottom up (first = lowest). Decide it by what covers what in the picture.
--order depthsorts by mean depth instead, a quick guess for separate objects spread through a scene, wrong for things that sit on each other. - A cropped part from a project is found in the source automatically; if it was repainted or scaled, the script says so, then give its place as
name=file@x,y.
It writes layers.psd (background, then one layer per element, the source and the depth map as hidden layers on top), png/ (the background at full size, each element cropped to its own box, source.png, depth.png), layers.json (canvas size; per layer: file, x, y, width, height, z with 0 = bottom, mean depth) and preview.png.
Look at preview.png before you hand it over. A red "≠ source" card (and a check: warning) means the stacked layers do not reproduce the source there: a part is incomplete, misplaced or was repainted. Also look for ragged edges, missing hair, a halo, a part that grabbed its neighbour, a layer that should be two or two that should be one, the stacking order. Fix and build again. Then delete <slug>-layers/work/ unless the user wants the masks.
4. Hand it over
Tell the user briefly, in their language: where the folder is, which layers it has (names, in order), and how to use it:
layers.psdopens in Photoshop, Affinity Photo, Procreate, GIMP, or free in the browser at Photopea. The source and depth layers are hidden; switch them on to compare.png/withlayers.jsonfor After Effects, Figma, Keynote or a game engine: place each PNG at itsx, y, stack byz.- What the limits were: soft fill where a big element left the background, gaps where layers covered each other, text kept as pixels.
- They can turn the same picture into a film with
/lemo-wake:wake.
Share a film to the lemo-wake gallery
The gallery is the gallery branch of https://github.com/lemomo-ai/lemo-wake. A submission is one folder, films/<id>/, added through a pull request from the user's own GitHub account. A maintainer reviews it; after the merge it appears on the gallery page automatically.
Talk to the user in their language (Chinese or English; follow the user). These docs are in English only for you.
Nothing leaves the machine until the user has seen exactly what will be published and said yes. Never upload on your own initiative, never upload someone else's film, never skip the confirmation.
$U = this skill's folder: ${CLAUDE_SKILL_DIR} (if that still reads literally as ${...}, it is the folder that contains this SKILL.md). Never take a path from the shell variables CLAUDE_SKILL_DIR / CLAUDE_PLUGIN_DATA.
1. Find the film
The argument, if any, is a film file or a lemo-wake project folder. Otherwise look in the current working directory for the most recent project (<slug>-alive/) and its <slug>.webp. The gallery takes an animated WebP or GIF (prefer the WebP: original size, best quality). If it is unclear which film is meant, ask.
2. Collect the details (one message, in the user's language)
Ask in a single message, with your suggestion filled in for each so the user can just say "OK":
- Title - short, up to 80 characters; suggest " · ", e.g. "炉边三花猫 · 炉火醒来". The gallery is bilingual, so also suggest the other language's version (Chinese title -> English, English title -> Chinese), e.g. "Calico by the fire · The fire wakes up". Pass the Chinese one as
--titleand the English one as--title-en. - Category - the scene the picture comes from (not its style):
life(everyday photos: food, pets, places, travel),people(portraits, couples, family, milestones),poster(posters, ads, campaigns),brand(logos, brand marks),data(charts, reports),social(Xiaohongshu covers, chat screenshots, social posts),sticker(stickers, greeting images),art(paintings, drawings, picture books). Suggest one. - Credit - the name shown under the film. Default: their GitHub username.
- Original image (optional) - show the source next to the film? It is saved as a JPEG with all metadata (location, camera, date) removed, long side at most 1600 px.
- Notes (optional) - a few lines about how it was made (the director notes can be a starting point). Published as written; no personal details.
- License and consent - the film (and the original, if included) is published under CC BY-NC 4.0 (others may share and adapt it with credit, not for commercial use), and the lemo-wake project may show it in its README, gallery and posts about the project. They must have the rights to the image: their own photo or artwork, or one they are allowed to share. Photos of other people need those people's OK.
Point out anything that looks private: faces of people other than the user, children, names, phone numbers, addresses, chat contents, licence plates, documents. Suggest leaving such a film out rather than publishing it.
3. Prepare and show what will be published
uv run $U/scripts/prepare.py <film> --title "..." --title-en "..." --category <cat> --author "<credit>" \
--author-url https://github.com/<login> [--source <original image>] [--notes <notes.md>] \
--out <workdir>/lemo-wake-upload --agree
--agree records the user's yes to the license and consent from step 2 - pass it only if they said yes. <login> is their GitHub username (gh api user --jq .login; if gh is not logged in yet, see step 4). The folder id is <date>-<login>-<slug>.
It checks the film (animated WebP/GIF, at most 8 MB; a bigger WebP is re-compressed, never below 12 fps / q50 - if it still does not fit it stops and says so), makes preview.webp (long side 360, at most 1 MB) for the gallery grid, writes the original without metadata, writes meta.json, and prints a JSON summary. It warns about text in the notes that looks like an email, phone number or local file path - fix those before going on. Use a work folder under the current working directory (not the user's image folder).
Show the user the summary: the folder films/<id>/ with every file and its size, the full meta.json, the notes text if any, and where it goes (a pull request to lemomo-ai/lemo-wake, branch gallery, from their GitHub account <login>; the pull request and files are public once the repository is public). Ask for a clear yes.
4. Submit (only after the yes)
Needs the GitHub CLI (gh) logged in. If gh auth status fails, ask the user to run ! gh auth login themselves - never handle their password or token.
python3 $U/scripts/submit.py <workdir>/lemo-wake-upload/films/<id>
It always submits to the official repository lemomo-ai/lemo-wake - also if this plugin came from a fork or a copy; never point it elsewhere. It forks the repository if the user cannot push to it, puts the folder on a new branch submit/<id> based on the current gallery, commits under the user's GitHub no-reply address (their real email is never used), pushes, opens the pull request and prints its URL. Exit 20 = gh missing or not logged in; 21 = the id already exists in the gallery (choose another title or slug); 22 = a git or GitHub step failed (the message says which; fix it, then run again - it is safe to repeat).
Tell the user the pull request URL, that an automatic check runs first and a maintainer reviews it, and that it shows up on https://lemomo-ai.github.io/lemo-wake/ after the merge. Then delete the work folder.
lemo-wake 1.1.0 · official repository: https://github.com/lemomo-ai/lemo-wake
lemo-wake: wake up a still image
Input: one image. Output: one film made for that image (about 5 s, loops forever), delivered in the formats and at the size the user picks.
Everything in this skill is a reference, not a rule. You are the director and the motion designer: you look at the image and decide what happens, how big, how it ends and when it is good enough. The references, types, effect blocks and scripts are tools and lessons from earlier films. If you have a better idea, do it; no need to explain why you departed from the docs.
Fixed boundaries: no image generation, no services that need API keys, no calling other skills. Material comes only from the image itself, from code, and from local models (depth, cut-out, hole filling).
Talk to the user in their language. Everything you say to the user - questions, progress updates, the final summary - is in the language the user writes in (Chinese or English; follow the user). These docs are in English only for you.
Two things matter most.
- Imagine what this picture could become, not just what in it could wiggle: things leave, arrive, assemble, swap, react to each other; people act on each other and on the things around them. The signature move should surprise and still belong to this image.
- Direct it as a whole film: a beat (setup → action → payoff → return), every element doing a job in that line, rhythm judged by watching it play. The camera follows an action; it never replaces one.
Read references/taste.md before planning. It is the most important reference: what viewers loved and rejected. In short: things in the picture must really move (light or colour alone is not motion); default to big actions that chain across the whole picture; the signature move grows from this image. The output size is the user's choice; what happens inside that frame is yours.
Use the tools. The local models (cut-out, element picking, depth, hole filling) are what let things leave their place and move for real. Take the picture apart with them before you plan (step 3); what you can lift out is what you can choreograph.
Paths
Only the text substituted into this file counts. Never take the shell variables CLAUDE_SKILL_DIR or CLAUDE_PLUGIN_DATA (echo, env) for these paths: the Bash environment can carry values that belong to another plugin (seen in practice: another plugin's data folder), and using them would put models and history in someone else's folder. The scripts never read those variables either; the only path override they honour is LEMO_WAKE_MODELS (ignored, with a warning, if it points into another plugin's data folder).
$S= this skill's folder:${CLAUDE_SKILL_DIR}. If that still reads literally as a${...}placeholder,$Sis the folder that contains this SKILL.md (the path you loaded it from, e.g.~/.claude/skills/lemo-wake). Scripts are in$S/scripts/.- Persistent data folder:
${CLAUDE_PLUGIN_DATA}- kept across plugin updates, never inside the plugin folder itself.- If the line above shows a real path (and it belongs to lemo-wake): put models there by prefixing every model command with
LEMO_WAKE_MODELS="<that path>/models", and keep the history at<that path>/history.jsonl. Shell variables do not survive between your commands, so write the prefix each time. - If it still starts with
${(e.g. the skill was installed by copying or linking the folder): set nothing. The scripts find their models folder themselves ($S/scripts/models.py whereprints it; usually$S/models/) and the history lives at$S/history.jsonl. - If you cannot or may not write there (a sandbox, a read-only install, or the user asked you not to touch the skill folder), keep the history in the current working directory as
lemo-wake-history.jsonlinstead, and read it from there too.
- If the line above shows a real path (and it belongs to lemo-wake): put models there by prefixing every model command with
- Project output goes into the current working directory, never into the folder of the user's image.
Workflow
Go at your own pace; skip or repeat steps.
0. First run: check the environment
node $S/scripts/doctor.mjs # says what is missing; --fix installs npm deps + headless browser (~190 MB)
Needs Node >= 18, ffmpeg, uv. Tested on macOS; on Linux/Windows, if a step fails, work out what is missing and fix it (install a dependency, adjust a path, set CHROME=<browser path>).
1. Ask once: output size and formats
Before you build, ask the user one short question in their language (one message, or your question tool if you have one), with the defaults filled in so they can simply say "go". Skip it if the user already said what they want.
- Output size. Default: the source's own size and aspect ratio (name it, e.g. "1086x1448, 3:4"). Offer other ratios when they would suit this image or where it is going: 16:9 (landscape posts, video covers), 9:16 (stories, Douyin), 1:1, 3:4 (Xiaohongshu). If the long side is over 2560 px, say that the film is rendered at 2560 for speed by default and that full resolution is possible but slower.
- Formats. Default: MP4 (posts) and GIF (chats). On request: WebP (web pages, GitHub, the community gallery), WeChat sticker GIF, Apple Live Photo (only offer it on macOS).
- Local models, only if doctor showed some missing and consent "not asked yet": add one line to the same message (what they are for, about 600 MB in all from Hugging Face, where they are stored; see "Local models" below), so the user is not interrupted later. Only a clear yes counts; record it with
models.py consent yes|no. - No answer, or "just do it": use the defaults. Formats can be added later without re-rendering.
The size is the user's choice; how the picture uses that frame is yours. A different ratio is a new canvas to design for, not a crop or a stretch.
2. Create the project
$S/scripts/new_project.py <image> <slug> --dur 4.5 [--out 16:9] # render length; total = this + any reset transition appended later
It makes <slug>-alive/ in the current folder, with the page in <slug>-alive/src/. The canvas is the source's own pixel size unless the user picked another (--out W:H keeps the source's long side, --out WxH is exact; then design coordinates are output pixels and CFG.img is the source size). HEIC is converted and EXIF rotation applied; images with a long side over 2560 px are scaled down for speed and it says so (--max-long 0 keeps everything, for a user who wants full resolution). All coordinates of the picture refer to <src>/assets/source.*.
The length can change any time: edit dur in <src>/config.js and re-render (render.mjs renders fps x dur frames, t = 0 .. dur - 1/fps). With an in-picture ending, dur is the whole film and render(dur) should look like render(0); with a reset.py transition, the transition is added after dur.
3. Take the picture apart (before planning: what you can lift out is what you can move)
First look at the image: its kind, its elements, what could be an actor. Then see which tools you have ($S/scripts/models.py lists the local models and whether they are installed) and take the picture apart with them. For any photo, painting or illustration that means, by default:
- a depth map;
- every possible actor cut out on its own: objects with SAM (one box each, or
--each), people withportraitmerged withgeneral(one SAM box per person when they should move separately); - the plate behind the actors, so they can leave their place.
Then look at the parts together and fix what is ragged (missing hair, halos, a bitten edge) before building on it:
$S/scripts/sheet.py <proj>/parts.png --parts <src> # cut-outs on a checkerboard, masks over the image, plates, depth
Flat images (charts, logos, UI, text cards) are often cleaner rebuilt in code; photos, real people and specific products come from the source, lifted out with the models.
$S/scripts/measure.py grid <src>/assets/source.jpg <proj>/grid.png # coordinate grid, drawn 1.5x larger with labels in source pixels
$S/scripts/measure.py info|palette <img> # size / main colours
$S/scripts/measure.py bbox|runs|vruns <img> --color '#hex' ... # element bounds (-h lists the options)
$S/scripts/depth.py <src>/assets/source.jpg --out <src>/assets/depth.png # depth (near = white)
$S/scripts/segment.py <src>/assets/source.jpg --out <src>/assets/mask.png [--cutout subj.png]
# --model general (main subject) | portrait (people, hair) | sam (pick elements: --point x,y ... --neg x,y --box x0,y0,x1,y1 --each)
# several objects in one mask: --box 20,30,300,360 --box 400,30,700,360 (write the numbers out; zsh won't split an unquoted $VAR)
$S/scripts/inpaint.py <src>/assets/source.jpg <mask.png> --out <src>/assets/plate.png [--engine lama|opencv] [--dilate N] [--split]
# --split: the mask holds several neighbouring objects (a row of planets, products, icons + labels) - fill each one
# on its own at near-native resolution instead of one big downscaled blob (watch stderr for "downscale 3x")
node $S/scripts/fetch_fonts.mjs <src> "family=..." # Google Fonts saved locally; CJK fonts: add &text= with the used characters
(Model commands: add the LEMO_WAKE_MODELS=... prefix from Paths; see "Local models" below.)
What each tool makes possible:
| Tool | Makes possible |
|---|---|
SAM (segment.py --model sam) | objects that jump, fall, fly off, swap places, settle back |
portrait + general | people who move, turn, lean, reach, with their hair intact |
LaMa (inpaint.py) | a clean place left behind, so an actor can leave and come back |
depth (depth.py) | parallax, near things passing in front of far ones, light or wind arriving by distance |
Getting clean parts:
- SAM: a box is steadier than a point; add
--negpoints to drop a neighbour; one click often gets only part of a thing, so add a point on the missing part. - People:
portraitkeeps flyaway hair; take the maximum withgeneralto keep held objects and full bodies. - Edges: shrink or feather a mask by 1-2 px where a halo of the old background shows. General libraries (OpenCV, NumPy, scikit-image through
uv) are fine for this; don't fetch other models. - Plates: inpaint each region on its own near native resolution (
--split, or crops); large filled areas go soft, so stage the film so they are rarely seen in full, or paint big simple surfaces in code. - Depth: compute it on the text-free plate when there is text; a 16-bit map must be normalised before converting to 8-bit.
4. Plan with the parts in front of you (write it into <proj>/DIRECTOR.md)
Decide what happens to the parts: which action belongs only to this image (one sentence), what state the picture starts in, the beat (setup → action → payoff → return, with rough times), what each main actor (each person, each lifted object) does and what it acts on, where the climax is, how it ends and loops. References:
$S/references/taste.md- the quality bar (read first).$S/types/<kind>.md- what works for this kind of image, with case cards of approved films:photo,portrait,multi(several photos),poster,illustration,clay(clay / paper-cut / 3D),ui(screenshots),chart,logo,sticker(stickers / avatars),xhs(Xiaohongshu covers / text cards). Mixed images: read two.$S/references/motion-grammar.md- reading questions, structures, camera, motion principles, rhythm, self-check.$S/references/recipes.md- techniques that worked across types.$S/references/effects.md- the 49 effect blocks and 27 reset transitions.$S/references/pitfalls.md- technical traps.- The history file (see Paths), if it exists: recent films, so this one isn't more of the same. Change
seedvalues every film;FX.pick(name, seed)draws parameters from recommended ranges.
If the plan needs a part you have not lifted yet, go back and lift it.
5. Build <src>/index.html from the template (layers #view frame / #cam camera / #post post-processing).
render.mjsgrabs frames with several headless browsers in parallel and out of order, sowindow.render(t)must draw the same frame for the sametevery time (no state carried from the previous frame). Setwindow.READY = trueonly after all images and fonts are loaded.lib.js: easing, keyframes, springs, shake, seamless loops, noise, camera, parallax, glyphs, ink, ribbons, tiles, pixel particles, noise dissolve, text animation, number rolls, analytic particles (see the comments in the file).L.Cameranever zooms below 1 and keeps the view inside the source; to look past the edge, paint that area and passextend(recipes.md, "Extending the canvas beyond the source").- The template's base colour follows the source's border and its paper grain is off (
GRAIN = null); switch grain on for paper or print looks, not for dark images. fx.js: 49 ready-made effect blocks,FX.make(name, params)->draw(g, t). Good as supporting actors, atmosphere, loop transitions or raw material; the signature move is usually your own code.- three.js may be downloaded locally if real 3D helps.
6. Look at frames and iterate
node $S/scripts/render.mjs <src> stills 0.2 1.0 2.0 3.0 4.4
$S/scripts/sheet.py <proj>/sheet.png --stills <src> 0.2 1.0 2.0 3.0 4.4
$S/scripts/sheet.py <proj>/vs.png --vs-source <src> 4.4 # compare with the source (render that still first)
$S/scripts/sheet.py <proj>/f.png --frames <src>/frames --idx 0 40 80 -1 # after a full render: by frame number (or --n 8)
Rendering is fast, so look often. A first version usually only "moves"; if it is not big or good enough, start over.
7. Full render and the loop
node $S/scripts/render.mjs <src> frames # -> <src>/frames/f_00000.jpg ...; page errors go to render.log, exit code 2
$S/scripts/reset.py --list # 27 frame-level transitions
$S/scripts/reset.py <src>/frames --kind <kind> [--seed N] [--origin x,y] [--pre-hold .3] # -> <src>/frames_loop
The content does not need to return to its start: the end can be full and the beginning empty. Join last frame to first with a transition that fits the style - an in-picture ending you write (often the best), an fx.js in-picture transition (backplay, passby, pushcut, lightcut), or a reset.py kind. The first frame doubles as the still preview in many apps, so make it look good.
8. Encode and QA
$S/scripts/encode.py <frames dir> <proj>/<slug> --no-webp --no-sticker # the default formats; drop a --no-x to add one
$S/scripts/livephoto.py <frames dir> <proj>/<slug> --src <src> # Live Photo (macOS), when asked
$S/scripts/qa.py <frames dir> --src <src> --encode <proj>/<slug>.encode.json
The formats, all from the same frames:
| File | Size | For |
|---|---|---|
<slug>.mp4 | original pixels, H.264 (an odd width or height is rounded down to even: 941 -> 940) | posts: WeChat Moments, Xiaohongshu, Douyin, Instagram, X |
<slug>.gif | scaled only as far as needed, <= 5 MB, width < 1080 (busy full-frame motion can end up ~300-450 px wide) | chats: WeChat, QQ, Weibo |
<slug>.webp | original pixels; ~8 MB is a target (quality/fps drop a little first, never below 12 fps / q50) | web pages, GitHub, galleries |
<slug>-sticker.gif | longest side 240, dropping (to 120 at most) when needed to stay <= 500 KB | WeChat custom sticker |
<slug>.pvt | Live Photo bundle: a still (the cover) + the film sped up to 3 s, at the output size (video long side <= 1920) | iPhone Photos, then Xiaohongshu / Moments; macOS only |
Use --no-mp4 / --no-gif / --no-webp / --no-sticker to skip one (a rerun merges into the existing <slug>.encode.json, so a format added later just needs a rerun with the others skipped), and --gif-max / --webp-max / --sticker-max (MB) when the user names a platform limit. --gif-width is only a cap: the size limit decides the GIF's width, so for a wider chat GIF raise --gif-max as well. qa.py FAIL usually means a technical problem worth fixing; WARN is often intentional (an empty first frame by design). It also writes qa_sheet.jpg whose last tile is the first frame, to check the loop seam.
The Live Photo's cover is the still people see before they press it, so it should be the most complete frame, not frame 0 (films often start empty). Without --cover SEC the script takes the frame closest to the source, or the most detailed calm frame; look at it and choose another if needed. Tell the user to AirDrop the .pvt itself (Finder shows it as one file); a loose HEIC + MOV pair arrives as a separate photo and video.
9. Deliver
Append one line to the history file (see Paths; create it if missing):
{"date":"2026-01-31","slug":"cat","image_type":"photo","arc":"build","signature":"breakfast crouches, leaps out, bounces back onto the plates","main":"own code: SAM sprites + squash","fx":["steam seed=12"],"reset":"in-picture: true loop","dur":5,"verdict":"","why":""}
If the user later gives a verdict, fill in verdict and why.
Tell the user (in their language): the file paths and sizes and what each is for, the signature move and structure, how it loops, anything notable from QA, and what can only be judged by watching it play. Invite changes. Mention once that other formats (from step 1) can still be added. If the user likes the film, you may mention once that it can be shared to the community gallery with /lemo-wake:upload (plugin installs; it takes the WebP or GIF); never upload anything yourself.
Local models
Five small ONNX models run on the CPU: Depth Anything V2 Small (depth, 99 MB), BiRefNet-lite (subject cut-out, 224 MB), MODNet (portrait matting, 26 MB), MobileSAM (pick elements, 44 MB in 2 files), LaMa (fill holes, 208 MB). Each is downloaded from Hugging Face only when first needed. Most films get better with them: clean cut-outs and plates are what let things really move, so use them freely. $S/scripts/models.py shows status. Consent is only about downloading: a model already on disk just runs, with no question to the user (status then reads "not needed (models already installed)"). Ask only when a script actually stops with exit code 10.
- Exit code 10 - ask once. The first time a model would be downloaded, the script stops and prints what is needed. Tell the user once, in their language: which model(s), what they are for, size, source (Hugging Face), where they will be stored, and what declining costs (you will still finish the film with code-only approaches; say concretely what gets harder, e.g. depth parallax, clean cut-outs of photo subjects, filling the hole behind a moved object). Record the answer with
$S/scripts/models.py consent yesorconsent noand re-run. It is never asked again. If a model is missing and consent is "not asked yet", ask together with the step 1 question so the user isn't interrupted mid-way. - Exit code 11 - declined. Do not ask again; work around it.
- Exit code 12 - download failed. Find a way yourself: retry with a mirror (
HF_ENDPOINT=https://hf-mirror.com, common for mainland China), a proxy, or a manual download to the exact path the script prints. Files are sha256-checked either way. models.py fetch allpre-downloads everything (only when the user wants that).
When a model is unavailable - declined, or the download failed - never get stuck. Find a reasonable compromise with your own methods and still complete the film: colour keys, measure.py bbox, hand-drawn polygons or masks, elements rebuilt in code, layered 2D parallax instead of depth, inpaint.py --engine opencv for small holes, code-painted backgrounds, or staging that keeps objects in place and hides holes behind motion, dust, fog or paint. Mention briefly in the final summary which compromise you chose.
Adjustable (decide yourself if the user doesn't say)
- Duration: about 5 s including the loop transition. If the user wants N seconds, scale the beats but keep physical timings (impacts, drops) about the same; give the extra time to reveals and holds. Films that must feature many parts (several photos) may run longer.
- Size and formats: asked in step 1 (defaults: the source's own size; MP4 + GIF). The MP4 and WebP keep the output size; size limits only change the chat GIF and the sticker; the WebP limit is a target.
- Frame rate: render at 30; the WebP drops to 12-15 fps as needed, the chat GIF and sticker lower.
lemo-wake 1.1.0 · official repository: https://github.com/lemomo-ai/lemo-wake · gallery: https://lemomo-ai.github.io/lemo-wake/
Sponsors
Details
- Marketplace
- lemomo-ai/lemo-wake
- Category
- Community