Hello World - Edit your first video using JSON

Shotstack enables video editing at scale. Our API allows you to describe your video edit in JSON, and then use your favorite programming language to render hundreds to thousands of data-driven videos concurrently in the cloud.

If this sounds like what you need, you're at the right place. In this tutorial we'll take you through the basics, arming you with the knowledge to start building complex video-centric applications using the Shotstack API.

We will start off by using a video clip, add a title, and then overlay a soundtrack to give it some feeling. We'll finish off our programmatically created video with some professional looking effects.

Getting started

Sign up for an API key

In order to build our first video you'll need to sign up for a developer account. This is completely free and will allow you to access all of Shotstack's video editing functionalities to build videos and develop applications. After registering just log in via the Shotstack website to receive a developer key.

cURL vs Postman

This tutorial presumes a basic knowledge of interacting with API's. For this guide we'll be using cURL but for any other application such as Postman you can use the JSON, credentials and endpoints to achieve the same results.

To check cURL is installed, type the command in your terminal or command prompt:

curl --version

Video editing basics

Before diving in and writing any code it is a good idea to acquaint yourself with some basic video editing principles and how these relate to Shotstacks JSON video editing format.

Edit

An edit in Shotstack is essentially a JSON object describing how assets such as titles, video clips and images are arranged to create a video.

Timeline

The timeline represents the entire duration of your video in seconds. For example, a 30 second video edit would have a 30 second timeline. Clips are placed along the timeline via a track.

Tracks

A track runs for the entire duration of the timeline and is used to layer clips on top of each other. For example, you can layer text on top of an image or a video clip. You can place multiple tracks on top of each other to create complex compositions.

Clips

A clip is a placeholder for an asset (titles, images, videos, audio, html, and Luma assets) and are positioned on the timeline (via a track) at specific time intervals. For example, you could add a clip that starts playing at the 5th second until the 10th second. Here you can also apply transitions, filters, and motion effects.

Assets

When creating a clip, you specify the type of asset to be displayed. This can be a text title, image, video clip, HTML, audio or a Luma asset. Each asset has options specific to its type. For example a title asset will have a type style, and a video asset might have a trim point to cut the start and end of the clip.

Output

The output specifies the final render properties, with the API supporting mp4 video files and gifs in a range of resolutions such as HD, SD and mobile.

If this does not all make sense yet, it will all become clearer once we create a few examples.

Your first Edit

Let's create a very simple "Hello World" title video.

Create a text file called hello.json with the following contents:

{
  "timeline": {
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future"
            },
            "start": 0,
            "length": 5
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

In this JSON snippet we specify a timeline with a black background, a track with a single clip which plays for 5 seconds, and a title asset with the text 'Hello World'. We specify the output as an mp4 video with SD resolution.

Now we post the Edit to the API for rendering by running the command below. Remember to replace the x-api-key parameter value above with your own staging key. If you don't have a key yet you can get one by signing up here.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d @hello.json \
  https://api.shotstack.io/stage/render

You should see a response similar to:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655"
  }
}

Copy the response id returned by the API as we will need it in the next step.

To check the status of the render run the following command, making sure to replace d2b46ed6–998a-4d6b-9d91-b8cf0193a655 with the id just copied.

curl -X GET \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.shotstack.io/stage/render/d2b46ed6-998a-4d6b-9d91-b8cf0193a655

The video should only take a few seconds to render. Once it is ready the response will show a status of done and include a URL to the final video file:

{
  "success": true,
  "message": "OK",
  "response": {
    "id": "d2b46ed6-998a-4d6b-9d91-b8cf0193a655",
    "owner": "hckwccw3q3",
    "plan": "sandbox",
    "status": "done",
    "error": "",
    "duration": 5,
    "billable": 5,
    "renderTime": 2488.23,
    "url": "https://s3-ap-southeast-2.amazonaws.com/shotstack-api-stage-output/hckwccw3q3/d2b46ed6-998a-4d6b-9d91-b8cf0193a655.mp4",
    "data": {
      "output": {...},
      "timeline": {...}
    },
    "created": "2019-04-16T12:02:42.148Z",
    "updated": "2019-04-16T12:02:51.867Z"
  }
}

If the status is not yet done (it might show queued, rendering, saving, fetching, or failed) wait a few seconds and run the command again.

Once your video is completed you can copy the URL and open it in your browser. You should see a simple 5 second video with the words 'Hello World' on a black background similar to the below.

Congratulations, you have created your first video using the Shotstack API.

It is obviously still a little bit boring so let's spice it up by adding a soundtrack and a background video.

Adding a video clip and soundtrack

Replace the contents of hello.json with the following snippet:

{
  "timeline": {
    "soundtrack": {
      "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/freepd/motions.mp3"
    },
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future"
            },
            "start": 0,
            "length": 15
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/earth.mp4"
            },
            "start": 0,
            "length": 15
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "1080"
  }
}

In this example we have added a new soundtrack file as a second track (motions.mp3), in addition to the video asset earth.mp4. Both the title and video clip have a length of 15 seconds and start at 0 seconds, meaning we have composited these tracks on top of each other.

Note that the video asset is positioned below the title asset. This makes sure that the text is rendered on top of the video file and not hidden underneath.

Go ahead and use the previous cURL commands to post the video and check its status. You should end up with a video like the one below:

This video is already a lot more interesting, but it could still do with a bit of refinement to give it a more professional touch.

Adding the final touches to our edit

To add some final polish we will reposition and resize the title and fade in and out both the video clip and soundtrack, in addition to a few other styling improvements.

Replace the hello.json file with the following and post it to the API using the cURL command and check its status.

{
  "timeline": {
    "soundtrack": {
      "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/music/freepd/motions.mp3",
      "effect": "fadeOut"
    },
    "background": "#000000",
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "title",
              "text": "Hello World",
              "style": "future",
              "position": "left",
              "size": "x-small"
            },
            "start": 4,
            "length": 11,
            "transition": {
              "in": "fade",
              "out": "fade"
            },
            "effect": "zoomIn"
          }
        ]
      },
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/earth.mp4",
              "trim": 5
            },
            "start": 0,
            "length": 15,
            "transition": {
              "in": "fade",
              "out": "fade"
            }
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

In the Edit above we've added the following:

• A fadeOut effect is added on the soundtrack;
• We use a fade in and fade out transition on the title asset and on the video asset;
• We position the title asset to the left and adjust its size;
• We start displaying the title asset after 4 seconds in time to the music;
• We add a zoomIn motion effect to the title asset;
• We trim the first 5 seconds off the start of the video asset.

The result is below:

Next steps

This guide should give you a basic grounding in how the Shotstack API works and some of the core features used to programmatically generate videos.

Using the programming language of your choice, you can now start building applications that tie directly into the Shotstack API.

Our API reference documentation will introduce you to all the available functionality.

Additionally, to help you get started please refer to our examples on GitHub using PHP and NodeJS.

If you are keen to learn more and are ready to take on a more complex challenge please take a look at our guide on using HTML and CSS to create videos.