Livestream

Create a livestream

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

POST

stream

import { Livepeer } from "livepeer";
import { Profile, TranscodeProfileEncoder, TranscodeProfileProfile, Type } from "livepeer/models/components";

const livepeer = new Livepeer({
  apiKey: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await livepeer.stream.create({
    name: "test_stream",
    pull: {
      source: "https://myservice.com/live/stream.flv",
      headers: {
        "Authorization": "Bearer 123",
      },
      location: {
        lat: 39.739,
        lon: -104.988,
      },
    },
    playbackPolicy: {
      type: Type.Webhook,
      webhookId: "1bde4o2i6xycudoy",
      webhookContext: {
        "streamerId": "my-custom-id",
      },
      refreshInterval: 600,
    },
    profiles: [
      {
        width: 1280,
        name: "720p",
        height: 720,
        bitrate: 3000000,
        fps: 30,
        fpsDen: 1,
        quality: 23,
        gop: "2",
        profile: Profile.H264Baseline,
      },
    ],
    record: false,
    recordingSpec: {
      profiles: [
        {
          width: 1280,
          name: "720p",
          height: 720,
          bitrate: 3000000,
          quality: 23,
          fps: 30,
          fpsDen: 1,
          gop: "2",
          profile: TranscodeProfileProfile.H264Baseline,
          encoder: TranscodeProfileEncoder.H264,
        },
        {
          width: 1280,
          name: "720p",
          height: 720,
          bitrate: 3000000,
          quality: 23,
          fps: 30,
          fpsDen: 1,
          gop: "2",
          profile: TranscodeProfileProfile.H264Baseline,
          encoder: TranscodeProfileEncoder.H264,
        },
      ],
    },
    multistream: {
      targets: [
        {
          profile: "720p0",
          videoOnly: false,
          id: "PUSH123",
          spec: {
            name: "My target",
            url: "rtmps://live.my-service.tv/channel/secretKey",
          },
        },
      ],
    },
  });

  // Handle the result
  console.log(result);
}

run();

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": "test_stream",
  "kind": "stream",
  "creatorId": {
    "type": "unverified",
    "value": "user123"
  },
  "userTags": {},
  "lastSeen": 1587667174725,
  "sourceSegments": 1,
  "transcodedSegments": 2,
  "sourceSegmentsDuration": 1,
  "transcodedSegmentsDuration": 2,
  "sourceBytes": 1,
  "transcodedBytes": 2,
  "ingestRate": 1,
  "outgoingRate": 2,
  "isActive": true,
  "isHealthy": null,
  "issues": null,
  "createdByTokenName": "abc-123-xyz-456",
  "createdAt": 1587667174725,
  "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "streamKey": "hgebdhhigq",
  "pull": {
    "source": "https://myservice.com/live/stream.flv",
    "headers": {
      "Authorization": "Bearer 123"
    },
    "isMobile": 0,
    "location": {
      "lat": 39.739,
      "lon": -104.988
    }
  },
  "playbackId": "eaw4nk06ts2d0mzb",
  "playbackPolicy": {
    "type": "webhook",
    "webhookId": "1bde4o2i6xycudoy",
    "webhookContext": {
      "streamerId": "my-custom-id"
    },
    "refreshInterval": 600,
    "allowedOrigins": [
      "<string>"
    ]
  },
  "profiles": [
    {
      "name": "240p0",
      "fps": 0,
      "bitrate": 250000,
      "width": 426,
      "height": 240
    },
    {
      "name": "360p0",
      "fps": 0,
      "bitrate": 800000,
      "width": 640,
      "height": 360
    },
    {
      "name": "480p0",
      "fps": 0,
      "bitrate": 1600000,
      "width": 854,
      "height": 480
    },
    {
      "name": "720p0",
      "fps": 0,
      "bitrate": 3000000,
      "width": 1280,
      "height": 720
    }
  ],
  "projectId": "aac12556-4d65-4d34-9fb6-d1f0985eb0a9",
  "record": false,
  "recordingSpec": {
    "profiles": [
      {
        "width": 1280,
        "name": "720p",
        "height": 720,
        "bitrate": 3000000,
        "quality": 23,
        "fps": 30,
        "fpsDen": 1,
        "gop": 2,
        "profile": "H264Baseline",
        "encoder": "H.264"
      }
    ]
  },
  "multistream": {
    "targets": [
      {
        "id": "PUSH123",
        "profile": "720p"
      }
    ]
  },
  "suspended": true,
  "lastTerminatedAt": 1713281212993,
  "userId": "we7818e7-610a-4057-8f6f-b785dc1e6f88",
  "renditions": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

any

required

pull

any

creatorId

playbackPolicy

object | null

Whether the playback policy for an asset or stream is public or signed

playbackPolicy.type

enum<string>

required

Available options:

public,

jwt,

webhook

Example:

"webhook"

playbackPolicy.webhookId

string

ID of the webhook to use for playback policy

Example:

"1bde4o2i6xycudoy"

playbackPolicy.webhookContext

object

User-defined webhook context

Example:

{ "streamerId": "my-custom-id" }

playbackPolicy.refreshInterval

number

Interval (in seconds) at which the playback policy should be refreshed (default 600 seconds)

Example:

600

playbackPolicy.allowedOrigins

string[]

List of allowed origins for CORS playback (<scheme>://<hostname>:<port>, <scheme>://<hostname>)

profiles

object[] | null

Transcode profile

record

any

recordingSpec

object

multistream

any

userTags

any

Response

201

application/json

Success

name

string

required

Example:

"test_stream"

string

Example:

"de7818e7-610a-4057-8f6f-b785dc1e6f88"

kind

string

deprecated

Example:

"stream"

creatorId

object

userTags

object

User input tags associated with the stream

lastSeen

number

Example:

1587667174725

sourceSegments

number

Example:

1

transcodedSegments

number

Example:

2

sourceSegmentsDuration

number

Duration of all the source segments, sec

Example:

1

transcodedSegmentsDuration

number

Duration of all the transcoded segments, sec

Example:

2

sourceBytes

number

Example:

1

transcodedBytes

number

Example:

2

ingestRate

number

Rate at which sourceBytes increases (bytes/second)

Example:

1

outgoingRate

number

Rate at which transcodedBytes increases (bytes/second)

Example:

2

isActive

boolean

If currently active

Example:

true

isHealthy

any

issues

any

createdByTokenName

string

Name of the token used to create this object

Example:

"abc-123-xyz-456"

createdAt

number

Timestamp (in milliseconds) at which stream object was created

Example:

1587667174725

parentId

string

Points to parent stream object

Example:

"de7818e7-610a-4057-8f6f-b785dc1e6f88"

streamKey

string

Used to form RTMP ingest URL

Example:

"hgebdhhigq"

pull

object

Configuration for a stream that should be actively pulled from an external source, rather than pushed to Livepeer. If specified, the stream will not have a streamKey.

pull.source

string

required

URL from which to pull from.

Example:

"https://myservice.com/live/stream.flv"

pull.headers

object

Headers to be sent with the request to the pull source.

Example:

{ "Authorization": "Bearer 123" }

pull.isMobile

default:0

Indicates whether the stream will be pulled from a mobile source.

Available options:

0,

1,

2

pull.location

object

Approximate location of the pull source. The location is used to determine the closest Livepeer region to pull the stream from.

playbackId

string

The playback ID to use with the Playback Info endpoint to retrieve playback URLs.

Example:

"eaw4nk06ts2d0mzb"

playbackPolicy

object | null

Whether the playback policy for an asset or stream is public or signed

playbackPolicy.type

enum<string>

required

Available options:

public,

jwt,

webhook

Example:

"webhook"

playbackPolicy.webhookId

string

ID of the webhook to use for playback policy

Example:

"1bde4o2i6xycudoy"

playbackPolicy.webhookContext

object

User-defined webhook context

Example:

{ "streamerId": "my-custom-id" }

playbackPolicy.refreshInterval

number

Interval (in seconds) at which the playback policy should be refreshed (default 600 seconds)

Example:

600

playbackPolicy.allowedOrigins

string[]

List of allowed origins for CORS playback (<scheme>://<hostname>:<port>, <scheme>://<hostname>)

profiles

object[]

Profiles to transcode the stream into. If not specified, a default set of profiles will be used with 240p, 360p, 480p and 720p resolutions. Keep in mind that the source rendition is always kept.

Transcode profile

projectId

string

The ID of the project

Example:

"aac12556-4d65-4d34-9fb6-d1f0985eb0a9"

record

boolean

Should this stream be recorded? Uses default settings. For more customization, create and configure an object store.

Example:

false

recordingSpec

object

Configuration for recording the stream. This can only be set if record is true.

multistream

object

multistream.targets

object[]

References to targets where this stream will be simultaneously streamed to

Example:

[{ "id": "PUSH123", "profile": "720p" }]

suspended

boolean

If currently suspended

lastTerminatedAt

number | null

Timestamp (in milliseconds) when the stream was last terminated

Example:

1713281212993

userId

string

deprecated

Example:

"we7818e7-610a-4057-8f6f-b785dc1e6f88"

renditions

object

Overview Retrieve a livestream

import { Livepeer } from "livepeer";
import { Profile, TranscodeProfileEncoder, TranscodeProfileProfile, Type } from "livepeer/models/components";

const livepeer = new Livepeer({
  apiKey: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await livepeer.stream.create({
    name: "test_stream",
    pull: {
      source: "https://myservice.com/live/stream.flv",
      headers: {
        "Authorization": "Bearer 123",
      },
      location: {
        lat: 39.739,
        lon: -104.988,
      },
    },
    playbackPolicy: {
      type: Type.Webhook,
      webhookId: "1bde4o2i6xycudoy",
      webhookContext: {
        "streamerId": "my-custom-id",
      },
      refreshInterval: 600,
    },
    profiles: [
      {
        width: 1280,
        name: "720p",
        height: 720,
        bitrate: 3000000,
        fps: 30,
        fpsDen: 1,
        quality: 23,
        gop: "2",
        profile: Profile.H264Baseline,
      },
    ],
    record: false,
    recordingSpec: {
      profiles: [
        {
          width: 1280,
          name: "720p",
          height: 720,
          bitrate: 3000000,
          quality: 23,
          fps: 30,
          fpsDen: 1,
          gop: "2",
          profile: TranscodeProfileProfile.H264Baseline,
          encoder: TranscodeProfileEncoder.H264,
        },
        {
          width: 1280,
          name: "720p",
          height: 720,
          bitrate: 3000000,
          quality: 23,
          fps: 30,
          fpsDen: 1,
          gop: "2",
          profile: TranscodeProfileProfile.H264Baseline,
          encoder: TranscodeProfileEncoder.H264,
        },
      ],
    },
    multistream: {
      targets: [
        {
          profile: "720p0",
          videoOnly: false,
          id: "PUSH123",
          spec: {
            name: "My target",
            url: "rtmps://live.my-service.tv/channel/secretKey",
          },
        },
      ],
    },
  });

  // Handle the result
  console.log(result);
}

run();

{
  "id": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "name": "test_stream",
  "kind": "stream",
  "creatorId": {
    "type": "unverified",
    "value": "user123"
  },
  "userTags": {},
  "lastSeen": 1587667174725,
  "sourceSegments": 1,
  "transcodedSegments": 2,
  "sourceSegmentsDuration": 1,
  "transcodedSegmentsDuration": 2,
  "sourceBytes": 1,
  "transcodedBytes": 2,
  "ingestRate": 1,
  "outgoingRate": 2,
  "isActive": true,
  "isHealthy": null,
  "issues": null,
  "createdByTokenName": "abc-123-xyz-456",
  "createdAt": 1587667174725,
  "parentId": "de7818e7-610a-4057-8f6f-b785dc1e6f88",
  "streamKey": "hgebdhhigq",
  "pull": {
    "source": "https://myservice.com/live/stream.flv",
    "headers": {
      "Authorization": "Bearer 123"
    },
    "isMobile": 0,
    "location": {
      "lat": 39.739,
      "lon": -104.988
    }
  },
  "playbackId": "eaw4nk06ts2d0mzb",
  "playbackPolicy": {
    "type": "webhook",
    "webhookId": "1bde4o2i6xycudoy",
    "webhookContext": {
      "streamerId": "my-custom-id"
    },
    "refreshInterval": 600,
    "allowedOrigins": [
      "<string>"
    ]
  },
  "profiles": [
    {
      "name": "240p0",
      "fps": 0,
      "bitrate": 250000,
      "width": 426,
      "height": 240
    },
    {
      "name": "360p0",
      "fps": 0,
      "bitrate": 800000,
      "width": 640,
      "height": 360
    },
    {
      "name": "480p0",
      "fps": 0,
      "bitrate": 1600000,
      "width": 854,
      "height": 480
    },
    {
      "name": "720p0",
      "fps": 0,
      "bitrate": 3000000,
      "width": 1280,
      "height": 720
    }
  ],
  "projectId": "aac12556-4d65-4d34-9fb6-d1f0985eb0a9",
  "record": false,
  "recordingSpec": {
    "profiles": [
      {
        "width": 1280,
        "name": "720p",
        "height": 720,
        "bitrate": 3000000,
        "quality": 23,
        "fps": 30,
        "fpsDen": 1,
        "gop": 2,
        "profile": "H264Baseline",
        "encoder": "H.264"
      }
    ]
  },
  "multistream": {
    "targets": [
      {
        "id": "PUSH123",
        "profile": "720p"
      }
    ]
  },
  "suspended": true,
  "lastTerminatedAt": 1713281212993,
  "userId": "we7818e7-610a-4057-8f6f-b785dc1e6f88",
  "renditions": {}
}

Overview

APIs

Authorizations

Body

Response