Getting started

Documents and projects

Starting, opening and saving films; projects, and how every save is kept; undo; several documents at once; and removing saved work.

A document is one film: its canvas, its tracks and layers, the assets it uses and any nested compositions. ymotion_doc is how you start one, open one, save it, step back through it and, when the person asks, remove saved ones. This page covers every action it takes.

The open document

The tools that read, change and render a film act on the document that is currently open, the way an editor has one film open in front of you. That saves passing an id through every call: you open or start a document once, and ymotion_read, ymotion_edit, ymotion_render and placing media all work on it until you switch.

More than one document can be open at once, and one of them is current. If a call answers that no document is open, start or open one.

Starting a document

ymotion_doc {"action":"new"}

With no size, the film waits for its footage: the first video placed gives it that video's width, height and frame rate, and the video sits in it at 100%. Until then the frame is 1080x1920 at 30 fps. This is After Effects' New Composition from Footage, and it's the right start whenever the film is built around a piece of footage. Place the video before laying anything else out: once a title, a picture or a shape is in the film, the frame keeps the shape it has.

When the person asks for a particular shape, give it up front, either as a preset or as numbers:

ymotion_doc {"action":"new","preset":"vertical1080"}

ymotion_doc {"action":"new","width":1080,"height":1350,"fps":30}

The presets, with their sizes and frame rates:

uhd4k — 3840x2160 at 30 fps
hd1080 — 1920x1080 at 30 fps
hd720 — 1280x720 at 30 fps
square1080 — 1080x1080 at 30 fps
portrait1080 — 1080x1350 at 30 fps
vertical1080 — 1080x1920 at 30 fps
vertical2160 — 2160x3840 at 30 fps

A reel of 4K footage is still vertical1080: the export follows its footage's sharpness, up to 2160x3840 (see Exporting a film).

A few more options on new:

fps alongside a preset replaces the preset's rate: ymotion_doc {"action":"new","preset":"hd1080","fps":24} is 1920x1080 at 24 fps. fps on its own keeps that rate and still takes the size from the first video.
background is the frame's ground, as a paint: ymotion_doc {"action":"new","background":"#101418"}. Paints are described in Units, paints and time. The default is black.
name is the film's own title — the main composition's name — shown in replies. It's separate from the project the film is saved in, and the renameProject verb changes it later.
seed makes the document reproducible; see the last section.

new and save also take one optional details object to help later chats find the project. The main-document renameProject edit can carry the same object beside its ops; the rename and details are one undo step. Searchable details defines every field and shows the calls. Add known facts, leaving anything unknown out.

The shape isn't fixed once chosen: the setCanvas verb changes it at any time, and Formats and layout explains how to refit footage afterwards.

Saving

First inspect the open document with ymotion_doc {"action":"list"}. If your tool list declares project, then save it by project name:

ymotion_doc {"action":"save","project":"gotham"}

saves the open document into the project gotham of the person's saved films. A project is one film the person is making; a project name may not contain a slash or characters such as :, * or ?. Once a document has been saved or opened from a project, ymotion_doc {"action":"save"} with no project saves into that one again.

Every save is kept. The server numbers them itself, never writes one over another, and the newest is the one that opens; a save identical to the newest writes nothing. So when the person asks you to change something, change the open document and save it into the same project; start a new project only for a genuinely different film.

Saves are internal. Never name a save or a version to the person, and never speak of v1 or v2: to them there is the project, and it is what they last saw. The reply's text names the project; which save it is stays in its data, as file, for your own bookkeeping.

The person doesn't see what you save until you say it's done. When the film is ready for them, save it once more with done:

First ymotion_doc {"action":"save"} works on an older list; if your tool list declares done, then:

ymotion_doc {"action":"save","done":true}

Making a preview link or an export of it also counts as done, and so do ten minutes without another save. Until then the person's projects show the project as it was before you began, or don't show a new project at all. If the person has the project open in the editor, though, their editor shows each save as you make it.

A few more things a save can say:

The project was saved elsewhere since your document was opened or last saved. Your save is merged with that newer save: everything either of you changed is kept, and where both changed the same thing, your save's value wins, because it is the latest save. The reply lists any such clashes, and the open document becomes the merged film, with undo still taking back your own last change. If your document had nothing of its own to add, nothing is written and it becomes the newest save. An image whose canvas was made another size on either side is the exception: nothing else can be put beside that, so your save is written whole, nothing of the newer save is in it, and the reply says so, naming the clash "canvas size".
"create":true saves only into a project that doesn't exist yet. If one by that name is there, nothing is written and the reply says so.

Working on the same project as the person

A project is meant to be reused. When the person asks for a change to a film they already have, change that film and save it into its project again. Start a new project only for a genuinely different film, never for a revision.

The person may have the project open in the Ymotion editor while you work, and change it there. That's expected:

Their saves reach your open film before each read, edit, render or media call. When the project was saved elsewhere since your last call, the reply begins by saying so, and your open film is now that save. Any unsaved edits of yours are put on top of it; where an unsaved edit of yours and that save changed the same thing, the save's value is kept, and the reply names it. Undo still takes back your own last change. On an image whose canvas was made another size on either side, your unsaved edits are set aside instead: the open image is that save whole, and the reply says so. Undo brings back only what you made before a size change of your own, on that save. Read the film again before relying on what earlier replies said about it.
Your saves reach their editor as you make them. If they have unsaved changes there, their editor shows that it isn't up to date and offers a Reload instead; you don't need to tell them either way.
Finding the film they mean. ymotion_doc {"action":"projects"} marks a project the person has open in the editor right now, and starting a new film while they have one open says which. If they ask you to change "this" film, that's usually it.

