# shape.add

> Adds a rectangle, rounded rectangle or ellipse to a visual track.

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/reference/commands/shape.add

Adds a shape item with the given size in pixels before scale. Colours are hex or a template colour name like "$accent"; radius is for rounded_rect only. x and y default to the frame centre.

## Arguments

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `duration` | `string` | yes | A length of at least 1 frame. |
| `fill` | `string` | no | A colour; default #FFFFFF. |
| `height` | `number` | yes | Pixels before scale, above 0. |
| `id` | `string` | no |  |
| `radius` | `number` | no | Pixels, 0 or more; rounded_rect only. |
| `shape` | `rect`, `rounded_rect`, `ellipse` | yes |  |
| `start` | `string` | yes | a time with a unit: "12.5s", "375f" or "00:00:12.500" |
| `stroke_color` | `string` | no | A colour; default #000000. |
| `stroke_width` | `number` | no | Pixels, 0 or more. |
| `track_id` | `string` | yes | A visual track. |
| `width` | `number` | yes | Pixels before scale, above 0. |
| `x` | `number` | no |  |
| `y` | `number` | no |  |

## Example

As one operation of an `edit` batch (the `edit` tool of MCP, `vukem-video edit --ops`, or `POST /api/v1/projects/{id}/edit`):

```json
{
  "op": "shape.add",
  "args": {
    "duration": "3s",
    "fill": "#ff0000",
    "height": 200,
    "shape": "rect",
    "start": "0s",
    "track_id": "trk_f6g7h8j9k0",
    "width": 400
  }
}
```

## Errors

[`E_VALIDATION`](/docs/reference/error-codes#e_validation), [`E_INVALID_TIME`](/docs/reference/error-codes#e_invalid_time), [`E_NOT_FOUND`](/docs/reference/error-codes#e_not_found), [`E_TYPE_MISMATCH`](/docs/reference/error-codes#e_type_mismatch), [`E_ID_EXISTS`](/docs/reference/error-codes#e_id_exists), [`E_LIMIT`](/docs/reference/error-codes#e_limit), [`E_OVERLAP`](/docs/reference/error-codes#e_overlap)

## Scope and phase

Scope `edit`, phase `alpha`. Run `vukem-video command:help shape.add` for the same description from the binary.
