Shotstack is a cloud based [video editing API](https://shotstack.io). Unlike traditional desktop video editing
applications like Adobe Premiere or After Effects, Shotstack is purely code based - you create an edit using code. The
API uses a REST architectural style using JSON to describe how the video should be edited.

Although code based, the API follows many of the principles of desktop editing software such as a timeline, tracks and
clips. If you have used with Adobe Premiere, After Effects or even Flash some of these concepts should be familiar, all
be it without a graphical user interface.

These core concepts and principles are described below:

### Edit

An edit encompasses everything about the video that you want to create and is made of two components - the `timeline`
which describes the assets \(videos, images and titles\) that you want use and how they are arranged \(edited\) and the
`output` format \(gif or mp4\) and resolution \(HD, SD, mobile, etc..\).

```json
{
    "timeline": {...},   // the main video edit description
    "output": {...}      // the output format and resolution
}
```

:::info

The Edit is the JSON payload that you POST to the _render_ endpoint to create your video.

:::

### Timeline

The timeline represents the time that the video will play for, using seconds and starting from 0. A timeline is made up
of `tracks` which are like layers that contain clips.

```json
{
    "timeline": {
        "tracks": [{...}]   // array of tracks
    },
    ...
}
```

### Tracks

Tracks are like layers within the timeline which span the entire length of the timeline, a track contains one or more
`clips` Tracks can be visualized as layers that can be placed one on top of another. Clips on the top most track will
obscure those on tracks below it. This can be useful for when you want to layer a title over a video clip or you want to
fade between clips.

Tracks also help to logically organize different types of content, for example a title track which plays over the top of
a video and a watermark track that plays over the top of everything.

Tracks are an array within the timeline, the first element is the top track and the last element is the bottom most
track:

```json
{
    "timeline": {
        "tracks": [
            {
                ...   // top track
            },
            {
                ...   // bottom track
            }
        ]
    },
    ...
}
```

### Clips

Clips are where you select the asset \(video, image or title\) you want to display within a track on the timeline, when
it starts, how long it plays for and what effects, transitions and filters you want to apply.

Clips are placed on a track at a specific `start` time, for example a clip with a `start` time of 3 will appear in
the video after three seconds have played. Clips also have a `length` which determines how long the clip will play for
in seconds.

You can choose to set the `start` or `length` property automatically by setting it to `auto` or `end`. See the
[smart clips](/docs/guide/architecting-an-application/smart-clips) section for all options.

Each `asset` type has a specific set of options and features but you must specify the `type` of asset and also the
`content` of the asset such a URL `src` to a video or image file or for titles a `text` string.

```json
{
    "timeline": {
        "tracks": [
            {
                "clips": [
                   {
                       // place an image at the very start of the track/timeline that plays for 4 seconds.
                       "asset":{
                           "type": "image",
                           "src": "https://s3-ap-southeast-2.amazonaws.com/my-bucket/photo.jpg",
                       },
                       "start": 0,
                       "length": 4
                    },
                    {
                        // place a video that starts on the fourth second of the track/timeline ("start": 4) that has
                        // the first two seconds trimmed ("trim": 2) and plays for 6 seconds ("length": 6).
                       "asset":{
                           "type": "video",
                           "src": "https://s3-ap-southeast-2.amazonaws.com/my-bucket/footage.mp4",
                           "trim": 2
                       },
                       "start": 4,
                       "length": 6
                    }
                ]
            },
        ]
    },
    ...
}
```

:::danger

Do not place clips on a track so that their start or end times overlap. This will result in the clips
flickering because the API does not know which clip to display.

:::

A clip can also have transitions, effects and filters applied to them. A clip may look something like this when more
options are applied:

```json
{
    "asset":{
        "type": "video",
        "src": "https://s3-ap-southeast-2.amazonaws.com/my-bucket/footage.mp4",
        "trim": 2,
        "volume": 0.5
    },
    "start": 0,
    "length": 4,
    "transition": {
        "in": "fade",
        "out": "fade"
    },
    "filter": "boost",
    "effect": "slideRight"
}
```

From these basic building blocks you should be able to assemble a sophisticated, reusable template to create videos.
Assets can be replaced or clips added using loops, conditions and other coding constructs allowing you to build a range
of video based applications.