Getting started

Exporting a film

Show the person the film with a preview link, or queue an mp4 of all or part of it, follow it, share it and remove it.

An export turns the open document into an mp4. Before that, there's usually a simpler thing to give the person: a preview link, which plays the film in their browser with nothing to wait for and nothing to download. This page covers both: showing the film, then asking for an export, exporting part of a film, following its progress, sharing the finished file and removing it.

Showing the film: a preview link

Always give the person one of three links when you've made or changed something: a film's preview link, an image's preview link (both from ymotion_render {"what":"preview"}), or a finished export's own link. To show the person the film, give them a preview link: it plays at once, and there's nothing to download. Export only when they want a file to download. A preview is lighter than the final picture so it plays smoothly; the export is full quality. Tell the person so when you give them the link.

ymotion_render {"what":"preview"}

The reply carries the link twice, in its text and as preview in its data. It also names the film and its project, and lists any exports of exactly the same film, so a link and the mp4s of one film are never two unconnected things. Which save it was made from is in the data only, as version: it's internal, and the person is never told one. It's a link on the site's own host, /preview/ and a token, and it opens a page that plays the film in the browser with sound: the editor's own player, with every panel hidden and the picture filling the window on black, a play symbol until it's started, and one button that switches to the full editor. A click or a tap plays and pauses it, and it loops. Nothing is rendered or encoded, so it's ready the moment the reply arrives.

It plays the film as it is now. The link keeps a snapshot of the open document, so edits made after asking don't reach it. After changing something, ask again for a fresh link. Asking twice for an unchanged film gives the same link on the same day.
Anyone with the link can watch it, without signing in, for about a week; the reply says the moment it stops, in UTC. Asking again later gives a link that lasts another week. Paste it exactly as it comes back.
It holds the film and nothing else of the document. The main timeline, the compositions it places and the files something places are kept; an upload sitting unplaced in the document and a composition nobody placed are left out.
It plays what the person's account can hand out. Footage, pictures and sound placed through ymotion_media, library sound effects and cut-outs all play. A file that was dropped into an editor tab and never uploaded can't be played anywhere else, and the reply names how many there are.
Switching to the editor from the link opens the whole editor on that film, for anyone holding the link: they can change it and copy it. The film's owner, signed in, can save it into the project the link was made from; anyone else can't save it.
It finishes the save it was made from. A save you made stays out of the person's projects until it's done, and a preview link of it is it being done; see Documents and projects.

To take a link back, so that it and every other link to the same film stop opening:

ymotion_media {"action":"remove","src":"<the preview link>"}

Removing a project with ymotion_doc takes back the preview links made from it too. A link already handed out can't be recalled from whoever copied the film while it was open, so take it back as soon as the person asks.

How an export works

MP4 has no alpha channel. The completed picture is composited over black, so fades and translucent colours keep their visible strength. Export posters and chatbot delivery frames use the same conversion. The editor and PNG output retain transparency.

A finished film takes minutes to encode and is tens of megabytes, so it can't come back in a reply the way a frame does. Instead, asking for an export queues a job, and a render worker picks it up. The worker draws every frame with the same engine that draws your previews, at the film's own frame rate and its size — or its footage's sharpness, below — mixes the sound, and writes an mp4 (H.264 video, with AAC audio when the film has sound) to the person's storage.

ymotion_render {"what":"export"}

The reply gives the export's id, the length and size being rendered, and its own link, which plays and downloads the file once it's done and doesn't expire, in its text and as link in its data. It also names the person's Exports page, /exports on the site's own host (ymotion.ai/exports), which lists every export of theirs newest first, as share. The reply also says what the export was made from, which is recorded with it and never changes:

The film and its project. The film's name and its project, or that it was never saved. If the film had changes not saved, the reply says so, which makes it a different film from any save. Which save it was opened from or saved as is in the data only, as version, for your own bookkeeping: to the person it's the film and its project.
Who asked and when. A chatbot or the editor, as the client names itself, and the time to the second, in UTC.
The film's content, as hash in the data. The same film always has the same hash, so an export and a preview link of one document share it and point at each other.

Nothing more is needed from you while it runs.

