kinemo API reference

kinemo 0.9.0 (IR 1.0.0). Every name in kinemo.__all__ and every public method of a public class, with signatures, parameters, props and canonical examples. Examples start with import kinemo as k and pass kinemo check --strict.

Also: Diagnostics, Command line, Configuration.

Scene #

Scenes, the timeline cursor and the blocks that shape time (s.play, s.start, s.during).

k.scene: Turns a function def name(s: k.Scene) into a scene.
k.SceneDef: A scene function plus its configuration.
k.Scene: Timeline of one scene.
k.TimeSpan: Where a play/start landed.
k.time: Global scene time in seconds, as a read-only signal.

Methods:

s.play: Schedules animations at the cursor and advances the cursor to their end.
s.start: Schedules animations at the cursor without moving it: this is how to run something in the background (clocks, simulations, continuous motion) while the script continues.
s.wait: Advances the cursor by d seconds (default 1).
s.wait_for: Moves the main cursor to the time of an event (the count-th firing after the cursor) and returns the EventInfo.
s.add: Puts objects in the scene instantly, at the cursor.
s.remove: Takes objects out of the scene instantly, at the cursor.
s.mark: Creates a time anchor at the cursor without moving it and returns the time.
s.during: with block that applies state changes on entry and reverts them, animated, on exit.
s.tempo: with block that multiplies the speed of everything inside: s.tempo(4) divides durations and waits by 4.
s.voice: Narrated with block: takes text (TTS from the provider in kinemo.toml) or an audio file, and lasts at least as long as the audio.

Object state #

Changing objects: animated state changes (.to()), instant writes (.set()), copies.

k.Node: Objects are values: creating one does not put it in the scene (use s.add or a verb).
k.reparent: Moves an object to another group at the scheduled time, keeping its world position (inside a container, it takes its place in the flow).

Methods:

obj.to: Animated state change: interpolates each prop from its value at the cursor to the target.
obj.set: Instant change at the cursor.
obj.unbind: Removes reactive bindings (all props when no name is given), keeping the current value.
obj.copy: Creates a new identity with the same props.

Verbs #

Entrance, exit and emphasis animations (k.draw, k.fade_out, k.indicate, k.morph).

k.draw: Entrance verb: traces the outline and then fills it.
k.write: Entrance verb: writes the text character by character.
k.fade_in: Entrance verb: opacity from 0 to 1.
k.fade_out: Exit verb: opacity from 1 to 0, and then the objects leave the scene.
k.grow: Entrance verb: scales up from the center (default) or from a side (from_="bottom", "left", "top-left"...).
k.shrink: Exit verb: the inverse of k.grow.
k.indicate: Emphasis: temporarily tints and pulses the object; the final state equals the initial one.
k.flash: Emphasis: a ring of light that expands from the object's edge and fades away.
k.squash: Emphasis: an elastic squash against the object's base; amount= controls the intensity.
k.follow: Motion: the object travels along a path (the outline of another object or a list of points, in world coordinates).
k.sound: Audio: plays a sound file at the moment it is scheduled (zero duration in the script).
k.morph: Swap: a leaves, b enters and the matching parts travel between them (identical characters and tokens slide; the rest fades out and in).

Composition #

Combining animations in sequence, in parallel and with a lag; reusable clips; easing.

k.seq: Composes animations in sequence: each one starts when the previous one ends.
k.par: Composes animations in parallel: they all start together and the group lasts as long as the longest one.
k.stagger: Staggers a list of animations: each one starts lag seconds after the previous one.
k.clip: Decorator that turns a function def name(s: k.Scene, ...) into a reusable sequence with its own cursor.
k.Animation: Immutable: only has an effect when passed to s.play or s.start.
k.ease: Easing curves.

Methods:

anim.with_: Returns a copy of the animation with a different duration, easing or delay.

Objects #

Shapes, groups, images, SVG and mass objects (points, vector fields, stream lines).

