Getting started

What the measurements mean

Evidence, finding thresholds, pending work and client limits for frames, sheets, timelines and measured sound.

Ymotion can read its document, paint export frames, measure geometry and pixels, and meter the sound the export delivers. Each reply says which of these happened and what remains unchecked. A measurement is evidence about its stated scope; it is not a promise that the finished film looks or sounds right. The owner currently has measured findings switched off. Frame pictures, structure facts, tile measurements, timeline facts and sound numbers remain available. If findings are enabled later, nothing found still is not a pass.

Evidence and limits

document_verified: Times, keys, sound plan or structure read from the document. The document says this, within the named scope.
geometry_verified: Layer boxes with the needed typefaces loaded. This geometry was measured. A missing face is not_observable, not a zero-width box.
frame_rendered: The server painted the named export frame. You observed it only if its image reached you. The mp4 encode and sound remain unchecked.
sequence_rendered: The server sent a sheet of export frames. You sampled those tiles only if its picture reached you; frames between sampled tiles were not seen.
pixels_measured: Numbers computed on rendered tiles, such as differences, repeats and colour. Report the number and the tile or stretch it covers. A tile does not prove full-size contrast.
audio_measured: Loudness and peaks measured on what the export delivers, before a mixed export's AAC encode. Report the numbers as audio_structure_checked: measured, not heard.
source_verified: A transcript record's word indexes and file-clock times mapped through its layer. Name the indexed interval; do not invent or quote words that were not read.
user_preview_required: The server could not judge the finished viewing or listening experience. Ask the person to play the preview and check the encode, colour and sound as heard.

A finding has a severity (blocker, major, moderate, minor or subjective) and an outcome such as improve, remove, needs_more_evidence or blocked. A missing record or typeface calls for more evidence; a meter disabled by its self-test is blocked. The server never declares pass. Read each reply's Not checked: line and its data unchecked list. Frames do not show intervening moments; a region does not show the rest of the frame; a sheet may sample rather than show every frame; the timeline does not show what a frame looks like; the meter has not listened. The whole-film review cannot identify faces, eyes or hands under text, read type burned into footage, inspect cuts within an uploaded file, or verify the final player's colour and sound.

What each call measures

ymotion_read {"what":"tracks"} lists layers by exact start time, with their track, source and sound clocks, keys and flags. The first page adds cuts, gaps, delivery facts and unchecked work. The page size is 60 rows by default, at most 200, with a 24 KB text cap; copy next.call until there is no next page. ymotion_read {"what":"tracks","like":"caption"} filters by layer id, name or kind. To inspect inside a composition, use its compId; each placing's main-timeline times are named.
ymotion_render {"t":1.5,"full":true} paints the export frame that contains 1.5 seconds at the export canvas. A printed frame time rounded to three decimals can be sent back in "t" to get that same frame. Times outside the film are clamped and said. A preview fidelity label means smaller density or a stated caveat; export means the frame painted for export before encoding. Mixed-rate footage, a missing face and a different face loaded on this server are named as caveats.
ymotion_render {"from":2,"to":3} gives a sheet of each export frame shown in [2,3) when at most 48 fit. Longer stretches are sampled with a stated step and calls for every frame in parts. A ranged export rounds its ends differently; use the export call printed by the sheet if you need exactly its frames. A stretch sheet can measure tile changes and a motion trace, not details smaller than a tile.
ymotion_render {"count":24} reviews the whole film as a storyboard with first and last frames, settled shot frames and evenly filled remainder. Its structure covers beginning, middle, end, pacing, consistency and delivery. The sheet's tile numbers and structure facts are available while findings are off. A sheet over a layer or composition uses "layerId" with "count".
ymotion_render {"what":"waveform"} measures none, a copied source stream or the export's mixed sound. It reports integrated LUFS, loudness range, peaks, each audible stem and, when records allow, speech margins and effect timing. ymotion_render {"what":"waveform","from":2,"to":6} measures a window. For a mixed export, the AAC encode itself is still unchecked.