The export also captures the project's optional search details, with its own known output file type, size, length or pieces. They belong to this export, so later changes to a project's notes do not rewrite it. Searchable details defines those fields. Descriptive notes and tags never affect the picture or turn an unchanged film into a second charge; changing the canonical title remains a rename, with its existing identity behaviour.

A few things follow from how this works:

The export is of the document as it is now. It takes the open document at the moment you ask, so later edits don't change a queued export. It doesn't need to be saved first, though saving before exporting lets the person find the exact film that was rendered — and an export of a save is that save done, shown in the person's projects; see Documents and projects.
Asking twice gives the same export. A request is identified by the document itself, so asking again for the identical film returns the export already made for it rather than starting a second one, and the reply says where that one stands: queued, running, done, or failed with the reason. It keeps the save it was first made from, so if two saves hold the identical film the reply says both: the save you asked from, and the save the one export of that film is recorded under. Any change to the document makes it a new export. To retry a failed export of an unchanged film, remove it (below) and ask again.
Interrupted work recovers automatically. A worker restart or retryable storage/database failure keeps the same queued export and its captured document. Do not change the film just to start a duplicate while one is queued or running. A final failure gives its reserved export minutes back once; the status includes the reason.
Deleting a project does not cancel its captured export. Removing a required upload can make unfinished work fail, while a worker that already has its bytes can finish. To cancel a queued export, remove that export itself; a running export must finish or fail first.
The picture matches the preview. Every length in a document is measured relative to the frame, so the frame you rendered at 1080 pixels is the same picture the export draws at full size. Render and look before exporting; see Looking at your work.
The frame rate is the film's. A film that took its shape from its footage already runs at the footage's rate. Any other film runs at the rate it was made with, which is 30 frames a second unless one was given, so 24 fps footage in it has some frames shown twice. To match the footage, set the rate before exporting with ymotion_edit {"ops":[{"verb":"setCanvas","args":{"patch":{"fps":24}}}]}. Keyframe times are seconds, so changing the rate moves nothing.
The size follows the footage's sharpness. A film under 2160 on its short side that draws footage or a picture sharper than its canvas is exported at that sharpness, up to 2160: a 1080x1920 film of 4K footage is a 2160x3840 mp4, the same picture with four times the pixels. So vertical1080 is right for a reel of 4K footage too, and the reply says the size it renders. A 4K film is vertical2160.
HDR footage is drawn in SDR. An iPhone's HLG, or PQ, is converted to BT.709 SDR the same way in a frame, a preview and the export, and the mp4 is BT.709, tagged so.
Odd sizes are evened. The H.264 encoder needs even dimensions, so an odd width or height is rounded up by one pixel in the export: a 641x361 film is drawn at 642x362, with everything in it laid out on that frame.
A film with nothing audible exports with no sound at all. Mute or zero a layer and it is not heard, in the editor, the preview and the file alike: when no layer reaches the mix (every sound muted, at level zero or switched off, or its track muted), the mp4 carries no audio stream.
Every sound is read from its own file. A sound whose file can't be read fails the export, and the failure names its layer, rather than leaving that sound out or playing another file's sound in its place.

Exporting part of the film

To render a stretch rather than the whole film, give from and to in composition seconds. This is After Effects' work area:

ymotion_render {"what":"export","from":2,"to":6.5}

Give both ends or neither; with neither, the whole film is exported. Each end is rounded to the nearest frame, and the frames rendered are exactly the frames the whole export would draw at those moments, with the sound cut at the same frames. A range has to start at or after 0 and before the film ends, stop after it starts, and hold at least one frame; a to past the end stops at the end. A range that covers the whole film is the same export as asking with neither.

If the person set a work area in the editor, its Export button renders that stretch, and you can match it. The editor keeps the work area on the document under meta.workArea, with the main composition's under an empty key:

ymotion_read {"what":"json","path":"meta.workArea"}

If that answers {"": {"start": 1.5, "end": 4}}, pass "from":1.5,"to":4. If it answers that nothing is at that path, no work area is set and the whole film is the work area.

Following progress

ymotion_render {"what":"exports"}

