---
title: User guide
description: Open, edit, preview, and export .motion projects with Motionly's tracks, clips, video assets, and MP4 output.
---

# Motionly User Guide

Motionly lets you open, edit, preview, save, and export `.motion` animations visually.

## Basic Workflow

1. Open a `.motion` project or use the project loaded by the development server.
2. Select a layer from Scene, the canvas, or the timeline.
3. Change its visual properties and animation timing.
4. Preview with Play/Pause or scrub to an exact frame.
5. Save the updated `.motion` project.
6. Export MP4 when the animation is ready.

## Top Toolbar

- Open loads a `.motion` file.
- Save overwrites an opened file when the browser provides a file handle. New or fallback uploads use Save As.
- Export MP4 renders the current project and downloads an MP4.
- The GitHub Star control opens the repository and displays its current star count.

## Preview

The center preview preserves the canvas aspect ratio defined by the project.

- Play/Pause controls playback.
- Reset returns to the first frame.
- The time and frame readout shows the current position.
- Fit centers the full canvas in the available space.
- Zoom controls change the editor view without changing the project.
- Fullscreen gives the preview more room.

Click empty preview space to clear selection. Click a visible image, SVG, or text object to select it. Drag selected objects to move them and use corner handles to scale them.

## Properties

Available controls depend on the selected layer:

- Position X/Y
- Scale and asset width
- Rotation
- Opacity
- Background color for scene overlays
- Text content, font size, and color
- Animation preset
- Duration, delay, and easing

Motionly updates the `.motion` source after each visual edit.

## Timeline

The timeline uses persistent simple layers:

- Every visual layer accepts text, image, video, overlay, or effect content.
- Clips move freely, gaps and overlaps are allowed, and no layer ripples neighboring clips.
- **Audio Tracks** remain at the bottom and move horizontally only.

Editing controls:

- Scrub the ruler or drag the playhead to seek to an exact frame.
- Drag clips horizontally to change time or vertically to any visual layer.
- Drag either edge to trim without moving neighboring clips.
- Select a clip and use Split to cut it at the playhead. This works for media, text, image, overlay, and effect clips.
- Toggle Magnet for optional edge/playhead snapping.
- Use Undo/Redo or `Ctrl/Cmd+Z` and `Ctrl/Cmd+Shift+Z`.
- Zoom with the timeline controls or `Ctrl/Cmd` + wheel/trackpad pinch.
- Use the eye on visual tracks and speaker on audio-capable tracks to isolate work without deleting it.

Dragging media from Assets creates a persisted `clip`. Track declarations, clip timing, visibility, and mute state save through `.motion`, so reopening a project reconstructs the same timeline.

## Audio

Audio is now persisted in `.motion` format using the `audio` syntax:

```motion
audio "/assets/my-project/background.mp3" {
  start 0s
}
```

Audio files:
- Show in the organized Audio panel
- Play synchronized with preview playback
- Stay on the bottom timeline track and persist horizontal start-time edits
- Render a normalized waveform preview inside the clip so you can align beats visually
- Export with MP4 at the same timeline offset
- Persist in saved `.motion` projects
- Are mixed into MP4 export from their persisted timeline offset

## Animated Assets

Motionly treats MP4, WebM, MOV/M4V, GIF, animated SVG, and Lottie as animated clips. Import media, drag it onto a track, and the renderer synchronizes frames to the project timeline whenever the format exposes frame seeking:

```motion
import "/assets/my-project/intro.mp4" as intro

clip intro {
  track main
  start 0s
  duration 4s
  trimIn 0s
  trimOut 0s
}
```

Animated clips support the same timeline operations as other media—drag to time, trim either edge, split at the playhead, and scrub. Video, Lottie, and supported GIF frames use `trimIn + (projectTime - start)` during preview and export.

Current limitations:

- **MP4 export does not mix video audio.** Motionly writes only the project `audio` element into the exported file.
- **A single imported video cannot play two source times at once.** If you need the same file at two different offsets on the timeline, import it under two aliases.
- **Codec support follows the browser** (typically H.264/AAC MP4 and VP8/VP9 WebM). MOV works when the browser supports the codec inside the container.
- **Animated SVG uses real-time Canvas playback.** Its internal timeline cannot be deterministically frame-seeked, and CSS keyframes may differ from browser DOM playback, so Motionly shows a clear warning and uses real-time playback/export.
- **GIF exact seeking uses `ImageDecoder`.** Browsers without it use real-time playback/export and show a warning.

## Animation Presets

The visual editor currently exposes a small entrance set:

- Fade in
- Rise in
- Scale in
- Blur reveal
- Soft drift

Use `power3.out` as the default for restrained motion. Additional presets and scene transitions will be added only when they provide a distinct, reusable motion pattern.

## MP4 Export

Motionly renders evaluated canvas frames at the project's resolution and FPS, sends them to the local FFmpeg export server, and mixes project audio at its timeline offset. Video, Lottie, and decoded GIF assets seek before each frame. Projects containing real-time animated SVG/GIF fallbacks export at wall-clock speed so their animation is preserved.

## `.motion` Source

The `.motion` file remains the saved source of truth. Use the source toggle for inspection or repair, not as the normal editing workflow.