k.Circle: Circle of radius r, centered on its position.
k.Dot: Filled dot (default radius 0.08), with no stroke.
k.Ellipse: Ellipse of width w and height h, centered on its position.
k.Rect: Rectangle of width w and height h, centered on its position; radius= rounds the corners (for rounded corners prefer k.RoundedRect).
k.RoundedRect: Rectangle with rounded corners (radius=0.15 by default).
k.Square: Square with side side, centered on its position.
k.Polygon: Polygon from its vertices (k.Polygon((0, 0), (2, 0), (1, 1))), centered on its bounding box.
k.Triangle: Triangle from its three vertices (no arguments: equilateral with radius 1).
k.Line: Segment from start to end (local coordinates), or centered with length=.
k.Arrow: Arrow from start to end with a tip of size tip.
k.Arc: Circular arc of radius r, starting at start_angle and sweeping angle degrees (counterclockwise).
k.Path: Path from SVG commands (d="M 0 0 L 1 1") or a polyline from a list of points; closed=True closes the outline.
k.union: Boolean operations between shapes: k.union(a, b), k.intersect(a, b) and k.subtract(a, b) return a new k.Path computed from the outlines at the cursor (with the style of a, unless another one is passed).
k.intersect: Shape covering both a and b.
k.subtract: a with b cut out.
k.Bar: A value shown as a bar that grows from its base, with an optional label (label=True).
k.Group: Groups objects: transforms compose and opacity multiplies.
k.Image: Raster image (PNG or JPEG) drawn by the renderer, centered on its position.
k.SVG: Imports an SVG illustration (a file or inline markup): each shape becomes a k.Path with the SVG's fill, stroke and stroke width, and each <g> becomes a k.Group.
k.Brace: Curly brace (}) along one side of an object's box: direction= "down", "up", "left" or "right", gap units away from it, with the tip pointing outward.
k.Points: Thousands of points in a single object, batch-drawn in the core.
k.VectorField: Arrows of a field fn(x, y) -> (vx, vy) on a grid with density columns across the width of the region (x_range, y_range).
k.StreamLines: Streamlines of a field (a k.VectorField or a function), integrated with RK4 in the core from seeds (a count or points).

Text #

Text, LaTeX math and highlighted code, with addressable parts.

k.Text: Text with minimal inline markup (**bold**, *italic*, `code`).
k.Math: Formula in LaTeX syntax, typeset by the built-in engine (no TeX installation needed).
k.Code: Code with syntax highlighting (tree-sitter) and stable tokens: lang=, line_numbers=True, size=, theme="auto" (follows the scene background).

Methods:

code.highlight: Named transition: dims every line except lines (numbered from 1); code.highlight(None) removes the highlight.

Layout #

Placement by constraints (.place) and containers (k.Row, k.Column, k.Grid, k.Stack).

k.Row: Container that lays its children out in a row (flexbox), with gap= and align= ("center", "top", "bottom").
k.Column: Container that stacks its children in a column, with gap= and align= ("center", "left", "right").
k.Grid: Grid container with cols= columns and gap=.
k.Stack: Container that overlays its children, centered (or aligned by align=).

Methods:

