uxkero/aimo/aimo

AIMO

Artificial Intelligence in Motion. Video editor.

A local video editor where the video is code. The user watches the video, steps through it frame by frame, clicks anything to see which function drew it, changes numbers and colors by dragging, and leaves notes on points, zones or ranges. You see exactly the same through the tools of the aimo MCP.

Reply in the language the user writes in.

Open

open with the video folder. It starts the editor if it is not running and opens it in the browser. If a tool says no browser tab is connected, call open with no folder. Never ask the user to run a command.

Units

Times are seconds. Positions and boxes are video pixels (the canvas size that status reports, origin top-left), never pixels of a returned image: get_frame says the scale in its caption. Code locations are project-relative paths, 1-based lines and 0-based columns.

See what the user sees

• status: playhead, video size and fps, selection, open notes and the editor view. Start here when the user talks about "this" or "here".
• get_selection: what they have selected, with the function chain and the code line of each one.
• get_frame: the image at a time. It moves their playhead (unless keep_playhead): they see what you are looking at. region zooms into a detail; boxes numbers every element group on the image with a legend.
• contact_sheet: evenly spaced frames of the whole video in one image, to see what happens over time without moving the playhead.
• list_elements: what is drawn in a frame, grouped by function, or every draw call with id, z order, color, font and alpha.
• inspect_point: what is at a point (x, y), top to bottom, with the code.
• find_element: when and where a text, a function or an image appears across the whole video.
• timeline, project_info, list_texts: duration, scenes and sounds; files and the brief; every visible text with its literal.

Change it

• edit_literal changes one exact value; element_literals lists the values on the lines that draw an element and can move it with dx, dy.
• edit_text changes a text by its value; text_style and set_text_style read and change its font, weight, size, color, alignment and position, following helpers like title(g, 'Hi', ...).
• Anything else: edit the source file. Check with get_frame. undo, redo and history cover your changes and the user's.
• select, highlight, seek, play, pause, set_track and set_view drive the editor itself.

Notes

Notes are the user's requests. Each one has a time, position, text, the code element it marked and the image of the frame with the mark.

1. list_notes to read them all.
2. resolve_note with status in_progress when you start each one.
3. Make the change in the code. The editor reloads on its own and keeps the playhead.
4. get_frame at that time to check with your own eyes that it looks as requested. If not, keep going.
5. resolve_note with solved and what you did in one sentence.

If a note is ambiguous, do not guess: add_note with your question on that frame and go on with the others.

A note of type move was created by the user dragging an element in the video. It has dx and dy in video pixels and the scope: whole_path moves the element along its whole path and only_at_t moves it only around that time, without changing the rest of its animation. Follow the origin to where the position is defined (element_literals at the note's point lists the candidates); if it is inside a transform with scale or rotation, convert the offset to those coordinates. Check with get_frame that it ended up where it was dropped.

Ask

If you need a decision from the user, use ask_user with short options and continue with their answer. Do not end the turn with a question in the text.

Point things out

highlight moves their playhead to a time and highlights a zone with a label. Use it when you explain something visual ("this is the shadow that gets cut") instead of describing coordinates.

Sound

If the project has sound.py with synth.Mix, the editor instruments it: every m.add shows up in the timeline with its track and its line. Saving sound.py rebuilds the sound on its own. sound_events returns the events or the error. search_sounds, recommended_sounds and download_sound bring free sounds and music into assets/sounds.

A note of type image was created by the user dragging an asset onto the video: it has file, the box x, y, w, h in video pixels and the range t to t1. Draw it on top of everything, in a function with its own name, with a short entrance and exit.

Requests about a whole track ("the whole Music track") are about that entire bus in sound.py, not about one moment. The names the user gave to tracks and sounds are in timeline (and rename sets them); use them when you talk to them.

Texts and export

The user edits texts on their own: double click on the text in the video or the Texts tab, which write the literal into the code. For that to work, every visible text has to be a string literal in the call that draws it, not built from pieces. If you build it letter by letter, pass the whole text as a literal to the function.

Export is done with the project's render.py plus ffmpeg (MP4, WebM, GIF, PNG, ranges, sizes, platform presets like yt-shorts or x-gif) through export. You do not need to export unless the user asks.

Generate images

generate_image creates characters, backgrounds, objects or textures with an image model through OpenRouter or Vercel AI Gateway and saves them in assets/gen. With background: "transparent" it comes out cut out. import_file brings a file from the computer or a URL into the project; reference_video_frames lets you look at a video file. Pass as reference the project images that define the style or the character so everything comes out consistent. Illustrated characters and painted worlds are generated; the code does the compositing and the motion.

Code the editor understands best

The inspector follows the call stack of every draw call, so the code becomes editable by hand when:

• Each visible thing has its own named function (logo, phone, leapShot), not one giant function.
• The values someone would want to tweak (position, size, color, text, timing) are literals in the call or in the function, not hidden calculations.
• The page exposes window.renderFrame(n) and window.__ready (the OpusCut contract) so every frame is exact. Any other animated page also works, with a virtual clock.

When you write or rewrite a video that the user is going to edit, follow those three things.

What not to do

• Do not restart the server or reload the browser: everything reloads on its own when you save.
• Do not render the whole video to check a change: get_frame is enough.
• Do not change what the user did not mark.