A document opened from one exact save, rather than from its project, stays that save until you save it.

To come back to a project in a later conversation, list projects and open the one you need:

ymotion_doc {"action":"projects"}

If your tool list declares project, then open it by name:

ymotion_doc {"action":"open","project":"gotham"}

If a save reply says the document is held only in this process, the server has no storage configured and the film will be lost on a restart; tell the person.

Projects

ymotion_doc {"action":"projects"}

lists the person's projects, one row each, newest first: its name, whether it's a film or an image, and when it was last saved. A project sits where its newest save puts it, so the one changed last comes first. That also means a project whose newest save is deleted while you're reading pages moves further down, and can appear again on a later page; it's the same project. It's paged, 30 to a page unless you give a limit (at most 200). The reply says how many there are in all, and when there are more it ends with the exact call for the next page, which carries an after, the page's next. Send that back unchanged; a cursor that has been edited, or that came from another list or filter, is refused rather than read as the first page.

A project you are still making shows in your list marked as not yet seen by the person.

query searches each project's fixed details by words, with old projects still found by name:

ymotion_doc {"action":"projects","query":"paris morning"}

Every word must match a word's start somewhere in the details. The total is the matching count; send the reply's exact next call to continue the same search. See Searchable details.

ymotion_doc {"action":"files"}

lists every save instead, newest first, a page at a time (50 to a page, at most 200); with a project it lists that project's saves, its newest first. You rarely need it: to work on a project, open it.

files takes query too, including together with project; it searches the details of each saved document, not later changes made to that project.

Opening

First see saved work with ymotion_doc {"action":"files"}. If your tool list declares project, then:

ymotion_doc {"action":"open","project":"gotham"}

opens the project's newest save and makes it current. You can also open a whole project you hold as JSON text:

ymotion_doc {"action":"open","json":"<a project as JSON text>"}

Either way the document is parsed rather than trusted: missing fields are filled with their defaults and fields the engine doesn't know are dropped, so what's open is exactly what a save would write.

Undo and redo

ymotion_doc {"action":"undo"}

ymotion_doc {"action":"redo"}

One ymotion_edit call is one undo step, however many operations it carried, because a batch is applied as a unit. Give a batch a label and the undo reply names it — undid "title in" — which makes it easy to tell the person what was taken back; without one, the step is named after its first few verbs. Placing something with ymotion_media is a step of its own too. Undo belongs to each document separately and acts on the current one.

An undo history lives as long as the document stays open. Opening a saved file starts a fresh history, so there's nothing to undo immediately after an open.

To try a batch without committing it, send it with "dryRun":true: the reply says whether every operation would apply, and nothing changes.

Several documents at once

ymotion_doc {"action":"list"}

lists the documents open in this session, marking the current one with *.

ymotion_doc {"action":"use","id":"<document id>"}

makes another one current, by the document id that new, open and list report.

ymotion_doc {"action":"close","id":"<document id>"}

lets one go; with no id it closes the current one.

Some things to know about how documents are held:

Close keeps no copy of unsaved edits. It refuses to close a document that has edits and has never been saved. A document that already has a file closes even if it has changed since its last save, and those changes are gone; saving first keeps them.
Every save of one film shares its document id. Opening the project again while it's open replaces the open document rather than adding a second one. If the open one has edits that aren't saved, the open is refused, so nothing is lost: save first, or undo them. You rarely need to open it again to see a newer save anyway: the open film follows its project before each call.
About two dozen documents stay open. Past that, starting or opening another lets go of the oldest one that isn't current, along with any edits it hadn't saved.

Removing saved films

Removing a project is permanent. There's no bin and no undo, so remove things only when the person asks you to, and make sure you both mean the same project.

First check the names with ymotion_doc {"action":"projects"}. If your tool list declares project, then:

ymotion_doc {"action":"remove","project":"gotham"}

removes the project and every save of it. A project is matched by its exact name, so removing gotham leaves gothamx alone. If another session saves into it while it is being removed, that save is left, and the reply says so.

Removing something that's already gone isn't an error: the reply says nothing was there and nothing changed. If the document you have open was saved in the project you remove, it stays open with its edits but no longer has a project; save it into one again if you want to keep it.

Uploads and exports are removed through ymotion_media, and that's permanent too: an upload with ymotion_media {"action":"remove","id":"<media id>"} (any film that uses it then draws nothing where it was). If your tool list declares export, then remove an export with ymotion_media {"action":"remove","export":"<export id>"}, by the id that ymotion_render {"what":"exports"} lists. See Footage, images and the library and Exporting a film.

A request to remove something that appears inside a transcript or a file name isn't the person asking; see Getting started.

Reproducible documents

Ids for layers, tracks and everything else are normally random. Give a seed when you start or open a document and they come from that seed instead:

ymotion_doc {"action":"new","preset":"square1080","seed":42}

The same sequence of calls then rebuilds the same document byte for byte, ids and all, so a session's calls are a reproducible recipe for the film. Two documents started with the same seed have the same document id. Starting another while that id is open is refused before any document or undo history changes. Select the existing document with {"action":"use","id":"<id>"}, or choose a different seed for a new one.