Finding thresholds when enabled

These are the review's limits. A finding names the layer and time it covers; some tests use document facts, others need geometry, rendered pixels, media records or measured audio. Checks that could not run are listed as not_observable or blocked, rather than silently treated as clear.

M1 off frame: More than 2% of the visible letters box outside the frame is major; more than 50% is blocker.
M2 unsafe zone: On a vertical frame (height/width ≥ 1.5), ink meeting y > 0.80, or x > 0.88 while 0.35 < y < 0.85, is moderate.
M3 text over text: Intersection over the smaller visible text box > 0.10 at overlapping rest frames is major; pairs within one template instance are skipped.
M4 reading speed: More than 20 characters per readable second is moderate; more than 30 is major.
M5 short dwell: At least two words readable for < 0.8 seconds, after adjoining equal text is merged, is moderate.
M6 tiny type: style.size ≤ 1 is major; otherwise effective type under 2.5% of the frame's short edge is minor.
M7 track overlap: Neighbouring layers on one track overlapping is moderate; a transition-like overlap is a note.
M8 unseen keys: Every changing key segment outside the layer's shown span, allowing one frame either way, is moderate.
M9 pending cut-out: A pending cut-out mark overlapping shown footage and text in time is major.
M10 effect over speech: An effect's sync moment inside a mapped word is minor and needs more evidence.
M11 music against voice: Gains within 12 dB are a moderate structural warning; a measured speech margin from AM4 supersedes it.
M12 hidden text: An opaque picture above text covering at least 90% of its visible letters box is major; pairs within one template instance are skipped.
M13 never drawn: Missing footage or picture is blocker; an undrawn composition or alpha layer is major.
M14 out of film: A layer before zero or past the film's end, or a duration that cuts layers, is moderate.
M15 oversized footage: Unfitted footage shown at 100% scale and larger than the frame is moderate; contain or cover is a note.
M16 picture gap: No picture for at least one export frame between footage shots is moderate. A deliberate gap is the person's decision.
M17 delivery picture: Evened canvas, mixed-rate footage and lost film alpha are notes, not findings.
M18 delivery sound: A silent export and sound past the film end are reported. Server-prepared ramps and rate keys use their source clock, so they are not labelled as constant-rate drift. An unprepared one-rate fallback can still report drift over one frame.
M19 motion trace: A jump is displacement > 3× its ±3-frame neighbourhood median and > 2% of the short edge, with known hold, edge and ease exceptions; an unexplained one-frame opacity change > 0.5, a one-frame layer or a child jump can also be suspect moderate. At most 600 frames are traced per call before sampling.
M20 sequence pixels: Adjacent-tile difference < 0.5 of 255 is a repeat, expected when source frames repeat. Difference > 40 of 255 away from cuts, transitions, layer edges and hold or step keys is a suspect moderate pop.
M21 tile contrast: Median backdrop-to-flat-text contrast < 3:1 is moderate and needs more evidence from an export-pixel region. The tenth percentile is also reported; stroke, shadow, glow, plate or gradient cases are skipped and said.
S3 consistency: A caption role with > 2 sizes, > 2 faces or > 3 resting positions, or a film with > 2 transition kinds, is minor.
S5 colour: At a cut without a transition, adjacent shots differing by > 0.25 mean luma or > 0.15 mean chroma get a subjective flag; a deliberate look change is the person's call.

The sound checks use the delivered sound, not the height of stored peaks:

