Skip to main content
Version: 2.x (current)

Migrating from 1.x

crates/import-v1 is a one-way importer for v1 (Electron/TypeScript) .animathio projects. v1 serialized a project as pako-deflated JSON (the earliest releases used plain JSON) with media embedded as base64 data URLs. The importer inflates, parses leniently, decodes media into content-addressed BLAKE3 assets and rebuilds a v2 Project exclusively through animathio_core::Commands.

animathio-cli import-v1 project.animathio -o imported.amio

Warnings go to stderr; the import succeeds as long as the project is structurally usable. Resource limits guard untrusted input: ≤ 2 GiB inflated JSON, ≤ 1 GiB per embedded asset, ≤ 10,000 media entries.

Where 1.x features live​

Audited against the frozen legacy sidebar, renderer/types.ts, the resource panels and Mafs dialog. “Moved” means an equivalent workflow exists at the listed location; “missing” identifies a concrete parity gap, not a hidden Library tab. This describes authoring in 2.x; importing saved 1.x projects has the limitations below.

1.x featureWhere it lives in 2.xStatus
Video / image / audio resources, uploadLibrary → Media; Import media; kind filters, grid/list and drag to timelineMoved
Microphone audio recorderImport recorded audio files in Media; no in-app recording (#299)Missing
Plain text / Mafs textLibrary → Elements → Text & formulas → Text; source and size in dialog/inspectorMoved
Title, Subtitle, Body, Caption, Heading 1–6 typographyTitles has composition presets; Text has editable size; original styles and font weights await #300Missing
LaTeX, matrix source, formula colourElements → Text & formulas → LaTeX; source, snippets, templates and colour in dialog/inspectorMoved
Natural-language → LaTeX (Gemini)No equivalent; optional integration tracked in #302Missing
Mafs point, line segment, vector, polygon, circle, ellipseElements → Shapes & geometry; each has a configurable dialog and inspectorMoved
Mafs function plotElements → Graphs & grids → Plot; expression and ranges in dialog/inspectorMoved
Mafs Cartesian / polar coordinatesElements → Graphs & grids → Cartesian grid / Polar grid; editable as separate layersMoved
Fade in/out, directional slide in/out, breatheEffects → Animations: In / Out / Emphasis; inspector → AnimationsMoved
Mafs reveal in/outEffects → zoom-in / zoom-out presets; LaTeX also has Write onMoved
Clip-path slide and per-character slideWhole-clip slide and typewriter are alternatives; exact parity awaits #301Missing
None, black-and-white, sepia, invert, saturate effectsEffects → Video effects; inspector → Effects (remove/bypass gives None)Moved
Audio mixer volume and muteTrack gain/mute/solo controls; clip inspector gain/mute; viewer monitor volumeMoved
Background FillFile → Project settings → background colourMoved
Element list, order, placement and timingMulti-track timeline, track order and inspector → TransformMoved
Manim source importFile → Import Manim sceneMoved
Canvas settings and MP4 video exportFile → Project settings; Export dialogMoved
WebM video exportNo WebM output backend (#303)Missing

Plugin clip sources appear only in Elements. Plugins is the installed inventory: all loaded kinds, versions, enabled status and source directories. Titles contains composition/caption presets; Effects contains video/audio effects, transitions and animation presets. Media search and media-kind filters belong only to Media.

What maps​

v1v2
Canvas width/height/background/maxTime, fpsCommand::SetSettings (width, height, background, duration, frame rate)
editor_elements z-orderOne Track per element, in the same order
Embedded media (base64 data URLs)Deduplicated content-addressed assets (AssetId = BLAKE3), registered via AddAsset
image elementClipKind::Image
video elementClipKind::Video (decoded by the media crate)
audio elementClipKind::Audio with gain + muted clip params; masterVolume → SetTrackGain
text elementClipKind::Plugin (org.animathio.text) with normalized font size and color
mafs graph elementClipKind::Image (see gaps below)
fadeIn / fadeOutOpacity keyframes
slideIn / slideOutX/Y keyframes (directions left/right/top/bottom)
breatheScaleX/ScaleY keyframes (bounded by slide-in/out window)
mafsRevealOpacity keyframes as a fallback
Effects (blackAndWhite, sepia, invert, saturate)One EffectInstance per clip (grayscale/sepia/invert, and saturate with amount = 2) from the org.animathio.effects-basic plugin, run in the plugin sandbox

v1 stores milliseconds and pixels as f64; v2 stores integer ticks and normalized canvas fractions. The conversion is exact-but-lossy by design, with bounds checked where they matter.

What doesn't map (known gaps)​

  • Mafs graphs become static images. v1 rasterized graphs to a PNG and never stored the graph definition, so only a marker (v1.mafs) survives for a future graph plugin. A warning is emitted.
  • Unknown effects are ignored with a warning. The four v1 presets become real, renderable plugin effects (grayscale/sepia/invert, saturate with amount = 2; the plugin must be installed to render them).
  • Rotation is approximated as center-based. v1 rotated around the Konva top-left corner; the importer warns and uses the element center.
  • fontWeight is dropped — the v2 text component has no weight equivalent.
  • Per-character text animation is flattened. A character-level slide is imported as a whole-element slide (warning).
  • mafsReveal is a fallback. It becomes an opacity fade, not a path reveal.
  • Animations with no targetId, unknown types, or invalid durations are skipped, as are animations targeting missing elements. A slide/fade whose duration exceeds the clip is clamped to the clip length.
  • Fractional or invalid fps is rounded (fractional to the nearest integer, invalid to 60). Invalid maxTime falls back to 30 s; invalid canvas values fall back or clamp to 65535.
  • Unknown top-level fields, element/property/media/animation fields and element types are ignored with warnings, never fatal.
  • Duplicate element ids: animations target the last element with that id (warning).

Not covered by this importer​

  • WebM export. Video clips import as ordinary video clips and export to H.264 + AAC MP4 like any other project; WebM output is not implemented.
  • Manim import is a separate importer (crates/import-manim), run inside the org.animathio.import-manim plugin and used via animathio-cli import-manim, the editor's Import Manim scene… dialog or the MCP import_manim_scene tool.
  • v1's Animations panel (fade, slide, breathe, Mafs reveal) maps to the org.animathio.animations presets in the inspector's Animations section: fade-in, fade-out, slide-in, slide-out, breathe and zoom-in/zoom-out (reveal). v1's clip-path slide and per-character slide have no preset; typewriter-in reveals text one character at a time instead.
  • Round-tripping. Import is one-way; there is no v2 → v1 export.

Verifying an import​

animathio-cli import-v1 project.animathio -o imported.amio
animathio-cli validate imported.amio
animathio-cli render imported.amio --frame 0 -o frame.png

validate checks model invariants and asset hashes; it does not decode video.

Serializer fixture corpus​

The checked-in corpus under crates/import-v1/tests/fixtures is produced by running v1's own serializer on constructed store state. Public CLI integration coverage imports and renders every compressed project at three times, including all v1 element, animation and effect types, embedded media, missing media, Unicode, non-unit scales, empty and very long projects, and a v1 Manim Text translation. Placement reads v1's scaleX/scaleY names (older snake-case inputs remain accepted).

This is not yet the complete M4 corpus: actual DOM-rasterized LaTeX/graph captures, historical serializers and user-authored projects remain to be added. The fixture README records provenance and regeneration instructions.