API Reference

SDKs

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 automatically upload and play back a video on IPFS and Arweave with Livepeer React

Play video from IPFS/Arweave

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 mint a video NFT on the Aptos or an EVM-compatible blockchain with Livepeer React

Mint a video NFT

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 React, 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 rngagement 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

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

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 toolkit you need to build with Livepeer

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.

Golang

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

Python

Get started building with Livepeer React!

Getting Started

The livepeer Client is a framework agnostic client that manages wallet connection state and configuration, such as: auto-connection, connectors, and ethers providers.

Client

The LivepeerConfig component manages configuration for all hooks using React Context.

LivepeerConfig

The Player component provides an easy way to display video or audio.

The Broadcast component provides an easy way to livestream video or audio.

Broadcast

useCreateAsset

useAsset

useUpdateAsset

React Hook for retrieving metrics for an asset.

useAssetMetrics

useCreateStream

useStream

useUpdateStream

React Hook for retrieving a stream session.

useStreamSession

React Hook for retrieving the stream sessions associated with a stream ID.

useStreamSessions

React Hook for retrieving playback details for a playback ID.

usePlaybackInfo

Application Binary Interface

All contract addresses for the Livepeer protocol.

Authentication

POST /stream creates a stream object. The configuration on this stream
object is inherited by all live sessions using this stream's streamKey.

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"}`


Create a stream

In order to retrieve a specific stream, you can just pass the stream id
to this API


Retrieve a stream

`PATCH /stream/{id}` can be used to modify a stream object. It is a single
endpoint that can update any of the mutable properties of a stream.
Specifically:
- record
- suspended
- multistream.targets

All fields in the request payload are optional, and any field that is
not included will keep the same value as before in the saved object.

A 204 No Content status response indicates the stream was successfully
updated


Update a stream

`DELETE /stream/{id}` deletes an existing stream object.

 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 stream

GET `/stream` endpoint is used to retrieve all stream objects with the same userId. The response will include both parent stream objects and the historic stream objects with a parentId, which represent a single live stream session. Please note that the usage of these "child-session" stream objects is deprecated, and it is recommended to use the session endpoints instead.
\
\
To filter the API response and exclude the historic stream objects with a parentId, you can add the `?streamsonly=true` query string.


Retrieve all streams

Create a clip

Retrieve clips of a livestream

Create a multistream

You can retrieve a multistream target from its ID with this API.

Retrieve a multistream

`PATCH /multistream/target/{id}` updates an existing multistream target
object. You can change any user-defined field in the current object,
specifically name, url and disabled.

You cannot access the current url field for updating it since we redact
it from GET responses. If you want to update the URL you have to build
it from scratch. You can also omit it from the PATCH payload to keep it
as is.


Update a multistream

DELETE /multistream/target/{id} deletes an existing multistream target
object. Make sure to remove any references to the target on existing
streams before actually deleting it from the API.


Delete a multistream

Use /multistream/target to a return a list of your existing multistream
targets.


Retrieve all multistreams

Create a webhook

Retrieve a webhook

You can update a webhook by calling the PATCH webhook endpoint with the
webhookId. It is a single endpoint that can update any of the mutable
properties of a webhook. Specifically: name, url and events fields.


Update a webhook

Delete a webhook

Retrieve all webhooks

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:



>  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 the UploadFile object
definition above.


Import a video Asset from an external URL.


Upload asset via URL

Retrieve an asset

Update an asset

Delete an asset

Retrieve assets

Retrieve a session

Retrieve all sessions

Retrieve recorded sessions

Retrieve clips of a session

`PATCH /access-control/signing-key/{KEY_ID}` updates an existing signing
key. It is a single endpoint that can update any of the mutable
properties of a stream. Specifically `name` and `disabled` fields.


Create a signing key

Retrieve a signing key

PATCH `/access-control/signing-key/{KEY_ID}` updates an existing signing
key. It is a single endpoint that can update any of the mutable
properties of a stream. Specifically:
- name
- disabled

All fields are optional, and if any field is not included in the request
payload it will be kept unchanged from the saved object.


Update a signing key

Delete a signing key

You can list all the signing keys in your account by making a GET
request on `/api/access-control/signing-key`.


Retrieve signing keys

Retrieve tasks

Retrieves the details of a Task, including progress updates and status.
Use the unique Task ID that was returned from your previous request
or from an Asset export.


Retrieve a task

You can retrieve the playback information about any playback identifier
by calling this endpoint. It accepts playbackIds from any resource in
the API as well as dStorage IDs for assets.


Retrieve Playback Info

`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.
```js
{
    "url": "https://www.example.com/video.mp4"
}
```

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
- fMP4 (Fragmented MP4)

**HLS**

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

**MP4**

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

**Fragmented MP4**
\
The path specified in the `fmp4` property of the request will be used to store the fragmented mp4 files packaged with both HLS and DASH. The audio and video tracks are stored as separate mp4 files. Note the following files in the example below:
  - `index-stream0.mp4` —> audio track
  - `index-streamN.mp4` —> renditions (e.g. 1080p, 720p, etc)
  - `media_N.m3u8` —> HLS media playlists corresponding to renditions
  - `index.mpd` —> DASH manifest
  - `master.m3u8` —> HLS master manifest

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



## Profiles
\
The output profiles of the transcoded videos will follow an ABR (Adaptive Bitrate Streaming) ladder and can be set in one of the following ways:
- Default ABR ladder
- Target ABR ladder
- Target Bitrate

**Default ABR**
\
The `profiles` can be left blank to generate output videos with Livepeer's default ABR ladder. This will include a resolution that matches the input video's resolution and some additional resolutions.

```json

 profiles: [
   {}
 ]

```

**Target ABR**
\
To generate output videos with a specific ABR ladder, the `profiles` property can be set as follows.

```json

 profiles: [
   {
     name: "480p",
     bitrate: 1000000,
     fps: 30,
     width: 854,
     height: 480
   },
   {
     name: "360p",
     bitrate: 500000,
     fps: 30,
     width: 640,
     height: 360
   }
 ]

```

**Target Bitrate**
\
To generate a single output video that matches the input’s resolution with a target bitrate, set only the `bitrate` field of the `profiles` property.
```json

 profiles: [
   {
     name: "1080",
     bitrate: 4000000
   }
 ]

```


Transcode a video

Allows querying any metric in its raw form. Requires a private
(non-CORS) API key to be used.


Query viewership metrics

Allows querying any metric in its raw form. 
This can be called from the frontend with a CORS key.


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

Allows querying creator-specific 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). Returns only the
higher level metrics like viewCount and platimeMins. Can be used from
the frontend with a CORS key.


Getting Started

Guides

References

Core Concepts

Introduction

Quickstart

Core Concepts

Guides

API References

Explore the Livepeer SDKs

JavaScript

React & React Native

Ruby

Getting Started

Guides

References

Core Concepts

Quickstart

Core Concepts

Guides

API References

​Explore the Livepeer SDKs

JavaScript

React & React Native

Ruby

Explore the Livepeer SDKs