Skip to main content

Render issues

The video looks like a slideshow​

The animation uses CSS @keyframes, which advance on wall-clock time and do not respond to seeking, so every captured frame is identical.

Everything that moves must be driven from window.CLEYA.seekTo(t). With --runtime gsap, author a paused timeline and hand it to cleya.scene(tl). See Determinism.

Elements appear before their entrance​

A base state was missed — the element is visible from frame 0 because nothing hid it before its in time. In raw HTML, use cleya.visible(sel, t0, t1) to gate it structurally rather than relying on discipline. In a scene spec, entrances handle this for you.

Text overflows or wraps oddly​

Use fit: { maxWidth, maxHeight } to let the runtime shrink the font until it fits. Note that text wraps only when you ask for it — via maxWidth, fit, an explicit wrap, or a \n — so a centred single line will not wrap on its own.

Fonts pop in mid-render​

Every capture path awaits window.CLEYA.ready, and scenes resolve it on document.fonts.ready (bounded at 15 seconds). If you are rendering raw HTML, make sure your page resolves ready only once its fonts have loaded.

Renders are slow​

  • Iterate with --check, --at and --preview instead of full renders. A single frame is under a second; a full 1080p30 render costs roughly one second per second of output.
  • Raise CLEYA_RENDER_WORKERS on a machine with cores to spare.
  • Do not set CLEYA_NO_GPU unless you must — GPU rasterisation is dramatically faster for full-frame filter effects, and output is bit-identical GPU-to-GPU.
  • --motion-blur multiplies capture time by the sample count. Use it on the final master only.

A colour looks different in the output​

Renders are captured through a forced sRGB profile. A wide-gamut (P3) colour in your source will be converted. Check what actually landed with palette, and score it against the brand with brand_check.

contrast or align returns nothing​

Both depend on OCR through the macOS Vision framework. Off macOS they are unavailable — review still runs its FFmpeg-based checks (black, frozen, dead-air) everywhere.