This lists the account's exports newest first, 20 to a page unless you give a limit (at most 100). Each one comes with its id, the film and the save it was made from, who asked, when, its status and progress, and a preview link when one of exactly that film is kept. Each finished one has its own link, which plays and downloads it; the person also sees every one on their Exports page, whose address the reply gives as share. It doesn't need a document open. The reply says how many there are in all; when there are more, it ends with the exact call for the next page, which carries an after, the page's next. Send it back unchanged.

Start with the whole list, which works from an older tool list:

ymotion_render {"what":"exports"}

If your tool list declares project, you can then see only one project's exports:

ymotion_render {"what":"exports","project":"gotham"}

Each export's save is in the list's data as version, never in its text. An export made before exports recorded where they came from lists as "unknown film".

query searches every saved detail and the export's known output information by words; it can be combined with project. Old exports remain findable by their recorded name. Its total counts only matches, and its next call keeps the same query and filter:

ymotion_render {"what":"exports","query":"paris reel"}

The statuses are:

queued: waiting for a worker.
running: being rendered, with a percentage.
done: finished, on the person's Exports page to play and download.
failed: stopped, with the reason.
not queued: recorded, but the queue never took it. Asking for the same film again queues it.

The id in this list is the export's own: the same id the reply to "export" gave, and the one remove takes.

An export usually takes a few minutes, longer for a long or large film. Rather than asking repeatedly, tell the person it's queued and check again when they come back to it. They can also see their exports in Ymotion itself: Exports, at /exports on the site (ymotion.ai/exports), shows all of them together, and on their Home page a project opens to its own.

To hand the person a finished export, give them its link: every export reply and every list of exports carries it as link (on the live site, https://ymotion.ai/export/…). It plays the film in a tab and downloads it under its name, at full quality, and it doesn't expire. Every reply also names their Exports page as share (https://ymotion.ai/exports), where, signed in, they see every export by its film's name, newest first. Paste the link whole, never build one. Removing the export is how to take it away; its link then opens nothing.

If the person only wants to watch the film, a preview link (above) needs no export at all.

Removing an export

First inspect stored media with ymotion_media {"action":"list"}; then, if your tool list declares export, use the export id the Exports page showed:

ymotion_media {"action":"remove","export":"<export id>"}

This deletes the mp4, the still picture its card on the Exports page shows, and its record permanently, and it leaves the person's Exports page. There's no undo, so do it only when the person asks. What happens depends on the export's state:

A queued export is cancelled before any worker starts on it.
A running export can't be removed until it finishes or fails, which takes minutes. The reply says so.
One that's already gone is reported as gone, and nothing changes.

Exports are listed by ymotion_render but removed by ymotion_media, which is where stored things are taken out of an account. That keeps ymotion_render a tool that never deletes anything, so it can be called freely.

When an export is refused

The reply always says why. The common reasons:

Out of export minutes. Every account is given 60 minutes of export once, and they never reset. Each export uses its own length every time it is made — a 15-second reel uses 0.25 minutes, and 0.25 minutes again when it is exported again after a change — a stretch of a film its stretch, and a failed or cancelled export none. The refusal, code export_minutes, says how long the export is and how many of the account's 60 free minutes are left; a shorter stretch that fits still exports, and ymotion_help {"topic":"account"} says what is left.
No signed-in account. An export is filed against an account, so a session connected with a shared access key rather than a sign-in can't queue one. Exports also need the hosted server, which has the job queue; a server running on the person's own machine can't export.
Nothing to render. A document with no layers is refused rather than rendered as an empty file.
Too much to draw. There's a ceiling on how much an export may paint across all its frames, about two hours of 1080p at 30 fps for a film with no nesting. The reply gives the film's size, length and frame rate. Lowering them brings it under, and so does nesting compositions less deeply, since a composition placed inside another is drawn at its own full size every time it's placed.
A file that isn't this account's. Every asset has to point at this account's own uploads, or at the shared sound-effects library. An asset copied out of somebody else's document won't resolve; place the file through ymotion_media instead.
Library sounds. A sound from the shared library has to be an audio asset, and a document can use 64 different library sounds. Placing one sound many times counts once, and placeSfx registers each correctly; see Sound, music and sound effects.