API Reference

Livepeer Dev Kit

Catalyst

What's New

Community

Livepeer Docs

Documentation

Dashboard

Discord

Explore APIs, guides, and examples to integrate with Livepeer.

Introduction

Learn how to create an API key and start adding live and on-demand video to your app or website!

Quickstart

Practical step-by-step guides to help you achieve a specific goal. These guides are designed to help you get started with a specific task or feature.

Learn how to upload and play back an asset

Upload an asset

Play an asset

Learn how to listen to asset events using Studio webhooks.

Listen to asset events

Learn how to upload and play back an encrypted video asset

Upload encrypted assets

Learn how to retrieve thumbnails for a video asset

Get an asset thumbnail

Create a livestream

Learn how to use a media player with Livepeer

Play a livestream

Learn how to stream into Livepeer Studio with OBS

Livestream via OBS

In-browser broadcasting

Learn how to optimize latency for your Livepeer Studio workflow.

Optimize latency

Learn how to monitor stream metrics on Livepeer

Monitor stream health

Learn how to listen to stream events using Studio webhooks

Listen to stream events

Set up a multistream

Learn how to create clips from your livestream

Clip a livestream

Learn how to retrieve thumbnails for a live stream

Get a livestream thumbnail

Learn how to add access control to a content with React, using webhooks

Control access using webhooks

Learn how to add access control to a content with Livepeer UI Kit, using JWTs

Control access using JWTs

Learn how to set up a webhook using Node.js and Ngrok to receive notifications from Livepeer.

Set up and listen for webhooks

Transcode with Storj

Transcode with W3S

Learn how to check out viewer engagement on Livepeer

Engagement via API

Learn how to visualize your engagement metrics with Grafana

Engagement via Grafana

Learn how to analyze Livepeer video engagement metrics with Timeplus

Engagement via Timeplus

Learn how to Build a decentralized video application with FVM and Livepeer

Youtube clone with FVM

Learn how to token gate videos using Livepeer and Lit: A step-by-step tutorial

Token gate videos with Lit

Bridge LPT to Arbitrum

Migrate stake to Arbitrum

Yield Calculation on Explorer

Get started

Learn how to install go-livepeer and become an orchestrator

Install Go Livepeer

Connect to Arbitrum

Reward Calls

Set Session Limits

Set Pricing

Benchmark Transcoding

Assess concurrent stream

Monitor Metrics

Vote on proposals

Dual Mine

Connect to Transcoders

Migrate to Arbitrum

Migrate Stake from Contract

Broadcaster Introspection

Troubleshoot

What is Catalyst?

Running Catalyst Locally

Deploying Catalyst

Developing with Catalyst

API Support Matrix

Bandwidth Requirements

CLI Reference

GPU Support

Hardware Requirements

Prometheus Metrics

Addresses of deployed contracts of the Livepeer protocol on various networks.

Contract Addresses

Curated collection of Livepeer example applications and integrations

Example Applications

Awesome Livepeer

Player

The Livepeer Dev Kit is a set of SDKs, pre-built UI components, and tools for interacting with the Livepeer API.

Learn how to create your first stream using the Livepeer Javascript SDK.

JavaScript

Learn how to create your first stream using the Livepeer Ruby SDK.

Ruby

Learn how to create your first stream using the Livepeer Go SDK.

Learn how to create your first stream using the Livepeer Python SDK.

Python

Get started building with the Livepeer React UI Kit.

Getting Started

The `Player.Root` component is the React Context wrapper for the Player.

Root

The `Container` component is the container element for the Player. It wraps all other elements and acts as an aspect ratio container by default.

Container

The `Video` component renders the actual video content and manages various aspects of media playback.

Video

The `ErrorIndicator` component is a visual representation of error states in media playback based on error types.

Error

The `LoadingIndicator` component is a visual indicator of the loading state of the media.

Loading

The `Portal` component allows projection of content into different parts of the DOM.

Portal

The `Poster` component displays a visual placeholder for media content prior to playback.

Poster

The `Broadcast.Root` component is the React Context wrapper for Broadcast.

The `Container` component is the container element for Broadcast. It wraps all other elements and acts as an aspect ratio container by default.

The `Video` component is a container for previewing broadcast video content.

The `EnabledTrigger` and `EnabledIndicator` components provide broadcasters with interactive controls and visual cues to manage the "enabled" state of the broadcast.

Enable

The `ErrorIndicator` component is a visual representation of error states in broadcast based on error types.

A comprehensive example showcasing the integration of various `@livepeer/react/player` components to create a full-featured player interface with controls and settings.

A comprehensive example showcasing the integration of various `@livepeer/react/broadcast` components to create a full-featured broadcast interface with controls, settings, and device selection.