obj.place: Declares where the object sits, relative to the frame (at="top", margin=) or to another object (above=, below=, left_of=, right_of=, inside= with pad=), with gap= (accepts a signal) and align=.
obj.to_place: Animated change of placement: the .to of .place.
obj.unpin: Releases the position constraint at the cursor: the object keeps its current position and is free to animate x/y.
group.fit: Scales the group once, at the cursor, until it fits an area (usually s.frame.safe, the frame's safe area), with an optional margin=.
group.swap: Named transition: swaps the places of two children and the container animates the reflow.
group.insert: Named transition: inserts a child at position i; it enters together with the reflow.
group.pop: Named transition: removes the child at position i (default: the last one); it exits together with the reflow.

Charts #

Axes, number lines, polar axes, plots and data charts.

k.PolarAxes: Polar axes (rings and spokes): r=(0, r_max, step), radius= in units, spokes=.
k.Axes: Cartesian axes with ticks, labels and an optional grid: x=(min, max, step), y=(min, max), labels=("x", "y"), width=/height= in units.
k.NumberLine: A horizontal number line: a k.Axes with only the x axis.
Plot: A curve y = fn(x) of an axes.
k.BarChart: Bar chart from a table: x= is the category column, y= the value column and key= identifies each bar.
k.LineChart: A k.Axes with one line per y= column (one or several), connecting the table's points in x= order.
k.Table: Table of k.Text with a highlighted header; columns= selects and orders the columns.

Methods:

ax.parametric: Parametric curve (fx(t), fy(t)) for t=(start, end); clipped to the visible ranges.
ax.plot: Draws the curve y = fn(x) on the axes, with adaptive sampling.
ax.area: Filled region under a curve (down to the x axis) or between two curves (between=).
ax.vline: Vertical line on the axes at at= (accepts a signal: the line moves with it); style="dashed" makes it dashed.
ax.hline: Horizontal line on the axes at at= (accepts a signal); style="dashed" makes it dashed.
ax.scatter: Points (xs[i], ys[i]) on the axes, as a group of k.Dot.
ax.zoom_to: Named transition: animates the visible ranges of the axes (x=(a, b), y=(c, d)).
ax.point: Data point (x, y) in world coordinates, reactive when x or y are signals.
curve.point_at: World position of the curve at x; reactive when x is a signal.
curve.tangent_at: Tangent segment length units long, centered on the curve at x, reactive when x is a signal.
curve.slope_at: Numerical derivative of the curve at x, reactive when x is a signal.

Reactive #

Signals, derived values and reactive collections.

k.signal: A value with a timeline.
k.Signal: A value that changes over the timeline: .set (instant), .to (animated), .now.
k.computed: Derived value with several dependencies: k.computed(lambda: f(a(), b())).
k.Expr: A value that may change over time.
k.list: List signal.
k.ListSignal: Python lists are not tracked; k.list([...]) is.
k.python: Marks an opaque Python function (external libraries, math, untraceable logic).
k.lerp: Interpolation modes of a signal, passed as k.signal(..., lerp=): linear (default), round (integers), step (switches at the end), step_start (switches at the start) and pointwise (lists of points, point by point).

Methods:

x.map: Applies a function to a signal: hour.map(solar_curve).

Native blocks #

Math blocks that run in the native core inside lambdas, .map and plots.

k.sin: Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x).
k.atan2: Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x).
k.cos: cos(x), native on signals.
k.exp: exp(x), native on signals.
k.log: ln(x), native on signals.
k.sqrt: sqrt(x), native on signals.
k.tan: tan(x), native on signals.
k.floor: Native rounding down (k.floor) and up (k.ceil).
k.ceil: ceil(x), native on signals.
k.min: Native minimum and maximum of two or more values (k.min(a, b, c)).
k.max: Native minimum and maximum of two or more values (k.min(a, b, c)).
k.clamp: Clamps a value to the range [lo, hi], natively.
k.where: The traceable if: a where cond holds, otherwise b.
k.piecewise: Piecewise function: k.piecewise((cond1, v1), (cond2, v2), default=v); the first true condition wins.
k.spline: Smooth table interpolation (natural cubic spline): k.spline(x, xs, ys).
k.interp: Linear table interpolation: k.interp(x, xs, ys).
k.mix: Linear mix a + (b - a) * t of numbers, vectors or colors (colors in OKLab, with no gray in the middle).
k.smoothstep: Smooth transition from 0 to 1 as x goes from e0 to e1 (cubic Hermite).
k.noise: Smooth, deterministic noise in [-1, 1] (seed= changes the sequence).
k.vec: 2D vector from two values (numbers or signals).
k.Vec: Vec(x, y)
k.pi: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.
k.e: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.
k.tau: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.

Stateful systems #

Conditions, integration and simulations resolved before rendering.

k.when: Edge-triggered effect: when cond goes from false to true, it fires an animation or emits an event.
k.integrate: Integral of an expression with respect to the change in d= (default k.time), starting at the cursor, with initial= and clamp=(lo, hi).
k.simulate: Fixed-step simulation: step(state, dt) -> state, run in Python during resolve.
k.State: Base of simulation states: plain fields (floats, bools, pairs) plus k.Events. class Ball(k.State): y: float = 4.0 v: float = 0.0 bounce: k.Event[Impact]
k.trace: Trail: the last length seconds of the path of a moving point (usually obj.world.position), drawn as a stroke.
k.Trail: Trail: the last length seconds of the path of a moving point (usually obj.world.position), drawn as a stroke.

