Trim a video using the Edit API

One of the most common tasks in video editing is trimming. You will often have a clip that is too long, or you only need to use a short section from source footage. To achieve this, you need to trim the video clips start, end or both.

To trim a video within a video application or workflow you can use the Shotstack API. Unlike desktop software like Adobe Premiere, Shotstack lets you automate this using code.

Before we begin, register for a free account to get an API key. The free account gives you 20 minutes render time per month, plus a developer sandbox.

Shorten a video to specified length

In Shotstack, we prepare a video edit using JSON. To keep things simple, we'll use cURL to post to the API but you can also use Postman or the dashboard JSON editor.

To shorten a video, first, create a file named trim.json with the content below:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/beach-overhead.mp4"
            },
            "start": 0,
            "length": 10
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

In the above example, we have a video asset, beach-overhead.mp4 that is 31 seconds in duration. If we want to shorten the video to 10 seconds, we do this by trimming the end of the video.

First, set the start to 0, this will start the video playing straight away on the timeline. We then set the length to 10. This tells the API to only render the first 10 seconds of the clip.

Post the edit to the API

Using cURL, post the JSON to the render endpoint for processing. Add your own API key instead of YOUR_API_KEY:

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

You'll get a response back containing JSON data that has an id key:

{
  "success": true,
  "message": "Created",
  "response": {
    "message": "Render Successfully Queued",
    "id": "29ef5e40-fedf-84db-7e71-6d93b8bf633f"
  }
}

Get the edit render status

Copy the id from the render response and then make another cURL request (paste in your API key and render ID). This time we call the same endpoint but with GET and the copied ID where it says RESPONSE_ID:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.shotstack.io/stage/render/RESPONSE_ID

The response will include a response.status value. When this is equal to done, rendering is complete and a response.url value points to the video file.

{
   "success":true,
   "message":"OK",
   "response":{
      "id":"29ef4d40-fedf-42db-8b81-6d90b8bf633e",
      "owner":"msgtwx8iw6",
      "plan":"sandbox",
      "status":"done",
      "error":"",
      "duration":10,
      "billable":10,
      "renderTime":5139.64,
      "url":"https://shotstack-api-v1-output.s3-ap-southeast-2.amazonaws.com/msgtwx8iw6/29ef4d40-fedf-42db-8b81-6d90b8bf633e.mp4",
      "poster":null,
      "thumbnail":null,
      "created":"2022-02-04T01:43:38.486Z",
      "updated":"2022-02-04T01:43:44.549Z"
   }
}

Copy the response.url value and open the URL in a browser. You should see the trimmed video, cut to 10 seconds in length.

Trim a specified duration from the end of a video

In the following examples, follow the same process above but use the new JSON file. To trim the end of a video file we need to work out the new duration.

To do this, subtract the duration to trim from the total length. To trim 10 seconds from the end of our 31 second beach-overhead.mp4 video, the new length will be 21 seconds (31s - 10s).

The JSON and output video are shown below:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/beach-overhead.mp4"
            },
            "start": 0,
            "length": 21
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

If you don't know the length of the source video clip, you can use the probe endpoint to look up its duration.

Trim the start of a video clip

Trimming the start of a video clip works slightly differently. Instead of setting the length, we set the trim property of the asset. The trim parameter sets where the asset should start playing from. The start of the clip specifies where on the timeline the video should play from.

The following JSON will trim the first 10 seconds from the video clip.

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/beach-overhead.mp4",
              "trim": 10
            },
            "start": 0,
            "length": 21
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

Notice that we also need to calculate the new length of the clip, which should be 21 (31s - 10s).

The trimmed video with the start cut:

Trim a section out of a video clip

Finally, you might want to trim a section or segment from a longer piece of source footage. This can be useful for cutting highlights out of longer video clips.

To trim a 10 second segment from the middle the original video, use the JSON below:

{
  "timeline": {
    "tracks": [
      {
        "clips": [
          {
            "asset": {
              "type": "video",
              "src": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/beach-overhead.mp4",
              "trim": 10
            },
            "start": 0,
            "length": 10
          }
        ]
      }
    ]
  },
  "output": {
    "format": "mp4",
    "resolution": "sd"
  }
}

Trimming, merging, and stitching video

With the techniques outlined above you can trim a video in all possible ways. With some simple maths you can shorten clips and extract sections to compose a video edit.

To compliment trimming, you will want merge or stitch videos together. Learn how to do this in our merge video tutorial.