Clip a livestream

​

Introduction

You can use Livepeer Studio to create clips of active streams provided via API. Currently, you can create clips from the most recent N seconds of a given stream. You may also clip specific sections of a long-running stream, such as a particular session from a live-streamed conference.

This guide offers a comprehensive walkthrough of the clipping functionality.

​

Create a stream

Follow our previous guide on creating a stream to get a stream key to provide to the creator on your platform. They can then start broadcasting to that stream.

​

Create a clip

Submit a request to the Create Clip API using the following request parameters:

​

API + Player Integration

If you are using HLS.js, it provides an API for getting the program date time, hls.playingDate, which can be used to get the browser’s current playhead. This returns a Date object which is used similar to:

import Hls from "hls.js";

const hls = new Hls();

// Assuming you have already connected HLS.js to a video element

const endTime = hls.playingDate.getTime(); // This retrieves the current playing date from HLS.js
const startTime = endTime - 30000; // 30 seconds before the endTime in milliseconds

const playbackId = process.env.PLAYBACK_ID_OF_RUNNING_STREAM;

const result = await livepeer.stream.createClip({
  startTime,
  endTime,
  playbackId,
  name: "Your clip name",
});

If you are using the Livepeer Player, you use the Clip Trigger, which abstracts this functionality into an easy-to-use primitive. You will need to call the Livepeer Clip API from your backend, and perform sanitization on the user input.

<Player.ClipTrigger
  onClip={({ playbackId, startTime, endTime }) => {
    // use the start/end time to call the Livepeer API, from your backend
    // e.g. this should be a fetch to your /api/clip endpoint, which then
    // makes a request to Livepeer's Clip endpoint, after validating the
    // input parameters (e.g. clip is less than 60 seconds, etc)
  }}
>
  <ClipIcon />
</Player.ClipTrigger>

​

Monitor the clip’s status

After calling the clip API, Livepeer generates an asset. You’ll receive the asset’s details in the response.

{
  "task": {
    "id": "635cbcbb-30cb-4136-a7f0-ec5ea2ac39d0"
  },
  "asset": {
    "id": "e28c63c6-ffe8-4f0f-8ae0-4fbbe5c7b493",
    "playbackId": "e28crdyrtxjkx836",
    "userId": "8f175616-1a6d-4481-86f5-7351c041b5ca",
    "createdAt": 1695835443441,
    "status": {
      "phase": "waiting",
      "updatedAt": 1695835443441
    },
    "name": "My Clip",
    "source": {
      "type": "clip",
      "sessionId": "e0d88141-8ade-4274-9039-360245283645"
    },
    "objectStoreId": "9b526cee-bd25-44d2-9fda-f98db3a38a48"
  }
}

There are two approaches to track the clip’s status:

• using the /api/asset/$ASSET_ID API

You can poll this endpoint to retrieve the current status of the asset. Keep polling until the asset.status field is ready.

• using webhooks

If you have configured a webhook in Livepeer to listen for the asset.ready event, you will receive a notification when the clip processing is complete. You can use the assetId received in the previous response to determine when your clip is ready.

To determine if an asset you are polling or receiving as an event is a clip, you can check the source field. If the source field contains a clip type and the relative session ID, then it is indeed a clip.

You can always fetch clips by stream using the Clips for Livestream API:

const playbackId = process.env.PLAYBACK_ID_OF_RUNNING_STREAM;

const livepeer = new Livepeer({
  apiKey: "your_api_key_here",
});

const id = "08eeeda4-681f-46e5-a760-63d6cac91d91";

await livepeer.stream.getAllClips(id);

// Alternatively, you can use the streamId or fetch the clips
// by session using the /api/session/$sessionId/clips endpoint.

​

Get your clip!

A clip generated in Livepeer is the same of any other Livepeer asset. You are able to get the playback URLs in your asset object, or fetching them from the Playback Info API, providing the playbackId of the output asset representing the clip.