# Anime com quadros-chave

> Mude uma propriedade ao longo do tempo com quadros-chave: posição, escala, rotação, opacidade e volume.

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

## O que você vai aprender

- o que é um quadro-chave e quais propriedades podem tê-los;
- como adicionar, mudar e remover quadros-chave no inspetor;
- como a mesma edição é feita por um comando.

## A ideia

Um **quadro-chave** fixa o valor de uma propriedade em um instante dentro de um item. Entre dois quadros-chave, o valor se move com a suavização do primeiro: `linear` (o padrão), `ease_in`, `ease_out`, `ease_in_out` ou `hold`, que mantém o valor até o próximo quadro-chave. As propriedades são `x`, `y`, `scale`, `rotation`, `opacity` e, para clipes e áudio, `volume`.

O instante de um quadro-chave é uma posição absoluta na linha do tempo e precisa estar dentro do item, inclusive o seu fim. O primeiro quadro-chave que você adiciona depois do início do item também cria um quadro-chave no início com o valor estático atual, para que a animação comece de onde o item estava. Remover o último quadro-chave de uma propriedade grava o seu valor de volta como valor estático.

A pré-visualização e a exportação interpolam os quadros-chave com a mesma função (veja [Renderização](/docs/concepts/render)).

## Início rápido

No editor, selecione um item, mova o cabeçote de reprodução para dentro dele e abra **Quadros-chave** no inspetor. Escolha uma propriedade, defina o valor e a suavização e pressione **Adicionar no cabeçote de reprodução**. Os quadros-chave aparecem como losangos no item e podem ser selecionados, alterados com um valor e uma suavização, removidos um a um ou apagados para a propriedade ou para o item inteiro.

**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` com as operações:

```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" } }
```

O `keyframe.clear` sem uma propriedade apaga todas as propriedades animadas; o valor no primeiro quadro do item passa a ser o valor estático.

## Erros comuns

- Definir um valor com `item.set_transform` em uma propriedade que tem quadros-chave: recusado. Use `keyframe.set`.
- Um `scale` de 0 ou maior que 20, uma `opacity` fora de 0 a 1 ou um `volume` acima de 4: `E_VALIDATION`.
- Um instante de quadro-chave fora do item: `E_INVALID_TIME`.
- Mudar a velocidade de um clipe reescala os seus quadros-chave pela mesma razão. É o comportamento esperado.

## Próximos passos

- [Transições](/docs/guide/transitions)
- [Efeitos e cor](/docs/guide/effects-and-color)