AM1 summary: Integrated and maximum momentary/short-term loudness, range, true and sample peaks are facts. −14 LUFS for short-form platforms is a reference, not a pass target.
AM2 peak: True peak > −1.0 dBTP is major because AAC encoding may distort the peak; a copied AAC stream may already have that distortion. Sample peak ≥ 0 dBFS is major. If per-frame true peak is unavailable, it is not stated.
AM3 silence: Short-term loudness below −60 LUFS for ≥ 1.0 second while the picture continues and sound exists elsewhere is moderate and needs more evidence.
AM4 speech: Each mapped word's speech stem is compared with the rest. Margin < 6 LU is moderate; < 0 LU is major. A word mixed with other sound inside a composition bus is not observable. Word calls use transcript file seconds.
AM5 effect timing: An acoustic moment from the sound catalogue or measured PCM is compared with the nearest visual event within ±0.5 seconds. Layer markers are author annotations and do not supply or override acoustic evidence. Two to four frames off is minor; five or more is moderate. No event in that window is a note.
AM6 cuts and beats: The offset of each cut to its nearest beat is reported as a distribution; it has no automatic pass threshold.
AM7 not heard: Muted footage with a transcript is moderate; other reasons a sound is absent are notes.
AM8 delivery: Missing sound sources are blockers because the export fails. Sound past the end and a source stream ending early are stated as delivery facts. Prepared server ramps and numeric rate keys follow their source clock rather than being rendered at one rate.

Pending work and asking again

A footage-heavy sheet can take more than 15 seconds and a meter job more than 3 seconds. Their pending replies still give document facts, a status, an askAgainIn delay and the same call to send again. A file being fetched is labelled fetching before the measuring job begins. You can continue with ordinary frames while a sheet is made. Asking for the same job joins it; a different request or changed film from the same owner supersedes the older job. An interim waveform picture may show stored peaks, plainly labelled not loudness. If the meter's FFmpeg self-test fails, its fallback stays labelled and its findings are blocked. A later same call gets a finished cached result when available; read the reply's suggested delay rather than guessing.

Picture sizes, regions and client lists

A sheet has at most 24 tiles per picture and at most two pictures. The server sizes it for the client's name at connection: openai for ChatGPT/OpenAI names (long side ≤ 2048 px, short side ≤ 768 px), and either otherwise (each edge ≤ 1568 px, at most 1.15 megapixels, short side ≤ 768 px). Tile detail is smaller than a full frame. Ask for one full frame to inspect fine type. If a busy full-size PNG is over 4 MB, it is still returned; JPEG or four export-pixel quadrants can make inspection easier.

First use an older-client-safe full-frame call:

ymotion_render {"t":1.5,"full":true}

If your tool list declares region, send that tool again with one of these optional second-call argument objects. They cover the frame without gaps:

{"t":1.5,"region":[0,0,0.5,0.5]}
{"t":1.5,"region":[0.5,0,0.5,0.5]}
{"t":1.5,"region":[0,0.5,0.5,0.5]}
{"t":1.5,"region":[0.5,0.5,0.5,0.5]}

The four numbers are fractions [left, top, width, height]; a region named by layer id also works. The server paints the full export frame, crops whole pixels, then enlarges them by an integer factor at most 8, with output long edge at most 2048 px. A region under 8×8 export pixels is refused. A positional filter may make a layer region the whole frame. A full frame can instead use ymotion_render {"t":1.5,"full":true,"format":"jpeg"}: JPEG 4:4:4 at quality 95 from the same pixels. The JPEG encoding is said in the reply.

An old client keeps the tool list it received when it connected. If it drops an argument the server offered, reconnect to refresh the list. For a region look, the server first offers a plain {"t":…} call. If you then ask at that time without region, its reply can say: If you sent "region", your client dropped it — its tool list predates it; reconnecting Ymotion refreshes the list. The whole frame is here. That line does not mean the region was shown.

"what":"tracks" with "t" and "limit"; "count", "times", "what":"waveform", and "full" — in a tool list since 2026-09-26. Available to these clients.
"layerId" on read or render — in a tool list since 2026-09-29. Use whole-film frames and the layer ids already shown by read replies.
"from" and "to" on render — in a tool list since 2026-10-03. Use 9–48 explicit "times" for a chosen stretch.
"region" on render — newer than 2026-10-03. First ask for the full frame with "t"; use region only as an optional second call if declared.

The "like" filter on tracks and frame "format":"jpeg" are supported by the current schema. Use them only when your client's list declares them. Every first look call in a reply uses older-list arguments; it never requires region.