Broadcast

Migration guide for the 4.0.0 release of Livepeer React.

Migration Guide for 4+

Authentication

The Assets API is used to create, retrieve, update, delete assets object from pipeline.

To upload an asset, your first need to request for a direct upload URL
and only then actually upload the contents of the asset.
\
\
Once you created a upload link, you have 2 options, resumable or direct
upload. For a more reliable experience, you should use resumable uploads
which will work better for users with unreliable or slow network
connections. If you want a simpler implementation though, you should
just use a direct upload.


## Direct Upload
For a direct upload, make a PUT request to the URL received in the url
field of the response above, with the raw video file as the request
body. response above:


## Resumable Upload
Livepeer supports resumable uploads via Tus. This section provides a
simple example of how to use tus-js-client to upload a video file.
\
\
From the previous section, we generated a URL to upload a video file to
Livepeer on POST /api/asset/request-upload. You should use the
tusEndpoint field of the response to upload the video file and track the
progress:

```
# This assumes there is an `input` element of `type="file"` with id
`fileInput` in the HTML


const input = document.getElementById('fileInput');

const file = input.files[0];

const upload = new tus.Upload(file, {
  endpoint: tusEndpoint, // URL from `tusEndpoint` field in the
`/request-upload` response
  metadata: {
    filename,
    filetype: 'video/mp4',
  },
  uploadSize: file.size,
  onError(err) {
    console.error('Error uploading file:', err);
  },
  onProgress(bytesUploaded, bytesTotal) {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
    console.log('Uploaded ' + percentage + '%');
  },
  onSuccess() {
    console.log('Upload finished:', upload.url);
  },
});

const previousUploads = await upload.findPreviousUploads();

if (previousUploads.length > 0) {
  upload.resumeFromPreviousUpload(previousUploads[0]);
}

upload.start();

```

> Note: If you are using tus from node.js, you need to add a custom URL
storage to enable resuming from previous uploads. On the browser, this
is enabled by default using local storage. In node.js, add urlStorage:
new tus.FileUrlStorage("path/to/tmp/file"), to the UploadFile object
definition above.


Upload asset via URL

Retrieve an asset

Update an asset

Delete an asset

Retrieve assets

The Livestream API is used to create, retrieve, update, delete stream object from pipeline.

The only parameter you are required to set is the name of your stream,
but we also highly recommend that you define transcoding profiles
parameter that suits your specific broadcasting configuration.
\
\
If you do not define transcoding rendition profiles when creating the
stream, a default set of profiles will be used. These profiles include
240p,  360p, 480p and 720p.
\
\
The playback policy is set to public by default for new streams. It can
also be added upon the creation of a new stream by adding
`"playbackPolicy": {"type": "jwt"}`


Retrieve a livestream

Update a livestream

`DELETE /stream/{id}/terminate` can be used to terminate an ongoing
session on a live stream. Unlike suspending the stream, it allows the
streamer to restart streaming even immediately, but it will force
terminate the current session and stop the recording.
\
\
A 204 No Content status response indicates the stream was successfully
terminated.


Terminates a livestream

Add a multistream target

Remove a multistream target


This will also suspend any active stream sessions, so make sure to wait
until the stream has finished. To explicitly interrupt an active
session, consider instead updating the suspended field in the stream
using the PATCH stream API.


Delete a livestream

Retrieve all livestreams

Create a clip

Retrieve clips of a livestream

The Multistream target API is used to create, retrieve, update, delete multi-stream targets object from pipeline.

Create a multistream

Retrieve a multistream

Update a multistream

Make sure to remove any references to the target on existing
streams before actually deleting it from the API.


Delete a multistream

Retrieve all multistreams

The Sessions API is used to retrieve sessions object from pipeline.

Retrieve a session

Retrieve all sessions

Retrieve recorded sessions

Retrieve clips of a session

The Access control API is used to create, retrieve, update, delete signing keys object from pipeline.


The publicKey is a representation of the public key, encoded as base 64 and is passed as a string, and  the privateKey is displayed only on creation. This is the only moment where the client can save the private key, otherwise it will be lost. Remember to decode your string when signing JWTs.
Up to 10 signing keys can be generated, after that you must delete at least one signing key to create a new one.


Create a signing key

Retrieve a signing key

Update a signing key

Delete a signing key

Retrieve signing keys

The Webhooks API is used to create, retrieve, update, delete webhooks object from pipeline.

To create a new webhook, you need to make an API call with the events you want to listen for and the URL that will be called when those events occur.


Create a webhook

Retrieve a webhook

Update a webhook

Delete a webhook

Retrieve all webhooks

The Tasks API is used to retrieve tasks object from pipeline.

Retrieve tasks

Retrieve a task