Events #

Event sources and handlers.

k.EventSource: A concrete event of one owner.
k.EventInfo: One firing of an event, received by .on handlers and returned by s.wait_for: e.time (instant), e.data (typed payload), e.count (n-th firing) and e.value(sig) (value of any signal at the instant of the event).

Methods:

event.on: Decorator that reacts to every firing of an event: @source.on registers def handler(s, e), run during resolve with its own s whose cursor starts at e.time (the main cursor does not change).

Components #

Reusable components with props, outputs, events and context.

k.Component: The only kind of reusable object: a subclass with props (k.Prop[T], inputs), static fields (name: T = default), outs (k.Out[T], outputs as signals) and events (k.Event), plus a build() that runs once and returns the visual.
k.Prop: Declares a reactive component prop: power: k.Prop[float] = k.prop(0.0).
k.Out: Declares a continuous component output: soc: k.Out[float].
k.Event: Declares an event on a component or a k.State: full: k.Event or, with a typed payload, bounce: k.Event[Impact].
k.field: Validated default for a static component field: k.field(0.2, range=(0, 1)) or k.field("a", choices=[...]).
k.prop: Validated default for a reactive prop: k.prop(0.0, range=(-5, 5)).
k.context: Declares a context (at module level): a value that many components need (clock, scale, unit), supplied with k.provide instead of passed down prop by prop.
k.Context: Clock = k.context("clock", default=k.time), declared at module level.
k.provide: with block that supplies a context value to the components constructed inside it.
k.from_context: Prop or field default that reads a context: time: k.Prop[float] = k.from_context(Clock).

Parameters #

Scene parameters for the interactive player and exports.

k.Int: Integer scene parameter in the range [lo, hi]: k.Int(3, 12, default=5).
k.Float: Real-valued scene parameter in the range [lo, hi]: k.Float(0.5, 2, default=1).
k.Bool: Boolean scene parameter: k.Bool(default=True).
k.Choice: Scene parameter with fixed options: k.Choice([k.BLUE, k.RED]) (the default is the first option, or default=).
k.Str: Text scene parameter: k.Str(default="...").

Output #

Movies made of several scenes and the transitions between them.

k.movie: Composes several scenes into a single output, with one transition per join (k.cut when omitted).
k.Movie: Composes several scenes into a single output, with one transition per join (k.cut when omitted).
k.cut: Hard-cut transition between two scenes of a k.movie (the default).
k.crossfade: Transition in which the end of one scene dissolves into the start of the next, over duration seconds.
k.morph_cut: Transition in which objects with the same key= in neighboring scenes travel across the cut.

Theme and colors #

Themes, theme tokens and colors.

k.theme: Tokens of the current theme: k.theme.bg, fg, accent, muted, secondary.
k.themes: Built-in themes: k.themes.dark (default), k.themes.light and k.themes.blueprint.
k.Theme: Built-in themes: k.themes.dark (default), k.themes.light and k.themes.blueprint.
k.BLUE: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.BLACK: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.GRAY: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.GREEN: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.ORANGE: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.PINK: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.PURPLE: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.RED: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.TEAL: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.TRANSPARENT: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.WHITE: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.YELLOW: Fixed palette: k.BLUE, k.RED, k.GREEN, k.YELLOW, k.ORANGE, k.PURPLE, k.PINK, k.TEAL, k.WHITE, k.BLACK, k.GRAY and k.TRANSPARENT.
k.rgb: Color from components from 0 to 1 (a= is the opacity).
k.Color: Color from components from 0 to 1 (a= is the opacity).

Tooling and types #

Names for tools and type annotations rather than scene code.

k.Diagnostic: Diagnostics are read with kinemo check and kinemo explain <code>.
k.IR_VERSION: IR format version, for tools.
k.KinemoError: A build error.
k.Val: Type alias T | Signal[T] | Callable[[], T], for annotations only.

Other pages#

Diagnostics: Every error and lint code, grouped by range, with explanations and fixes.
Command line: Every kinemo subcommand with its arguments and examples.
Configuration: kinemo.toml, @k.scene options, sizes and quality presets.