# Animate with keyframes

> Change a property over time with keyframes: position, scale, rotation, opacity and volume.

Source: https://alexgalhardo.github.io/vukem-video/docs/guide/keyframes/

## You will learn

- what a keyframe is and which properties can have them;
- how to add, change and remove keyframes in the inspector;
- how the same edit is done by a command.

## The idea

A **keyframe** fixes the value of a property at one time inside an item. Between two keyframes the value moves with the easing of the first one: `linear` (the default), `ease_in`, `ease_out`, `ease_in_out` or `hold`, which keeps the value until the next keyframe. The properties are `x`, `y`, `scale`, `rotation`, `opacity` and, for clips and audio, `volume`.

The time of a keyframe is an absolute position on the timeline and must be inside the item, its end included. The first keyframe you add after the item's start also creates a keyframe at the start with the current static value, so the animation begins from where the item was. Removing the last keyframe of a property writes its value back as the static value.

The preview and the export interpolate the keyframes with the same function (see [Render](/docs/concepts/render)).

## Quick start

In the editor, select an item, move the playhead inside it and open **Keyframes** in the inspector. Choose a property, set the value and the easing, and press **Add at playhead**. The keyframes appear as diamonds on the item and can be selected, changed with a value and an easing, removed one by one or cleared for the property or for the whole item.

**CLI**

```bash
vukem-video edit --project prj_7k2m9x4q1b keyframe.set item_id=itm_m1n2p3q4r5 \
  property=opacity at=0s value:=0
vukem-video edit --project prj_7k2m9x4q1b keyframe.set item_id=itm_m1n2p3q4r5 \
  property=opacity at=1s value:=1 easing=ease_out
vukem-video edit --project prj_7k2m9x4q1b keyframe.remove item_id=itm_m1n2p3q4r5 \
  property=opacity at=1s
vukem-video edit --project prj_7k2m9x4q1b keyframe.clear item_id=itm_m1n2p3q4r5
```

**MCP**

`edit` with the operations:

```json
{ "op": "keyframe.set", "args": {
  "item_id": "itm_m1n2p3q4r5", "property": "scale", "at": "2s", "value": 1.3
} }
{ "op": "keyframe.clear", "args": { "item_id": "itm_m1n2p3q4r5", "property": "scale" } }
```

`keyframe.clear` without a property clears every animated property; the value at the first frame of the item becomes the static value.

## Common mistakes

- Setting a value with `item.set_transform` on a property that has keyframes: refused. Use `keyframe.set`.
- A `scale` of 0 or more than 20, an `opacity` outside 0 to 1 or a `volume` above 4: `E_VALIDATION`.
- A keyframe time outside the item: `E_INVALID_TIME`.
- Changing a clip's speed rescales its keyframes by the same ratio. This is intended.

## Next steps

- [Transitions](/docs/guide/transitions)
- [Effects and color](/docs/guide/effects-and-color)