The Playback API is used to retrieve playback object from pipeline.

Retrieve Playback Info

The Transcode API is used to create transcode object from pipeline.

`POST /transcode` transcodes a video file and uploads the results to the
specified storage service.
\
\
Transcoding is asynchronous so you will need to check the status of the
task in order to determine when transcoding is complete. The `id` field
in the response is the unique ID for the transcoding `Task`. The task
status can be queried using the [GET tasks
endpoint](https://docs.livepeer.org/reference/api/get-tasks):
\
\
When `status.phase` is `completed`,  transcoding will be complete and
the results will be stored in the storage service and the specified
output location.
\
\
The results will be available under `params.outputs.hls.path` and
`params.outputs.mp4.path` in the specified storage service.
## Input
\
This endpoint currently supports the following inputs:
- HTTP
- S3 API Compatible Service
\
\
**HTTP**
\
A public HTTP URL can be used to read a video file.
```json
{
    "url": "https://www.example.com/video.mp4"
}
```
| Name | Type   | Description                          |
| ---- | ------ | ------------------------------------ |
| url  | string | A public HTTP URL for the video file. |

Note: For IPFS HTTP gateway URLs, the API currently only supports “path
style” URLs and does not support “subdomain style” URLs. The API will
support both styles of URLs in a future update.
\
\
**S3 API Compatible Service**
\
\
S3 credentials can be used to authenticate with a S3 API compatible
service to read a video file.

```json
{
    "type": "s3",
    "endpoint": "https://gateway.storjshare.io",
    "credentials": {
        "accessKeyId": "$ACCESS_KEY_ID",
        "secretAccessKey": "$SECRET_ACCESS_KEY"
    },
    "bucket": "inbucket",
    "path": "/video/source.mp4"
}
```


## Storage
\
This endpoint currently supports the following storage services:
- S3 API Compatible Service
- Web3 Storage
\
\
**S3 API Compatible Service**
```json
{
  "type": "s3",
    "endpoint": "https://gateway.storjshare.io",
    "credentials": {
        "accessKeyId": "$ACCESS_KEY_ID",
        "secretAccessKey": "$SECRET_ACCESS_KEY"
    },
    "bucket": "mybucket"
}
```

**Web3 Storage**

```json
{
  "type": "web3.storage",
    "credentials": {
        "proof": "$UCAN_DELEGATION_PROOF",
    }
}
```



## Outputs
\
This endpoint currently supports the following output types:
- HLS
- MP4

**HLS**

```json
{
  "hls": {
        "path": "/samplevideo/hls"
    }
}
```


**MP4**

```json
{
  "mp4": {
        "path": "/samplevideo/mp4"
    }
}
```


Transcode a video

Requires a private (non-CORS) API key to be used.


Query viewership metrics

Query usage metrics

Allows querying for the public metrics for viewership about a video.
This can be called from the frontend with a CORS key, or even
unauthenticated.


Query public total views metrics

Requires a proof of ownership to be sent in the request, which for now is just the assetId or streamId parameters (1 of those must be in the query-string).


Name	Description
`stream.started`	The parent stream object’s isActive value is marked as true and the .m3u8 HLS URL works
`stream.idle`	The parent stream object’s isActive value should be marked as false and the .m3u8 HLS URL no longer works
`recording.ready`	This fires when a recording is ready to be downloaded
`recording.started`	This fires when recording has started on an active stream
`recording.waiting`	This fires after a stream with recording on has concluded and is not yet ready to be downloaded. Typically it takes 5 minutes for recordings to be ready for download.
`multistream.connected`	This fires when we’ve successfully connected to the multistream target
`multistream.error`	This fires when we’ve encountered an error either while attempting to connect to the third party streaming service or while broadcasting.
`multistream.disconnected`	This fires when we are no longer sending video to the multistream target.
`asset.created`	This fires when a On Demand asset is created.
`asset.updated`	This fires when a On Demand asset is updated. The asset payload will contain a playback URL when playback is available.
`asset.ready`	This fires when a On Demand asset is ready. Playback will be available with all transcoded renditions.
`asset.failed`	This fires when a On Demand asset fails during the upload or during processing.
`asset.deleted`	This fires when a On Demand asset is deleted.
`task.spawned`	This fires when a task is spawned. (For example, an On Demand upload)
`task.updated`	This fires when a task is updated.
`task.completed`	This fires when a task completes its execution successfully.
`task.failed`	This fires when a task has failed.
`playback.accessControl`	A specialized webhook for playback access control. Unlike other events, this is only used for assets and streams that reference its ID on their playback policy.

Getting Started

Guides

References

Core Concepts

Webhooks

Types of Events

Getting Started

Guides

References

Core Concepts

​Types of Events

Types of Events