Pre-1.0: the API is not stable yet and may change from version to version. Pin the exact version in your Cargo.toml and check the changelog before upgrading.

oxframe

Check rules

What each rule in an oxframe check report means and how to fix it. The rule field of an issue in report.json is the name of its section here.

oxframe check plays every scene, samples frames and reports what a viewer would see as a mistake. An error makes the command exit 1; a warning does not. Each issue names the rule, the time range, the node and the line of code that added it. Thresholds live in oxframe.toml under [check].

Frame and layout

out_of_frame

A node stays outside the frame (error) or outside the safe area near the edges (warning). A node that only passes through the edge, entering or leaving, is not reported.

Reported by out_of_frame: A title pushed past the right edge.
Before: A title pushed past the right edge.
Fixed: The same title, centered and a size smaller.
After: The same title, centered and a size smaller.

Fix: move it inward, make it smaller, or place it with pct(), to_edge(Edge::…) or a Layout. --safe-inset 0 turns the warning off for a frame without a safe area.

text_overflow

Text is wider than its block: its max_width, or the Layout that holds it.

Reported by text_overflow: A heading wider than the 420 px card that holds it.
Before: A heading wider than the 420 px card that holds it.
Fixed: A shorter line in a smaller type style.
After: A shorter line in a smaller type style.

Fix: shorter text, a smaller type style (.h2(), .body()), or a wider block.

text_overlap

Two pieces of text cover each other.

Reported by text_overlap: Two lines placed on top of each other.
Before: Two lines placed on top of each other.
Fixed: The second line placed under the first with next_to.
After: The second line placed under the first with next_to.

Fix: place one relative to the other (next_to(other, Side::Bottom)), put both in a Layout, or fade the first out before the second comes in.

covers_text

A shader is drawn over text, so the text is hidden behind it.

Reported by covers_text: A waves shader added after the title paints over it.
Before: A waves shader added after the title paints over it.
Fixed: The shader added first and the title moved to the top.
After: The shader added first and the title moved to the top.

Fix: add the shader before the text, or move the text out of its box.

low_contrast

Text is too close in color to what is behind it, below the WCAG ratio (4.5 by default, --min-contrast).

Reported by low_contrast: Dark grey text on a dark grey card.
Before: Dark grey text on a dark grey card.
Fixed: The theme roles Text on Surface.
After: The theme roles Text on Surface.

Fix: use theme roles, which are built to contrast: Text on Background or Surface, OnAccent on Accent.

Timing

too_fast

Text is not on screen long enough to read at the reading speed (--chars-per-second), or a large move is quicker than --min-motion.

Fix: hold the text with wait_for(…) after it appears, or give the move a longer duration. In a presentation, hold before each slide_break: the video plays through it.

dead_time

Nothing changes on screen for longer than --max-still (not checked with a soundtrack).

Fix: shorten the wait, or give the viewer something to look at while it lasts.

Voice

voice_cut

A spoken line runs past the end of its scene and is cut.

Fix: line.await before the scene ends, or shorten the line.

voice_overlap

Two spoken lines overlap.

Fix: start the second line after first.await.

Shaders

shader_error

The WGSL of a shader does not compile, or a name or type does not match its Params.

Fix: the message names the line in the shader; see lesson 13.

param_unknown

A parameter is set from Rust that the shader's Params does not have.

Fix: add it to struct Params or correct the name.

shader_slow

A shader takes longer per frame than the budget.

Fix: a smaller box, fewer loop iterations, or a preset from shaders::.

input_cycle

A shader that reads drawn pixels (lens_drops, an effect) is inside a group that is itself drawn as a layer (opacity below 1, blur, clip, blend, shadow, another effect). The shader is skipped.

Fix: put the effect on that group instead, or take the node out of it.

Determinism and media

nondeterministic

Two paints of the same frame differ, so a seek or a render would not match the preview.

Fix: draw only from signals and ctx.time(); take randomness from ctx.rng(seed) or random(), never from the clock.

video_unavailable

A video clip cannot be opened; it shows as a dark box.

Fix: check the path, build with the video feature and install ffmpeg. The playground cannot play videos.